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