[Introduce]

eth-filter is a filter translator that runs on the network device. The goal of eth-filter is to allow the user to setup the policy to control the traffic to the network. For example, it can block the invalid packet or the packet with the wrong destination address. It can work with eth-multiplexer to control and reduce the traffic between eth-multiplexer and pfinet, and can also work alone, running directly on the real network device.


[Usage]

Usage: eth-filter [OPTION...]
Hurd filter translator.

  -i, --interface=DEVICE     Network interface to use
  -s, --send-filter=string   The filter rule which applies to the outgoing
                             packet
  -r, --receive-filter=string   The filter rule which applies to the ingoing
                             packet
  -S, --send-ip-range=IP range   A range of IP to create the send filter
  -R, --receive-ip-range=IP range
                             A range of IP to create the receive filter
  -?, --help                 Give this help list
      --usage                Give a short usage message
  -V, --version              Print program version

Mandatory or optional arguments to long options are also mandatory or optional
for any corresponding short options.


The '-i' option specifies the network interface the translator sits on. eth-filter can only connect to one network interface and the '-i' option should be only used once. DEVICE is a device file created by devnode translator.
The '-s' and '-r' options give the user a full control to specify the filter rules which applies to the outgoing packet and the incoming packet, respectively. The expression of the rule is the same as the one in TCPDUMP. 
The '-S' and '-R' options specify a range of IP that the user wants to filter. They are used to create the sending filter and the receiving filter, respectively. The generated rule is "arp or (ip and src net addr/prefixlen)" or "arp or (ip and dst net addr/prefixlen)". If prefixlen is 32, it can be omitted. 
NOTE: '-s' and '-S' cannot be used together. One will replace the other if they are both used. So are '-r' and '-R' options.
An example: settrans -acfg /servers/feth0 /hurd/eth-filter -i /dev/eth0 -S 192.168.8.0/24 -R 192.168.8.0/24

[Internal]

eth-filter works as a proxy, forwarding the packet between the user program and the network interface. In order to forward packets, eth-filter runs as a client to the network device. It opens the device and writes the packet to the network device as pfinet does. It calls device_set_filter() to set the filter rule and give its own port to the device so it can receive packets from the device. The rule passed to the network device is from the user program that connects to eth-filter.
eth-filter works as a RPC server to communicate with the user program and implements the server side functions in device.defs. It gets the packet in the server side function ds_device_write and gets the port to deliver packets to the user program in ds_device_set_filter. 
Three structures are used for one pair of the user program and the device: proxy_user, proxy_device, proxy. When the ds_device_open() is called, a proxy_user and proxy objectis created. A proxy_device object is created when the ds_device_set_filter() is called. The proxy_user and proxy_device extend port_info structure. When a packet is received from the user program or from the device, we have to retrieve the proxy object to get the corresponding information. This process is very similar as pflocal. When a user program exits, we need to destroy its proxy_user object and proxy object, and meanwhile, the proxy_device object related to the proxy object is also destroyed. 
Two filters exist in eth-filter, one for outgoing packets and the other for incoming packets. These are BPF filters, which are ported from GNU Mach. These BPF filters only decide whether the packet should be forwarded, and they cannot decide the destination of the packet. The BPF instructions are generated by libpcap from the filter rules given by '-s' and '-r' or '-S' and '-R' options.