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