Unison Help

  1. Unison Kernel
    1. Pthreads
      1. pthread_create()
      2. pthread_exit()
      3. pthread_self()
      4. pthread_equal()
      5. pthread_join()
      6. pthread_detach()
      7. pthread_setschedparam()
      8. pthread_getschedparam()
      9. pthread_attr_init()
      10. pthread_attr_destroy()
      11. pthread_attr_setstackaddr()
      12. pthread_attr_getstackaddr()
      13. pthread_attr_setstacksize()
      14. pthread_attr_getstacksize()
      15. pthread_attr_setschedparam()
      16. pthread_attr_getschedparam()
      17. pthread_attr_setdetachstate()
      18. pthread_attr_getdetachstate()
      19. pthread_stackinfo()
      20. pthread_setprio()
      21. pthread_getprio()
      22. sched_get_priority_max()
      23. sched_get_priority_min()
      24. sched_yield()
    2. Pthread Cancellation
      1. pthread_cleanup_pop()
      2. pthread_cleanup_push()
      3. pthread_cancel()
      4. pthread_setcanceltype()
      5. pthread_setcancelstate()
      6. pthread_testcancel()
    3. Mutex
      1. pthread_mutex_init()
      2. pthread_mutex_destroy()
      3. pthread_mutex_lock()
      4. pthread_mutex_trylock()
      5. pthread_mutex_unlock()
    4. Semaphores
      1. sem_open()
      2. sem_close()
      3. sem_unlink()
      4. sem_init()
      5. sem_destroy()
      6. sem_wait()
      7. sem_trywait()
      8. sem_timedwait()
      9. sem_post()
      10. sem_getvalue()
    5. Message Queues
      1. mq_open()
      2. mq_close()
      3. mq_unlink()
      4. mq_send()
      5. mq_receive()
      6. mq_notify()
      7. mq_setattr()
      8. mq_getattr()
      9. mq_timedreceive()
      10. mq_timedsend()
    6. Conditional Variables
      1. pthread_cond_init()
      2. pthread_cond_destroy()
      3. pthread_cond_wait()
      4. pthread_cond_timedwait()
      5. pthread_cond_signal()
      6. pthread_cond_broadcast()
      7. pthread_condattr_init()
      8. pthread_condattr_destroy()
    7. Barriers
      1. pthread_barrier_init()
      2. pthread_barrier_destroy()
      3. pthread_barrier_wait()
    8. Timers
      1. timer_create()
      2. timer_delete()
      3. timer_settime()
      4. timer_gettime()
      5. timer_getoverrun()
      6. timer_tick()
      7. nanosleep()
    9. Clocks
      1. time()
      2. uptime()
      3. sleep()
      4. clock_settime()
      5. clock_gettime()
      6. clock_getres()
      7. clock_init()
    10. Memory Allocation
      1. POSIX.1
        1. malloc()
        2. free()
      2. Variable Length (Pools)
        1. pool_create()
        2. pool_destroy()
        3. pool_alloc()
        4. pool_free()
      3. Fixed Length (Partitions)
        1. pt_create()
        2. pt_destroy()
        3. pt_getblock()
        4. pt_freeblock()
    11. Rendezvous
      1. mr_init()
      2. mr_send()
      3. mr_receive()
      4. mr_reply()
      5. mr_sigrecv()
      6. mr_sigpost()
    12. Interrupts
      1. interrupts
      2. i_disable()
      3. i_restore()
    13. Directory Services
      1. dir_register()
      2. dir_deregister()
      3. dir_lookup()
      4. dir_lookup_string()
    14. Miscellaneous
      1. checkIstack()
      2. NanoStart() or DSPexec_Start()
      3. _isrStackFill
      4. Kernel Scaling
      5. kfatal()
      6. kalloc()
      7. kfree()
      8. mpu or mmu
      9. pthreadStackFill
      10. thread_numb()
      11. thread_utilization_start()
      12. thread_utilization_stop()
      13. xprintf()
      14. xputs()
      15. xputchar()
  2. Unison I/O Library
    1. accept()
    2. bind()
    3. chmod()
    4. close()
    5. connect()
    6. creat()
    7. fstat()
    8. getpeername()
    9. getsockname()
    10. getsockopt()
    11. ioctl()
    12. link()
    13. listen()
    14. lseek()
    15. mkdir()
    16. mkfs()
    17. mount()
    18. open()
    19. read()
    20. recv()
    21. recvfrom()
    22. rename()
    23. renameat()
    24. rmdir()
    25. select()
    26. send()
    27. sendto()
    28. setsockopt()
    29. shutdown()
    30. socket()
    31. stat()
    32. sync()
    33. umount()
    34. unlink()
    35. write()
  3. Unison STDIO Library
    1. STDIO Library Calls
      1. clearerr()
      2. dprintf()
      3. fclose()
      4. fdopen()
      5. feof()
      6. ferror()
      7. fileno()
      8. fflush()
      9. fgetc()
      10. fgetpos()
      11. fgets()
      12. fopen()
      13. fprintf()
      14. fputc()
      15. fputs()
      16. fread()
      17. freopen()
      18. fscanf()
      19. fseek()
      20. fseeko()
      21. fsetpos()
      22. ftell()
      23. ftello()
      24. fwrite()
      25. getc()
      26. getc_unlocked()
      27. getchar()
      28. getchar_unlocked()
      29. getdelim()
      30. getline()
      31. gets()
      32. get_stderr_ptr()
      33. get_stdin_ptr()
      34. get_stdout_ptr()
      35. noperprintf()
      36. perprintf()
      37. perror()
      38. posix_compat()
      39. printf()
      40. putc()
      41. putc_unlocked()
      42. putchar()
      43. putchar_unlocked()
      44. puts()
      45. remove()
      46. rewind()
      47. scanf()
      48. setbuf()
      49. setvbuf()
      50. snprintf()
      51. sprintf()
      52. sscanf()
      53. stderr_init()
      54. stderr_close()
      55. stdin_init()
      56. stdin_close()
      57. stdout_init()
      58. stdout_close()
      59. vdprintf()
      60. vscanf()
      61. vsscanf()
      62. vfscanf()
      63. vprintf()
      64. vsnprintf()
      65. vsprintf()
      66. vfprintf()
      67. ungetc()
    2. Do-nothing Stubs
      1. ctermid()
      2. flockfile()
      3. fmemopen()
      4. ftrylockfile()
      5. open_memstream()
      6. pclose()
      7. popen()
      8. tempnam()
      9. tmpfile()
      10. tmpnam()
  4. Unison LIBC Library
    1. LIBC Library Calls
      1. assert()
      2. realloc()
      3. strcasecmp()
      4. strdup()
      5. strncasecmp()
      6. strftime()
    2. Do-nothing Stubs
      1. abort()
      2. execve()
      3. exit()
      4. _Exit()
      5. fork()
      6. getpid()
      7. isatty()
      8. kill()
      9. sbrk()
      10. times()
      11. wait()
    3. Do-nothing Wide-character Stubs
      1. <wchar.h>
      2. <wctype.h>
  5. Unison I/O Servers
    1. File Servers
      1. Multimedia File Server - fsys
      2. FAT File System - fatfs
      3. NAND File Server - nandfsys
      4. NOR File Server - norfsys
      5. Network File Server - nfs
  6. Graphics, Camera, Video, Audio
    1. Vendor Graphics
    2. Prism++ Graphics
    3. ADPCM Services - adpcmd
    4. Camera
  7. Network Protocols
    1. TCP and UDP Server - tcpd
      1. IPv4 only server
      2. IPv4/IPv6 server
    2. DHCP Client Service - dhcp client
    3. DHCP Server - dhcpd
    4. Telnet Server - telnetd
    5. Tiny FTP Server - tftpd
    6. Point to Point - pppd
    7. Network Translation - NAT with PAT
    8. Firewall
      1. Packet filter: pf
      2. Packet filter control: pfctl
      3. Fitler rules: pf.filtering
      4. Translation rules: pf.nat
    9. Tiny HTTP Server - thttpd
    10. Tiny HTTP Server with TLS
    11. POP3 Server
    12. Simple Mail Transfer Protocol Services (SMTP)
    13. Bootp Protocol
    14. File Transfer Protocol Server (FTP)
    15. File Transfer Client Services
    16. RPC / XDR
    17. DNS Client
    18. HTTP/HTTPS Client
    19. REST Client
    20. AutoIP Service - autoip client
    21. mDNS server - mdnsd
    22. SNTP Client
    23. SNMP Agent - Snmpd server
    24. SSL/TLS library
    25. SSH server
    26. IP security
      1. IPsec description
      2. IPsec administration: ipsecadm
      3. Virtual Private Network: VPN
    27. Power Control
      1. Motor and Motion Control Servers
      2. PWM, Encoders
    28. Serial I/O
      1. Asynchronous Serial I/O Server - ttyserver
      2. CAN Server - cand
      3. I2C Server - i2cd
      4. I2S Server - i2sd
    29. System Services
      1. Power Management Servers
      2. Login Service - login_services
      3. XML
      4. POSIX Shell and Login Service - posh
    30. Universal Serial Bus (USB)
      1. USB Server
      2. USB Device Server
      3. USB Embedded Host Server
    31. Wireless
      1. Wireless Servers and Drivers
      2. 802.15.4 Radio Servers
      3. TCP/v6 with 6loWPAN
      4. ZigBee
      5. BlueTooth Server
      6. 802.11 Wi-Fi
      7. GPRS, UHF and GPS Radio Servers
    32. Remedy Tools for Unison
      1. Remedy Data Logging and Event Display Tools
      2. Remedy Diagnostics
      3. Remedy Flash Downloader/Bootloader
      4. Remedy Power On Self Test - POST
      5. Remedy OS Object Viewer
      6. Remedy Remote Control Tools

7.8.3.Fitler rules: pf.filtering #


pf.filtering – filter rule configuration description for packet filtering


The pf packet filter drops, passes and modifies packets according to the rules. Rules can be defined using the function pfctl_rules_parse() from libraty pfctl. For each packet inspected by the filter, the set of rules is evaluated from top to bottom, and the last matching rule decides what action is performed.


Syntax for filter rules in BNF:

     rule           = action ( "in" | "out" )
                      [ "quick" ]
                      [ "on" ( interface-name | "{" interface-list "}" ) ]
                      [ route ] [ af ]
                      [ "proto" ( proto-name | proto-number |
                                  "{" proto-list "}" ) ]
                      [ flags ] ( [ icmp-type ] | [ ipv6-icmp-type ] )
                      [ "keep state" ] [ "modulate state" ]
                      [ "no-df" ] [ "min-ttl" number ] [ "allow-opts" ].

     action         = "pass" | "block" [ return ] | "scrub" .
     return         = "return-rst" |
                          [ "(" ( icmp-code-name | icmp-code-number ) ")" ] |
                          [ "(" ( icmp-code-name | icmp-code-number ) ")" ] .

     interface-list = interface-name [ "," interface-list ] .
     af             = "inet" | "inet6" .
     proto-list     = ( proto-name | proto-number ) [ "," proto-list ] .

     hosts          = "all" |
                      "from" ( "any" | "no-route" | host | "{" host-list "}" ) [ port ]
                      "to"   ( "any" | "no-route" | host | "{" host-list "}" ) [ port ] .

     host           = [ "!" ] address [ "/" mask-bits ] .
     address        = ( interface-name | host-name | ipv4-dotted-quad |
                        ipv6-coloned-hex ) .
     host-list      = host [ "," host-list ] .
     port           = "port" ( unary-op | binary-op | "{" port-list "}" ) .
     port-list      = ( unary-op | binary-op ) [ "," port-list ] .
     unary-op       = [ "=" | "!=" | "<" | "<=" | ">" | ">=" ] port-number .
     binary-op      = port-number ( "<>" | "><" ) port-number .

     flags          = "flags" ( flag-set | flag-set "/" flag-set | "/" flag-set ) .
     flag-set       = [ "F" ] [ "S" ] [ "R" ] [ "P" ] [ "A" ] [ "U" ] .

     icmp-type      = "icmp-type" ( icmp-type-code | "{" icmp-list "}" ) .
     ipv6-icmp-type = "ipv6-icmp-type" ( icmp-type-code | "{" icmp-list "}" ) .
     icmp-type-code = ( icmp-type-name | icmp-type-number )
                      [ "code" ( icmp-code-name | icmp-code-number ) ] .
     icmp-list      = icmp-type-code [ "," icmp-list ] .

     route          = "fastroute" |
                      "route-to" interface-name[":"address] |
                      "dup-to" interface-name[":"address]


For each packet processed by the packet filter, the filter rules are evaluated in sequential order, from first to last. Each rule either matches the packet or doesn’t. The last matching rule decides what ac- tion is taken. If no rule matches the packet, the default action is pass. To block everything by default and only pass packets that match explicit rules, one uses

     block in all
     block out all

as the first two rules.


The packet is passed.


The packet is blocked. Optionally, the filter can return a TCP RST or ICMP UNREACHABLE packet to the sender, where applicable.


The packet is run through normalization/defragmentation. Scrub rules are not considered last matching rules. IPv6 packets are not defragmented.


If a packet matches a rule which has the quick option set, this rule is considered the last matching rule, and evaluation of subsequent rules is skipped.


If a packet matches a rule with a route option set, the packet filter will route the packet according to the type of route option.

The fastroute option does a normal route lookup to find the next hop for the packet.


The route-to option routes the packet to the specified interface with an optional address for the next hop.


The dup-to option creates a duplicate of the packet and routes it like route-to. The original packet gets routed as it normally would.


The rule parameters specify for what packets a rule applies. A packet always comes in on or goes out through one interface. Most parameters are optional. If a parameter is specified, the rule only applies to packets with matching attributes. Certain parameters can be expressed as lists, in which case pfctl generates all needed rule combinations.

in or out
The rule applies to incoming or outgoing packets. Either in or out must be specified. To cover both directions, two rules are needed.


on <interface>
The rule applies only to packets coming in on or going out through this particular interface.


The rule applies only to packets of this address family. Supported values are inet and inet6.


proto <protocol>
The rule applies only to packets of this protocol. Common protocols used here are tcp, udp, icmp, ipv6-icmp, igmp, esp, ah, and ipencap. The rest protocols can be defined as numbers.


from <source> port <source> to <dest> port <dest>
The rule applies only to packets with the specified source and destina- tion addresses/ports.

Addresses can be specified in CIDR notation (matching netblocks), as symbolic interface names, or as any of the following keywords:
any – means any address;
no-route – means any address which is not currently routable.

Host name resolution and interface to address translation are done at rule set load-time. When the address of an interface (or host name) changes (by DHCP or PPP, for instance), the rule set must be reloaded for the change to be reflected in the tcp-server.

Ports can be specified using these operators

         = (equal), != (unequal), < (lesser), <= (lesser or equal), > (greater),
         >= (greater or equal), >< (range) and <> (except range).

>< and <> are binary operators (they take two arguments), and the range doesn’t include the limits, for instance:

port 2000 >< 2004
means ‘all ports > 2000 and < 2004’, hence ports 2001, 2002 and 2003.
port 2000 <> 2004
means ‘all ports < 2000 or > 2004’, hence ports 1-1999 and 2005-65535.

The host and port specifications are optional, as the following examples show:

         pass in all
         pass in from any to any
         pass in proto tcp from any port <= 1024 to any
         pass in proto tcp from any to any port 25
         pass in proto tcp from port > 1024 to ! port != 22
flags <a> | <a>/<b> | /<b>
The rule only applies to TCP packets that have the flags <a> set out of set <b>. Flags not specified in <b> are ignored. Possible flags are F (FIN), S (SYN), R (RST), P (PUSH), A (ACK) and U (URG).

flags S/S
Flag SYN is set. The other flags are ignored.
flags S/SA
Of SYN and ACK, exactly SYN is set. SYN, SYN+PSH, SYN+RST match, but SYN+ACK, ACK and ACK+RST don’t. This is more restrictive than the previous example.
flags S
If the second set is not specified, it defaults to FSRPAU. Hence, only packets with SYN set and all other flags unset match this rule. This is more restrictive than the previous example.
flags /SFRA
If the first set is not specified, it defaults to none. All of SYN, FIN, RST and ACK must be unset.
icmp-type <type> code <code> and ipv6-icmp-type <type> code <code>
The rule only applies to ICMP or ICMPv6 packets with the specified type and code. This parameter is only valid for rules that cover protocols icmp or ipv6-icmp. The protocol and the icmp type indicator (icmp-type or ipv6-icmp-type) must match.


By default, packets which contain IP options are blocked. When allow-opts is specified for a pass rule, packets that pass the filter based on that rule (last matching) do so even if they contain IP options. For packets that match state, the rule that initially created the state is used. The implicit pass rule that is used when a packet doesn’t match any rules does not allow IP options.


pf is a stateful packet filter, which means it can track the state of a connection. Instead of passing all traffic to port 25, for instance, one can pass only the initial packet and keep state.

If a packet matches a pass … keep state rule, the filter creates a state for this connection and automatically lets pass all following packets of that connection.

Before any rules are evaluated, the filter checks whether the packet matches any state. If it does, the packet is passed without evaluation of any rules.

States are removed after the connection is closed or has timed out.

This has several advantages. Comparing a packet to a state involves checking its sequence numbers. If the sequence numbers are outside the narrow windows of expected values, the packet is dropped. This prevents spoofing attacks, where the attacker sends packets with a fake source address/port but doesn’t know the connection’s sequence numbers.

Also, looking up states is usually faster than evaluating rules. If one has 50 rules, all of them are evaluated sequentially in O(n). Even with 50’000 states, only 16 comparisons are needed to match a state, since states are stored in a binary search tree that allows searches in O(log2 n).

For instance:

         block out all
         block in  all
         pass out proto tcp from any to any         flags S/SA keep state
         pass in  proto tcp from any to any port 25 flags S/SA keep state

This rule set blocks everything by default. Only outgoing connections and incoming connection to port 25 are allowed. The inital packet of each connection has the SYN flag set, will be passed and creates state. All further packets of these connections are passed if they match a state.

Specifying flags S/SA restricts state creation to the initial SYN packet of the TCP handshake. One can also be less restrictive, and allow state creation from intermediate (non-SYN) packets. This will cause pf to synchronize to existing connections, for instance if one flushes the state table.

For UDP, which is stateless by nature, keep state will create state as well. UDP packets are matched to states using only host addresses and ports.

ICMP messages fall in two categories: ICMP error messages, which always refer to a TCP or UDP packet, are matched against the refered to connection. If one keeps state on a TCP connection, and an ICMP source quench message refering to this TCP connection arrives, it will be matched to the right state and get passed.

For ICMP queries, keep state creates an ICMP state, and pf knows how to match ICMP replies to states. For example

pass out inet proto icmp all icmp-type echoreq keep state

lets echo requests (pings) out, creates state, and matches incoming echo replies correctly to states.

Note: nat/rdr rules (see pf.nat) implicitly create state for connections.


Much of the security derived from TCP is attributable to how well the initial sequence numbers (ISNs) are chosen. Some popular stack implementations choose very poor ISNs thus are normally susceptible to ISN prediction exploits. By applying a “modulate state” rule to a TCP connection, pf will create a high quality random sequence number for each connection endpoint.

The “modulate state” directive implicitly keeps state on the rule and is only applicable to TCP connections.

For instance:

         block out all
         block in  all
         pass out proto tcp from any to any                    modulate state
         pass in  proto tcp from any to any port 25 flags S/SA modulate state

Caveat: If pf picks up an already established connection (the firewall was rebooted, the state table was flushed, …) it will not be able to safely modulate the state of that connection. pf will fall back and operate as if “keep state” was specified instead. Without this fallback, modulation would cause both end hosts to each think that the other had somehow lost sync.

Caveat: If the state table is flushed or the firewall is rebooted, currently modulated connections can not be continued or picked up again by the firewall. State modulation causes the firewall to phase shift the sequencing of each side of a connection (add a random number to each side.) The sudden withdrawl of the modulation will appear to each side of the connection that its peer has suddenly shifted its sequence by a random amount. Neither side will be able to recover and the connection will stall then eventually close.


Packet normalization is invoked via the scrub directive. Normalization is used to sanitize packet content in such a way that there are no ambiguities in packet interpretation on the receiving side.

The normalizer does full IP fragment reassembly to prevent attacks that confuse intrusion detection systems by sending overlapping IP fragments.

Clears the dont-fragment bit from a matching ip packet.
min-ttl <number>
Enforces a minimum ttl for matching ip packets.

Normalization occurs before filtering, scrub rules and pass/block rules are evaluated independantly. Hence, their relative position in the rule set is not relevant, and packets can’t be blocked before normalization.


The size of IP datagrams (packets) can be significantly larger than the the maximum transmission unit (MTU) of the network. In cases when it is necessary or more effecient to send such large packets, the large packet will be fragmented into many smaller packets that will each fit onto the wire. Unfortunately for a firewalling device, only the first logical fragment will contain the necessary header information for the subprotocol that allows pf to filter on things such as TCP ports or to perform NAT.

Using scrub rules, fragments can be reassembled by normalization. In this case, fragments are buffered until they form a complete packet, and only the completed packet is passed on to the filter. The advantage is that filter rules have to deal only with complete packets, and can ignore fragments. The drawback of caching fragments is the additional memory cost. But the full reassembly method is the only method that works with NAT.

The alternative is to filter individual fragments with filter rules. If no scrub rule applies to a fragment, it is passed to the filter. Filter rules with matching IP header parameters decide whether the fragment is passed or blocked, in the same way as complete packets are filtered. Without reassembly, fragments can only be filtered based on IP header fields (source/destination address, protocol), since subprotocol header fields are not available (TCP/UDP port numbers, ICMP code/type). Filter rules still apply to fragments, if they only specify IP header fields. For instance, the rule ‘pass in proto tcp from any to any port 80’ never applies to a fragment, even if the fragment is part of a TCP packet with destination port 80, because without reassembly, this information is not available for each fragment. This also means that fragments can’t create new or match existing state table entries, which makes stateful filtering and address translations (NAT, redirection) for fragments impossible.

In most cases, the benefits of reassembly outweigh the additional memory cost.

The memory allocated for fragment caching can be limited using pfctl. Once this limit is reached, fragments that would have to be cached are dropped until other entries time out. The timeout value can also be adjusted.


The following example demonstrates how to use the pf.filterng syntax to setup filtering rules.

     # The external interface is eth0 (, the only routable address)
     # and the private network is, for which we are doing NAT.

     # normalize all incoming traffic
     scrub in on eth0 all

     # block and log everything by default
     block             out log on eth0           all
     block             in  log on eth0           all
     block return-rst  out log on eth0 proto tcp all
     block return-rst  in  log on eth0 proto tcp all
     block return-icmp out log on eth0 proto udp all
     block return-icmp in  log on eth0 proto udp all

     # block anything coming form source we have no back routes for
     block in from no-route to any

     # block and log outgoing packets that don't have our address as source,
     # they are either spoofed or something is misconfigured (NAT disabled,
     # for instance), we want to be nice and don't send out garbage.
     block out log quick on eth0 from ! to any

     # silently drop broadcasts (cable modem noise)
     block in quick on eth0 from any to

     # block and log incoming packets from reserved address space and invalid
     # addresses, they are either spoofed or misconfigured, we can't reply to
     # them anyway (hence, no return-rst).
     block in log quick on eth0 from {,, \
   , } to any

     # ICMP

     # pass out/in certain ICMP queries and keep state (ping)
     # state matching is done on host addresses and ICMP id (not type/code),
     # so replies (like 0/0 for 8/0) will match queries
     # ICMP error messages (which always refer to a TCP/UDP packet) are
     # handled by the TCP/UDP states
     pass out on eth0 inet proto icmp all icmp-type 8 code 0 keep state
     pass in  on eth0 inet proto icmp all icmp-type 8 code 0 keep state

     # UDP

     # pass out all UDP connections and keep state
     pass out on eth0 proto udp all keep state

     # pass in certain UDP connections and keep state (DNS (53))
     pass in on eth0 proto udp from any to any port 53 keep state

     # TCP

     # pass out all TCP connections and modulate state
     pass out on eth0 proto tcp all modulate state

     # pass in certain TCP connections and keep state (SSH (22), SMTP (25), DNS (53))
     pass in on eth0 proto tcp from any to any port { 22, 25, 53 } keep state


There is a demo available for the Unison and DSPnano pf.filtering which is found in installdir/demos.


pfctl, pf.nat

Suggest Edit