blob: 9e52a3051b1908b72e26282551b70061fe997f38
| 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 | |
| 125 |