libexec/bootpd/bootpd.8

   1 .\" Copyright (c) 1988, 1989, 1991 Carnegie Mellon University
   2 .\"
   3 .\" $FreeBSD: src/libexec/bootpd/bootpd.8,v 1.10.2.5 2001/07/22 12:07:21 dd Exp $
   4 .\" $DragonFly: src/libexec/bootpd/bootpd.8,v 1.2 2003/06/17 04:27:07 dillon Exp $
   5 .\"
   6 .Dd November 6, 1993
   7 .Dt BOOTPD 8
   8 .Os
   9 .Sh NAME
  10 .Nm bootpd , bootpgw
  11 .Nd Internet Boot Protocol server/gateway
  12 .Sh SYNOPSIS
  13 .Nm
  14 .Op Fl i
  15 .Op Fl s
  16 .Op Fl t Ar timeout
  17 .Op Fl d Ar level
  18 .Op Fl c Ar chdir-path
  19 .Oo
  20 .Ar bootptab
  21 .Op Ar dumpfile
  22 .Oc
  23 .Nm bootpgw
  24 .Op Fl i
  25 .Op Fl s
  26 .Op Fl t Ar timeout
  27 .Op Fl d Ar level
  28 .Ar server
  29 .Sh DESCRIPTION
  30 .Nm Bootpd
  31 implements an Internet Bootstrap Protocol (BOOTP) server as defined in
  32 RFC951, RFC1532, and RFC1533.
  33 .Nm Bootpgw
  34 implements a simple BOOTP gateway which can be used to forward
  35 requests and responses between clients on one subnet and a
  36 BOOTP server (i.e.\&
  37 .Nm )
  38 on another subnet. While either
  39 .Nm
  40 or
  41 .Nm bootpgw
  42 will forward BOOTREPLY packets, only
  43 .Nm bootpgw
  44 will forward BOOTREQUEST packets.
  45 .Pp
  46 One host on each network segment is normally configured to run either
  47 .Nm
  48 or
  49 .Nm bootpgw
  50 from
  51 .Xr inetd 8
  52 by including one of the following lines in the file
  53 .Pa /etc/inetd.conf :
  54 .Pp
  55 .Dl bootps dgram udp wait root /usr/libexec/bootpd bootpd /etc/bootptab
  56 .Dl bootps dgram udp wait root /usr/libexec/bootpgw bootpgw server
  57 .Pp
  58 This mode of operation is referred to as "inetd mode" and causes
  59 .Nm
  60 (or
  61 .Nm bootpgw )
  62 to be started only when a boot request arrives.  If it does not
  63 receive another packet within fifteen minutes of the last one
  64 it received, it will exit to conserve system resources.  The
  65 .Fl t
  66 option controls this timeout (see OPTIONS).
  67 .Pp
  68 It is also possible to run
  69 .Nm
  70 (or
  71 .Nm bootpgw )
  72 in "standalone mode" (without
  73 .Xr inetd 8 )
  74 by simply invoking it from a shell like any other regular command.
  75 Standalone mode is particularly useful when
  76 .Nm
  77 is used with a large configuration database, where the start up
  78 delay might otherwise prevent timely response to client requests.
  79 (Automatic start up in standalone mode can be done by invoking
  80 .Nm
  81 from within
  82 .Pa /etc/rc.local ,
  83 for example.)
  84 Standalone mode is less useful for
  85 .Nm bootpgw
  86 which
  87 has very little start up delay because
  88 it does not read a configuration file.
  89 .Pp
  90 Either program automatically detects whether it was invoked from inetd
  91 or from a shell and automatically selects the appropriate mode.
  92 The
  93 .Fl s
  94 or
  95 .Fl i
  96 option may be used to force standalone or inetd mode respectively
  97 (see OPTIONS).
  98 .Sh OPTIONS
  99 The following options are available:
 100 .Bl -tag -width indent
 101 .It Fl t Ar timeout
 102 Specify the
 103 .Ar timeout
 104 value (in minutes) that a
 105 .Nm
 106 or
 107 .Nm bootpgw
 108 process will wait for a BOOTP packet before exiting.
 109 If no packets are received for
 110 .Ar timeout
 111 minutes, then the program will exit.
 112 A timeout value of zero means "run forever".
 113 In standalone mode, this option is forced to zero.
 114 .It Fl d Ar debug-level
 115 Set the
 116 .Ar debug-level
 117 variable that controls the amount of debugging messages generated.
 118 For example,
 119 .Fl d Ns 4
 120 or
 121 .Fl d
 122 4 will set the debugging level to 4.
 123 For compatibility with older versions of
 124 .Nm ,
 125 omitting the numeric parameter (i.e. just
 126 .Fl d Ns )
 127 will simply increment the debug level by one.
 128 .It Fl c Ar chdir-path
 129 Set the current directory used by
 130 .Nm
 131 while checking the existence and size of client boot files.  This is
 132 useful when client boot files are specified as relative pathnames, and
 133 .Nm
 134 needs to use the same current directory as the TFTP server
 135 (typically
 136 .Pa /tftpboot ) .
 137 This option is not recognized by
 138 .Nm bootpgw .
 139 .It Fl i
 140 Force inetd mode.  This option is obsolete, but remains for
 141 compatibility with older versions of
 142 .Nm .
 143 .It Fl s
 144 Force standalone mode.  This option is obsolete, but remains for
 145 compatibility with older versions of
 146 .Nm .
 147 .It Ar bootptab
 148 Specify the name of the configuration file from which
 149 .Nm
 150 loads its database of known clients and client options
 151 .No ( Nm
 152 only).
 153 .It Ar dumpfile
 154 Specify the name of the file that
 155 .Nm
 156 will dump its internal database into when it receives a
 157 SIGUSR1 signal
 158 .No ( Nm
 159 only). This option is only recognized if
 160 .Nm
 161 was compiled with the -DDEBUG flag.
 162 .It Ar server
 163 Specify the name of a BOOTP server to which
 164 .Nm bootpgw
 165 will forward all BOOTREQUEST packets it receives
 166 .Pf ( Nm bootpgw
 167 only).
 168 .El
 169 .Sh OPERATION
 170 Both
 171 .Nm
 172 and
 173 .Nm bootpgw
 174 operate similarly in that both listen for any packets sent to the
 175 .Em bootps
 176 port, and both simply forward any BOOTREPLY packets.
 177 They differ in their handling of BOOTREQUEST packets.
 178 .Pp
 179 When
 180 .Nm bootpgw
 181 is started, it determines the address of a BOOTP server
 182 whose name is provided as a command line parameter.  When
 183 .Nm bootpgw
 184 receives a BOOTREQUEST packet, it sets the "gateway address"
 185 and "hop count" fields in the packet and forwards the packet
 186 to the BOOTP server at the address determined earlier.
 187 Requests are forwarded only if they indicate that
 188 the client has been waiting for at least three seconds.
 189 .Pp
 190 When
 191 .Nm
 192 is started it reads a configuration file, (normally
 193 .Pa /etc/bootptab )
 194 that initializes the internal database of known clients and client
 195 options.  This internal database is reloaded
 196 from the configuration file when
 197 .Nm
 198 receives a hangup signal (SIGHUP) or when it discovers that the
 199 configuration file has changed.
 200 .Pp
 201 When
 202 .Nm
 203 receives a BOOTREQUEST packet, it
 204 .\" checks the modification time of the
 205 .\" configuration file and reloads the database if necessary.  Then it
 206 looks for a database entry matching the client request.
 207 If the client is known,
 208 .Nm
 209 composes a BOOTREPLY packet using the database entry found above,
 210 and sends the reply to the client (possibly using a gateway).
 211 If the client is unknown, the request is discarded
 212 (with a notice if debug > 0).
 213 .Pp
 214 If
 215 .Nm
 216 is compiled with the -DDEBUG option, receipt of a SIGUSR1 signal causes
 217 it to dump its internal database to the file
 218 .Pa /tmp/bootpd.dump
 219 or the dumpfile specified as a command line parameter.
 220 .Pp
 221 During initialization, both programs
 222 determine the UDP port numbers to be used by calling
 223 .Xr getservbyname 3
 224 (which normally uses
 225 .Pa /etc/services ) .
 226 Two service names (and port numbers) are used:
 227 .Pp
 228 .Dl bootps BOOTP Server listening port
 229 .Dl bootpc BOOTP Client destination port
 230 .Pp
 231 If the port numbers cannot be determined using
 232 .Xr getservbyname 3
 233 then the values default to bootps=67 and bootpc=68.
 234 .Sh FILES
 235 .Bl -tag -width /tmp/bootpd.dump -compact
 236 .It Pa /etc/bootptab
 237 Database file read by
 238 .Nm .
 239 .It Pa /tmp/bootpd.dump
 240 Debugging dump file created by
 241 .Nm .
 242 .It Pa /etc/services
 243 Internet service numbers.
 244 .It Pa /tftpboot
 245 Current directory typically used by the TFTP server and
 246 .Nm .
 247 .El
 248 .Sh BUGS
 249 Individual host entries must not exceed 1024 characters.
 250 .Sh CREDITS
 251 This distribution is currently maintained by
 252 .An Walter L. Wimer Aq walt+@cmu.edu .
 253 .Pp
 254 The original BOOTP server was created by
 255 .An Bill Croft
 256 at Stanford University in January 1986.
 257 .Pp
 258 The current version of
 259 .Nm
 260 is primarily the work of
 261 .An David Kovar ,
 262 .An Drew D. Perkins ,
 263 and
 264 .An Walter L. Wimer ,
 265 at Carnegie Mellon University.
 266 .Pp
 267 Enhancements and bug-fixes have been contributed by:
 268 .Pp
 269 (in alphabetical order)
 270 .Pp
 271 .An -split
 272 .An Danny Backx Aq db@sunbim.be
 273 .An John Brezak Aq brezak@ch.hp.com
 274 .An Frank da Cruz Aq fdc@cc.columbia.edu
 275 .An David R. Linn Aq drl@vuse.vanderbilt.edu
 276 .An Jim McKim Aq mckim@lerc.nasa.gov
 277 .An Gordon W. Ross Aq gwr@mc.com
 278 .An Jason Zions Aq jazz@hal.com .
 279 .Sh "SEE ALSO"
 280 .Xr bootptab 5 ,
 281 .Xr inetd 8 ,
 282 .Xr tftpd 8
 283 .Pp
 284 DARPA Internet Request For Comments:
 285 .Bl -tag -width RFC1533 -compact
 286 .It RFC951
 287 Bootstrap Protocol
 288 .It RFC1532
 289 Clarifications and Extensions for the Bootstrap Protocol
 290 .It RFC1533
 291 DHCP Options and BOOTP Vendor Extensions
 292 .El