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