1PPPOE-SERVER(8) System Manager's Manual PPPOE-SERVER(8)
2
3
4
6 pppoe-server - user-space PPPoE server
7
9 pppoe-server [options]
10
11
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
18
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
23
24 -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
31
32 -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
37
38 -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
45
46 -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
51
52 -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
57
58 -C ac_name
59 Specifies which name to report as the access concentrator name.
60 If not supplied, the host name is used.
61
62
63 -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
70
71 -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
75
76 -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
82
83 -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
87
88 -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
93
94 -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
101
102 -N num Allows at most num concurrent PPPoE sessions. If not specified,
103 the default is 64.
104
105
106 -M string
107 Sends string in a MOTM tag in a PADM packet right after sending
108 the PADS to a client.
109
110
111 -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
115
116 -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
120
121 -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
128 In addition to containing IP addresses, the pool file can con‐
129 tain lines of the form:
130
131 a.b.c.d-e
132
133 which includes all IP addresses from a.b.c.d to a.b.c.e. For
134 example, the line:
135
136 1.2.3.4-7
137
138 is equivalent to:
139
140 1.2.3.4
141 1.2.3.5
142 1.2.3.6
143 1.2.3.7
144
145
146 -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
150
151 -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
154
155 -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
161
162 -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
170
171 -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
176
177 -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
183
184 -i The -i option tells the server to completely ignore PADI frames
185 if there are no free session slots.
186
187
188 -h The -h option prints a brief usage message and exits.
189
190
191 -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
196
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
202 nodetach noaccomp nobsdcom nodeflate nopcomp novj novjccomp
203 default-asyncmap
204
205 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
211 Note that pppoe-server is meant mainly for testing PPPoE clients. It
212 is not a high-performance server meant for production use.
213
214
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
222 nc -U /run/pppoe-server.control
223
224 Assuming -U /run/pppoe-server.control was passed to pppoe-server.
225
226 The following commands are implemented:
227
228
229 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
236 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
242
243 show status
244 This will show basic status information for the connected-to pp‐
245 poe-server.
246
247
249 pppoe-server was written by Dianne Skoll <dianne@skoll.ca>.
250
251 The pppoe home page is https://dianne.skoll.ca/projects/rp-pppoe/.
252
253
255 pppd(8), pppoe(8), pppoe-sniff(8), pppoe-relay(8)
256
257
258
259
2604th Berkeley Distribution 21 June 2008 PPPOE-SERVER(8)