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.4 2006/02/17 19:33:31 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 RFC951, RFC1532, and RFC1533.
  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 SIGUSR1 signal
 159 .No ( Nm
 160 only). This option is only recognized if
 161 .Nm
 162 was compiled with the -DDEBUG flag.
 163 .It Ar server
 164 Specify the name of a BOOTP server to which
 165 .Nm bootpgw
 166 will forward all BOOTREQUEST packets it receives
 167 .Pf ( Nm bootpgw
 168 only).
 169 .El
 170 .Sh OPERATION
 171 Both
 172 .Nm
 173 and
 174 .Nm bootpgw
 175 operate similarly in that both listen for any packets sent to the
 176 .Em bootps
 177 port, and both simply forward any BOOTREPLY packets.
 178 They differ in their handling of BOOTREQUEST packets.
 179 .Pp
 180 When
 181 .Nm bootpgw
 182 is started, it determines the address of a BOOTP server
 183 whose name is provided as a command line parameter.  When
 184 .Nm bootpgw
 185 receives a BOOTREQUEST packet, it sets the "gateway address"
 186 and "hop count" fields in the packet and forwards the packet
 187 to the BOOTP server at the address determined earlier.
 188 Requests are forwarded only if they indicate that
 189 the client has been waiting for at least three seconds.
 190 .Pp
 191 When
 192 .Nm
 193 is started it reads a configuration file, (normally
 194 .Pa /etc/bootptab )
 195 that initializes the internal database of known clients and client
 196 options.  This internal database is reloaded
 197 from the configuration file when
 198 .Nm
 199 receives a hangup signal (SIGHUP) or when it discovers that the
 200 configuration file has changed.
 201 .Pp
 202 When
 203 .Nm
 204 receives a BOOTREQUEST packet, it
 205 .\" checks the modification time of the
 206 .\" configuration file and reloads the database if necessary.  Then it
 207 looks for a database entry matching the client request.
 208 If the client is known,
 209 .Nm
 210 composes a BOOTREPLY packet using the database entry found above,
 211 and sends the reply to the client (possibly using a gateway).
 212 If the client is unknown, the request is discarded
 213 (with a notice if debug > 0).
 214 .Pp
 215 If
 216 .Nm
 217 is compiled with the -DDEBUG option, receipt of a SIGUSR1 signal causes
 218 it to dump its internal database to the file
 219 .Pa /tmp/bootpd.dump
 220 or the dumpfile specified as a command line parameter.
 221 .Pp
 222 During initialization, both programs
 223 determine the UDP port numbers to be used by calling
 224 .Xr getservbyname 3
 225 (which normally uses
 226 .Pa /etc/services ) .
 227 Two service names (and port numbers) are used:
 228 .Pp
 229 .Dl bootps BOOTP Server listening port
 230 .Dl bootpc BOOTP Client destination port
 231 .Pp
 232 If the port numbers cannot be determined using
 233 .Xr getservbyname 3
 234 then the values default to bootps=67 and bootpc=68.
 235 .Sh FILES
 236 .Bl -tag -width /tmp/bootpd.dump -compact
 237 .It Pa /etc/bootptab
 238 Database file read by
 239 .Nm .
 240 .It Pa /tmp/bootpd.dump
 241 Debugging dump file created by
 242 .Nm .
 243 .It Pa /etc/services
 244 Internet service numbers.
 245 .It Pa /tftpboot
 246 Current directory typically used by the TFTP server and
 247 .Nm .
 248 .El
 249 .Sh "SEE ALSO"
 250 .Xr bootptab 5 ,
 251 .Xr inetd 8 ,
 252 .Xr tftpd 8
 253 .Pp
 254 DARPA Internet Request For Comments:
 255 .Bl -tag -width RFC1533 -compact
 256 .It RFC951
 257 Bootstrap Protocol
 258 .It RFC1532
 259 Clarifications and Extensions for the Bootstrap Protocol
 260 .It RFC1533
 261 DHCP Options and BOOTP Vendor Extensions
 262 .El
 263 .Sh BUGS
 264 Individual host entries must not exceed 1024 characters.
 265 .Sh CREDITS
 266 This distribution is currently maintained by
 267 .An Walter L. Wimer Aq walt+@cmu.edu .
 268 .Pp
 269 The original BOOTP server was created by
 270 .An Bill Croft
 271 at Stanford University in January 1986.
 272 .Pp
 273 The current version of
 274 .Nm
 275 is primarily the work of
 276 .An David Kovar ,
 277 .An Drew D. Perkins ,
 278 and
 279 .An Walter L. Wimer ,
 280 at Carnegie Mellon University.
 281 .Pp
 282 Enhancements and bug-fixes have been contributed by:
 283 .Pp
 284 (in alphabetical order)
 285 .Pp
 286 .An -split
 287 .An Danny Backx Aq db@sunbim.be
 288 .An John Brezak Aq brezak@ch.hp.com
 289 .An Frank da Cruz Aq fdc@cc.columbia.edu
 290 .An David R. Linn Aq drl@vuse.vanderbilt.edu
 291 .An Jim McKim Aq mckim@lerc.nasa.gov
 292 .An Gordon W. Ross Aq gwr@mc.com
 293 .An Jason Zions Aq jazz@hal.com .