libexec/bootpd/bootpd.8

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