Collapse gd_astpending and gd_reqpri together into gd_reqflags. gd_reqflags
[dragonfly.git] / libexec / pppoed / pppoed.8
CommitLineData
984263bc
MD
1.\"-
2.\" Copyright (c) 1999-2001 Brian Somers <brian@Awfulhak.org>
3.\" All rights reserved.
4.\"
5.\" Redistribution and use in source and binary forms, with or without
6.\" modification, are permitted provided that the following conditions
7.\" are met:
8.\" 1. Redistributions of source code must retain the above copyright
9.\" notice, this list of conditions and the following disclaimer.
10.\" 2. Redistributions in binary form must reproduce the above copyright
11.\" notice, this list of conditions and the following disclaimer in the
12.\" documentation and/or other materials provided with the distribution.
13.\"
14.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
15.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
16.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
17.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
18.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
19.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
20.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
21.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
22.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
23.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
24.\" SUCH DAMAGE.
25.\"
26.\" $FreeBSD: src/libexec/pppoed/pppoed.8,v 1.2.6.11 2002/03/26 11:40:37 brian Exp $
1de703da 27.\" $DragonFly: src/libexec/pppoed/pppoed.8,v 1.2 2003/06/17 04:27:07 dillon Exp $
984263bc
MD
28.\"
29.Dd November 8, 1999
30.Dt PPPOED 8
31.Os
32.Sh NAME
33.Nm pppoed
34.Nd handle incoming PPP over Ethernet connections
35.Sh SYNOPSIS
36.Nm
37.Op Fl Fd\&
38.Op Fl P Ar pidfile
39.Op Fl a Ar name
40.Op Fl e Ar exec | Fl l Ar label
41.Op Fl n Ar ngdebug
42.Op Fl p Ar provider
43.Ar interface
44.Sh DESCRIPTION
45The
46.Nm
47program listens to the given
48.Ar interface
49for PPP over Ethernet (PPPoE) service request packets, and actions them
50by negotiating a session then invoking a
51.Xr ppp 8
52program.
53The negotiation is implemented by the
54.Dq pppoe
55netgraph node.
56See
57.Xr ng_pppoe 4
58for details.
59.Pp
60.Nm
61will only offer services to clients requesting services from the given
62.Ar provider ,
63which is taken as an empty name if not provided.
64If a provider name of
65.Dq *
66is given, any PPPoE requests will be offered service.
67.Pp
68The supplied
69.Ar name
70will be given as the access concentrator name when establishing the connection.
71If no
72.Ar name
73is given, the current base hostname is used.
74.Pp
75After receiving a request (PADI) from the PPPoE netgraph node,
76.Nm
77.Xr fork 2 Ns s
78a child process and returns to service further requests.
79The child process offers service
80(using
81.Ar name )
82and waits for a
83.Dv SUCCESS
84indication from the PPPoE node.
85On receipt of the
86.Dv SUCCESS
87indication,
88.Nm
89will execute
90.Pp
91.D1 Ic exec Pa /usr/sbin/ppp Fl direct Ar label
92.Pp
93as a shell sub-process.
94If
95.Ar label
96has not been specified, it defaults to
97.Ar provider .
98It is possible to specify another command using the
99.Ar exec
100argument.
101This is mandatory if
102.Ar provider
103and
104.Ar label
105are not given.
106The child process will have standard input and standard output
107attached to the same
108.Xr netgraph 4
109data socket
110(see
111.Xr ng_socket 4 )
112when started.
113.Pp
114The environment variables
115.Ev HISMACADDR
116and
117.Ev ACNAME
118are made available to the child process and are set to the MAC address of
119the peer and the name of the AC respectively.
120.Pp
121Upon invocation,
122.Nm
123will attach a
124.Dq pppoe
125netgraph node to the relevant
126.Dq ether
127node using
128.Dq Ar interface Ns \&:
129as the node name, and then connect that
130.Dq pppoe
131node to a local
132.Dq socket
133node.
134If the
135.Fl F
136option has not been given,
137.Nm
138will then go into the background and disassociate itself from the controlling
139terminal.
140When the
141.Fl F
142option is given,
143.Nm
144stays in the foreground.
145.Pp
146If the
147.Fl d
148option is given, additional diagnostics are provided (see the
149.Sx DIAGNOSTICS
150section below).
151If the
152.Fl n
153option is given,
154.Fn NgSetDebug
155is called with an argument of
156.Ar ngdebug .
157.Pp
158If
159.Ar pidfile
160is given,
161.Nm
162will write its process ID to this file on startup.
163.Sh DIAGNOSTICS
164After creating the necessary
165.Xr netgraph 4
166nodes as described above,
167.Nm
168uses
169.Xr syslogd 8
170to report all incoming connections.
171If the
172.Fl d
173option is given,
174.Nm
175will report on the child processes creation of a new netgraph socket, it's
176service offer and the invocation of the
177.Xr ppp 8
178program.
179If the
180.Fl n
181option is given, netgraph diagnostic messages are also redirected to
182.Xr syslogd 8 .
183.Pp
184It is sometimes useful to add the following to
185.Pa /etc/syslog.conf :
186.Bd -literal -offset indent
187!pppoed
188*.* /var/log/pppoed.log
189.Ed
190.Pp
191and the following to
192.Pa /etc/newsyslog.conf :
193.Pp
194.Dl "/var/log/pppoed.log 640 3 100 * Z"
195.Sh SEE ALSO
196.Xr NgSetDebug 3 ,
197.Xr netgraph 4 ,
198.Xr ng_ether 4 ,
199.Xr ng_pppoe 4 ,
200.Xr ng_socket 4 ,
201.Xr syslog.conf 5 ,
202.Xr ppp 8 ,
203.Xr syslogd 8
204.Sh BUGS
205If another netgraph node is using the given interface,
206.Nm
207will fail to start.
208This is because
209.Xr netgraph 4
210does not currently allow node chaining.
211This may change in the future.
212.Sh HISTORY
213The
214.Nm
215program was written by
216.An Brian Somers Aq brian@Awfulhak.org
217and first appeared in
218.Fx 3.4 .