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