path: root/usr/src/man/man8/pppoed.8

'\" te
.\" Copyright (C) 2003, Sun Microsystems, Inc. All Rights Reserved
.\" 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.
.\" 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.
.\" 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]
.TH PPPOED 8 "Jan 6, 2003"
.SH NAME
pppoed \- PPPoE server daemon
.SH SYNOPSIS
.LP
.nf
\fBppoed\fR [\fIoptions\fR]
.fi

.SH DESCRIPTION
.sp
.LP
The \fBpppoed\fR daemon implements the server-side negotiation of PPPoE. When a
client requests service from this daemon, a copy of \fBpppd\fR(8) is invoked
to handle the actual PPP communication.
.sp
.LP
At startup, options are read from the command line and the \fB/etc/ppp/pppoe\fR
file. After these options have been read, options in the per-device
\fB/etc/ppp/pppoe.\fIdevice\fR\fR files are read, using the device names
specified on the command line or in \fB/etc/ppp/pppoe\fR. Device names are not
permitted in the per-device files. It is not an error if any of these files are
absent; missing files are ignored.
.sp
.LP
Options are reread in the same order on \fBSIGHUP\fR. Except for the
possibility of short delays due to the processing time, \fBSIGHUP\fR does not
interfere with any client operations. Current status, including options read,
is dumped to \fB/tmp/pppoed.\fIpid\fR\fR on \fBSIGINT\fR.
.sp
.LP
The options are used to set up a list of services to be offered to PPPoE
clients on the broadcast domains (Ethernet subnets) specified by the named
devices. Option parsing is always in one of two modes, either global mode or
service mode. The initial mode at the beginning of each file (and the command
line) is global mode. Options specified in global mode serve as default values
for subsequently defined services. Service mode is entered by the \fBservice\fR
\fIname\fR option. In this mode, the named option is defined. Options that
appear in this mode override any global mode definitions for the current
service.
.sp
.LP
The option parsing follows standard shell tokenizing rules, using whitespace to
delimit tokens, quotes to enclose strings that can contain whitespace, and
escape sequences for special characters. Environment variables are substituted
using familiar \fB$VAR\fR and \fB${VAR}\fR syntax and set using
\fBNEWVAR=\fIstring\fR\fR. Variables are both usable in subsequent options and
provided to the \fBpppd\fR(8) processes spawned for each client, but they are
interpreted as they are encountered during option processing. Thus, all set
variables are seen by all processes spawned; position in the configuration
files has no effect on this.
.SH OPTIONS
.sp
.LP
The \fBpppoed\fR daemon supports the following options:
.sp
.ne 2
.na
\fB\fBclient\fR [\fBexcept\fR] \fIclient-list\fR\fR
.ad
.sp .6
.RS 4n
This option restricts the clients that may receive the service. If the
\fBexcept\fR keyword is given, then the clients on the list cannot access the
service, but others can. If this keyword is not given, then only the listed
clients can access the service.
.sp
This option can be specified more than once for a given service. For a given
client, first match among all listed options encountered specifies the
handling. If it matches an option with \fBexcept\fR specified, then access is
denied. Otherwise, it is granted. The \fBclient\fR list within a service is
prepended to any list specified in the global context.
.sp
If no \fBclient\fR options are given or if all options are specified with
\fBexcept\fR, then all clients are permitted by default. If any \fBclient\fR
options without \fBexcept\fR are specified, then no clients are permitted by
default.
.sp
The \fIclient-list\fR is a comma-separated list of client identifiers. The
match is made if any client on the list matches; thus, these are logically
"ORed" together. Each client identifier can be either a symbolic name (resolved
through \fB/etc/ethers\fR or NIS, as defined by \fB/etc/nsswitch.conf\fR) or a
hexadecimal Ethernet address in the format \fBx:x:x:x:x:x\fR. In the latter
case, any byte of the address can be "\fB*\fR", which matches any value in that
position. For example, \fB40:0:1a:*:*:*\fR matches Ethernet adapters from the
manufacturer assigned block \fB40:0:1a\fR.
.RE

.sp
.ne 2
.na
\fB\fBdebug\fR\fR
.ad
.sp .6
.RS 4n
Increase debug logging detail level by one. The detail levels are 0 (no
logging), 1 (errors only; the default), 2 (warnings), 3 (informational
messages), and 4 (debug messages). Log messages are written by default to
\fBsyslog\fR(3C) using facility \fIdaemon\fR (see the \fBlog\fR option below).
When specified on the command line or in the global context of the
\fB/etc/ppp/pppoe\fR file, this option also sets the daemon's default
(non-service-related) detail level.
.RE

.sp
.ne 2
.na
\fB\fBdevice\fR \fIdevice-list\fR\fR
.ad
.sp .6
.RS 4n
Specify the devices on which the service is available. The \fIdevice-list\fR is
a comma-separated list of logical device names (without the leading
\fB/dev/\fR), such as \fBhme0\fR. This option is ignored if encountered in the
per-device \fB/etc/ppp/pppoe.\fIdevice\fR\fR files.
.RE

.sp
.ne 2
.na
\fB\fBextra\fR \fIstring\fR\fR
.ad
.sp .6
.RS 4n
Specifies extra options to \fBpppd\fR(8). It defaults to "\fBplugin pppoe.so
directtty\fR" and usually does not need to be overridden.
.RE

.sp
.ne 2
.na
\fB\fBfile\fR \fIpath\fR\fR
.ad
.sp .6
.RS 4n
Suspends parsing of the current file, returns to global mode, and reads options
from \fIpath\fR. This file must be present and readable; if it is not, an error
is logged. When the end of that file is reached, processing returns to the
current file and the mode is reset to global again.
.sp
The global mode options specified in files read by this command use the options
set in the current file's global mode; this condition extends to any file
included by those files. All files read are parsed as though the command line
had specified this option, and thus inherit the command line's global modes.
.sp
This option can be used to revert to global mode at any point in an option file
by specifying \fBfile /dev/null\fR.
.RE

.sp
.ne 2
.na
\fB\fBgroup\fR \fIname\fR\fR
.ad
.sp .6
.RS 4n
Specifies the group ID (symbolic or numeric) under which \fBpppd\fR is
executed. If \fBpppoed\fR is not run as root, this option is ignored.
.RE

.sp
.ne 2
.na
\fB\fBlog\fR \fIpath\fR\fR
.ad
.sp .6
.RS 4n
Specifies an alternate debug logging file. Debug messages are sent to this file
instead of \fBsyslog\fR. The special name \fBsyslog\fR is recognized to switch
logging back to \fBsyslog\fR. When specified on the command line or in the
global context of the \fB/etc/ppp/pppoe\fR file, this option also sets the
daemon's default (non-service-related) log file.
.RE

.sp
.ne 2
.na
\fB\fBnodebug\fR\fR
.ad
.sp .6
.RS 4n
Set debug logging detail level to 0 (no logging). When specified on the command
line or in the global context of the \fB/etc/ppp/pppoe\fR file, this option
also sets the daemon's default (non-service-related) detail level.
.RE

.sp
.ne 2
.na
\fB\fBnowildcard\fR\fR
.ad
.sp .6
.RS 4n
Specifies that the current service should not be included in response to
clients requesting "any" service. The client must ask for this service by name.
When specified on the command line or in the global context of the
\fB/etc/ppp/pppoe\fR file, this option causes \fBpppoed\fR to ignore all
wildcard service requests.
.RE

.sp
.ne 2
.na
\fB\fBpath\fR \fIpath\fR\fR
.ad
.sp .6
.RS 4n
Specifies the path to the \fBpppd\fR executable. Defaults to
\fB/usr/bin/pppd\fR.
.RE

.sp
.ne 2
.na
\fB\fBpppd\fR \fIstring\fR\fR
.ad
.sp .6
.RS 4n
Passes command-line arguments to \fBpppd\fR. It can be used to set the IP
addresses or configure security for the session. The default value is the empty
string.
.RE

.sp
.ne 2
.na
\fB\fBserver\fR \fIstring\fR\fR
.ad
.sp .6
.RS 4n
Specifies the PPPoE Access Concentrator name to be sent to the client. It
defaults to "Solaris PPPoE".
.RE

.sp
.ne 2
.na
\fB\fBservice\fR \fIname\fR\fR
.ad
.sp .6
.RS 4n
Closes any service being defined and begins definition of a new service. The
same service name can be used without conflict on multiple devices. If the same
service name is used on a single device, then the last definition encountered
during parsing overrides all previous definitions.
.RE

.sp
.ne 2
.na
\fB\fBuser\fR \fIname\fR\fR
.ad
.sp .6
.RS 4n
Specifies the user ID, symbolic or numeric, under which \fBpppd\fR is executed.
If \fBpppoed\fR is not run as root, this option is ignored.
.RE

.sp
.ne 2
.na
\fB\fBwildcard\fR\fR
.ad
.sp .6
.RS 4n
Specifies that the service should be included in responses to client queries
that request "any" service, which is done by requesting a service name of
length zero. When specified on the command line or in the global context of the
\fB/etc/ppp/pppoe\fR file, this option causes \fBpppoed\fR to ignore all
wildcard service requests. This is the default.
.RE

.SH EXAMPLES
.LP
\fBExample 1 \fRConfiguring for Particular Services
.sp
.LP
In the \fB/etc/ppp/pppoe\fR file:

.sp
.in +2
.nf
service internet
    device $DEV
    pppd "proxyarp 192.168.1.1:"
service debugging
    device hme0,$DEV
    pppd "debug proxyarp 192.168.1.1:"
.fi
.in -2

.sp
.LP
You then invoke the daemon with:

.sp
.in +2
.nf
example% \fB/usr/lib/inet/pppoed DEV=eri0\fR
.fi
.in -2
.sp

.sp
.LP
The lines in \fB/etc/ppp/pppoe\fR and the preceding command result in offering
services "internet" and "debugging" (and responding to wildcard queries) on
interface \fBeri0\fR, and offering only service "debugging" on interface
\fBhme0\fR.

.SH SIGNALS
.sp
.LP
The \fBpppoed\fR daemon responds to the following signals:
.sp
.ne 2
.na
\fB\fBSIGHUP\fR\fR
.ad
.RS 10n
Causes \fBpppoed\fR to reparse the original command line and all configuration
files, and close and reopen any log files.
.RE

.sp
.ne 2
.na
\fB\fBSIGINT\fR\fR
.ad
.RS 10n
Causes a snapshot of the state of the \fBpppoed\fR daemon to be written to
\fB/tmp/pppoed.\fIpid\fR\fR (where \fIpid\fR is the decimal process ID of the
daemon).
.RE

.SH FILES
.sp
.ne 2
.na
\fB\fB/usr/lib/inet/pppoed\fR \fR
.ad
.RS 25n
executable command
.RE

.sp
.ne 2
.na
\fB\fB/dev/sppptun\fR\fR
.ad
.RS 25n
Solaris PPP tunneling device driver
.RE

.sp
.ne 2
.na
\fB\fB/etc/ppp/pppoe\fR\fR
.ad
.RS 25n
main configuration option file
.RE

.sp
.ne 2
.na
\fB\fB/etc/ppp/pppoe.\fIdevice\fR\fR\fR
.ad
.RS 25n
per-device configuration option file
.RE

.sp
.ne 2
.na
\fB\fB/etc/ppp/pppoe-errors\fR\fR
.ad
.RS 25n
location of output from \fBpppd\fR's stderr
.RE

.sp
.ne 2
.na
\fB\fB/etc/ppp/pppoe.if\fR\fR
.ad
.RS 25n
list of Ethernet interfaces to be plumbed at boot time
.RE

.sp
.ne 2
.na
\fB\fB/tmp/pppoed.\fIpid\fR\fR\fR
.ad
.RS 25n
ASCII text file containing dumped \fBpppoed\fR state information
.RE

.SH SEE ALSO
.sp
.LP
.BR sppptun (4M),
.BR pppd (8),
.BR pppoec (8),
.BR sppptun (8)
.sp
.LP
Mamakos, L., et al. \fIRFC 2516, A Method for Transmitting PPP Over Ethernet
(PPPoE)\fR. Network Working Group. February 1999
.SH NOTES
.sp
.LP
Because \fBpppd\fR is installed setuid root, this daemon need not be run as
root. However, if it is not run as root, the \fBuser\fR and \fBgroup\fR options
are ignored.
.sp
.LP
The Ethernet interfaces to be used must be plumbed for PPPoE using the
\fBsppptun\fR(8) utility before services can be offered.
.sp
.LP
The daemon operate runs even if there are no services to offer. If you want to
modify a configuration, it is not necessary to terminate the daemon. Simply use
\fBpkill \fR\fB-HUP\fR\fB pppoed\fR after updating the configuration files.
.sp
.LP
The PPPoE protocol is far from perfect. Because it runs directly over Ethernet,
there is no possibility of security and the MTU is limited to 1492 (violating
RFC 1661's default value of 1500). It is also not possible to run the client
and the server of a given session on a single machine with a single Ethernet
interface for testing purposes. The client and server portions of a single
session must be run on separate Ethernet interfaces with different MAC
addresses.