peapod - EAPOL Proxy Daemon
peapod [-dtsqCoh] [-vvv] [-p pidfile] [-c configfile] [-l [logfile]]
peapod is a daemon that proxies IEEE 802.1X Extensible Authentication Protocol over LAN (EAPOL) packets between Ethernet interfaces. It supports a few tricks on a per-interface basis, so it may be considered a (highly) rudimentary general-purpose transparent bridging firewall/rewriting proxy for EAPOL.
EAPOL is a port-based network access control (PNAC) mechanism ensuring that only authorized devices are allowed to use a network. In a nutshell, EAPOL blocks regular network traffic, such as TCP/IP, from traversing the physical port (e.g. on a switch) to which a client is connected until the client successfully authenticates and establishes an EAPOL session.
Abilities surpassing those of a simple proxy include:
At startup, peapod reads its config file to determine the network interfaces on which it should listen for EAPOL packets and how packets should be received and sent on those interfaces. "EAPOL packet" in this sense is an Ethernet frame with the EAPOL EtherType of 0x888e encapsulating either an EAP packet or certain EAPOL control messages.
See peapod.conf(5) for config file semantics and syntax.
The remainder of this section provides an overview of peapod's control flow once it begins proxying packets proper, and is intended to assist in the creation of config files. This can be divided into ingress and egress phases.
peapod waits until an EAPOL packet arrives on any configured interface, which then becomes the ingress interface.
The following is then performed:
- If the packet is the first packet to be received on the ingress interface, and another interface is configured with "set-mac-from ingress-interface-name;":
- Change the other interface's MAC address to that of the packet's sender.
- Drop the packet.
- Determine the type of the packet.
- Check for ingress scripts and/or ingress filters (scripts/filters configured as ingress stanza options on the ingress interface) that match the packet type.
- Execute any matching ingress script.
- Apply any matching ingress filter (i.e. drop the packet).
Dropping a packet in this phase means immediately discarding it and returning to the beginning of the ingress phase.
If the packet was not dropped, peapod moves on to the egress phase.
The received packet is proxied to all configured interfaces except for the ingress interface, which then become the egress interfaces.
For each egress interface, the following is then performed:
- Make a copy of the packet to be used with the current egress interface.
- If an existing 802.1Q VLAN tag in the packet should be manipulated or removed, or one should be added (as configured in a dot1q option on the current egress interface):
- Make the necessary changes to the copy.
- Determine the type of the packet.
- Check for egress filters and/or egress scripts (filters/scripts configured as egress stanza options on the current egress interface) that match the packet type.
- Apply any matching egress filter (i.e. drop the packet).
- Execute any matching egress script.
- Send the (copy of the) packet on the current egress interface.
Dropping a packet in this phase means discarding the copy and moving on to the next egress interface.
At the end of the egress phase, the packet may have been proxied to one or more egress interfaces, and peapod returns to the beginning of the ingress phase to listen for more packets.
Example config files and scripts are included in peapod's shared resources in /usr/share/peapod/examples, as well as in the doc/examples subdirectory of the program sources.
See peapod.conf(5) for config file semantics and syntax.
All short options except -v also have a long form listed.
Mandatory arguments are mandatory for both forms.
Run as a daemon. Logging to the console (stdout and stderr) is disabled. Sets -s and causes a PID file to be used.
Specify a different PID file than /var/run/peapod.pid, the default. Sets -d.
Specify a different config file than /etc/peapod.conf, the default.
A config file is required. See peapod.conf(5) for more details.
Test the config file and exit.
Enable logging to a log file. Optionally, specify a different log file than /var/log/peapod.log, the default.
Enable logging to syslog. Set automatically by -d and -p.
Increase log verbosity. Can be specified up to three times. Overridden by the verbosity option in the config file.
With -v, informational messages are also logged.
With -vv, so are debug messages.
With -vvv, so are low-level debug messages such as Ethernet frame hexdumps. (As these last are extremely voluble, they are logged only to the console and/or to a log file, and never to syslog.)
Treat script execution notices as informational, so that they are logged only if at least one -v was specified.
Colorize logging output to console.
Do not restart the proxy after certain errors occur, such as a configured interface going down unexpectedly.
The default error handling behavior once the proxy is running is to wait ten seconds between unlimited restart attempts.
/usr/sbin/peapod
/etc/peapod.conf
/var/log/peapod.log
/var/run/peapod.pid
Definitely. For suggestions, bug reports, contributions, pull requests, etc., please contact the author via the project page at https://github.com/kangtastic/peapod or via e-mail.
While not a bug per se, note that peapod's usefulness is greatly limited on MACsec-enabled networks.
kangtastic