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.
"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.
Abilities surpassing those of a simple proxy include:
Proxy only certain kinds of packets between certain interfaces and execute user-defined scripts when proxying recognized packet types. This is supported for the nine EAPOL Packet Types defined by IEEE Std 802.1X-2010 and the four EAP Codes defined by IETF RFC 2284.
Add, modify, or remove priority tags in proxied EAPOL packets. (In fact, more than just the Priority Code Point field in the 802.1Q tag may be manipulated.)
Change interface MAC to a user-defined address, or to the address of an actual supplicant behind the proxy learned during runtime. This enables the device running peapod to masquerade as the supplicant and originate what appears to be authorized network traffic once the supplicant establishes an EAPOL session (as long as MACsec is not in use).
HTML versions: peapod(8), peapod.conf(5).
HTML version here (generated with doxygen).
Install the latest release for your system. 64-bit builds are also provided for the most popular Linux distributions.
Debian, Ubuntu, et al.:
$ wget -qO - https://kangtastic.github.io/peapod/pubkey.gpg | sudo apt-key add -
$ sudo apt-get install apt-transport-https
$ echo "deb https://kangtastic.github.io/peapod/apt amd64/" | sudo tee /etc/apt/sources.list.d/peapod.list
$ sudo apt-get update
$ sudo apt-get install peapod
RHEL, CentOS et al.:
$ sudo rpm -v --import https://kangtastic.github.io/peapod/pubkey.gpg
$ sudo yum-config-manager --add-repo https://kangtastic.github.io/peapod/rpm/x86_64/peapod.repo
$ sudo yum install peapod
Fedora et al.:
$ sudo rpm -v --import https://kangtastic.github.io/peapod/pubkey.gpg
$ sudo dnf config-manager --add-repo https://kangtastic.github.io/peapod/rpm/x86_64/peapod.repo
$ sudo dnf install peapod
See "Building from source."
Place a config file at /etc/peapod.conf, e.g.:
iface eth0;
iface eth1;
This is the minimum required config and silently proxies all EAPOL packets between eth0 and eth1.
See the manual pages for much more extensive documentation.
Start peapod:
$ sudo systemctl start peapod
Logs are saved to /var/log/peapod.log by default.
It may be helpful to refer to the log during initial setup to verify that peapod is doing its job. Log verbosity can be controlled by adding the following to the beginning of the config file:
verbosity N;
Here, N is 0, 1, 2, or 3. Verbosity is 0 by default.
Once everything is working properly, tell systemd to start peapod at boot:
$ sudo systemctl enable peapod
Prerequisites: recent-ish versions of Linux, systemd as the service manager, bison, flex, pkg-control, and, of course, gcc or similar.
$ make
$ sudo make install
$ make clean
$ sudo make uninstall
Prerequisite: a recent-ish version of doxygen.
$ make html
Also cleans any compiled files and existing source code documentation.
The result can be found at html/index.html in the program sources and will look like this.
$ make cleanhtml
This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
This package is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License along with this program. If not, see http://www.gnu.org/licenses/.