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.6 2008/05/09 20:31:04 swildner Exp $
   5 .\"
   6 .Dd November 6, 1993
   7 .Dt BOOTPD 8
   8 .Os
   9 .Sh NAME
  10 .Nm bootpd ,
  11 .Nm bootpgw
  12 .Nd Internet Boot Protocol server/gateway
  13 .Sh SYNOPSIS
  14 .Nm
  15 .Op Fl i
  16 .Op Fl s
  17 .Op Fl t Ar timeout
  18 .Op Fl d Ar level
  19 .Op Fl c Ar chdir-path
  20 .Oo
  21 .Ar bootptab
  22 .Op Ar dumpfile
  23 .Oc
  24 .Nm bootpgw
  25 .Op Fl i
  26 .Op Fl s
  27 .Op Fl t Ar timeout
  28 .Op Fl d Ar level
  29 .Ar server
  30 .Sh DESCRIPTION
  31 .Nm Bootpd
  32 implements an Internet Bootstrap Protocol (BOOTP) server as defined in
  33 RFC 951, RFC 1532, and RFC 1533.
  34 .Nm Bootpgw
  35 implements a simple BOOTP gateway which can be used to forward
  36 requests and responses between clients on one subnet and a
  37 BOOTP server (i.e.\&
  38 .Nm )
  39 on another subnet. While either
  40 .Nm
  41 or
  42 .Nm bootpgw
  43 will forward BOOTREPLY packets, only
  44 .Nm bootpgw
  45 will forward BOOTREQUEST packets.
  46 .Pp
  47 One host on each network segment is normally configured to run either
  48 .Nm
  49 or
  50 .Nm bootpgw
  51 from
  52 .Xr inetd 8
  53 by including one of the following lines in the file
  54 .Pa /etc/inetd.conf :
  55 .Pp
  56 .Dl bootps dgram udp wait root /usr/libexec/bootpd bootpd /etc/bootptab
  57 .Dl bootps dgram udp wait root /usr/libexec/bootpgw bootpgw server
  58 .Pp
  59 This mode of operation is referred to as "inetd mode" and causes
  60 .Nm
  61 (or
  62 .Nm bootpgw )
  63 to be started only when a boot request arrives.  If it does not
  64 receive another packet within fifteen minutes of the last one
  65 it received, it will exit to conserve system resources.  The
  66 .Fl t
  67 option controls this timeout (see OPTIONS).
  68 .Pp
  69 It is also possible to run
  70 .Nm
  71 (or
  72 .Nm bootpgw )
  73 in "standalone mode" (without
  74 .Xr inetd 8 )
  75 by simply invoking it from a shell like any other regular command.
  76 Standalone mode is particularly useful when
  77 .Nm
  78 is used with a large configuration database, where the start up
  79 delay might otherwise prevent timely response to client requests.
  80 (Automatic start up in standalone mode can be done by invoking
  81 .Nm
  82 from within
  83 .Pa /etc/rc.local ,
  84 for example.)
  85 Standalone mode is less useful for
  86 .Nm bootpgw
  87 which
  88 has very little start up delay because
  89 it does not read a configuration file.
  90 .Pp
  91 Either program automatically detects whether it was invoked from inetd
  92 or from a shell and automatically selects the appropriate mode.
  93 The
  94 .Fl s
  95 or
  96 .Fl i
  97 option may be used to force standalone or inetd mode respectively
  98 (see OPTIONS).
  99 .Sh OPTIONS
 100 The following options are available:
 101 .Bl -tag -width indent
 102 .It Fl t Ar timeout
 103 Specify the
 104 .Ar timeout
 105 value (in minutes) that a
 106 .Nm
 107 or
 108 .Nm bootpgw
 109 process will wait for a BOOTP packet before exiting.
 110 If no packets are received for
 111 .Ar timeout
 112 minutes, then the program will exit.
 113 A timeout value of zero means "run forever".
 114 In standalone mode, this option is forced to zero.
 115 .It Fl d Ar debug-level
 116 Set the
 117 .Ar debug-level
 118 variable that controls the amount of debugging messages generated.
 119 For example,
 120 .Fl d Ns 4
 121 or
 122 .Fl d
 123 4 will set the debugging level to 4.
 124 For compatibility with older versions of
 125 .Nm ,
 126 omitting the numeric parameter (i.e. just
 127 .Fl d Ns )
 128 will simply increment the debug level by one.
 129 .It Fl c Ar chdir-path
 130 Set the current directory used by
 131 .Nm
 132 while checking the existence and size of client boot files.  This is
 133 useful when client boot files are specified as relative pathnames, and
 134 .Nm
 135 needs to use the same current directory as the TFTP server
 136 (typically
 137 .Pa /tftpboot ) .
 138 This option is not recognized by
 139 .Nm bootpgw .
 140 .It Fl i
 141 Force inetd mode.  This option is obsolete, but remains for
 142 compatibility with older versions of
 143 .Nm .
 144 .It Fl s
 145 Force standalone mode.  This option is obsolete, but remains for
 146 compatibility with older versions of
 147 .Nm .
 148 .It Ar bootptab
 149 Specify the name of the configuration file from which
 150 .Nm
 151 loads its database of known clients and client options
 152 .No ( Nm
 153 only).
 154 .It Ar dumpfile
 155 Specify the name of the file that
 156 .Nm
 157 will dump its internal database into when it receives a
 158 .Dv SIGUSR1
 159 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
 201 .Dv ( SIGHUP )
 202 or when it discovers that the configuration file has changed.
 203 .Pp
 204 When
 205 .Nm
 206 receives a BOOTREQUEST packet, it
 207 .\" checks the modification time of the
 208 .\" configuration file and reloads the database if necessary.  Then it
 209 looks for a database entry matching the client request.
 210 If the client is known,
 211 .Nm
 212 composes a BOOTREPLY packet using the database entry found above,
 213 and sends the reply to the client (possibly using a gateway).
 214 If the client is unknown, the request is discarded
 215 (with a notice if debug > 0).
 216 .Pp
 217 If
 218 .Nm
 219 is compiled with the -DDEBUG option, receipt of a
 220 .Dv SIGUSR1
 221 signal causes it to dump its internal database to the file
 222 .Pa /tmp/bootpd.dump
 223 or the dumpfile specified as a command line parameter.
 224 .Pp
 225 During initialization, both programs
 226 determine the UDP port numbers to be used by calling
 227 .Xr getservbyname 3
 228 (which normally uses
 229 .Pa /etc/services ) .
 230 Two service names (and port numbers) are used:
 231 .Pp
 232 .Dl bootps BOOTP Server listening port
 233 .Dl bootpc BOOTP Client destination port
 234 .Pp
 235 If the port numbers cannot be determined using
 236 .Xr getservbyname 3
 237 then the values default to bootps=67 and bootpc=68.
 238 .Sh FILES
 239 .Bl -tag -width /tmp/bootpd.dump -compact
 240 .It Pa /etc/bootptab
 241 Database file read by
 242 .Nm .
 243 .It Pa /tmp/bootpd.dump
 244 Debugging dump file created by
 245 .Nm .
 246 .It Pa /etc/services
 247 Internet service numbers.
 248 .It Pa /tftpboot
 249 Current directory typically used by the TFTP server and
 250 .Nm .
 251 .El
 252 .Sh "SEE ALSO"
 253 .Xr bootptab 5 ,
 254 .Xr inetd 8 ,
 255 .Xr tftpd 8
 256 .Pp
 257 DARPA Internet Request For Comments:
 258 .Bl -tag -width "RFC 1533" -compact
 259 .It RFC 951
 260 Bootstrap Protocol
 261 .It RFC 1532
 262 Clarifications and Extensions for the Bootstrap Protocol
 263 .It RFC 1533
 264 DHCP Options and BOOTP Vendor Extensions
 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 .