blob: b24c10b8e6db918f737d32329a0d928546465daf
| 1 | .\" LIC: GPL |
| 2 | .TH PPPOE-SERVER 8 "21 June 2008" |
| 3 | .\"" |
| 4 | .UC 4 |
| 5 | .SH NAME |
| 6 | pppoe-server \- user-space PPPoE server |
| 7 | .SH SYNOPSIS |
| 8 | .B pppoe-server \fR[\fIoptions\fR] |
| 9 | |
| 10 | .SH DESCRIPTION |
| 11 | \fBpppoe-server\fR is a user-space server for PPPoE (Point-to-Point Protocol |
| 12 | over Ethernet) for Linux and other UNIX systems. \fBpppoe-server\fR works in |
| 13 | concert with the \fBpppoe\fR client to respond to PPPoE discovery packets |
| 14 | and set up PPPoE sessions. |
| 15 | |
| 16 | .SH OPTIONS |
| 17 | .TP |
| 18 | .B \-F |
| 19 | The \fB\-F\fR option causes \fBpppoe-server\fR not to fork and become a |
| 20 | daemon. The default is to fork and become a daemon. |
| 21 | |
| 22 | .TP |
| 23 | .B \-I \fIinterface\fR |
| 24 | The \fB\-I\fR option specifies the Ethernet interface to use. Under Linux, |
| 25 | it is typically \fIeth0\fR or \fIeth1\fR. The interface should be "up" |
| 26 | before you start \fBpppoe-server\fR, but should \fInot\fR be configured to have |
| 27 | an IP address. You can supply multiple \fB\-I\fR options if you want the |
| 28 | server to respond on more than one interface. |
| 29 | |
| 30 | .TP |
| 31 | .B \-T \fItimeout\fR |
| 32 | This option is passed directly to \fBpppoe\fR; see \fBpppoe\fR(8) for |
| 33 | details. If you are using kernel-mode PPPoE, this option has \fIno effect\fR. |
| 34 | |
| 35 | .TP |
| 36 | .B \-C \fIac_name\fR |
| 37 | Specifies which name to report as the access concentrator name. If not |
| 38 | supplied, the host name is used. |
| 39 | |
| 40 | .TP |
| 41 | .B \-S \fIname\fR |
| 42 | Offer a service named \fIname\fR. Multiple \fB\-S\fR options may |
| 43 | be specified; each one causes the named service to be advertised |
| 44 | in a Service-Name tag in the PADO frame. The first \fB\-S\fR option |
| 45 | specifies the default service, and is used if the PPPoE client |
| 46 | requests a Service-Name of length zero. |
| 47 | |
| 48 | .TP |
| 49 | .B \-m \fIMSS\fR |
| 50 | This option is passed directly to \fBpppoe\fR; see \fBpppoe\fR(8) for |
| 51 | details. If you are using kernel-mode PPPoE, this option has \fIno effect\fR. |
| 52 | |
| 53 | .TP |
| 54 | .B \-x \fIn\fR |
| 55 | Limit the number of sessions per peer MAC address to \fIn\fR. If a given |
| 56 | MAC address attempts to create more than \fIn\fR sessions, then its |
| 57 | PADI and PADR packets are ignored. If you set \fIn\fR to 0 (the default), |
| 58 | then no limit is imposed on the number of sessions per peer MAC address. |
| 59 | |
| 60 | .TP |
| 61 | .B \-s |
| 62 | This option is passed directly to \fBpppoe\fR; see \fBpppoe\fR(8) for |
| 63 | details. In addition, it causes \fBpppd\fR to be invoked with the |
| 64 | \fIsync\fR option. |
| 65 | |
| 66 | .TP |
| 67 | .B \-L \fIip\fR |
| 68 | Sets the local IP address. This is passed to spawned \fBpppd\fR processes. |
| 69 | If not specified, the default is 10.0.0.1. |
| 70 | |
| 71 | .TP |
| 72 | .B \-R \fIip\fR |
| 73 | Sets the starting remote IP address. As sessions are established, |
| 74 | IP addresses are assigned starting from \fIip\fR. \fBpppoe-server\fR |
| 75 | automatically keeps track of the pool of addresses and passes a |
| 76 | valid remote IP address to \fBpppd\fR. If not specified, a starting address |
| 77 | of 10.67.15.1 is used. |
| 78 | |
| 79 | .TP |
| 80 | .B \-N \fInum\fR |
| 81 | Allows at most \fInum\fR concurrent PPPoE sessions. If not specified, |
| 82 | the default is 64. |
| 83 | |
| 84 | .TP |
| 85 | .B \-O \fIfname\fR |
| 86 | This option causes \fBpppoe-server\fR to tell \fBpppd\fR to use the option |
| 87 | file \fIfname\fR instead of the default \fI/etc/ppp/pppoe-server-options\fR. |
| 88 | |
| 89 | .TP |
| 90 | .B \-p \fIfname\fR |
| 91 | Reads the specified file \fIfname\fR which is a text file consisting of |
| 92 | one IP address per line. These IP addresses will be assigned to clients. |
| 93 | The number of sessions allowed will equal the number of addresses found |
| 94 | in the file. The \fB\-p\fR option overrides both \fB\-R\fR and \fB\-N\fR. |
| 95 | |
| 96 | In addition to containing IP addresses, the pool file can contain lines |
| 97 | of the form: |
| 98 | |
| 99 | .nf |
| 100 | a.b.c.d-e |
| 101 | .fi |
| 102 | |
| 103 | which includes all IP addresses from a.b.c.d to a.b.c.e. For example, |
| 104 | the line: |
| 105 | |
| 106 | .nf |
| 107 | 1.2.3.4-7 |
| 108 | .fi |
| 109 | |
| 110 | is equivalent to: |
| 111 | |
| 112 | .nf |
| 113 | 1.2.3.4 |
| 114 | 1.2.3.5 |
| 115 | 1.2.3.6 |
| 116 | 1.2.3.7 |
| 117 | .fi |
| 118 | |
| 119 | .TP |
| 120 | .B \-r |
| 121 | Tells the PPPoE server to randomly permute session numbers. Instead of |
| 122 | handing out sessions in order, the session numbers are assigned in an |
| 123 | unpredictable order. |
| 124 | |
| 125 | .TP |
| 126 | .B \-u |
| 127 | Tells the server to invoke \fBpppd\fR with the \fIunit\fR option. Note |
| 128 | that this option only works for \fBpppd\fR version 2.4.0 or newer. |
| 129 | |
| 130 | .TP |
| 131 | .B \-o \fIoffset\fR |
| 132 | Instead of numbering PPPoE sessions starting at 1, they will be numbered |
| 133 | starting at \fIoffset\fR+1. This allows you to run multiple servers on |
| 134 | a given machine; just make sure that their session numbers do not |
| 135 | overlap. |
| 136 | |
| 137 | .TP |
| 138 | .B \-f disc:sess |
| 139 | The \fB\-f\fR option sets the Ethernet frame types for PPPoE discovery |
| 140 | and session frames. The types are specified as hexadecimal numbers |
| 141 | separated by a colon. Standard PPPoE uses frame types 8863:8864. |
| 142 | \fIYou should not use this option\fR unless you are absolutely sure |
| 143 | the peer you are dealing with uses non-standard frame types. |
| 144 | |
| 145 | .TP |
| 146 | .B \-k |
| 147 | The \fB\-k\fR option tells the server to use kernel-mode PPPoE on Linux. |
| 148 | This option is available only on Linux kernels 2.4.0 and later, and |
| 149 | only if the server was built with kernel-mode support. |
| 150 | |
| 151 | .TP |
| 152 | .B \-h |
| 153 | The \fB\-h\fR option prints a brief usage message and exits. |
| 154 | |
| 155 | .SH OPERATION |
| 156 | |
| 157 | \fBpppoe-server\fR listens for incoming PPPoE discovery packets. When |
| 158 | a session is established, it spawns a \fBpppd\fR process. The following |
| 159 | options are passed to \fBpppd\fR: |
| 160 | |
| 161 | .nf |
| 162 | nodetach noaccomp nobsdcom nodeflate nopcomp novj novjccomp |
| 163 | default-asyncmap |
| 164 | .fi |
| 165 | |
| 166 | In addition, the local and remote IP address are set based on the |
| 167 | \fB\-L\fR and \fB\-R\fR options. The \fBpty\fR option is supplied along |
| 168 | with a \fBpppoe\fR command to initiate the PPPoE session. Finally, |
| 169 | additional \fBpppd\fR options can be placed in the file |
| 170 | \fB/etc/ppp/pppoe-server-options\fR (which must exist, even if it is just |
| 171 | empty!) |
| 172 | |
| 173 | Note that \fBpppoe-server\fR is meant mainly for testing PPPoE clients. |
| 174 | It is \fInot\fR a high-performance server meant for production use. |
| 175 | |
| 176 | .SH AUTHORS |
| 177 | \fBpppoe-server\fR was written by David F. Skoll <dfs@roaringpenguin.com>. |
| 178 | |
| 179 | The \fBpppoe\fR home page is \fIhttp://www.roaringpenguin.com/pppoe/\fR. |
| 180 | |
| 181 | .SH SEE ALSO |
| 182 | pppoe-start(8), pppoe-stop(8), pppoe-connect(8), pppd(8), pppoe.conf(5), |
| 183 | pppoe(8), pppoe-setup(8), pppoe-status(8), pppoe-sniff(8), pppoe-relay(8) |
| 184 | |
| 185 |