1PPPOE-SERVER(8) System Manager's Manual PPPOE-SERVER(8)
2
6 pppoe-server - user-space PPPoE server
7
9 pppoe-server [options]
10
13 pppoe-server is a user-space server for PPPoE (Point-to-Point Protocol
14 over Ethernet) for Linux and other UNIX systems. pppoe-server works in
15 concert with the pppoe client to respond to PPPoE discovery packets and
16 set up PPPoE sessions.
17
20 -F The -F option causes pppoe-server not to fork and become a dae‐
21 mon. The default is to fork and become a daemon.
22 -I interface
25 The -I option specifies the Ethernet interface to use. Under
26 Linux, it is typically eth0 or eth1. The interface should be
27 "up" before you start pppoe-server, but need not have an IP ad‐
28 dress. You can supply multiple -I options if you want the
29 server to respond on more than one interface.
30 -X pidfile
33 This option causes pppoe-server to write its process ID to pid‐
34 file. Additionally, it keeps the file locked so that only a
35 single process may be started for a given pidfile.
36 -q /path/to/pppd
39 Specifies the full path to the pppd program. The default is de‐
40 termined at compile time. One use of this option is to supply a
41 wrapper program that modifies the arguments passed to pppd.
42 This lets you do things not directly supported by the server
43 (for example, specify IPv6 addresses.)
44 -Q /path/to/pppoe
47 Specifies the full path to the pppoe program. The default is
48 determined at compile time. This option is only relevant if you
49 are not using kernel-mode PPPoE.
50 -T timeout
53 This option is passed directly to pppoe; see pppoe(8) for de‐
54 tails. If you are using kernel-mode PPPoE, this option has no
55 effect.
56 -C ac_name
59 Specifies which name to report as the access concentrator name.
60 If not supplied, the host name is used.
61 -S name
64 Offer a service named name. Multiple -S options may be speci‐
65 fied; each one causes the named service to be advertised in a
66 Service-Name tag in the PADO frame. The first -S option speci‐
67 fies the default service, and is used if the PPPoE client re‐
68 quests a Service-Name of length zero.
69 -m MSS This option is passed directly to pppoe; see pppoe(8) for de‐
72 tails. If you are using kernel-mode PPPoE, this option has no
73 effect.
74 -x n Limit the number of sessions per peer MAC address to n. If a
77 given MAC address attempts to create more than n sessions, then
78 its PADI and PADR packets are ignored. If you set n to 0 (the
79 default), then no limit is imposed on the number of sessions per
80 peer MAC address.
81 -s This option is passed directly to pppoe; see pppoe(8) for de‐
84 tails. In addition, it causes pppd to be invoked with the sync
85 option.
86 -L ip Sets the local IP address. This is passed to spawned pppd pro‐
89 cesses. If not specified, the default is 10.0.0.1. If speci‐
90 fied as 0.0.0.0 the selection of local IP address is delegated
91 to pppd.
92 -R ip Sets the starting remote IP address. As sessions are estab‐
95 lished, IP addresses are assigned starting from ip. pppoe-
96 server automatically keeps track of the pool of addresses and
97 passes a valid remote IP address to pppd. If not specified, a
98 starting address of 10.67.15.1 is used. If specified as 0.0.0.0
99 remote IP allocation will be delegated to pppd.
100 -N num Allows at most num concurrent PPPoE sessions. If not specified,
103 the default is 64.
104 -M string
107 Sends string in a MOTM tag in a PADM packet right after sending
108 the PADS to a client.
109 -H url Sends url in a HURL tag in a PADM packet right after sending the
112 PADS to a client. Note that url must start with either http://
113 or https://.
114 -O fname
117 This option causes pppoe-server to tell pppd to use the option
118 file fname instead of the default /etc/ppp/pppoe-server-options.
119 -p fname
122 Reads the specified file fname which is a text file consisting
123 of one IP address per line. These IP addresses will be assigned
124 to clients. The number of sessions allowed will equal the num‐
125 ber of addresses found in the file. The -p option overrides
126 both -R and -N.
127 In addition to containing IP addresses, the pool file can con‐
129 tain lines of the form:
130 a.b.c.d-e
132 which includes all IP addresses from a.b.c.d to a.b.c.e. For
134 example, the line:
135 1.2.3.4-7
137 is equivalent to:
139 1.2.3.4
141 1.2.3.5
142 1.2.3.6
143 1.2.3.7
144 -r Tells the PPPoE server to randomly permute session numbers. In‐
147 stead of handing out sessions in order, the session numbers are
148 assigned in an unpredictable order.
149 -u Tells the server to invoke pppd with the unit option. Note that
152 this option only works for pppd version 2.4.0 or newer.
153 -o offset
156 Instead of numbering PPPoE sessions starting at 1, they will be
157 numbered starting at offset+1. This allows you to run multiple
158 servers on a given machine; just make sure that their session
159 numbers do not overlap.
160 -f disc:sess
163 The -f option sets the Ethernet frame types for PPPoE discovery
164 and session frames. The types are specified as hexadecimal num‐
165 bers separated by a colon. Standard PPPoE uses frame types
166 8863:8864. You should not use this option unless you are abso‐
167 lutely sure the peer you are dealing with uses non-standard
168 frame types.
169 -k The -k option tells the server to use kernel-mode PPPoE on
172 Linux. This option is available only on Linux kernels 2.4.0 and
173 later, and only if the server was built with kernel-mode sup‐
174 port.
175 -g path
178 The -g option tells the server the full path to the pppoe.so or
179 rp-pppoe.so plugin to use with kernel-mode PPPoE. If omitted, a
180 compiled-in default is used; this default can be displayed using
181 the -h option.
182 -i The -i option tells the server to completely ignore PADI frames
185 if there are no free session slots.
186 -h The -h option prints a brief usage message and exits.
189 -U path
192 The -U option creates a UNIX socket which can be connected to in
193 order to manage pppoe-server at run-time. Please refer to the
194 CONTROL-SOCKET section below for more detailed instructions.
195
198 pppoe-server listens for incoming PPPoE discovery packets. When a ses‐
199 sion is established, it spawns a pppd process. The following options
200 are passed to pppd:
201 nodetach noaccomp nobsdcom nodeflate nopcomp novj novjccomp
203 default-asyncmap
204 In addition, the local and remote IP address are set based on the -L
206 and -R options. The pty option is supplied along with a pppoe command
207 to initiate the PPPoE session. Finally, additional pppd options can be
208 placed in the file /etc/ppp/pppoe-server-options (which must exist,
209 even if it is just empty!)
210 Note that pppoe-server is meant mainly for testing PPPoE clients. It
212 is not a high-performance server meant for production use.
213
216 The control-socket was implemented as a secondary mechanism to improve
217 run-time control of the pppoe-server. To use it you need to start pp‐
218 poe-server with the -U option described above. You can then (in the
219 absense of a control-client currently) use netcat to connect to the
220 control socket, for example:
221 nc -U /run/pppoe-server.control
223 Assuming -U /run/pppoe-server.control was passed to pppoe-server.
225 The following commands are implemented:
227 set drain {off|on|quit}
230 This will set whether or not pppoe-server responds to PADI pack‐
231 ets or not. When set to off pppoe-server will respond, else
232 PADI packets will be ignored. This allows the pppoe-server to
233 be drained from clients. In addition when set to quit will ter‐
234 minate pppoe-server when all pppoe-clients have terminated.
235 This allows for (mostly) seamless upgrades in that the currently
237 running instance can be issued with "set drain quit" prior to
238 starting a new interface on the same interfaces, thus allowing
239 new connections to be made whilst maintaining proper state on
240 existing clients.
241 show status
244 This will show basic status information for the connected-to pp‐
245 poe-server.
246
249 pppoe-server was written by Dianne Skoll <dianne@skoll.ca>.
250 The pppoe home page is https://dianne.skoll.ca/projects/rp-pppoe/.
252
255 pppd(8), pppoe(8), pppoe-sniff(8), pppoe-relay(8)
2564th Berkeley Distribution 21 June 2008 PPPOE-SERVER(8)