Ubuntu Manpage: pppoe-server - user-space PPPoE server

NAME

       pppoe-server - user-space PPPoE server

SYNOPSIS

       pppoe-server [options]

DESCRIPTION

       pppoe-server  is a user-space server for PPPoE (Point-to-Point Protocol over Ethernet) for
       Linux and other UNIX systems.  pppoe-server works in concert  with  the  pppoe  client  to
       respond to PPPoE discovery packets and set up PPPoE sessions.

OPTIONS

-F The -F option causes pppoe-server not to fork and become a daemon. The default is
to fork and become a daemon.

-I interface
The -I option specifies the Ethernet interface to use. Under Linux, it is
typically eth0 or eth1. The interface should be "up" before you start pppoe-
server, but need not have an IP address. You can supply multiple -I options if you
want the server to respond on more than one interface.

-X pidfile
This option causes pppoe-server to write its process ID to pidfile. Additionally,
it keeps the file locked so that only a single process may be started for a given
pidfile.

-q /path/to/pppd
Specifies the full path to the pppd program. The default is determined at compile
time. One use of this option is to supply a wrapper program that modifies the
arguments passed to pppd. This lets you do things not directly supported by the
server (for example, specify IPv6 addresses.)

-Q /path/to/pppoe
Specifies the full path to the pppoe program. The default is determined at compile
time. This option is only relevant if you are not using kernel-mode PPPoE.

-T timeout
This option is passed directly to pppoe; see pppoe(8) for details. If you are
using kernel-mode PPPoE, this option has no effect.

-C ac_name
Specifies which name to report as the access concentrator name. If not supplied,
the host name is used.

-S name
Offer a service named name. Multiple -S options may be specified; each one causes
the named service to be advertised in a Service-Name tag in the PADO frame. The
first -S option specifies the default service, and is used if the PPPoE client
requests a Service-Name of length zero.

-m MSS This option is passed directly to pppoe; see pppoe(8) for details. If you are
using kernel-mode PPPoE, this option has no effect.

-x n Limit the number of sessions per peer MAC address to n. If a given MAC address
attempts to create more than n sessions, then its PADI and PADR packets are
ignored. If you set n to 0 (the default), then no limit is imposed on the number
of sessions per peer MAC address.

-s This option is passed directly to pppoe; see pppoe(8) for details. In addition, it
causes pppd to be invoked with the sync option.

-L ip Sets the local IP address. This is passed to spawned pppd processes. If not
specified, the default is 10.0.0.1.

-R ip Sets the starting remote IP address. As sessions are established, IP addresses are
assigned starting from ip. pppoe-server automatically keeps track of the pool of
addresses and passes a valid remote IP address to pppd. If not specified, a
starting address of 10.67.15.1 is used.

-D Delegate the allocation of IP addresses to pppd. If specified, no local and remote
addresses passed to pppd.

-N num Allows at most num concurrent PPPoE sessions. If not specified, the default is 64.

-M string
Sends string in a MOTM tag in a PADM packet right after sending the PADS to a
client.

-H url Sends url in a HURL tag in a PADM packet right after sending the PADS to a client.
Note that url must start with either http:// or https://.

-O fname
This option causes pppoe-server to tell pppd to use the option file fname instead
of the default /etc/ppp/pppoe-server-options.

-p fname
Reads the specified file fname which is a text file consisting of one IP address
per line. These IP addresses will be assigned to clients. The number of sessions
allowed will equal the number of addresses found in the file. The -p option
overrides both -R and -N.

In addition to containing IP addresses, the pool file can contain lines of the
form:

a.b.c.d-e

which includes all IP addresses from a.b.c.d to a.b.c.e. For example, the line:

1.2.3.4-7

is equivalent to:

1.2.3.4
1.2.3.5
1.2.3.6
1.2.3.7

-r Tells the PPPoE server to randomly permute session numbers. Instead of handing out
sessions in order, the session numbers are assigned in an unpredictable order.

-u Tells the server to invoke pppd with the unit option. Note that this option only
works for pppd version 2.4.0 or newer.

-o offset
Instead of numbering PPPoE sessions starting at 1, they will be numbered starting
at offset+1. This allows you to run multiple servers on a given machine; just make
sure that their session numbers do not overlap.

-f disc:sess
The -f option sets the Ethernet frame types for PPPoE discovery and session frames.
The types are specified as hexadecimal numbers separated by a colon. Standard
PPPoE uses frame types 8863:8864. You should not use this option unless you are
absolutely sure the peer you are dealing with uses non-standard frame types.

-k The -k option tells the server to use kernel-mode PPPoE on Linux. This option is
available only on Linux kernels 2.4.0 and later, and only if the server was built
with kernel-mode support.

-i The -i option tells the server to completely ignore PADI frames if there are no
free session slots.

-h The -h option prints a brief usage message and exits.

OPERATION

       pppoe-server listens for incoming PPPoE discovery packets.  When a session is established,
       it spawns a pppd process.  The following options are passed to pppd:

       nodetach noaccomp nobsdcom nodeflate nopcomp novj novjccomp
       default-asyncmap

       In addition, the local and remote IP address are set based on the -L and -R options.   The
       pty option is supplied along with a pppoe command to initiate the PPPoE session.  Finally,
       additional pppd options can be placed in  the  file  /etc/ppp/pppoe-server-options  (which
       must exist, even if it is just empty!)

       Note  that  pppoe-server  is  meant  mainly  for testing PPPoE clients.  It is not a high-
       performance server meant for production use.

AUTHORS