libexec/pppoed/pppoed.8

   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.