61894099c23ff2f8e6c5475125ee3a12c4b32754
[dragonfly.git] / libexec / pppoed / pppoed.8
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 $
27 .\"
28 .Dd November 8, 1999
29 .Dt PPPOED 8
30 .Os
31 .Sh NAME
32 .Nm pppoed
33 .Nd handle incoming PPP over Ethernet connections
34 .Sh SYNOPSIS
35 .Nm
36 .Op Fl Fd\&
37 .Op Fl P Ar pidfile
38 .Op Fl a Ar name
39 .Op Fl e Ar exec | Fl l Ar label
40 .Op Fl n Ar ngdebug
41 .Op Fl p Ar provider
42 .Ar interface
43 .Sh DESCRIPTION
44 The
45 .Nm
46 program listens to the given
47 .Ar interface
48 for PPP over Ethernet (PPPoE) service request packets, and actions them
49 by negotiating a session then invoking a
50 .Xr ppp 8
51 program.
52 The negotiation is implemented by the
53 .Dq pppoe
54 netgraph node.
55 See
56 .Xr ng_pppoe 4
57 for details.
58 .Pp
59 .Nm
60 will only offer services to clients requesting services from the given
61 .Ar provider ,
62 which is taken as an empty name if not provided.
63 If a provider name of
64 .Dq *
65 is given, any PPPoE requests will be offered service.
66 .Pp
67 The supplied
68 .Ar name
69 will be given as the access concentrator name when establishing the connection.
70 If no
71 .Ar name
72 is given, the current base hostname is used.
73 .Pp
74 After receiving a request (PADI) from the PPPoE netgraph node,
75 .Nm
76 .Xr fork 2 Ns s
77 a child process and returns to service further requests.
78 The child process offers service
79 (using
80 .Ar name )
81 and waits for a
82 .Dv SUCCESS
83 indication from the PPPoE node.
84 On receipt of the
85 .Dv SUCCESS
86 indication,
87 .Nm
88 will execute
89 .Pp
90 .D1 Ic exec Pa /usr/sbin/ppp Fl direct Ar label
91 .Pp
92 as a shell sub-process.
93 If
94 .Ar label
95 has not been specified, it defaults to
96 .Ar provider .
97 It is possible to specify another command using the
98 .Ar exec
99 argument.
100 This is mandatory if
101 .Ar provider
102 and
103 .Ar label
104 are not given.
105 The child process will have standard input and standard output
106 attached to the same
107 .Xr netgraph 4
108 data socket
109 (see
110 .Xr ng_socket 4 )
111 when started.
112 .Pp
113 The environment variables
114 .Ev HISMACADDR
115 and
116 .Ev ACNAME
117 are made available to the child process and are set to the MAC address of
118 the peer and the name of the AC respectively.
119 .Pp
120 Upon invocation,
121 .Nm
122 will attach a
123 .Dq pppoe
124 netgraph node to the relevant
125 .Dq ether
126 node using
127 .Dq Ar interface Ns \&:
128 as the node name, and then connect that
129 .Dq pppoe
130 node to a local
131 .Dq socket
132 node.
133 If the
134 .Fl F
135 option has not been given,
136 .Nm
137 will then go into the background and disassociate itself from the controlling
138 terminal.
139 When the
140 .Fl F
141 option is given,
142 .Nm
143 stays in the foreground.
144 .Pp
145 If the
146 .Fl d
147 option is given, additional diagnostics are provided (see the
148 .Sx DIAGNOSTICS
149 section below).
150 If the
151 .Fl n
152 option is given,
153 .Fn NgSetDebug
154 is called with an argument of
155 .Ar ngdebug .
156 .Pp
157 If
158 .Ar pidfile
159 is given,
160 .Nm
161 will write its process ID to this file on startup.
162 .Sh DIAGNOSTICS
163 After creating the necessary
164 .Xr netgraph 4
165 nodes as described above,
166 .Nm
167 uses
168 .Xr syslogd 8
169 to report all incoming connections.
170 If the
171 .Fl d
172 option is given,
173 .Nm
174 will report on the child processes creation of a new netgraph socket, it's
175 service offer and the invocation of the
176 .Xr ppp 8
177 program.
178 If the
179 .Fl n
180 option is given, netgraph diagnostic messages are also redirected to
181 .Xr syslogd 8 .
182 .Pp
183 It is sometimes useful to add the following to
184 .Pa /etc/syslog.conf :
185 .Bd -literal -offset indent
186 !pppoed
187 *.*                             /var/log/pppoed.log
188 .Ed
189 .Pp
190 and the following to
191 .Pa /etc/newsyslog.conf :
192 .Pp
193 .Dl "/var/log/pppoed.log                        640  3     100  *     Z"
194 .Sh SEE ALSO
195 .Xr NgSetDebug 3 ,
196 .Xr netgraph 4 ,
197 .Xr ng_ether 4 ,
198 .Xr ng_pppoe 4 ,
199 .Xr ng_socket 4 ,
200 .Xr syslog.conf 5 ,
201 .Xr ppp 8 ,
202 .Xr syslogd 8
203 .Sh HISTORY
204 The
205 .Nm
206 program was written by
207 .An Brian Somers Aq Mt brian@Awfulhak.org
208 and first appeared in
209 .Fx 3.4 .
210 .Sh BUGS
211 If another netgraph node is using the given interface,
212 .Nm
213 will fail to start.
214 This is because
215 .Xr netgraph 4
216 does not currently allow node chaining.
217 This may change in the future.