peapod - EAPOL Proxy Daemon

• Overview
  • EAPOL/EAP classification, filtering, and script execution
  • VLAN priority tag handling
  • MAC spoofing
• Getting started
  • Documentation
    • Manual pages
    • Source code documentation
  • Installation
    • apt
    • rpm
    • Sources
  • Configuration
    • Bare minimum
    • Anything more
  • Usage
• Building from source
  • Executable, man pages, examples, and systemd unit file
    • Build and install
    • Clean and uninstall
  • Source code documentation
    • Build
    • Clean
• Legal

Overview

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:

EAPOL/EAP classification, filtering, and script execution

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.

VLAN priority tag handling

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.)

MAC spoofing

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).

Getting started

Documentation

Manual pages

HTML versions: peapod(8), peapod.conf(5).

Source code documentation

HTML version here (generated with doxygen).

Installation

Install the latest release for your system. 64-bit builds are also provided for the most popular Linux distributions.

apt

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

rpm

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

Sources

See "Building from source."

Configuration

Bare minimum

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.

Anything more

See the manual pages for much more extensive documentation.

Usage

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

Building from source

Prerequisites: recent-ish versions of Linux, systemd as the service manager, bison, flex, pkg-control, and, of course, gcc or similar.

Executable, man pages, examples, and systemd unit file

Build and install

$ make
$ sudo make install

Clean and uninstall

$ make clean
$ sudo make uninstall

Source code documentation

Prerequisite: a recent-ish version of doxygen.

Build

$ 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.

Clean

$ make cleanhtml

Legal

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/.