release/src/router/rp-pppoe/man/pppoe-relay.8

   1 .\" LIC: GPL
   2 .TH PPPOE-RELAY 8 "26 January 2001"
   3 .\""
   4 .UC 4
   5 .SH NAME
   6 pppoe-relay \- user-space PPPoE relay agent.
   7 .SH SYNOPSIS
   8 .B pppoe-relay \fR[\fIoptions\fR]
   9
  10 .SH DESCRIPTION
  11 \fBpppoe-relay\fR is a user-space relay agent for PPPoE
  12 (Point-to-Point Protocol over Ethernet) for Linux.  \fBpppoe-relay\fR
  13 works in concert with the \fBpppoe\fR client and \fBpppoe-server\fR
  14 server.  See the OPERATION section later in this manual for
  15 details on how \fBpppoe-relay\fR works.
  16
  17 .SH OPTIONS
  18 .TP
  19 .B \-S \fIinterface\fR
  20 Adds the Ethernet interface \fIinterface\fR to the list of interfaces
  21 managed by \fBpppoe-relay\fR.  Only PPPoE servers may be connected to
  22 this interface.
  23
  24 .TP
  25 .B \-C \fIinterface\fR
  26 Adds the Ethernet interface \fIinterface\fR to the list of interfaces
  27 managed by \fBpppoe-relay\fR.  Only PPPoE clients may be connected to
  28 this interface.
  29
  30 .TP
  31 .B \-B \fIinterface\fR
  32 Adds the Ethernet interface \fIinterface\fR to the list of interfaces
  33 managed by \fBpppoe-relay\fR.  Both PPPoE clients and servers may be
  34 connected to this interface.
  35
  36 .TP
  37 .B \-n \fInum\fR
  38 Allows at most \fInum\fR concurrent PPPoE sessions.  If not specified,
  39 the default is 5000.  \fInum\fR can range from 1 to 65534.
  40
  41 .TP
  42 .B \-i \fItimeout\fR
  43 Specifies the session idle timeout.  If both peers in a session are idle
  44 for more than \fItimeout\fR seconds, the session is terminated.
  45 If \fItimeout\fR is specified as zero, sessions will never be terminated
  46 because of idleness.
  47
  48 Note that the idle-session expiry routine is never run more frequently than
  49 every 30 seconds, so the timeout is approximate.  The default value for
  50 \fItimeout\fR is 600 seconds (10 minutes.)
  51
  52 .TP
  53 .B \-F
  54 The \fB\-F\fR option causes \fBpppoe-relay\fR \fInot\fR to fork into the
  55 background; instead, it remains in the foreground.
  56
  57 .TP
  58 .B \-h
  59 The \fB\-h\fR option prints a brief usage message and exits.
  60
  61 .SH OPERATION
  62
  63 \fBpppoe-relay\fR listens for incoming PPPoE PADI frames on all interfaces
  64 specified with \fB-B\fR or \fB-C\fR options.  When a PADI frame appears,
  65 \fBpppoe-relay\fR adds a Relay-Session-ID tag and broadcasts the PADI
  66 on all interfaces specified with \fB-B\fR or \fB-S\fR options (except the
  67 interface on which the frame arrived.)
  68
  69 Any PADO frames received are relayed back to the client which sent the
  70 PADI (assuming they contain valid Relay-Session-ID tags.)  Likewise,
  71 PADR frames from clients are relayed back to the matching access
  72 concentrator.
  73
  74 When a PADS frame is received, \fBpppoe-relay\fR enters the two peers'
  75 MAC addresses and session-ID's into a hash table.  (The session-ID seen
  76 by the access concentrator may be different from that seen by the client;
  77 \fBpppoe-relay\fR must renumber sessions to avoid the possibility of duplicate
  78 session-ID's.)  Whenever either peer sends a session frame, \fBpppoe-relay\fR
  79 looks up the session entry in the hash table and relays the frame to
  80 the correct peer.
  81
  82 When a PADT frame is received, \fBpppoe-relay\fR relays it to the peer
  83 and deletes the session entry from its hash table.
  84
  85 If a client and server crash (or frames are lost), PADT frames may never
  86 be sent, and \fBpppoe-relay\fR's hash table can fill up with stale sessions.
  87 Therefore, a session-cleaning routine runs periodically, and removes old
  88 sessions from the hash table.  A session is considered "old" if no traffic
  89 has been seen within \fItimeout\fR seconds.  When a session is deleted because
  90 of a timeout, a PADT frame is sent to each peer to make certain that they
  91 are aware the session has been killed.
  92
  93 .SH EXAMPLE INVOCATIONS
  94
  95 .nf
  96 pppoe-relay -C eth0 -S eth1
  97 .fi
  98
  99 The example above relays frames between PPPoE clients on the eth0 network
 100 and PPPoE servers on the eth1 network.
 101
 102 .nf
 103 pppoe-relay -B eth0 -B eth1
 104 .fi
 105
 106 This example is a transparent relay -- frames are relayed between any mix
 107 of clients and servers on the eth0 and eth1 networks.
 108
 109 .nf
 110 pppoe-relay -S eth0 -C eth1 -C eth2 -C eth3
 111 .fi
 112
 113 This example relays frames between servers on the eth0 network and
 114 clients on the eth1, eth2 and eth3 networks.
 115
 116 .SH AUTHORS
 117 \fBpppoe-relay\fR was written by David F. Skoll <dfs@roaringpenguin.com>.
 118
 119 The \fBpppoe\fR home page is \fIhttp://www.roaringpenguin.com/pppoe/\fR.
 120
 121 .SH SEE ALSO
 122 pppoe-start(8), pppoe-stop(8), pppoe-connect(8), pppd(8), pppoe.conf(5),
 123 pppoe(8), pppoe-setup(8), pppoe-status(8), pppoe-sniff(8), pppoe-server(8)
 124