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.Dd November 8, 1999 27.Dt PPPOED 8 28.Os 29.Sh NAME 30.Nm pppoed 31.Nd handle incoming PPP over Ethernet connections 32.Sh SYNOPSIS 33.Nm 34.Op Fl Fd\& 35.Op Fl P Ar pidfile 36.Op Fl a Ar name 37.Op Fl e Ar exec | Fl l Ar label 38.Op Fl n Ar ngdebug 39.Op Fl p Ar provider 40.Ar interface 41.Sh DESCRIPTION 42The 43.Nm 44utility listens to the given 45.Ar interface 46for PPP over Ethernet (PPPoE) service request packets, and actions them 47by negotiating a session then invoking a 48.Xr ppp 8 49program. 50The negotiation is implemented by the 51.Dq pppoe 52netgraph node. 53See 54.Xr ng_pppoe 4 55for details. 56.Pp 57The 58.Nm 59utility 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, its 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 203.Sh HISTORY 204The 205.Nm 206utility was written by 207.An Brian Somers Aq Mt brian@Awfulhak.org 208and first appeared in 209.Fx 3.4 . 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. 218