pppoe-server - user-space PPPoE server

pppoe-server was written by Dianne Skoll <dianne@skoll.ca>.

       The pppoe home page is https://dianne.skoll.ca/projects/rp-pppoe/.

       The  control-socket  was  implemented  as a secondary mechanism to improve run-time control of the pppoe-
       server.  To use it you need to start pppoe-server with the -U option described above.  You can  then  (in
       the absence of a control-client currently) use netcat to connect to the control socket, for example:

       nc -U /run/pppoe-server.control

       Assuming -U/run/pppoe-server.control was passed to pppoe-server.

       The following commands are implemented:

       setdrain{off|on|quit}
              This will set whether or not pppoe-server responds to PADI packets or not.  When set to off pppoe-
              server  will  respond,  else  PADI  packets  will  be ignored.  This allows the pppoe-server to be
              drained from clients.  In addition when set to quit will terminate pppoe-server  when  all  pppoe-
              clients have terminated.

              This  allows  for  (mostly) seamless upgrades in that the currently running instance can be issued
              with "set drain quit" prior to starting a new interface on the same interfaces, thus allowing  new
              connections to be made whilst maintaining proper state on existing clients.

       showstatus
              This will show basic status information for the connected-to pppoe-server.

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.

       pppoe-server - user-space PPPoE server

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.

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

       -Iinterface
              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.

       -Xpidfile
              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.

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

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

       -Sname
              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.

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

       -xn   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.

       -Lip  Sets  the  local  IP  address.   This  is passed to spawned pppd processes.  If not specified, the
              default is 10.0.0.1.  If specified as 0.0.0.0 the selection of local IP address  is  delegated  to
              pppd.

       -Rip  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.  If
              specified as 0.0.0.0 remote IP allocation will be delegated to pppd.

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

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

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

       -Hurl 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://.

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

       -pfname
              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.

       -ooffset
              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.

       -fdisc: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.
              Youshouldnotusethisoption 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.

       -gpath
              The -g option tells the server the full path to the pppoe.so or rp-pppoe.so  plugin  to  use  with
              kernel-mode PPPoE.  If omitted, a compiled-in default is used; this default can be displayed using
              the -h option.

       -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.

       -Upath
              The -U option creates a UNIX socket which can be connected to in order to manage  pppoe-server  at
              run-time.  Please refer to the CONTROL-SOCKET section below for more detailed instructions.

pppd(8), pppoe(8), pppoe-sniff(8), pppoe-relay(8)

4th Berkeley Distribution                         21 June 2008                                   PPPOE-SERVER(8)

pppoe-server [options]