platform/external/pppoe.git - Unnamed repository; edit this file 'description' to name the repository.

1 .\" LIC: GPL
2 .TH PPPOE 8 "3 July 2000"
3 .UC 4
4 .SH NAME
5 pppoe \- user-space PPPoE client.
6 .SH SYNOPSIS
7 .B pppd pty 'pppoe \fR[\fIpppoe_options\fR]\fB' \fR[\fIpppd_options\fR]
8 .P
9 .B pppoe -A \fR[\fIpppoe_options\fR]
10 .SH DESCRIPTION
11 \fBpppoe\fR is a user-space client for PPPoE (Point-to-Point Protocol
12 over Ethernet) for Linux and other UNIX systems.  \fBpppoe\fR works in
13 concert with the \fBpppd\fR PPP daemon to provide a PPP connection
14 over Ethernet, as is used by many DSL service providers.
15
16 .SH OPTIONS
17 .TP
18 .B \-I \fIinterface\fR
19 The \fB\-I\fR option specifies the Ethernet interface to use.  Under Linux,
20 it is typically \fIeth0\fR or \fIeth1\fR.  The interface should be "up"
21 before you start \fBpppoe\fR, but should \fInot\fR be configured to have
22 an IP address.
23
24 .TP
25 .B \-T \fItimeout\fR
26 The \fB\-T\fR option causes \fBpppoe\fR to exit if no session traffic
27 is detected for \fItimeout\fR seconds.  I recommend that you use this
28 option as an extra safety measure, but if you do, you should make sure
29 that PPP generates enough traffic so the timeout will normally not be
30 triggered.  The best way to do this is to use the
31 \fIlcp-echo-interval\fR option to \fBpppd\fR.  You should set the
32 PPPoE timeout to be about four times the LCP echo interval.
33
34 .TP
35 .B \-D \fIfile_name\fR
36 The \fB\-D\fR option causes every packet to be dumped to the specified
37 \fIfile_name\fR.  This is intended for debugging only; it produces huge
38 amounts of output and greatly reduces performance.
39
40 .TP
41 .B \-V
42 The \fB\-V\fR option causes \fBpppoe\fR to print its version number and
43 exit.
44
45 .TP
46 .B \-A
47 The \fB\-A\fR option causes \fBpppoe\fR to send a PADI packet and then print
48 the names of access concentrators in each PADO packet it receives.  Do not
49 use this option in conjunction with \fBpppd\fR; the \fB\-A\fR option is
50 meant to be used interactively to give interesting information about the
51 access concentrator.
52
53 .TP
54 .B \-S \fIservice_name\fR
55 Specifies the desired service name.  \fBpppoe\fR will only initiate sessions
56 with access concentrators which can provide the specified service.  In
57 most cases, you should \fInot\fR specify this option.  Use it only if you
58 know that there are multiple access concentrators or know that you need a
59 specific service name.
60
61 .TP
62 .B \-C \fIac_name\fR
63 Specifies the desired access concentrator name.  \fBpppoe\fR will only
64 initiate sessions with the specified access concentrator.  In
65 most cases, you should \fInot\fR specify this option.  Use it only if you
66 know that there are multiple access concentrators.  If both the
67 \fB\-S\fR and \fB\-C\fR options are specified, they must \fIboth\fR match
68 for \fBpppoe\fR to initiate a session.
69
70 .TP
71 .B \-U
72 Causes \fBpppoe\fR to use the Host-Uniq tag in its discovery packets.  This
73 lets you run multiple \fBpppoe\fR daemons without having their discovery
74 packets interfere with one another.  You must supply this option to
75 \fIall\fR \fBpppoe\fR daemons if you intend to run multiple daemons
76 simultaneously.
77
78 .TP
79 .B \-s
80 Causes \fBpppoe\fR to use \fIsynchronous\fR PPP encapsulation.  If you
81 use this option, then you \fImust\fR use the \fBsync\fR option with
82 \fBpppd\fR.  You are encouraged to use this option if it works, because
83 it greatly reduces the CPU overhead of \fBpppoe\fR.  However, it
84 MAY be unreliable on slow machines -- there is a race condition between
85 pppd writing data and pppoe reading it.  For this reason, the default
86 setting is asynchronous.  If you encounter bugs or crashes with Synchronous
87 PPP, turn it off -- don't e-mail me for support!
88
89 .TP
90 .B \-m \fIMSS\fR
91 Causes \fBpppoe\fR to \fIclamp\fR the TCP maximum segment size at the specified
92 value.  Because of PPPoE overhead, the maximum segment size for PPPoE is
93 smaller than for normal Ethernet encapsulation.  This could cause problems
94 for machines on a LAN behind a gateway using PPPoE.  If you have a LAN
95 behind a gateway, and the gateway connects to the Internet using PPPoE,
96 you are strongly recommended to use a \fB\-m 1412\fR option.  This avoids
97 having to set the MTU on all the hosts on the LAN.
98
99 .TP
100 .B \-p \fIfile\fR
101 Causes \fBpppoe\fR to write its process-ID to the specified file.  This
102 can be used to locate and kill \fBpppoe\fR processes.
103
104 .TP
105 .B \-e \fIsess:mac\fR
106 Causes \fBpppoe\fR to skip the discovery phase and move directly to the
107 session phase.  The session is given by \fIsess\fR and the MAC address of
108 the peer by \fImac\fR.  This mode is \fInot\fR meant for normal use; it
109 is designed only for \fBpppoe-server\fR(8).
110
111 .TP
112 .B \-n
113 Causes \fBpppoe\fR not to open a discovery socket.  This mode is
114 \fInot\fR meant for normal use; it is designed only for
115 \fBpppoe-server\fR(8).
116
117 .TP
118 .B \-k
119 Causes \fBpppoe\fR to terminate an existing session by sending a PADT frame,
120 and then exit.  You must use the \fB\-e\fR option in conjunction with this
121 option to specify the session to kill.  This may be useful for killing
122 sessions when a buggy peer does not realize the session has ended.
123
124 .TP
125 .B \-d
126 Causes \fBpppoe\fR to perform discovery and then exit, after printing
127 session information to standard output.  The session information is printed
128 in exactly the format expected by the \fB\-e\fR option.  This option lets
129 you initiate a PPPoE discovery, perform some other work, and then start
130 the actual PPP session.  \fIBe careful\fR; if you use this option in a loop,
131 you can create many sessions, which may annoy your peer.
132
133 .TP
134 .B \-f disc:sess
135 The \fB\-f\fR option sets the Ethernet frame types for PPPoE discovery
136 and session frames.  The types are specified as hexadecimal numbers
137 separated by a colon.  Standard PPPoE uses frame types 8863:8864.
138 \fIYou should not use this option\fR unless you are absolutely sure
139 the peer you are dealing with uses non-standard frame types.  If your
140 ISP uses non-standard frame types, complain!
141
142 .TP
143 .B \-h
144 The \fB\-h\fR option causes \fBpppoe\fR to print usage information and
145 exit.
146
147 .SH PPPOE BACKGROUND
148
149 PPPoE (Point-to-Point Protocol over Ethernet) is described in RFC 2516
150 and is a protocol which allows the session abstraction to be maintained
151 over bridged Ethernet networks.
152
153 PPPoE works by encapsulating PPP frames in Ethernet frames.  The protocol
154 has two distinct stages:  The \fIdiscovery\fR and the \fIsession\fR stage.
155
156 In the discovery stage, the host broadcasts a special PADI (PPPoE
157 Active Discovery Initiation) frame to discover any \fIaccess
158 concentrators\fR.  The access concentrators (typically, only one
159 access concentrator) reply with PADO (PPPoE Active Discovery Offer)
160 packets, announcing their presence and the services they offer.  The
161 host picks one of the access concentrators and transmits a PADR (PPPoE
162 Active Discovery Request) packet, asking for a session.  The access
163 concentrator replies with a PADS (PPPoE Active Discovery
164 Session-Confirmation) packet.  The protocol then moves to the session stage.
165
166 In the session stage, the host and access concentrator exchange PPP frames
167 embedded in Ethernet frames.  The normal Ethernet MTU is 1500 bytes, but
168 the PPPoE overhead plus two bytes of overhead for the encapsulated PPP
169 frame mean that the MTU of the PPP interface is at most 1492 bytes.
170 This causes \fIall kinds of problems\fR if you are using a Linux machine
171 as a firewall and interfaces behind the firewall have an MTU greater than
172 1492.  In fact, to be safe, I recommend setting the MTU of machines
173 behind the firewall to 1412, to allow for worst-case TCP and IP options
174 in their respective headers.
175
176 Normally, PPP uses the Link Control Protocol (LCP) to shut down a PPP
177 link.  However, the PPPoE specification allows the link to be shut down
178 with a special PADT (PPPoE Active Discovery Terminate) packet.  This client
179 recognizes this packet and will correctly terminate if a terminate request
180 is received for the PPP session.
181
182 .SH DESIGN GOALS
183
184 My design goals for this PPPoE client were as follows, in descending order
185 of importance:
186
187 .TP
188 .B o
189 It must work.
190
191 .TP
192 .B o
193 It must be a user-space program and not a kernel patch.
194
195 .TP
196 .B o
197 The code must be easy to read and maintain.
198
199 .TP
200 .B o
201 It must be fully compliant with RFC 2516, the proposed PPPoE standard.
202
203 .TP
204 .B o
205 It must never hang up forever -- if the connection is broken, it must
206 detect this and exit, allowing a wrapper script to restart the connection.
207
208 .TP
209 .B o
210 It must be fairly efficient.
211
212 .P
213 I believe I have achieved all of these goals, but (of course) am open
214 to suggestions, patches and ideas.  See my home page,
215 http://www.roaringpenguin.com, for contact information.
216
217 .SH NOTES
218
219 For best results, you must give \fBpppd\fR an mtu option of
220 1492.  I have observed problems with excessively-large frames
221 unless I set this option.  Also, if \fBpppoe\fR is running on a firewall
222 machine, all machines behind the firewall should have MTU's of 1412.
223
224 If you have problems, check your system logs.  \fBpppoe\fR logs interesting
225 things to syslog.  You may have to turn on logging of \fIdebug\fR-level
226 messages for complete diagnosis.
227
228 .SH AUTHORS
229 \fBpppoe\fR was written by David F. Skoll <dfs@roaringpenguin.com>,
230 with much inspiration from an earlier version by Luke Stras.
231
232 The \fBpppoe\fR home page is \fIhttp://www.roaringpenguin.com/pppoe/\fR.
233
234 .SH SEE ALSO
235 pppoe-start(8), pppoe-stop(8), pppoe-connect(8), pppd(8), pppoe.conf(5), pppoe-setup(8), pppoe-status(8), pppoe-sniff(8), pppoe-server(8), pppoe-relay(8)
236
237
1	.\" LIC: GPL
2	.TH PPPOE 8 "3 July 2000"
3	.UC 4
4	.SH NAME
5	pppoe \- user-space PPPoE client.
6	.SH SYNOPSIS
7	.B pppd pty 'pppoe \fR[\fIpppoe_options\fR]\fB' \fR[\fIpppd_options\fR]
8	.P
9	.B pppoe -A \fR[\fIpppoe_options\fR]
10	.SH DESCRIPTION
11	\fBpppoe\fR is a user-space client for PPPoE (Point-to-Point Protocol
12	over Ethernet) for Linux and other UNIX systems. \fBpppoe\fR works in
13	concert with the \fBpppd\fR PPP daemon to provide a PPP connection
14	over Ethernet, as is used by many DSL service providers.
15
16	.SH OPTIONS
17	.TP
18	.B \-I \fIinterface\fR
19	The \fB\-I\fR option specifies the Ethernet interface to use. Under Linux,
20	it is typically \fIeth0\fR or \fIeth1\fR. The interface should be "up"
21	before you start \fBpppoe\fR, but should \fInot\fR be configured to have
22	an IP address.
23
24	.TP
25	.B \-T \fItimeout\fR
26	The \fB\-T\fR option causes \fBpppoe\fR to exit if no session traffic
27	is detected for \fItimeout\fR seconds. I recommend that you use this
28	option as an extra safety measure, but if you do, you should make sure
29	that PPP generates enough traffic so the timeout will normally not be
30	triggered. The best way to do this is to use the
31	\fIlcp-echo-interval\fR option to \fBpppd\fR. You should set the
32	PPPoE timeout to be about four times the LCP echo interval.
33
34	.TP
35	.B \-D \fIfile_name\fR
36	The \fB\-D\fR option causes every packet to be dumped to the specified
37	\fIfile_name\fR. This is intended for debugging only; it produces huge
38	amounts of output and greatly reduces performance.
39
40	.TP
41	.B \-V
42	The \fB\-V\fR option causes \fBpppoe\fR to print its version number and
43	exit.
44
45	.TP
46	.B \-A
47	The \fB\-A\fR option causes \fBpppoe\fR to send a PADI packet and then print
48	the names of access concentrators in each PADO packet it receives. Do not
49	use this option in conjunction with \fBpppd\fR; the \fB\-A\fR option is
50	meant to be used interactively to give interesting information about the
51	access concentrator.
52
53	.TP
54	.B \-S \fIservice_name\fR
55	Specifies the desired service name. \fBpppoe\fR will only initiate sessions
56	with access concentrators which can provide the specified service. In
57	most cases, you should \fInot\fR specify this option. Use it only if you
58	know that there are multiple access concentrators or know that you need a
59	specific service name.
60
61	.TP
62	.B \-C \fIac_name\fR
63	Specifies the desired access concentrator name. \fBpppoe\fR will only
64	initiate sessions with the specified access concentrator. In
65	most cases, you should \fInot\fR specify this option. Use it only if you
66	know that there are multiple access concentrators. If both the
67	\fB\-S\fR and \fB\-C\fR options are specified, they must \fIboth\fR match
68	for \fBpppoe\fR to initiate a session.
69
70	.TP
71	.B \-U
72	Causes \fBpppoe\fR to use the Host-Uniq tag in its discovery packets. This
73	lets you run multiple \fBpppoe\fR daemons without having their discovery
74	packets interfere with one another. You must supply this option to
75	\fIall\fR \fBpppoe\fR daemons if you intend to run multiple daemons
76	simultaneously.
77
78	.TP
79	.B \-s
80	Causes \fBpppoe\fR to use \fIsynchronous\fR PPP encapsulation. If you
81	use this option, then you \fImust\fR use the \fBsync\fR option with
82	\fBpppd\fR. You are encouraged to use this option if it works, because
83	it greatly reduces the CPU overhead of \fBpppoe\fR. However, it
84	MAY be unreliable on slow machines -- there is a race condition between
85	pppd writing data and pppoe reading it. For this reason, the default
86	setting is asynchronous. If you encounter bugs or crashes with Synchronous
87	PPP, turn it off -- don't e-mail me for support!
88
89	.TP
90	.B \-m \fIMSS\fR
91	Causes \fBpppoe\fR to \fIclamp\fR the TCP maximum segment size at the specified
92	value. Because of PPPoE overhead, the maximum segment size for PPPoE is
93	smaller than for normal Ethernet encapsulation. This could cause problems
94	for machines on a LAN behind a gateway using PPPoE. If you have a LAN
95	behind a gateway, and the gateway connects to the Internet using PPPoE,
96	you are strongly recommended to use a \fB\-m 1412\fR option. This avoids
97	having to set the MTU on all the hosts on the LAN.
98
99	.TP
100	.B \-p \fIfile\fR
101	Causes \fBpppoe\fR to write its process-ID to the specified file. This
102	can be used to locate and kill \fBpppoe\fR processes.
103
104	.TP
105	.B \-e \fIsess:mac\fR
106	Causes \fBpppoe\fR to skip the discovery phase and move directly to the
107	session phase. The session is given by \fIsess\fR and the MAC address of
108	the peer by \fImac\fR. This mode is \fInot\fR meant for normal use; it
109	is designed only for \fBpppoe-server\fR(8).
110
111	.TP
112	.B \-n
113	Causes \fBpppoe\fR not to open a discovery socket. This mode is
114	\fInot\fR meant for normal use; it is designed only for
115	\fBpppoe-server\fR(8).
116
117	.TP
118	.B \-k
119	Causes \fBpppoe\fR to terminate an existing session by sending a PADT frame,
120	and then exit. You must use the \fB\-e\fR option in conjunction with this
121	option to specify the session to kill. This may be useful for killing
122	sessions when a buggy peer does not realize the session has ended.
123
124	.TP
125	.B \-d
126	Causes \fBpppoe\fR to perform discovery and then exit, after printing
127	session information to standard output. The session information is printed
128	in exactly the format expected by the \fB\-e\fR option. This option lets
129	you initiate a PPPoE discovery, perform some other work, and then start
130	the actual PPP session. \fIBe careful\fR; if you use this option in a loop,
131	you can create many sessions, which may annoy your peer.
132
133	.TP
134	.B \-f disc:sess
135	The \fB\-f\fR option sets the Ethernet frame types for PPPoE discovery
136	and session frames. The types are specified as hexadecimal numbers
137	separated by a colon. Standard PPPoE uses frame types 8863:8864.
138	\fIYou should not use this option\fR unless you are absolutely sure
139	the peer you are dealing with uses non-standard frame types. If your
140	ISP uses non-standard frame types, complain!
141
142	.TP
143	.B \-h
144	The \fB\-h\fR option causes \fBpppoe\fR to print usage information and
145	exit.
146
147	.SH PPPOE BACKGROUND
148
149	PPPoE (Point-to-Point Protocol over Ethernet) is described in RFC 2516
150	and is a protocol which allows the session abstraction to be maintained
151	over bridged Ethernet networks.
152
153	PPPoE works by encapsulating PPP frames in Ethernet frames. The protocol
154	has two distinct stages: The \fIdiscovery\fR and the \fIsession\fR stage.
155
156	In the discovery stage, the host broadcasts a special PADI (PPPoE
157	Active Discovery Initiation) frame to discover any \fIaccess
158	concentrators\fR. The access concentrators (typically, only one
159	access concentrator) reply with PADO (PPPoE Active Discovery Offer)
160	packets, announcing their presence and the services they offer. The
161	host picks one of the access concentrators and transmits a PADR (PPPoE
162	Active Discovery Request) packet, asking for a session. The access
163	concentrator replies with a PADS (PPPoE Active Discovery
164	Session-Confirmation) packet. The protocol then moves to the session stage.
165
166	In the session stage, the host and access concentrator exchange PPP frames
167	embedded in Ethernet frames. The normal Ethernet MTU is 1500 bytes, but
168	the PPPoE overhead plus two bytes of overhead for the encapsulated PPP
169	frame mean that the MTU of the PPP interface is at most 1492 bytes.
170	This causes \fIall kinds of problems\fR if you are using a Linux machine
171	as a firewall and interfaces behind the firewall have an MTU greater than
172	1492. In fact, to be safe, I recommend setting the MTU of machines
173	behind the firewall to 1412, to allow for worst-case TCP and IP options
174	in their respective headers.
175
176	Normally, PPP uses the Link Control Protocol (LCP) to shut down a PPP
177	link. However, the PPPoE specification allows the link to be shut down
178	with a special PADT (PPPoE Active Discovery Terminate) packet. This client
179	recognizes this packet and will correctly terminate if a terminate request
180	is received for the PPP session.
181
182	.SH DESIGN GOALS
183
184	My design goals for this PPPoE client were as follows, in descending order
185	of importance:
186
187	.TP
188	.B o
189	It must work.
190
191	.TP
192	.B o
193	It must be a user-space program and not a kernel patch.
194
195	.TP
196	.B o
197	The code must be easy to read and maintain.
198
199	.TP
200	.B o
201	It must be fully compliant with RFC 2516, the proposed PPPoE standard.
202
203	.TP
204	.B o
205	It must never hang up forever -- if the connection is broken, it must
206	detect this and exit, allowing a wrapper script to restart the connection.
207
208	.TP
209	.B o
210	It must be fairly efficient.
211
212	.P
213	I believe I have achieved all of these goals, but (of course) am open
214	to suggestions, patches and ideas. See my home page,
215	http://www.roaringpenguin.com, for contact information.
216
217	.SH NOTES
218
219	For best results, you must give \fBpppd\fR an mtu option of
220	1492. I have observed problems with excessively-large frames
221	unless I set this option. Also, if \fBpppoe\fR is running on a firewall
222	machine, all machines behind the firewall should have MTU's of 1412.
223
224	If you have problems, check your system logs. \fBpppoe\fR logs interesting
225	things to syslog. You may have to turn on logging of \fIdebug\fR-level
226	messages for complete diagnosis.
227
228	.SH AUTHORS
229	\fBpppoe\fR was written by David F. Skoll <dfs@roaringpenguin.com>,
230	with much inspiration from an earlier version by Luke Stras.
231
232	The \fBpppoe\fR home page is \fIhttp://www.roaringpenguin.com/pppoe/\fR.
233
234	.SH SEE ALSO
235	pppoe-start(8), pppoe-stop(8), pppoe-connect(8), pppd(8), pppoe.conf(5), pppoe-setup(8), pppoe-status(8), pppoe-sniff(8), pppoe-server(8), pppoe-relay(8)
236
237