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