forked from jaysoffian/eap_proxy
-
Notifications
You must be signed in to change notification settings - Fork 3
/
Copy pathREADME
368 lines (281 loc) · 14.4 KB
/
README
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
EAP_PROXY(1) EAP Proxy EAP_PROXY(1)
NAME
eap_proxy - EAP Proxy
SYNOPSIS
eap_proxy [-h] [--ping-gateway] [--ignore-when-wan-up] [--ignore-start]
[--ignore-logoff] [--vlan IF_VLAN] [--restart-dhcp]
[--set-mac] [--daemon] [--pidfile [[PIDFILE]] [--syslog]
[--promiscuous] [--debug] [--debug-packets]
IF_WAN IF_ROUTER
DESCRIPTION
eap_proxy proxies 802.1X EAPOL (Extensible Authentication Protocol over
LAN) frames between the Ethernet interfaces IF_WAN and IF_ROUTER.
OPTIONS
Required options (all others are optional)
IF_WAN 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 eth0.0 or vlan0 on an interface
named eth0).
See CONFIGURATION, EXAMPLES, and interfaces(5) for more informa‐
tion on how to configure a VLAN subinterface.
IF_ROUTER
Interface to which the ISP router is connected.
Help message
-h, --help
Print a help message.
Checking whether WAN is up
--ping-gateway
Normally the WAN is considered up if IF_VLAN has an IP address.
This option additionally requires that there is a default route
gateway that responds to a ping.
Ignoring router packets
--ignore-when-wan-up
Do not proxy any EAPOL traffic from the router when the WAN is up
(see --ping-gateway).
--ignore-start
Always ignore 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 authen‐
tication process, it replies with a EAP-Response Identity packet
to periodic EAP-Request Identity transmissions made by an authen‐
ticator. Although not required, devices can also send
EAPOL-Start frames on their own to ask any available authentica‐
tor to immediately transmit EAP-Request Identity.
--ignore-logoff
Always ignore EAPOL-Logoff from the router.
Once a device sends EAPOL-Logoff, it must authenticate again
before using the network for any non-EAP traffic.
Configuring the VLAN subinterface on IF_WAN
--vlan IF_VLAN
VLAN ID or interface name of the VLAN subinterface on IF_WAN
(e.g. ´0´, ´eth0.4´, 'vlan0´). The value of IF_VLAN that is
passed to eap_proxy is a hint to influence what it uses for
IF_VLAN internally. If --vlan is specified, both --vlan and
IF_VLAN must be specified together. IF_VLAN may be a VLAN ID
number (0 - 4094, inclusive), a network interface name, or
`none`.
If IF_VLAN is specified as a VLAN ID number, the system's VLAN
configuration will be checked and the existing VLAN subinterface
on IF_WAN with that VLAN ID will be used. For example, given
that IF_WAN is eth0, and IF_VLAN was specified as 2, eap_proxy
will change the value of IF_VLAN that it uses internally to point
to the correct VLAN subinterface for your system. The existing
VLAN subinterface on eth0 with VLAN ID 2 could have been named
eth0.2, eth0.0002, vlan2, vlan0002, or perhaps even something
else.
If 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 IF_WAN.
For example, given that IF_WAN is eth0, IF_VLAN was specified as
eth0.0, and eth0.0 is actually present on the system, eap_proxy
will use eth0.0 as IF_VLAN.
If IF_VLAN is specified as ´none´, eap_proxy will use IF_WAN
directly as its internal value for IF_VLAN.
In the case that --vlan is NOT specified at all, eap_proxy will
behave by default as though it were called with --vlan 0. For
example, given that IF_WAN is eth0, eap_proxy will change the
value of IF_VLAN that it uses internally to point to the VLAN
subinterface on eth0 with VLAN ID 0, whether the system's name
for it is eth0.0, eth0.0000, vlan0, vlan0000, or something else.
However, if no such subinterface exists, this default for IF_VLAN
will be treated as specified but invalid.
Finally, in the error case that IF_VLAN is specified but invalid,
eap_proxy will behave as though it were called with --vlan none,
and use IF_WAN directly.
The addition of --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 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. Config‐
urations for older versions of eap_proxy that assumed the neces‐
sity and presence of a VLAN with VLAN ID 0 will continue to be
usable with no changes.
--restart-dhcp
Check whether WAN (i.e. IF_VLAN) is up after receiving EAP-Suc‐
cess on IF_WAN (see --ping-gateway).
If not, restart the system's DHCP client on IF_VLAN.
Setting MAC address
--set-mac
Set IF_WAN and IF_VLAN's MAC (Ethernet) address to the router's
MAC address.
Matching MAC addresses is probably required, but you may prefer
to do it manually instead of having eap_proxy do it for you.
Daemonization
--daemon
Become a daemon. Implies --syslog.
--pidfile [PIDFILE]
Record eap_proxy's process identifier to PIDFILE.
If --pidfile is given, but PIDFILE is not, PIDFILE will default
to /var/run/eap_proxy.pid.
--syslog
Log messages to syslog instead of to the standard error stream
stderr.
Debugging
--promiscuous
Place the IF_WAN and IF_ROUTER interfaces into promiscuous mode
instead of multicast mode.
--debug
Enable debug-level logging.
--debug-packets
Print packets in a hexdump-like format to assist with debugging.
Implies --debug.
CONFIGURATION
eap_proxy is installed as a daemon. An initscript is placed at
/etc/init.d/eap-proxy and a default configuration file at
/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.
Note that the package and initscript are named eap-proxy. Everything
else is named with an underscore as eap_proxy.
/etc/eap_proxy.conf
The default configuration file is a standard text file. Each line con‐
tains one option or a comment. Lines beginning with "#" are considered
comments and will not be parsed.
The first two options (lines that are not comments) must contain IF_WAN
and 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.
Users who must use a VLAN subinterface of IF_WAN with a nonzero VLAN ID
in order to successfully use eap_proxy will also need to specify the
VLAN ID or interface name by uncommenting and editing the --vlan line.
If PIDFILE is specified in addition to --pidfile, and PIDFILE contains
spaces, it must be enclosed in quotes.
If eap_proxy is run as a daemon via the initscript (or by systemd's sys‐
temctl, which itself runs the initscript), --daemon is implied and its
setting in the configuration file is ignored.
See the OPTIONS section for more information about options.
Interfaces and VLAN
IF_WAN and 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 IF_WAN that has VLAN ID 0 to match the behavior of most
users' routers, but a VLAN is not a requirement to use eap_proxy, with
the probable exception of users whose routers are configured to use a
nonzero VLAN ID.
For --restart-dhcp to work, at least IF_WAN (and, if present, also
IF_VLAN) should not be managed by NetworkManager (which uses an internal
DHCP client), but in /etc/network/interfaces. IF_WAN (or, if present,
IF_VLAN, but not both) should be configured to get its IP via DHCP.
For more information on configuring network interfaces, VLANs, and DHCP,
see EXAMPLES and interfaces(5).
EXAMPLES
These examples are for a system running a typical Debian-based Linux
distribution, and should be followed only with consideration for indi‐
vidual circumstances. If everything is configured perfectly, issuing
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.
Assumptions
* The network interface to be used as IF_WAN is named eth0,
* the interface to be used as IF_ROUTER is named eth1,
* a VLAN subinterface named eth0.0 will be created and used as
IF_VLAN, and
* the MAC address of the ISP router is DE:AD:8B:AD:F0:0D.
Desired behavior
* We would like to disable NetworkManager (see Disabling Network‐
Manager below) on eth0 and eth1,
* change eth0's MAC address to DE:AD:8B:AD:F0:0D,
* create a VLAN (see Creating VLANs below) named eth0.0 as a subin‐
terface on eth0 with VLAN ID 0 that gets its IP via DHCP,
* and bring eth0, eth0.0, and eth1 up automatically when the system
starts.
/etc/network/interfaces
Place the following lines in /etc/network/interfaces.
allow-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
Now that definitions for the network interfaces are in /etc/net‐
work/interfaces, NetworkManager is most likely disabled on them. The
MAC address set on eth0 will be inherited by the VLAN subinterface
eth0.0.
Some systems will hang for several minutes during boot while 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 systemd) edit /etc/systemd/system/net‐
work-online.target.wants to do the same by adding something like Time‐
outStartSec=10sec to the [Service] section.
/etc/eap_proxy.conf
Edit the first two noncommented lines in /etc/eap_proxy.conf, substitut‐
ing the actual names of your interfaces.
[ ... ]
# Required options
# IF_WAN
eth0
# IF_ROUTER
eth1
[ ... ]
Because the VLAN ID of eth0.0 is 0, explicitly configuring it as IF_VLAN
is not required.
Disabling NetworkManager
The surest way to stop using NetworkManager is to uninstall it. It will
also will not manage interfaces listed in /etc/network/interfaces, if
the following is present (which is likely) in /etc/NetworkManager/Net‐
workManager.conf:
[main]
plugins=ifupdown,keyfile
[ifupdown]
managed=false
Creating VLANs
VLAN support is provided by the vlan package.
VLAN autocreation is handled by the /etc/network/if-pre-up.d/vlan
script, which normally guesses parameters for the VLAN name type, ID,
and raw interface from reading /etc/network/interfaces.
At this point, the interface configuration in /etc/network/interfaces
will probably result in a VLAN subinterface on eth0 named eth0.0000.
eap_proxy now supports discovering and using this interface as IF_VLAN
based on its VLAN ID of 0, but if the automatic creation of a VLAN
subinterface named eth0.0 is desired instead, it is necessary to also
edit /etc/network/if-pre-up.d/vlan to supply the aforementioned parame‐
ters explicitly:
case "$IFACE" in
[ ... ]
# 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
;;
[ ... ]
USAGE
The preferred method of running eap_proxy is through systemd by issuing
sudo systemctl start eap-proxy from the command line.
Issue sudo systemctl stop eap-proxy to stop the proxy.
Issue sudo systemctl enable eap-proxy to make the proxy run at every
boot.
Directly call the proxy from the command line by issuing eap_proxy
[options].
Issue man eap_proxy to read the manual page.
Setting up routing between IF_WAN (or, if used, IF_VLAN) and another
network interface is likely the next step, but will be left as an exer‐
cise for the reader.
See the CONFIGURATION and EXAMPLES sections for more information.
FILES
/etc/eap_proxy.conf
Default configuration file. See CONFIGURATION and EXAMPLES for
more information.
/etc/init.d/eap-proxy
Default initscript. See CONFIGURATION for more information.
/share/man/man1/eap_proxy.1.gz
This manual file.
/usr/sbin/eap_proxy
Program executable.
ERRATA
The package and initscript are named eap-proxy.
Everything else is named with an underscore as eap_proxy.
An initscript is used instead of a modern systemd .service file to parse
/etc/eap_proxy.conf and pass on the correct options to the proxy.
(Backward compatibility, too, for what that's worth.)
AUTHOR
Jay Soffian <jaysoffian@gmail.com> (original)
kangtastic <kangscinate@gmail.com> (modifications, documentation, and
packaging for Debian)
SEE ALSO
interfaces(5)
eap_proxy December 14, 2017 EAP_PROXY(1)