libexec/bootpd/bootpd.8

   1 .\" Copyright (c) 1988, 1989, 1991 Carnegie Mellon University
   2 .\"
   3 .\" $FreeBSD$
   4 .\"
   5 .Dd February 10, 2004
   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 t Ar timeout
 107 Specify the
 108 .Ar timeout
 109 value (in minutes) that a
 110 .Nm
 111 or
 112 .Nm bootpgw
 113 process will wait for a BOOTP packet before exiting.
 114 If no packets are received for
 115 .Ar timeout
 116 minutes, then the program will exit.
 117 A timeout value of zero means "run forever".
 118 In standalone mode, this option is forced to zero.
 119 .It Fl d Ar debug-level
 120 Set the
 121 .Ar debug-level
 122 variable that controls the amount of debugging messages generated.
 123 For example,
 124 .Fl d Ns 4
 125 or
 126 .Fl d
 127 4 will set the debugging level to 4.
 128 For compatibility with older versions of
 129 .Nm ,
 130 omitting the numeric parameter (i.e., just
 131 .Fl d )
 132 will simply increment the debug level by one.
 133 .It Fl c Ar chdir-path
 134 Set the current directory used by
 135 .Nm
 136 while checking the existence and size of client boot files.
 137 This is
 138 useful when client boot files are specified as relative pathnames, and
 139 .Nm
 140 needs to use the same current directory as the TFTP server
 141 (typically
 142 .Pa /tftpboot ) .
 143 This option is not recognized by
 144 .Nm bootpgw .
 145 .It Fl h Ar hostname
 146 Specify the hostname corresponding to the IP address to listen on.
 147 By default,
 148 .Nm
 149 listens on the IP address corresponding to the machine's hostname, as
 150 returned by
 151 .Xr gethostname 3 .
 152 .It Fl i
 153 Force inetd mode.
 154 This option is obsolete, but remains for
 155 compatibility with older versions of
 156 .Nm .
 157 .It Fl s
 158 Force standalone mode.
 159 This option is obsolete, but remains for
 160 compatibility with older versions of
 161 .Nm .
 162 .It Ar bootptab
 163 Specify the name of the configuration file from which
 164 .Nm
 165 loads its database of known clients and client options
 166 .No ( Nm
 167 only).
 168 .It Ar dumpfile
 169 Specify the name of the file that
 170 .Nm
 171 will dump its internal database into when it receives a
 172 SIGUSR1 signal
 173 .No ( Nm
 174 only).
 175 This option is only recognized if
 176 .Nm
 177 was compiled with the -DDEBUG flag.
 178 .It Ar server
 179 Specify the name of a BOOTP server to which
 180 .Nm bootpgw
 181 will forward all BOOTREQUEST packets it receives
 182 .Pf ( Nm bootpgw
 183 only).
 184 .El
 185 .Sh OPERATION
 186 Both
 187 .Nm
 188 and
 189 .Nm bootpgw
 190 operate similarly in that both listen for any packets sent to the
 191 .Em bootps
 192 port, and both simply forward any BOOTREPLY packets.
 193 They differ in their handling of BOOTREQUEST packets.
 194 .Pp
 195 When
 196 .Nm bootpgw
 197 is started, it determines the address of a BOOTP server
 198 whose name is provided as a command line parameter.
 199 When
 200 .Nm bootpgw
 201 receives a BOOTREQUEST packet, it sets the "gateway address"
 202 and "hop count" fields in the packet and forwards the packet
 203 to the BOOTP server at the address determined earlier.
 204 Requests are forwarded only if they indicate that
 205 the client has been waiting for at least three seconds.
 206 .Pp
 207 When
 208 .Nm
 209 is started it reads a configuration file, (normally
 210 .Pa /etc/bootptab )
 211 that initializes the internal database of known clients and client
 212 options.
 213 This internal database is reloaded
 214 from the configuration file when
 215 .Nm
 216 receives a hangup signal (SIGHUP) or when it discovers that the
 217 configuration file has changed.
 218 .Pp
 219 When
 220 .Nm
 221 receives a BOOTREQUEST packet, it
 222 .\" checks the modification time of the
 223 .\" configuration file and reloads the database if necessary.  Then it
 224 looks for a database entry matching the client request.
 225 If the client is known,
 226 .Nm
 227 composes a BOOTREPLY packet using the database entry found above,
 228 and sends the reply to the client (possibly using a gateway).
 229 If the client is unknown, the request is discarded
 230 (with a notice if debug > 0).
 231 .Pp
 232 If
 233 .Nm
 234 is compiled with the -DDEBUG option, receipt of a SIGUSR1 signal causes
 235 it to dump its internal database to the file
 236 .Pa /tmp/bootpd.dump
 237 or the dumpfile specified as a command line parameter.
 238 .Pp
 239 During initialization, both programs
 240 determine the UDP port numbers to be used by calling
 241 .Xr getservbyname 3
 242 (which normally uses
 243 .Pa /etc/services ) .
 244 Two service names (and port numbers) are used:
 245 .Pp
 246 .Dl bootps BOOTP Server listening port
 247 .Dl bootpc BOOTP Client destination port
 248 .Pp
 249 If the port numbers cannot be determined using
 250 .Xr getservbyname 3
 251 then the values default to bootps=67 and bootpc=68.
 252 .Sh FILES
 253 .Bl -tag -width /tmp/bootpd.dump -compact
 254 .It Pa /etc/bootptab
 255 Database file read by
 256 .Nm .
 257 .It Pa /tmp/bootpd.dump
 258 Debugging dump file created by
 259 .Nm .
 260 .It Pa /etc/services
 261 Internet service numbers.
 262 .It Pa /tftpboot
 263 Current directory typically used by the TFTP server and
 264 .Nm .
 265 .El
 266 .Sh BUGS
 267 Individual host entries must not exceed 1024 characters.
 268 .Sh CREDITS
 269 This distribution is currently maintained by
 270 .An Walter L. Wimer Aq walt+@cmu.edu .
 271 .Pp
 272 The original BOOTP server was created by
 273 .An Bill Croft
 274 at Stanford University in January 1986.
 275 .Pp
 276 The current version of
 277 .Nm
 278 is primarily the work of
 279 .An David Kovar ,
 280 .An Drew D. Perkins ,
 281 and
 282 .An Walter L. Wimer ,
 283 at Carnegie Mellon University.
 284 .Pp
 285 Enhancements and bug-fixes have been contributed by:
 286 .Pp
 287 (in alphabetical order)
 288 .Pp
 289 .An -split
 290 .An Danny Backx Aq db@sunbim.be
 291 .An John Brezak Aq brezak@ch.hp.com
 292 .An Frank da Cruz Aq fdc@cc.columbia.edu
 293 .An David R. Linn Aq drl@vuse.vanderbilt.edu
 294 .An Jim McKim Aq mckim@lerc.nasa.gov
 295 .An Gordon W. Ross Aq gwr@mc.com
 296 .An Jason Zions Aq jazz@hal.com .
 297 .Sh "SEE ALSO"
 298 .Xr bootptab 5 ,
 299 .Xr inetd 8 ,
 300 .Xr tftpd 8
 301 .Pp
 302 DARPA Internet Request For Comments:
 303 .Bl -tag -width RFC1533 -compact
 304 .It RFC951
 305 Bootstrap Protocol
 306 .It RFC1532
 307 Clarifications and Extensions for the Bootstrap Protocol
 308 .It RFC1533
 309 DHCP Options and BOOTP Vendor Extensions
 310 .El