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