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