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 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 HISTORY 205The 206.Nm 207program was written by 208.An Brian Somers Aq brian@Awfulhak.org 209and first appeared in 210.Fx 3.4 . 211.Sh BUGS 212If another netgraph node is using the given interface, 213.Nm 214will fail to start. 215This is because 216.Xr netgraph 4 217does not currently allow node chaining. 218This may change in the future. 219