libexec/bootpd/bootpd.8

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