| blob | 23ae9bcd9f87e4a2481c5889a1d2939f577058c4 |
1 '\" te
2 .\" Copyright (C) 2003, Sun Microsystems, Inc. All Rights Reserved
3 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License.
4 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License.
5 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
6 .TH PPPOED 8 "Jan 6, 2003"
7 .SH NAME
8 pppoed \- PPPoE server daemon
9 .SH SYNOPSIS
10 .LP
11 .nf
12 \fBppoed\fR [\fIoptions\fR]
13 .fi
15 .SH DESCRIPTION
16 .sp
17 .LP
18 The \fBpppoed\fR daemon implements the server-side negotiation of PPPoE. When a
19 client requests service from this daemon, a copy of \fBpppd\fR(8) is invoked
20 to handle the actual PPP communication.
21 .sp
22 .LP
23 At startup, options are read from the command line and the \fB/etc/ppp/pppoe\fR
24 file. After these options have been read, options in the per-device
25 \fB/etc/ppp/pppoe.\fIdevice\fR\fR files are read, using the device names
26 specified on the command line or in \fB/etc/ppp/pppoe\fR. Device names are not
27 permitted in the per-device files. It is not an error if any of these files are
28 absent; missing files are ignored.
29 .sp
30 .LP
31 Options are reread in the same order on \fBSIGHUP\fR. Except for the
32 possibility of short delays due to the processing time, \fBSIGHUP\fR does not
33 interfere with any client operations. Current status, including options read,
34 is dumped to \fB/tmp/pppoed.\fIpid\fR\fR on \fBSIGINT\fR.
35 .sp
36 .LP
37 The options are used to set up a list of services to be offered to PPPoE
38 clients on the broadcast domains (Ethernet subnets) specified by the named
39 devices. Option parsing is always in one of two modes, either global mode or
40 service mode. The initial mode at the beginning of each file (and the command
41 line) is global mode. Options specified in global mode serve as default values
42 for subsequently defined services. Service mode is entered by the \fBservice\fR
43 \fIname\fR option. In this mode, the named option is defined. Options that
44 appear in this mode override any global mode definitions for the current
45 service.
46 .sp
47 .LP
48 The option parsing follows standard shell tokenizing rules, using whitespace to
49 delimit tokens, quotes to enclose strings that can contain whitespace, and
50 escape sequences for special characters. Environment variables are substituted
51 using familiar \fB$VAR\fR and \fB${VAR}\fR syntax and set using
52 \fBNEWVAR=\fIstring\fR\fR. Variables are both usable in subsequent options and
53 provided to the \fBpppd\fR(8) processes spawned for each client, but they are
54 interpreted as they are encountered during option processing. Thus, all set
55 variables are seen by all processes spawned; position in the configuration
56 files has no effect on this.
57 .SH OPTIONS
58 .sp
59 .LP
60 The \fBpppoed\fR daemon supports the following options:
61 .sp
62 .ne 2
63 .na
64 \fB\fBclient\fR [\fBexcept\fR] \fIclient-list\fR\fR
65 .ad
66 .sp .6
67 .RS 4n
68 This option restricts the clients that may receive the service. If the
69 \fBexcept\fR keyword is given, then the clients on the list cannot access the
70 service, but others can. If this keyword is not given, then only the listed
71 clients can access the service.
72 .sp
73 This option can be specified more than once for a given service. For a given
74 client, first match among all listed options encountered specifies the
75 handling. If it matches an option with \fBexcept\fR specified, then access is
76 denied. Otherwise, it is granted. The \fBclient\fR list within a service is
77 prepended to any list specified in the global context.
78 .sp
79 If no \fBclient\fR options are given or if all options are specified with
80 \fBexcept\fR, then all clients are permitted by default. If any \fBclient\fR
81 options without \fBexcept\fR are specified, then no clients are permitted by
82 default.
83 .sp
84 The \fIclient-list\fR is a comma-separated list of client identifiers. The
85 match is made if any client on the list matches; thus, these are logically
86 "ORed" together. Each client identifier can be either a symbolic name (resolved
87 through \fB/etc/ethers\fR or NIS, as defined by \fB/etc/nsswitch.conf\fR) or a
88 hexadecimal Ethernet address in the format \fBx:x:x:x:x:x\fR. In the latter
89 case, any byte of the address can be "\fB*\fR", which matches any value in that
90 position. For example, \fB40:0:1a:*:*:*\fR matches Ethernet adapters from the
91 manufacturer assigned block \fB40:0:1a\fR.
92 .RE
94 .sp
95 .ne 2
96 .na
97 \fB\fBdebug\fR\fR
98 .ad
99 .sp .6
100 .RS 4n
101 Increase debug logging detail level by one. The detail levels are 0 (no
102 logging), 1 (errors only; the default), 2 (warnings), 3 (informational
103 messages), and 4 (debug messages). Log messages are written by default to
104 \fBsyslog\fR(3C) using facility \fIdaemon\fR (see the \fBlog\fR option below).
105 When specified on the command line or in the global context of the
106 \fB/etc/ppp/pppoe\fR file, this option also sets the daemon's default
107 (non-service-related) detail level.
108 .RE
110 .sp
111 .ne 2
112 .na
113 \fB\fBdevice\fR \fIdevice-list\fR\fR
114 .ad
115 .sp .6
116 .RS 4n
117 Specify the devices on which the service is available. The \fIdevice-list\fR is
118 a comma-separated list of logical device names (without the leading
119 \fB/dev/\fR), such as \fBhme0\fR. This option is ignored if encountered in the
120 per-device \fB/etc/ppp/pppoe.\fIdevice\fR\fR files.
121 .RE
123 .sp
124 .ne 2
125 .na
126 \fB\fBextra\fR \fIstring\fR\fR
127 .ad
128 .sp .6
129 .RS 4n
130 Specifies extra options to \fBpppd\fR(8). It defaults to "\fBplugin pppoe.so
131 directtty\fR" and usually does not need to be overridden.
132 .RE
134 .sp
135 .ne 2
136 .na
137 \fB\fBfile\fR \fIpath\fR\fR
138 .ad
139 .sp .6
140 .RS 4n
141 Suspends parsing of the current file, returns to global mode, and reads options
142 from \fIpath\fR. This file must be present and readable; if it is not, an error
143 is logged. When the end of that file is reached, processing returns to the
144 current file and the mode is reset to global again.
145 .sp
146 The global mode options specified in files read by this command use the options
147 set in the current file's global mode; this condition extends to any file
148 included by those files. All files read are parsed as though the command line
149 had specified this option, and thus inherit the command line's global modes.
150 .sp
151 This option can be used to revert to global mode at any point in an option file
152 by specifying \fBfile /dev/null\fR.
153 .RE
155 .sp
156 .ne 2
157 .na
158 \fB\fBgroup\fR \fIname\fR\fR
159 .ad
160 .sp .6
161 .RS 4n
162 Specifies the group ID (symbolic or numeric) under which \fBpppd\fR is
163 executed. If \fBpppoed\fR is not run as root, this option is ignored.
164 .RE
166 .sp
167 .ne 2
168 .na
169 \fB\fBlog\fR \fIpath\fR\fR
170 .ad
171 .sp .6
172 .RS 4n
173 Specifies an alternate debug logging file. Debug messages are sent to this file
174 instead of \fBsyslog\fR. The special name \fBsyslog\fR is recognized to switch
175 logging back to \fBsyslog\fR. When specified on the command line or in the
176 global context of the \fB/etc/ppp/pppoe\fR file, this option also sets the
177 daemon's default (non-service-related) log file.
178 .RE
180 .sp
181 .ne 2
182 .na
183 \fB\fBnodebug\fR\fR
184 .ad
185 .sp .6
186 .RS 4n
187 Set debug logging detail level to 0 (no logging). When specified on the command
188 line or in the global context of the \fB/etc/ppp/pppoe\fR file, this option
189 also sets the daemon's default (non-service-related) detail level.
190 .RE
192 .sp
193 .ne 2
194 .na
195 \fB\fBnowildcard\fR\fR
196 .ad
197 .sp .6
198 .RS 4n
199 Specifies that the current service should not be included in response to
200 clients requesting "any" service. The client must ask for this service by name.
201 When specified on the command line or in the global context of the
202 \fB/etc/ppp/pppoe\fR file, this option causes \fBpppoed\fR to ignore all
203 wildcard service requests.
204 .RE
206 .sp
207 .ne 2
208 .na
209 \fB\fBpath\fR \fIpath\fR\fR
210 .ad
211 .sp .6
212 .RS 4n
213 Specifies the path to the \fBpppd\fR executable. Defaults to
214 \fB/usr/bin/pppd\fR.
215 .RE
217 .sp
218 .ne 2
219 .na
220 \fB\fBpppd\fR \fIstring\fR\fR
221 .ad
222 .sp .6
223 .RS 4n
224 Passes command-line arguments to \fBpppd\fR. It can be used to set the IP
225 addresses or configure security for the session. The default value is the empty
226 string.
227 .RE
229 .sp
230 .ne 2
231 .na
232 \fB\fBserver\fR \fIstring\fR\fR
233 .ad
234 .sp .6
235 .RS 4n
236 Specifies the PPPoE Access Concentrator name to be sent to the client. It
237 defaults to "Solaris PPPoE".
238 .RE
240 .sp
241 .ne 2
242 .na
243 \fB\fBservice\fR \fIname\fR\fR
244 .ad
245 .sp .6
246 .RS 4n
247 Closes any service being defined and begins definition of a new service. The
248 same service name can be used without conflict on multiple devices. If the same
249 service name is used on a single device, then the last definition encountered
250 during parsing overrides all previous definitions.
251 .RE
253 .sp
254 .ne 2
255 .na
256 \fB\fBuser\fR \fIname\fR\fR
257 .ad
258 .sp .6
259 .RS 4n
260 Specifies the user ID, symbolic or numeric, under which \fBpppd\fR is executed.
261 If \fBpppoed\fR is not run as root, this option is ignored.
262 .RE
264 .sp
265 .ne 2
266 .na
267 \fB\fBwildcard\fR\fR
268 .ad
269 .sp .6
270 .RS 4n
271 Specifies that the service should be included in responses to client queries
272 that request "any" service, which is done by requesting a service name of
273 length zero. When specified on the command line or in the global context of the
274 \fB/etc/ppp/pppoe\fR file, this option causes \fBpppoed\fR to ignore all
275 wildcard service requests. This is the default.
276 .RE
278 .SH EXAMPLES
279 .LP
280 \fBExample 1 \fRConfiguring for Particular Services
281 .sp
282 .LP
283 In the \fB/etc/ppp/pppoe\fR file:
285 .sp
286 .in +2
287 .nf
288 service internet
289 device $DEV
290 pppd "proxyarp 192.168.1.1:"
291 service debugging
292 device hme0,$DEV
293 pppd "debug proxyarp 192.168.1.1:"
294 .fi
295 .in -2
297 .sp
298 .LP
299 You then invoke the daemon with:
301 .sp
302 .in +2
303 .nf
304 example% \fB/usr/lib/inet/pppoed DEV=eri0\fR
305 .fi
306 .in -2
307 .sp
309 .sp
310 .LP
311 The lines in \fB/etc/ppp/pppoe\fR and the preceding command result in offering
312 services "internet" and "debugging" (and responding to wildcard queries) on
313 interface \fBeri0\fR, and offering only service "debugging" on interface
314 \fBhme0\fR.
316 .SH SIGNALS
317 .sp
318 .LP
319 The \fBpppoed\fR daemon responds to the following signals:
320 .sp
321 .ne 2
322 .na
323 \fB\fBSIGHUP\fR\fR
324 .ad
325 .RS 10n
326 Causes \fBpppoed\fR to reparse the original command line and all configuration
327 files, and close and reopen any log files.
328 .RE
330 .sp
331 .ne 2
332 .na
333 \fB\fBSIGINT\fR\fR
334 .ad
335 .RS 10n
336 Causes a snapshot of the state of the \fBpppoed\fR daemon to be written to
337 \fB/tmp/pppoed.\fIpid\fR\fR (where \fIpid\fR is the decimal process ID of the
338 daemon).
339 .RE
341 .SH FILES
342 .sp
343 .ne 2
344 .na
345 \fB\fB/usr/lib/inet/pppoed\fR \fR
346 .ad
347 .RS 25n
348 executable command
349 .RE
351 .sp
352 .ne 2
353 .na
354 \fB\fB/dev/sppptun\fR\fR
355 .ad
356 .RS 25n
357 Solaris PPP tunneling device driver
358 .RE
360 .sp
361 .ne 2
362 .na
363 \fB\fB/etc/ppp/pppoe\fR\fR
364 .ad
365 .RS 25n
366 main configuration option file
367 .RE
369 .sp
370 .ne 2
371 .na
372 \fB\fB/etc/ppp/pppoe.\fIdevice\fR\fR\fR
373 .ad
374 .RS 25n
375 per-device configuration option file
376 .RE
378 .sp
379 .ne 2
380 .na
381 \fB\fB/etc/ppp/pppoe-errors\fR\fR
382 .ad
383 .RS 25n
384 location of output from \fBpppd\fR's stderr
385 .RE
387 .sp
388 .ne 2
389 .na
390 \fB\fB/etc/ppp/pppoe.if\fR\fR
391 .ad
392 .RS 25n
393 list of Ethernet interfaces to be plumbed at boot time
394 .RE
396 .sp
397 .ne 2
398 .na
399 \fB\fB/tmp/pppoed.\fIpid\fR\fR\fR
400 .ad
401 .RS 25n
402 ASCII text file containing dumped \fBpppoed\fR state information
403 .RE
405 .SH SEE ALSO
406 .sp
407 .LP
408 \fBpppd\fR(8), \fBpppoec\fR(8), \fBsppptun\fR(8), \fBsppptun\fR(7M)
409 .sp
410 .LP
411 Mamakos, L., et al. \fIRFC 2516, A Method for Transmitting PPP Over Ethernet
412 (PPPoE)\fR. Network Working Group. February 1999
413 .SH NOTES
414 .sp
415 .LP
416 Because \fBpppd\fR is installed setuid root, this daemon need not be run as
417 root. However, if it is not run as root, the \fBuser\fR and \fBgroup\fR options
418 are ignored.
419 .sp
420 .LP
421 The Ethernet interfaces to be used must be plumbed for PPPoE using the
422 \fBsppptun\fR(8) utility before services can be offered.
423 .sp
424 .LP
425 The daemon operate runs even if there are no services to offer. If you want to
426 modify a configuration, it is not necessary to terminate the daemon. Simply use
427 \fBpkill \fR\fB-HUP\fR\fB pppoed\fR after updating the configuration files.
428 .sp
429 .LP
430 The PPPoE protocol is far from perfect. Because it runs directly over Ethernet,
431 there is no possibility of security and the MTU is limited to 1492 (violating
432 RFC 1661's default value of 1500). It is also not possible to run the client
433 and the server of a given session on a single machine with a single Ethernet
434 interface for testing purposes. The client and server portions of a single
435 session must be run on separate Ethernet interfaces with different MAC
436 addresses.