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 "December 14, 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 [ \-\^\-vlan
\f[BI]IF_VLAN\fR]
.RB [ \-\^\-restart\-dhcp ]
.br
.RB [ \-\^\-set\-mac ]
.RB [ \-\^\-daemon ]
.RB [ \-\^\-pidfile
[[\f[BI]PIDFILE\fR]]
.RB [ \-\^\-syslog ]
.br
.RB [ \-\^\-promiscuous ]
.RB [ \-\^\-debug ]
.RB [ \-\^\-debug\-packets ]
.br
\f[BI]IF_WAN\fR
\f[BI]IF_ROUTER\fR
.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 (all others are optional)"
.TP
\f[BI]IF_WAN\fR
Interface to which the WAN uplink is connected.

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

See
.BR CONFIGURATION ,
.BR EXAMPLES ,
and
.BR interfaces (5)
for more information on how to configure a VLAN subinterface.
.TP
\f[BI]IF_ROUTER\fR
Interface to which the ISP router 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
.I IF_VLAN
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 VLAN subinterface on \f[BI]IF_WAN\fR"
.TP
.B \-\^\-vlan
\f[BI]IF_VLAN\fR
.br
VLAN ID or interface name of the VLAN subinterface on
.I IF_WAN
(e.g. \'0\', \'eth0.4\', 'vlan0\').
The value of
.I IF_VLAN
that is passed to
.B eap_proxy
is a hint to influence what it uses for
.I IF_VLAN
internally.
If
.B \-\^\-vlan
is specified,
both
.B \-\^\-vlan
and
.I IF_VLAN
must be specified together.
.I IF_VLAN
may be a VLAN ID number
(0 - 4094, inclusive),
a network interface name,
or \`none\`.

If
.I IF_VLAN
is specified as a VLAN ID number,
the system's VLAN configuration will be checked and the existing VLAN subinterface on
.I IF_WAN
with that VLAN ID will be used.
For example,
given that
.I IF_WAN
is
.BR eth0 ,
and
.I IF_VLAN
was specified as
.BR 2 ,
.B eap_proxy
will change the value of
.I IF_VLAN
that it uses internally to point to the correct VLAN subinterface for your system.
The existing VLAN subinterface on
.B eth0
with VLAN ID 2 could have been named
.BR eth0.2 ,
.BR eth0.0002 ,
.BR vlan2 ,
.BR vlan0002 ,
or perhaps even something else.

If
.I IF_VLAN
is specified as a network interface name,
the system's VLAN configuration will be checked and that network interface
will be used if it is an existing VLAN subinterface on
.IR IF_WAN .
For example,
given that
.I IF_WAN
is
.BR eth0 ,
.I IF_VLAN
was specified as
.BR eth0.0 ,
and
.B eth0.0
is actually present on the system,
.B eap_proxy
will use
.B eth0.0
as
.I IF_VLAN.

If
.I IF_VLAN
is specified as \'none\',
.B eap_proxy
will use
.I IF_WAN
directly as its internal value for
.IR IF_VLAN .

In the case that
.B \-\^\-vlan
is
.I NOT
specified at all,
.B eap_proxy
will behave by default as though it were called with
.B \-\^\-vlan
.BR 0 .
For example,
given that
.I IF_WAN
is
.BR eth0 ,
.B eap_proxy
will change the value of
.I IF_VLAN
that it uses internally to point to the VLAN subinterface on
.B eth0
with VLAN ID 0,
whether the system's name for it is
.BR eth0.0 ,
.BR eth0.0000 ,
.BR vlan0 ,
.BR vlan0000 ,
or something else.
However,
if no such subinterface exists,
this default for
.I IF_VLAN
will be treated as specified but invalid.

Finally,
in the error case that
.I IF_VLAN
is specified but invalid,
.B eap_proxy
will behave as though it were called with
.B \-\^\-vlan
.BR none ,
and use
.I IF_WAN
directly.

The addition of
.B \-\^\-vlan
is to accommodate the fact that although the majority of users
with routers set to use VLAN ID 0 appear to be able to successfully use
.B eap_proxy
with no VLAN at all,
some users have routers set to use a nonzero VLAN ID
and may still need to use a VLAN with a corresponding nonzero VLAN ID.
Configurations for older versions of
.B eap_proxy
that assumed the necessity and presence of
a VLAN with VLAN ID 0 will continue to be usable with no changes.
.TP
.B \-\^\-restart\-dhcp
Check whether WAN
(i.e.
.IR IF_VLAN )
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
.IR IF_VLAN .
.SS "Setting MAC address"
.TP
.B \-\^\-set\-mac
Set
.I IF_WAN
and
.IR IF_VLAN '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 instead of having
.B eap_proxy
do it for you.
.SS "Daemonization"
.TP
.B \-\^\-daemon
Become a daemon.
Implies
.BR \-\^\-syslog .
.TP
.B "\-\^\-pidfile \fR[\f[BI]PIDFILE\fR]"
.br
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 network interfaces connected to the WAN uplink
and the ISP router.
Most users will only need to edit these two lines in the configuration file.
.PP
Users who must use a VLAN subinterface of
.I IF_WAN
with a nonzero VLAN ID in order to successfully use
.B eap_proxy
will also need to specify the VLAN ID or interface name
by uncommenting and editing the
.B \-\^\-vlan
line.
.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
.I IF_WAN
and
.I IF_ROUTER
should be physical network interfaces for most users,
but more exotic setups in which they are bridges
(hopefully with a single port assigned)
are now possible.
There may also be a VLAN subinterface on
.I IF_WAN
that has VLAN ID 0 to match the behavior of most users' routers,
but a VLAN is not a requirement to use
.BR eap_proxy ,
with the probable exception of users whose routers are configured to use a nonzero VLAN ID.
.PP
For
.B \-\^\-restart\-dhcp
to work,
at least
.I IF_WAN
(and,
if present,
also
.IR IF_VLAN )
should not be managed by
.B NetworkManager
(which uses an internal DHCP client),
but in
.IR "/etc/network/interfaces" .
.I IF_WAN
(or,
if present,
.IR IF_VLAN ,
but not both)
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
.BR eth0 ,
.IP *
the interface to be used as
.I IF_ROUTER
is named
.BR eth1 ,
.IP *
a VLAN subinterface named
.B eth0.0
will be created and used as
.IR IF_VLAN ,
and
.IP *
the MAC address of the ISP router 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
as a subinterface on
.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
Now that definitions for the network interfaces are in
.IR /etc/network/interfaces ,
.B NetworkManager
is most likely disabled on them.
The MAC address set on
.B eth0
will be inherited by the VLAN subinterface
.BR eth0.0 .
.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
.BR 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
.PP
Because the VLAN ID of
.B eth0.0
is 0,
explicitly configuring it as
.I IF_VLAN
is not required.
.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 normally guesses parameters for the VLAN name type,
ID,
and raw interface from reading
.IR /etc/network/interfaces .

At this point,
the interface configuration in
.I /etc/network/interfaces
will probably result in a VLAN subinterface on
.B eth0
named
.BR eth0.0000 .

.B eap_proxy
now supports discovering and using this interface as
.B IF_VLAN
based on its VLAN ID of 0,
but if the automatic creation of a VLAN subinterface named
.B eth0.0
is desired instead,
it is necessary to also edit
.I /etc/network/if\-pre\-up.d/vlan
to supply the aforementioned parameters explicitly:
.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
.I IF_WAN
(or,
if used,
.IR IF_VLAN )
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.
.TP
.I /share/man/man1/eap_proxy.1.gz
This manual file.
.TP
.I /usr/sbin/eap_proxy
Program executable.

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