Ubuntu Manpage: pppoe-relay - user-space PPPoE relay agent.

NAME

       pppoe-relay - user-space PPPoE relay agent.

SYNOPSIS

       pppoe-relay [options]

DESCRIPTION

       pppoe-relay  is  a  user-space  relay  agent for PPPoE (Point-to-Point Protocol over Ethernet) for Linux.
       pppoe-relay works in concert with the pppoe client and pppoe-server server.  See  the  OPERATION  section
       later in this manual for details on how pppoe-relay works.

OPTIONS

       -S interface
              Adds  the  Ethernet  interface  interface  to the list of interfaces managed by pppoe-relay.  Only
              PPPoE servers may be connected to this interface.

       -C interface
              Adds the Ethernet interface interface to the list of  interfaces  managed  by  pppoe-relay.   Only
              PPPoE clients may be connected to this interface.

       -B interface
              Adds  the  Ethernet  interface  interface  to the list of interfaces managed by pppoe-relay.  Both
              PPPoE clients and servers may be connected to this interface.

       -n num Allows at most num concurrent PPPoE sessions.  If not specified, the default  is  5000.   num  can
              range from 1 to 65534.

       -i timeout
              Specifies  the  session  idle  timeout.  If both peers in a session are idle for more than timeout
              seconds, the session is terminated.  If timeout is specified  as  zero,  sessions  will  never  be
              terminated because of idleness.

              Note  that  the idle-session expiry routine is never run more frequently than every 30 seconds, so
              the timeout is approximate.  The default value for timeout is 600 seconds (10 minutes.)

       -F     The -F option causes pppoe-relay not to fork into the  background;  instead,  it  remains  in  the
              foreground.

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

OPERATION

pppoe-relay listens for incoming PPPoE PADI frames on all interfaces specified with -B or -C options.
When a PADI frame appears, pppoe-relay adds a Relay-Session-ID tag and broadcasts the PADI on all
interfaces specified with -B or -S options (except the interface on which the frame arrived.)

Any PADO frames received are relayed back to the client which sent the PADI (assuming they contain valid
Relay-Session-ID tags.) Likewise, PADR frames from clients are relayed back to the matching access
concentrator.

When a PADS frame is received, pppoe-relay enters the two peers' MAC addresses and session-ID's into a
hash table. (The session-ID seen by the access concentrator may be different from that seen by the
client; pppoe-relay must renumber sessions to avoid the possibility of duplicate session-ID's.) Whenever
either peer sends a session frame, pppoe-relay looks up the session entry in the hash table and relays
the frame to the correct peer.

When a PADT frame is received, pppoe-relay relays it to the peer and deletes the session entry from its
hash table.

If a client and server crash (or frames are lost), PADT frames may never be sent, and pppoe-relay's hash
table can fill up with stale sessions. Therefore, a session-cleaning routine runs periodically, and
removes old sessions from the hash table. A session is considered "old" if no traffic has been seen
within timeout seconds. When a session is deleted because of a timeout, a PADT frame is sent to each
peer to make certain that they are aware the session has been killed.

EXAMPLE INVOCATIONS

       pppoe-relay -C eth0 -S eth1

       The example above relays frames between PPPoE clients on the eth0 network and PPPoE servers on  the  eth1
       network.

       pppoe-relay -B eth0 -B eth1

       This  example  is a transparent relay -- frames are relayed between any mix of clients and servers on the
       eth0 and eth1 networks.

       pppoe-relay -S eth0 -C eth1 -C eth2 -C eth3

       This example relays frames between servers on the eth0 network and clients on the  eth1,  eth2  and  eth3
       networks.

AUTHORS

       pppoe-relay was written by David F. Skoll <dfs@roaringpenguin.com>.

       The pppoe home page is http://www.roaringpenguin.com/pppoe/.