eap_proxy.1

.\" Process this file with
.\" groff -man -Tascii eap_proxy.1
.\" Pipe to col -bx to remove extra formatting from the page
.\"
.TH EAP_PROXY 1 "November 20, 2017" "eap_proxy" "EAP Proxy"
.SH NAME
eap_proxy \- EAP Proxy
.SH SYNOPSIS
.TP 10
.B eap_proxy
.RB [ \-h | \-\^\-help ]
.RB [ \-\^\-ping\-gateway ]
.RB [ \-\^\-ignore\-when\-wan\-up ]
.RB [ \-\^\-ignore\-start ]
.br
.RB [ \-\^\-ignore\-logoff ]
.RB [ \-\^\-restart\-dhcp ]
.RB [ \-\^\-set\-mac ]
.RB [ \-\^\-daemon ]
.br
.RB [ \-\^\-pidfile
.RI [[ PIDFILE ]]
.RB [ \-\^\-syslog ]
.RB [ \-\^\-promiscuous ]
.RB [ \-\^\-debug ]
.br
.RB [ \-\^\-debug\-packets ]
.br
.I IF_WAN
.I IF_ROUTER
.SH DESCRIPTION
.B eap_proxy
proxies 802.1X EAPOL
(Extensible Authentication Protocol over LAN)
frames between the Ethernet interfaces
.I IF_WAN
and
.IR IF_ROUTER .
.SH OPTIONS
.SS "Required options"
.TP
\f[BI]IF_WAN\fR
Physical interface to which the AT&T ONT/WAN is connected.

A VLAN named
.IR IF_WAN \.0
configured to get its IP address automatically via DHCP must also exist on it
(e.g. as
.B eth0\.0
on an interface named
.BR eth0 ).

See
.BR CONFIGURATION ,
.BR EXAMPLES ,
and
.BR interfaces (5)
for more information on how to configure a VLAN interface.
.TP
\f[BI]IF_ROUTER\fR
Physical interface to which the AT&T Residential Gateway is connected.
.SS "Help message"
.TP
.BR \-h ", " \-\^\-help
Print a help message.
.SS "Checking whether WAN is up"
.TP
.B \-\^\-ping\-gateway
Normally the WAN is considered up if
.IR IF_WAN \.0
has an IP address.
.br
This option additionally requires that
there is a default route gateway that responds to a ping.
.SS "Ignoring router packets"
.TP
.B \-\^\-ignore\-when\-wan\-up
Do not proxy any EAPOL traffic from the router
when the WAN is up (see
.BR \-\^\-ping\-gateway ).
.TP
.B \-\^\-ignore\-start
Always ignore
.B EAPOL\-Start
from the router.

A new device on a network with EAP access control
is not allowed to use the network for any non-EAP traffic.
To start the authentication process,
it replies with a
.B "EAP\-Response Identity"
packet to periodic
.B "EAP\-Request Identity"
transmissions made by an authenticator.
Although not required,
devices can also send
.B EAPOL\-Start
frames on their own to ask any available authenticator to immediately transmit
.BR "EAP\-Request Identity" .
.TP
.B \-\^\-ignore\-logoff
Always ignore
.B EAPOL\-Logoff
from the router.

Once a device sends
.BR EAPOL\-Logoff ,
it must authenticate again before using the network for any non-EAP traffic.
.SS "Configuring the \f[BI]IF_WAN\fR\fB\.0 VLAN interface\fR"
.TP
.B \-\^\-restart\-dhcp
Check whether WAN is up after receiving
.B EAP\-Success
on
.I IF_WAN
(see
.BR \-\^\-ping\-gateway ).
.br
If not,
restart the system's DHCP client on the
.IR IF_WAN \.0
VLAN interface.
.TP
.B \-\^\-set\-mac
Set
.IR IF_WAN \.0's
MAC (Ethernet) address to the router's MAC address.
.br
Matching MAC addresses is probably required,
but you may prefer to do it manually.
.SS "Daemonization"
.TP
.B \-\^\-daemon
Become a daemon.
Implies
.BR \-\^\-syslog .
.TP
.B \-\^\-pidfile
.RI [ PIDFILE ]
Record
.BR eap_proxy 's
process identifier to
.IR PIDFILE .
.br
If
.B \-\^\-pidfile
is given, but
.I PIDFILE
is not,
.I PIDFILE
will default to
.IR /var/run/eap_proxy.pid .
.TP
.B \-\^\-syslog
Log messages to
.B syslog
instead of to the standard error stream
.BR stderr .
.SS "Debugging"
.TP
.B \-\^\-promiscuous
Place the
.I IF_WAN
and
.I IF_ROUTER
interfaces into promiscuous mode instead of multicast mode.
.TP
.B \-\^\-debug
Enable debug-level logging.
.TP
.B \-\^\-debug\-packets
Print packets in a
.BR hexdump -like
format to assist with debugging.
Implies
.BR \-\^\-debug .
.SH CONFIGURATION
.PP
.B eap_proxy
is installed as a daemon.
An initscript is placed at
.I /etc/init.d/eap\-proxy
and a default configuration file at
.IR /etc/eap_proxy.conf .
The configuration file is not used by the proxy itself.
Instead,
the proxy is configured when it is launched by the initscript,
which parses the configuration file to pass on the proper options.
.PP
Note that the package and initscript are named
.BR eap\-proxy .
Everything else is named with an underscore as
.BR eap_proxy .
.SS \f[BI]/etc/eap_proxy.conf\fR
.PP
The default configuration file is a standard text file.
Each line contains one option or a comment.
Lines beginning with "\fB#\fR" are considered comments and will not be parsed.
.PP
The first two options
(lines that are not comments)
must contain
.I IF_WAN
and
.IR IF_ROUTER ,
the device names of the physical network interfaces connected to the AT&T ONT
and the AT&T Residential Gateway.
Most users will only need to edit these two lines in the configuration file.
.PP
If
.I PIDFILE
is specified in addition to
.BR \-\^\-pidfile ,
and
.I PIDFILE
contains spaces,
it must be enclosed in quotes.
.PP
If
.B eap_proxy
is run as a daemon via the initscript (or by
.BR systemd 's
.BR systemctl ,
which itself runs the initscript),
.B \-\^\-daemon
is implied and its setting in the configuration file is ignored.
.PP
See the
.B OPTIONS
section for more information about options.
.SS "Interfaces and VLAN"
.PP
Both
.I IF_WAN
and
.I IF_ROUTER
must be physical network interfaces.
There must also be a VLAN interface named
.IR IF_WAN \.0
on top of
.I IF_WAN
that has VLAN ID 0.
.PP
For
.B \-\^\-restart\-dhcp
to work,
at least
.I IF_WAN
and
.IR IF_WAN \.0
should be managed in
.I /etc/network/interfaces
instead of by
.BR NetworkManager ,
and
.IR IF_WAN \.0
should be configured to get its IP via DHCP.
.PP
For more information on configuring network interfaces,
VLANs, and DHCP,
see
.B EXAMPLES
and
.BR interfaces (5).
.SH "EXAMPLES"
.PP
These examples are for a system running a typical Debian-based Linux distribution,
and should be followed only with consideration for individual circumstances.
If everything is configured perfectly,
issuing
.B "sudo systemctl enable eap-proxy"
from a command line and restarting the system will fulfill various hopes and dreams.

Firewalling,
routing,
DNS,
IPv6,
VPNs,
and local DHCP assignments are beyond this document's scope.
.SS "Assumptions"
.IP *
The network interface to be used as
.I IF_WAN
is named
.B eth0
(implying that
.IR IF_WAN \.0
would be named
.BR eth0\.0 ),
.IP *
the interface to be used as
.I IF_ROUTER
is named
.BR eth1 ,
and
.IP *
the MAC address of the AT&T Residential Gateway is
.BR DE:AD:8B:AD:F0:0D .
.SS "Desired behavior"
.IP *
We would like to disable
.B NetworkManager
.SM (see
.SB Disabling
.SB NetworkManager
.SM below)
on
.B eth0
and
.BR eth1 ,
.IP *
change
.BR eth0 's
MAC address to
.BR DE:AD:8B:AD:F0:0D ,
.IP *
create a VLAN
.SM (see
.SB Creating
.SB VLANs
.SM below)
named
.B eth0\.0
on top of
.B eth0
with VLAN ID 0 that gets its IP via DHCP,
.IP *
and bring
.BR eth0 ,
.BR eth0\.0 ,
and
.B eth1
up automatically when the system starts.
.SS \f[BI]/etc/network/interfaces\fR
.PP
Place the following lines in
.IR /etc/network/interfaces .
.IP
.nf
\fBallow\-hotplug eth0
iface eth0 inet manual
        hwaddress de:ad:8b:ad:f0:0d

auto eth0.0
iface eth0.0 inet dhcp
        vlan\-raw\-device eth0

allow\-hotplug eth1
iface eth1 inet manual\fR
.fi
.PP
Some systems will hang for several minutes during boot while
.B eth0.0
tries and fails to get a DHCP assignment.
To fix this,
either edit the configuration file for your DHCP client
so that it uses a sane value for DHCP timeout,
and/or
(if using
.B systemd)
edit
.I /etc/systemd/system/network-online.target.wants
to do the same by adding something like
.B TimeoutStartSec=10sec
to the
.B [Service]
section.
.SS \f[BI]/etc/eap_proxy.conf\fR
.PP
Edit the first two noncommented lines in
.IR /etc/eap_proxy.conf ,
substituting the actual names of your interfaces.
.IP
.nf
.RI "[ " \.\.\. " ]"
# Required options

# IF_WAN
.B eth0

# IF_ROUTER
.B eth1
.RI "[ " \.\.\. " ]"
.fi
.SS "Disabling NetworkManager"
.PP
The surest way to stop using
.B NetworkManager
is to uninstall it.
It will also will not manage interfaces listed in
.IR /etc/network/interfaces ,
if the following is present (which is likely) in
.IR /etc/NetworkManager/NetworkManager.conf :
.IP
.nf
[main]
plugins=ifupdown,keyfile

[ifupdown]
.B managed=false
.fi
.SS "Creating VLANs"
.PP
VLAN support is provided by the
.B vlan
package.
VLAN autocreation is handled by the
.I /etc/network/if\-pre\-up.d/vlan
script,
which will almost certainly need to be edited to add a special case for
.IR IF_WAN \.0,
explicitly specifying the parameters that it normally guesses from reading
.I /etc/network/interfaces
for the VLAN name type, ID, and underlying interface:
.IP
.nf
case "$IFACE" in
.RI "  [ " \.\.\. " ]"
  \fB# for eap_proxy: special case to create eth0.0 properly
  eth0.0)
    vconfig set_name_type DEV_PLUS_VID_NO_PAD
    VLANID=0
    IF_VLAN_RAW_DEVICE=eth0
  ;;\fR
.RI "  [ " \.\.\. " ]"
.fi
.SH USAGE
.PP
The preferred method of running
.B eap_proxy
is through
.B systemd
by issuing
.B "sudo systemctl start eap-proxy"
from the command line.
.PP
Issue
.B "sudo systemctl stop eap-proxy"
to stop the proxy.
.PP
Issue
.B "sudo systemctl enable eap-proxy"
to make the proxy run at every boot.
.PP
Directly call the proxy from the command line by issuing
.BR eap_proxy " [" options "]."
.PP
Issue
.B "man eap_proxy"
to read the manual page.
.PP
Setting up routing between
.IR IF_WAN \.0
and another network interface is likely the next step,
but will be left as an exercise for the reader.
.PP
See the
.B CONFIGURATION
and
.B EXAMPLES
sections for more information.

.SH FILES
.TP
.I /etc/eap_proxy.conf
Default configuration file. See
.B CONFIGURATION
and
.B EXAMPLES
for more information.
.TP
.I /etc/init.d/eap-proxy
Default initscript.
See
.B CONFIGURATION
for more information.
.SH ERRATA
The package and initscript are named
.BR eap\-proxy .

Everything else is named with an underscore as
.BR eap_proxy .

An initscript is used instead of a modern systemd .service file to parse
.I /etc/eap_proxy.conf
and pass on the correct options to the proxy.
(Backward compatibility,
too,
for what that's worth.)
.SH AUTHOR
Jay Soffian <jaysoffian@gmail.com> (original)

kangtastic <kangscinate@gmail.com> (modifications, documentation, and packaging for Debian)
.SH "SEE ALSO"
.BR interfaces (5)