1 '\" te
   2 .\"  Copyright (c) 1992-1996 Competitive Automation, Inc. Copyright (c) 2009 Sun Microsystems, Inc. All Rights Reserved.
   3 .\"  Copyright (c) 2016-2017, Chris Fraire <cfraire@me.com>.
   4 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.
   5 .\" See the License for the specific language governing permissions and limitations under the License. When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the
   6 .\" fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   7 .TH DHCPAGENT 1M "Jun 30, 2017"
   8 .SH NAME
   9 dhcpagent \- Dynamic Host Configuration Protocol (DHCP) client daemon
  11 .LP
  12 .nf
  13 \fBdhcpagent\fR [\fB-a\fR] [ \fB-d\fR \fIn\fR] [\fB-f\fR] [\fB-v\fR]
  14 .fi
  17 .LP
  18 \fBdhcpagent\fR implements the client half of the Dynamic Host Configuration
  19 Protocol \fB(DHCP)\fR for machines running illumos software.
  20 .sp
  21 .LP
  22 The \fBdhcpagent\fR daemon obtains configuration parameters for the client
  23 (local) machine's network interfaces from a \fBDHCP\fR server. These parameters
  24 may include a lease on an \fBIP\fR address, which gives the client machine use
  25 of the address for the period of the lease, which may be infinite. If the
  26 client wishes to use the \fBIP\fR address for a period longer than the lease,
  27 it must negotiate an extension using \fBDHCP\fR. For this reason,
  28 \fBdhcpagent\fR must run as a daemon, terminating only when the client machine
  29 powers down.
  30 .sp
  31 .LP
  32 For IPv4, the \fBdhcpagent\fR daemon is controlled through \fBipadm\fR(1M),
  33 \fBnwamcfg\fR(1M), or \fBifconfig\fR(1M) in much the same way that the
  34 \fBinit\fR(1M) daemon is controlled by \fBtelinit\fR(1M). \fBdhcpagent\fR can
  35 be invoked as a user process, albeit one requiring root privileges, but this is
  36 not necessary, as \fBipadm\fR(1M), \fBnwamcfg\fR(1M), or \fBifconfig\fR(1M)
  37 will start \fBdhcpagent\fR automatically.
  38 .sp
  39 .LP
  40 For IPv6, the \fBdhcpagent\fR daemon is invoked automatically by
  41 \fBin.ndpd\fR(1M). It can also be controlled through \fBifconfig\fR(1M), if
  42 necessary.
  43 .sp
  44 .LP
  45 When invoked, \fBdhcpagent\fR enters a passive state while it awaits
  46 instructions from \fBipadm\fR(1M), \fBnwamcfg\fR(1M), \fBifconfig\fR(1M), or
  47 \fBin.ndpd\fR(1M). When \fBdhcpagent\fR receives a command to configure an
  48 interface, \fBdhcpagent\fR brings up the interface (if necessary) and starts
  49 DHCP. Once DHCP is complete, \fBdhcpagent\fR can be queried for the values of
  50 the various network parameters. In addition, if DHCP was used to obtain a lease
  51 on an address for an interface, \fBdhcpagent\fR configures the address for use.
  52 When a lease is obtained, it is automatically renewed as necessary. If the
  53 lease cannot be renewed, \fBdhcpagent\fR will unconfigure the address, but the
  54 interface will be left up, and \fBdhcpagent\fR will attempt to acquire a new
  55 address lease.
  56 .sp
  57 .LP
  58 \fBdhcpagent\fR monitors system suspend/resume events and will validate any
  59 non-permanent leases with the DHCP server upon resume. Similarly,
  60 \fBdhcpagent\fR monitors link up/down events and will validate any
  61 non-permanent leases with the DHCP server when the downed link is brought back
  62 up. The lease validation mechanism will restart DHCP if the server indicates
  63 that the existing lease is no longer valid. If the server cannot be contacted,
  64 then the existing lease will continue. This behavior can be modified with the
  65 \fBVERIFIED_LEASE_ONLY\fR parameter in the \fB/etc/default/dhcpagent\fR file.
  66 See the description of this parameter below.
  67 .sp
  68 .LP
  69 For IPv4, if the configured interface is found to be unplumbed, or to have a
  70 different IP address, subnet mask, or broadcast address from those obtained
  71 from DHCP, the interface is abandoned from DHCP control.
  72 .sp
  73 .LP
  74 For IPv6, \fBdhcpagent\fR automatically plumbs and unplumbs logical interfaces
  75 as necessary for the IPv6 addresses supplied by the server. The IPv6 prefix
  76 length (netmask) is not set by the DHCPv6 protocol, but is instead set by
  77 \fBin.ndpd\fR(1M) using prefix information obtained by Router Advertisements.
  78 If any of the logical interfaces created by \fBdhcpagent\fR is unplumbed, or
  79 configured with a different IP address, it will be abandoned from DHCP control.
  80 If the link-local interface is unplumbed, then all addresses configured by DHCP
  81 on that physical interface will be removed.
  82 .sp
  83 .LP
  84 In addition to \fBDHCP\fR, \fBdhcpagent\fR also supports \fBBOOTP\fR (IPv4
  85 only). See \fIRFC 951, Bootstrap Protocol\fR. Configuration parameters obtained
  86 from a \fBBOOTP\fR server are treated identically to those received from a
  87 \fBDHCP\fR server, except that the \fBIP\fR address received from a \fBBOOTP\fR
  88 server always has an infinite lease.
  89 .sp
  90 .LP
  91 \fBDHCP\fR also acts as a mechanism to configure other information needed by
  92 the client, for example, the domain name and addresses of routers. Aside from
  93 the IP address, and for IPv4 alone, the netmask, broadcast address, and default
  94 router, the agent does not directly configure the workstation, but instead acts
  95 as a database which may be interrogated by other programs, and in particular by
  96 \fBdhcpinfo\fR(1).
  97 .sp
  98 .LP
  99 On clients with a single interface, this is quite straightforward. Clients with
 100 multiple interfaces may present difficulties, as it is possible that some
 101 information arriving on different interfaces may need to be merged, or may be
 102 inconsistent. Furthermore, the configuration of the interfaces is asynchronous,
 103 so requests may arrive while some or all of the interfaces are still
 104 unconfigured. To handle these cases, one interface may be designated as
 105 primary, which makes it the authoritative source for the values of \fBDHCP\fR
 106 parameters in the case where no specific interface is requested. See
 107 \fBdhcpinfo\fR(1) and \fBifconfig\fR(1M) for details.
 108 .sp
 109 .LP
 110 For IPv4, the \fBdhcpagent\fR daemon can be configured to request a particular
 111 Fully Qualified Domain Name (FQDN) or host name. See the \fBREQUEST_FQDN\fR or
 112 \fBREQUEST_HOSTNAME\fR description in the \fBFILES\fR section. When first
 113 configuring a client to request an FQDN or host name, you must perform the
 114 following steps as root to ensure that the full DHCP negotiation takes place:
 115 .sp
 116 .in +2
 117 .nf
 118 # pkill dhcpagent
 119 # rm /etc/dhcp/\fIinterface\fR.dhc
 120 # reboot
 121 .fi
 122 .in -2
 123 .sp
 125 .sp
 126 .LP
 127 All DHCP packets sent by \fBdhcpagent\fR include a vendor class identifier (RFC
 128 2132, option code 60; RFC 3315, option code 16). This identifier is the same as
 129 the platform name returned by the \fBuname\fR \fB-i\fR command, except:
 130 .RS +4
 131 .TP
 132 .ie t \(bu
 133 .el o
 134 Any commas in the platform name are changed to periods.
 135 .RE
 136 .RS +4
 137 .TP
 138 .ie t \(bu
 139 .el o
 140 If the name does not start with a stock symbol and a comma, it is automatically
 141 prefixed with \fBSUNW\fR.
 142 .RE
 143 .SS "Messages"
 144 .LP
 145 The \fBdhcpagent\fR daemon writes information and error messages in five
 146 categories:
 147 .sp
 148 .ne 2
 149 .na
 150 \fBcritical\fR
 151 .ad
 152 .sp .6
 153 .RS 4n
 154 Critical messages indicate severe conditions that prevent proper operation.
 155 .RE
 157 .sp
 158 .ne 2
 159 .na
 160 \fBerrors\fR
 161 .ad
 162 .sp .6
 163 .RS 4n
 164 Error messages are important, sometimes unrecoverable events due to resource
 165 exhaustion and other unexpected failure of system calls; ignoring errors may
 166 lead to degraded functionality.
 167 .RE
 169 .sp
 170 .ne 2
 171 .na
 172 \fBwarnings\fR
 173 .ad
 174 .sp .6
 175 .RS 4n
 176 Warnings indicate less severe problems, and in most cases, describe unusual or
 177 incorrect datagrams received from servers, or requests for service that cannot
 178 be provided.
 179 .RE
 181 .sp
 182 .ne 2
 183 .na
 184 \fBinformational\fR
 185 .ad
 186 .sp .6
 187 .RS 4n
 188 Informational messages provide key pieces of information that can be useful to
 189 debugging a \fBDHCP\fR configuration at a site. Informational messages are
 190 generally controlled by the \fB-v\fR option. However, certain critical pieces
 191 of information, such as the IP address obtained, are always provided.
 192 .RE
 194 .sp
 195 .ne 2
 196 .na
 197 \fBdebug\fR
 198 .ad
 199 .sp .6
 200 .RS 4n
 201 Debugging messages, which may be generated at two different levels of
 202 verbosity, are chiefly of benefit to persons having access to source code, but
 203 may be useful as well in debugging difficult DHCP configuration problems.
 204 Debugging messages are only generated when using the \fB-d\fR option.
 205 .RE
 207 .sp
 208 .LP
 209 When \fBdhcpagent\fR is run without the \fB-f\fR option, all messages are sent
 210 to the system logger \fBsyslog\fR(3C) at the appropriate matching priority and
 211 with a facility identifier \fBLOG_DAEMON\fR. When \fBdhcpagent\fR is run with
 212 the \fB-f\fR option, all messages are directed to standard error.
 213 .SS "DHCP Events and User-Defined Actions"
 214 .LP
 215 If an executable (binary or script) is placed at \fB/etc/dhcp/eventhook\fR, the
 216 \fBdhcpagent\fR daemon will automatically run that program when any of the
 217 following events occur:
 218 .sp
 219 .ne 2
 220 .na
 221 \fB\fBBOUND\fR and \fBBOUND6\fR\fR
 222 .ad
 223 .sp .6
 224 .RS 4n
 225 These events occur during interface configuration. The event program is invoked
 226 when \fBdhcpagent\fR receives the DHCPv4 ACK or DHCPv6 Reply message from the
 227 DHCP server for the lease request of an address, indicating successful initial
 228 configuration of the interface. (See also the \fBINFORM\fR and \fBINFORM6\fR
 229 events, which occur when configuration parameters are obtained without address
 230 leases.)
 231 .RE
 233 .sp
 234 .ne 2
 235 .na
 236 \fB\fBEXTEND\fR and \fBEXTEND6\fR\fR
 237 .ad
 238 .sp .6
 239 .RS 4n
 240 These events occur during lease extension. The event program is invoked just
 241 after \fBdhcpagent\fR receives the DHCPv4 ACK or DHCPv6 Reply from the DHCP
 242 server for the DHCPv4 REQUEST (renew) message or the DHCPv6 Renew or Rebind
 243 message.
 244 .sp
 245 Note that with DHCPv6, the server might choose to remove some addresses, add
 246 new address leases, and ignore (allow to expire) still other addresses in a
 247 given Reply message. The \fBEXTEND6\fR event occurs when a Reply is received
 248 that leaves one or more address leases still valid, even if the Reply message
 249 does not extend the lease for any address. The event program is invoked just
 250 before any addresses are removed, but just after any new addresses are added.
 251 Those to be removed will be marked with the \fBIFF_DEPRECATED\fR flag.
 252 .RE
 254 .sp
 255 .ne 2
 256 .na
 257 \fB\fBEXPIRE\fR and \fBEXPIRE6\fR\fR
 258 .ad
 259 .sp .6
 260 .RS 4n
 261 These events occur during lease expiration. For DHCPv4, the event program is
 262 invoked just before the leased address is removed from an interface. For
 263 DHCPv6, the event program is invoked just before the last remaining leased
 264 addresses are removed from the interface.
 265 .RE
 267 .sp
 268 .ne 2
 269 .na
 270 \fB\fBDROP\fR and \fBDROP6\fR\fR
 271 .ad
 272 .sp .6
 273 .RS 4n
 274 These events occur during the period when an interface is dropped. The event
 275 program is invoked just before the interface is removed from DHCP control. If
 276 the interface has been abandoned due the user unplumbing the interface, then
 277 this event will occur after the user's action has taken place. The interface
 278 might not be present.
 279 .RE
 281 .sp
 282 .ne 2
 283 .na
 284 \fB\fBINFORM\fR and \fBINFORM6\fR\fR
 285 .ad
 286 .sp .6
 287 .RS 4n
 288 These events occur when an interface acquires new or updated configuration
 289 information from a DHCP server by means of the DHCPv4 \fBINFORM\fR or the
 290 DHCPv6 Information-Request message. These messages are sent using an
 291 \fBifconfig\fR(1M) \fBdhcp inform\fR command or when the DHCPv6 Router
 292 Advertisement \fBO\fR (letter 0) bit is set and the \fBM\fR bit is not set.
 293 Thus, these events occur when the DHCP client does not obtain an IP address
 294 lease from the server, and instead obtains only configuration parameters.
 295 .RE
 297 .sp
 298 .ne 2
 299 .na
 300 \fB\fBLOSS6\fR\fR
 301 .ad
 302 .sp .6
 303 .RS 4n
 304 This event occurs during lease expiration when one or more valid leases still
 305 remain. The event program is invoked just before expired addresses are removed.
 306 Those being removed will be marked with the \fBIFF_DEPRECATED\fR flag.
 307 .sp
 308 Note that this event is not associated with the receipt of the Reply message,
 309 which occurs only when one or more valid leases remain, and occurs only with
 310 DHCPv6. If all leases have expired, then the EXPIRE6 event occurs instead.
 311 .RE
 313 .sp
 314 .ne 2
 315 .na
 316 \fB\fBRELEASE\fR and \fBRELEASE6\fR\fR
 317 .ad
 318 .sp .6
 319 .RS 4n
 320 This event occurs during the period when a leased address is released. The
 321 event program is invoked just before \fBdhcpagent\fR relinquishes the address
 322 on an interface and sends the DHCPv4 \fBRELEASE\fR or DHCPv6 Release packet to
 323 the DHCP server.
 324 .RE
 326 .sp
 327 .LP
 328 The system does not provide a default event program. The file
 329 \fB/etc/dhcp/eventhook\fR is expected to be owned by root and have a mode of
 330 755.
 331 .sp
 332 .LP
 333 The event program will be passed two arguments, the interface name and the
 334 event name, respectively. For DHCPv6, the interface name is the name of the
 335 physical interface.
 336 .sp
 337 .LP
 338 The event program can use the \fBdhcpinfo\fR(1) utility to fetch additional
 339 information about the interface. While the event program is invoked on every
 340 event defined above, it can ignore those events in which it is not interested.
 341 The event program runs with the same privileges and environment as
 342 \fBdhcpagent\fR itself, except that \fBstdin\fR, \fBstdout\fR, and \fBstderr\fR
 343 are redirected to \fB/dev/null\fR. Note that this means that the event program
 344 runs with root privileges.
 345 .sp
 346 .LP
 347 If an invocation of the event program does not exit after 55 seconds, it is
 348 sent a \fBSIGTERM\fR signal. If does not exit within the next three seconds, it
 349 is terminated by a \fBSIGKILL\fR signal.
 350 .sp
 351 .LP
 352 See EXAMPLES for an example event program.
 354 .LP
 355 The following options are supported:
 356 .sp
 357 .ne 2
 358 .na
 359 \fB\fB-a\fR\fR
 360 .ad
 361 .sp .6
 362 .RS 4n
 363 Adopt a configured IPv4 interface. This option is for use with diskless
 364 \fBDHCP\fR clients. In the case of diskless \fBDHCP\fR, \fBDHCP\fR has already
 365 been performed on the network interface providing the operating system image
 366 prior to running \fBdhcpagent\fR. This option instructs the agent to take over
 367 control of the interface. It is intended primarily for use in boot scripts.
 368 .sp
 369 The effect of this option depends on whether the interface is being adopted.
 370 .sp
 371 If the interface is being adopted, the following conditions apply:
 372 .sp
 373 \fBdhcpagent\fR uses the client id specified in
 374 \fB/chosen\fR:\fI<client_id>\fR, as published by the PROM or as specified on a
 375 \fBboot\fR(1M) command line. If this value is not present, the client id is
 376 undefined. The DHCP server then determines what to use as a client id. It is an
 377 error condition if the interface is an Infiniband interface and the PROM value
 378 is not present.
 379 .sp
 380 If the interface is not being adopted:
 381 .sp
 382 \fBdhcpagent\fR uses the value stored in \fB/etc/default/dhcpagent\fR. If this
 383 value is not present, the client id is undefined. If the interface is
 384 Infiniband and there is no value in \fB/etc/default/dhcpagent\fR, a client id
 385 is generated as described by the draft document on DHCP over Infiniband,
 386 available at:
 387 .sp
 388 .in +2
 389 .nf
 390 http://www.ietf.org
 391 .fi
 392 .in -2
 394 .RE
 396 .sp
 397 .ne 2
 398 .na
 399 \fB\fB-d\fR \fIn\fR\fR
 400 .ad
 401 .sp .6
 402 .RS 4n
 403 Set debug level to \fIn\fR. Two levels of debugging are currently available, 1
 404 and 2; the latter is more verbose.
 405 .RE
 407 .sp
 408 .ne 2
 409 .na
 410 \fB\fB-f\fR\fR
 411 .ad
 412 .sp .6
 413 .RS 4n
 414 Run in the foreground instead of as a daemon process. When this option is used,
 415 messages are sent to standard error instead of to \fBsyslog\fR(3C).
 416 .RE
 418 .sp
 419 .ne 2
 420 .na
 421 \fB\fB-v\fR\fR
 422 .ad
 423 .sp .6
 424 .RS 4n
 425 Provide verbose output useful for debugging site configuration problems.
 426 .RE
 429 .LP
 430 \fBExample 1 \fRExample Event Program
 431 .sp
 432 .LP
 433 The following script is stored in the file \fB/etc/dhcp/eventhook\fR, owned by
 434 root with a mode of 755. It is invoked upon the occurrence of the events listed
 435 in the file.
 437 .sp
 438 .in +2
 439 .nf
 440 #!/bin/sh
 442 (
 443 echo "Interface name: " $1
 444 echo "Event: " $2
 446 case $2 in
 447 "BOUND")
 448      echo "Address acquired from server "\e
 449          `/sbin/dhcpinfo -i $1 ServerID`
 450      ;;
 451 "BOUND6")
 452      echo "Addresses acquired from server " \e
 453          `/sbin/dhcpinfo -v6 -i $1 ServerID`
 454      ;;
 455 "EXTEND")
 456     echo "Lease extended for " \e
 457          `sbin/dhcpinfo -i $1 LeaseTim`" seconds"
 458      ;;
 459 "EXTEND6")
 460     echo "New lease information obtained on $i"
 461      ;;
 462 "EXPIRE" | "DROP" | "RELEASE")
 463      ;;
 465 esac
 466 ) >/var/run/dhcp_eventhook_output 2>&1
 467 .fi
 468 .in -2
 469 .sp
 471 .sp
 472 .LP
 473 Note the redirection of stdout and stderr to a file.
 475 .SH FILES
 476 .ne 2
 477 .na
 478 \fB\fB/etc/dhcp/\fIif\fR.dhc\fR\fR
 479 .ad
 480 .br
 481 .na
 482 \fB\fB/etc/dhcp/\fIif\fR.dh6\fR\fR
 483 .ad
 484 .sp .6
 485 .RS 4n
 486 Contains the configuration for interface. The mere existence of this file does
 487 not imply that the configuration is correct, since the lease might have
 488 expired. On start-up, \fBdhcpagent\fR confirms the validity of the address
 489 using REQUEST (for DHCPv4) or Confirm (DHCPv6).
 490 .RE
 492 .sp
 493 .ne 2
 494 .na
 495 \fB\fB/etc/dhcp/duid\fR\fR
 496 .ad
 497 .br
 498 .na
 499 \fB\fB/etc/dhcp/iaid\fR\fR
 500 .ad
 501 .sp .6
 502 .RS 4n
 503 Contains persistent storage for system-generated DUID (DHCP Unique Identifier)
 504 and interface-specific IAID (Identity Association Identifier) values which are
 505 used if no \fBCLIENT_ID\fR is defined (see below). The format of these files is
 506 undocumented, and applications should not read from or write to them.  Instead,
 507 \fBdhcpinfo\fR(1) can be used to query the \fBdhcpagent\fR for \fIClientID\fR.
 508 For DHCPv6 interfaces, the result will contain the DUID. For DHCPv4 interfaces
 509 with \fBV4_DEFAULT_IAID_DUID\fR enabled (see below), the result will contain
 510 the IAID and DUID.
 511 .RE
 513 .sp
 514 .ne 2
 515 .na
 516 \fB\fB/etc/default/dhcpagent\fR\fR
 517 .ad
 518 .sp .6
 519 .RS 4n
 520 Contains default values for tunable parameters. All values may be qualified
 521 with the interface they apply to by prepending the interface name and a period
 522 (".") to the interface parameter name. The parameters include: the interface
 523 parameter name.
 524 .sp
 525 To configure IPv6 parameters, place the string \fB\&.v6\fR between the
 526 interface name (if any) and the parameter name. For example, to set the global
 527 IPv6 parameter request list, use \fB\&.v6.PARAM_REQUEST_LIST\fR. To set the
 528 \fBCLIENT_ID\fR (\fBDUID\fR) on \fBhme0\fR, use \fBhme0.v6.CLIENT_ID\fR.
 529 .sp
 530 The parameters include:
 531 .sp
 532 .ne 2
 533 .na
 535 .ad
 536 .sp .6
 537 .RS 4n
 538 Indicates that a \fBRELEASE\fR rather than a \fBDROP\fR should be performed on
 539 managed interfaces when the agent terminates. Release causes the client to
 540 discard the lease, and the server to make the address available again. Drop
 541 causes the client to record the lease in \fB/etc/dhcp/\fIinterface\fR.dhc\fR or
 542 \fB/etc/dhcp/\fIinterface\fR.dh6\fR for later use. In addition, when the link
 543 status changes to \fBup\fR or when the system is resumed after a suspend, the
 544 client will verify the lease with the server. If the server is unreachable for
 545 verification, then the old lease will be discarded (even if it has time
 546 remaining) and a new one obtained.
 547 .sp
 548 Enabling this option is often desirable on mobile systems, such as laptops, to
 549 allow the system to recover quickly from moves.
 550 .sp
 551 Default value of this option is \fIno\fR.
 552 .RE
 554 .sp
 555 .ne 2
 556 .na
 557 \fB\fBOFFER_WAIT\fR\fR
 558 .ad
 559 .sp .6
 560 .RS 4n
 561 Indicates how long to wait in seconds between checking for valid
 562 \fBOFFER\fRs after sending a \fBDISCOVER\fR. For DHCPv6, sets the time to
 563 wait between checking for valid Advertisements after sending a Solicit.
 564 .sp
 565 Default value of this option is \fI3\fR.
 566 .RE
 568 .sp
 569 .ne 2
 570 .na
 571 \fB\fBCLIENT_ID\fR\fR
 572 .ad
 573 .sp .6
 574 .RS 4n
 575 Indicates the value that should be used to uniquely identify the client to the
 576 server. This value can take one of three basic forms:
 577 .sp
 578 .in +2
 579 .nf
 580 \fIdecimal\fR,\fIdata\fR...
 581 0xHHHHH...
 582 "\fIstring\fR...."
 583 .fi
 584 .in -2
 585 .sp
 587 The first form is an RFC 3315 DUID. This is legal for both IPv4 DHCP and
 588 DHCPv6. For IPv4, an RFC 4361 Client ID is constructed from this value. In this
 589 first form, the format of \fIdata\fR... depends on the decimal value. The
 590 following formats are defined for this first form:
 591 .sp
 592 .ne 2
 593 .na
 594 \fB1,\fIhwtype\fR,\fItime\fR,\fIlla\fR\fR
 595 .ad
 596 .sp .6
 597 .RS 4n
 598 Type 1, DUID-LLT. The \fIhwtype\fR value is an integer in the range 0-65535,
 599 and indicates the type of hardware. The \fItime\fR value is the number of
 600 seconds since midnight, January 1st, 2000 UTC, and can be omitted to use the
 601 current system time. The \fIlla\fR value is either a colon-separated MAC
 602 address or the name of a physical interface. If the name of an interface is
 603 used, the \fIhwtype\fR value can be omitted. For example: \fB1,,,hme0\fR
 604 .RE
 606 .sp
 607 .ne 2
 608 .na
 609 \fB2,\fIenterprise\fR,\fIhex\fR...\fR
 610 .ad
 611 .sp .6
 612 .RS 4n
 613 Type 2, DUID-EN. The \fIenterprise\fR value is an integer in the range
 614 0-4294967295 and represents the SMI Enterprise number for an organization. The
 615 \fIhex\fR string is an even-length sequence of hexadecimal digits.
 616 .RE
 618 .sp
 619 .ne 2
 620 .na
 621 \fB3,\fIhwtype\fR,\fIlla\fR\fR
 622 .ad
 623 .sp .6
 624 .RS 4n
 625 Type 3, DUID-LL. This is the same as DUID-LLT (type 1), except that a time
 626 stamp is not used.
 627 .RE
 629 .sp
 630 .ne 2
 631 .na
 632 \fB*,\fIhex\fR\fR
 633 .ad
 634 .sp .6
 635 .RS 4n
 636 Any other type value (0 or 4-65535) can be used with an even-length hexadecimal
 637 string.
 638 .RE
 640 The second and third forms of \fBCLIENT_ID\fR are legal for IPv4 only. These
 641 both represent raw Client ID (without RFC 4361), in hex, or NVT ASCII string
 642 format. Thus, "\fBSun\fR" and \fB0x53756E\fR are equivalent.
 643 .RE
 645 .sp
 646 .ne 2
 647 .na
 649 .ad
 650 .sp .6
 651 .RS 4n
 652 Indicates whether to use, when CLIENT_ID is not defined, a system-managed,
 653 RFC 3315-style (i.e., DHCPv6-style) binding identifier as documented in
 654 RFC 4361, "Node-specific Client Identifiers for DHCPv4," for IPv4
 655 interfaces which for purposes of backward compatibility do not normally get
 656 default binding identifiers.
 657 .sp
 658 An IPv4 interface that is not in an IP network multipathing (IPMP) group,
 659 that is not IP over InfiniBand (IPoIB), and that is not a logical interface
 660 does not normally get a default binding identifier.
 661 .sp
 662 Default value of this option is \fIno\fR.
 663 .RE
 665 .sp
 666 .ne 2
 667 .na
 669 .ad
 670 .sp .6
 671 .RS 4n
 672 Specifies a list of comma-separated integer values of options for which the
 673 client would like values, or symbolic \fBSite\fR or \fBOption\fR option names.
 674 Symbolic option names for IPv4 are resolved through \fB/etc/dhcp/inittab\fR.
 675 Option names for IPv6 are resolved by means of \fB/etc/dhcp/inittab6\fR.
 676 .RE
 678 .sp
 679 .ne 2
 680 .na
 682 .ad
 683 .sp .6
 684 .RS 4n
 685 Specifies a list of options (constructed in the same manner as
 686 \fBPARAM_REQUEST_LIST\fR) that the DHCP client will ignore. Ignored options are
 687 treated as though the server did not return the options specified. Ignored
 688 options are not visible using \fBdhcpinfo\fR(1) or acted on by the client. This
 689 parameter can be used, for example, to disable an unwanted client name or
 690 default router.
 691 .RE
 693 .sp
 694 .ne 2
 695 .na
 697 .ad
 698 .sp .6
 699 .RS 4n
 700 Indicates the client requests the DHCP server to map the client's leased
 701 IPv4 address to the Fully Qualified Domain Name (FQDN) associated with the
 702 network interface that performs DHCP on the client and to collaborate with
 703 a compatible DNS server to manage A and PTR resource records for the FQDN
 704 for the life of the lease.
 705 .sp .6
 706 The \fIhostname\fR in the FQDN is determined from the following possible
 707 configurations:
 708 .sp
 709 .ne 2
 710 .na
 711 1.  \fBipadm\fR(1M): include the \fB-1,--primary\fR flag when creating an
 712 address that uses DHCP so that \fBnodename\fR(4) is used as the
 713 \fIhostname\fR.
 714 .ad
 715 .sp
 716 .ne 2
 717 .na
 718 2.  \fBipadm\fR(1M): include the \fB-h,--reqhost\fR \fIhostname\fR switch
 719 when executing the \fBcreate-addr -T dhcp\fR subcommand, or use the
 720 \fBset-addrprop -p reqhost=\fR\fIhostname\fR subcommand for any existing
 721 DHCP address.
 722 .ad
 723 .sp
 724 .ne 2
 725 .na
 726 3.  \fBnwamcfg\fR(1M): set a property,
 727 \fBip-primary=\fR\fIon\fR, for an ncu ip that uses DHCP so that
 728 \fBnodename\fR(4) is used as the \fIhostname\fR.
 729 .ad
 730 .sp
 731 .ne 2
 732 .na
 733 4.  \fBnwamcfg\fR(1M): set a property,
 734 \fBip-reqhost=\fR\fIhostname\fR, for an ncu ip that uses DHCP.
 735 .ad
 736 .sp
 737 The \fIhostname\fR value is either a Partially Qualified Domain Name (PQDN)
 738 or an FQDN (i.e., a "rooted" domain name ending with a '.' or one inferred
 739 to be an FQDN if it contains at least three DNS labels such as
 740 srv.example.com).  If a PQDN is specified, then an FQDN is constructed if
 741 \fBDNS_DOMAINNAME\fR is defined or if \fBADOPT_DOMAINNAME\fR is set to
 742 \fIyes\fR and an eligible domain name (as described below) is available.
 743 .sp
 744 If an FQDN is sent, \fBREQUEST_HOSTNAME\fR processing will not be done,
 745 per RFC 4702 (3.1):  "clients that send the Client FQDN option in their
 746 messages MUST NOT also send the Host Name."
 747 .sp
 748 Default value of this option is \fIyes\fR.
 749 .RE
 751 .sp
 752 .ne 2
 753 .na
 755 .ad
 756 .sp .6
 757 .RS 4n
 758 Indicates the value that should be appended to a PQDN specified by the
 759 \fB-h,--reqhost\fR option of \fBipadm\fR(1M), by the ncu \fBip-reqhost\fR
 760 property of \fBnwamcfg\fR(1M), or by \fBnodename\fR(4) to construct an FQDN
 761 for \fBREQUEST_FQDN\fR processing.
 762 If the \fIhostname\fR value is already an FQDN, then the value of this
 763 option is not used.
 764 .RE
 766 .sp
 767 .ne 2
 768 .na
 770 .ad
 771 .sp .6
 772 .RS 4n
 773 Indicates that a domain name returned by the DHCP server or the \fBdomain\fR
 774 from \fBresolv.conf\fR(4) should be adopted if needed to construct an FQDN
 775 from a PQDN specified by the \fB-h,--reqhost\fR option of \fBipadm\fR(1M),
 776 by the ncu \fBip-reqhost\fR property of \fBnwamcfg\fR(1M), or by
 777 \fBnodename\fR(4).
 778 If the \fIhostname\fR value is already an FQDN, then the value of this
 779 option is not applicable.
 780 The eligible DHCP option for domain name is DHCPv4 \fBDNSdmain\fR.
 781 .sp
 782 Default value of this option is \fIno\fR.
 783 .RE
 785 .sp
 786 .ne 2
 787 .na
 789 .ad
 790 .sp .6
 791 .RS 4n
 792 Indicates the client requests the DHCP server to map the client's leased IPv4
 793 address to the host name associated with the network interface that performs
 794 DHCP on the client. The host name must be specified as documented for a
 795 PQDN in \fBREQUEST_FQDN\fR above or specified in the
 796 \fB/etc/hostname.\fIinterface\fR\fR file for the relevant interface on a line
 797 of the form
 798 .sp
 799 .in +2
 800 .nf
 801 inet \fIhostname\fR
 802 .fi
 803 .in -2
 804 .sp
 806 where \fIhostname\fR is the host name requested.
 807 .sp
 808 This option works with DHCPv4 only.
 809 .sp
 810 Default value of this option is \fIyes\fR.
 811 .RE
 813 .RE
 815 .sp
 816 .ne 2
 817 .na
 818 \fB\fB/etc/dhcp/eventhook\fR\fR
 819 .ad
 820 .sp .6
 821 .RS 4n
 822 Location of a DHCP event program.
 823 .RE
 826 .LP
 827 See \fBattributes\fR(5) for descriptions of the following attributes:
 828 .sp
 830 .sp
 831 .TS
 832 box;
 833 c | c
 834 l | l .
 836 _
 837 Interface Stability     Committed
 838 .TE
 841 .LP
 842 \fBdhcpinfo\fR(1), \fBifconfig\fR(1M), \fBinit\fR(1M), \fBin.mpathd\fR(1M),
 843 \fBin.ndpd\fR(1M), \fBipadm\fR(1M), \fBnwamcfg\fR(1M), \fBsyslog\fR(3C),
 844 \fBnodename\fR(4), \fBresolv.conf\fR(4), \fBattributes\fR(5), \fBdhcp\fR(5)
 845 .sp
 846 .LP
 847 \fI\fR
 848 .sp
 849 .LP
 850 Croft, B. and Gilmore, J. \fIRFC 951, Bootstrap Protocol (BOOTP)\fR, Network
 851 Working Group, September 1985.
 852 .sp
 853 .LP
 854 Droms, R. \fIRFC 2131, Dynamic Host Configuration Protocol\fR, Network Working
 855 Group, March 1997.
 856 .sp
 857 .LP
 858 Lemon, T. and B. Sommerfeld. \fIRFC 4361, Node-specific Client Identifiers for
 859 Dynamic Host Configuration Protocol Version Four (DHCPv4)\fR. Nominum and Sun
 860 Microsystems. February 2006.
 861 .sp
 862 .LP
 863 Droms, R. \fIRFC 3315, Dynamic Host Configuration Protocol for IPv6
 864 (DHCPv6)\fR. Cisco Systems. July 2003.
 865 .SH NOTES
 866 .LP
 867 The \fBdhcpagent\fR daemon can be used on IPv4 logical interfaces, just as with
 868 physical interfaces. When used on a logical interface, the daemon automatically
 869 constructs a Client ID value based on the DUID and IAID values, according to
 870 RFC 4361. The  \fB/etc/default/dhcpagent\fR \fBCLIENT_ID\fR value, if any,
 871 overrides this automatic identifier.
 872 .sp
 873 .LP
 874 As with physical IPv4 interfaces, the \fB/etc/hostname.hme0:1\fR and
 875 \fB/etc/dhcp.hme0:1\fR files must also be created in order for \fBhme0:1\fR to
 876 be automatically plumbed and configured at boot. In addition, unlike physical
 877 IPv4 interfaces, \fBdhcpagent\fR does not add or remove default routes
 878 associated with logical interfaces.
 879 .sp
 880 .LP
 881 DHCP can be performed on IPMP IP interfaces to acquire and maintain IPMP data
 882 addresses. Because an IPMP IP interface has no hardware address, the daemon
 883 automatically constructs a Client ID using the same approach described above
 884 for IPv4 logical interfaces. In addition, the lack of a hardware address means
 885 the daemon must set the "broadcast" flag in all \fBDISCOVER\fR and
 886 \fBREQUEST\fR messages on IPMP IP interfaces. Some DHCP servers may refuse such
 887 requests.
 888 .sp
 889 .LP
 890 DHCP can be performed on IP interfaces that are part of an IPMP group (to
 891 acquire and maintain test addresses). The daemon will automatically set the
 892 \fBNOFAILOVER\fR and \fBDEPRECATED\fR flags on each test address. Additionally,
 893 the daemon will not add or remove default routes in this case. Note that the
 894 actual DHCP packet exchange may be performed over any active IP interface in
 895 the IPMP group. It is strongly recommended that test addresses have infinite
 896 leases. Otherwise, an extended network outage detectable only by probes may
 897 cause test address leases to expire, causing \fBin.mpathd\fR(1M) to revert to
 898 link-based failure detection and trigger an erroneous repair.
 899 .sp
 900 .LP
 901 With DHCPv6, the link-local interface must be configured using
 902 \fB/etc/hostname6.hme0\fR in order for DHCPv6 to run on \fBhme0\fR at boot
 903 time. The logical interfaces for each address are plumbed by \fBdhcpagent\fR
 904 automatically.