1dhcpagent(1M) System Administration Commands dhcpagent(1M)
2
6 dhcpagent - Dynamic Host Configuration Protocol (DHCP) client daemon
7
9 dhcpagent [-a] [ -d n] [-f] [-v]
10
13 dhcpagent implements the client half of the Dynamic Host Configuration
14 Protocol (DHCP) for machines running Solaris software.
15 The dhcpagent daemon obtains configuration parameters for the client
18 (local) machine's network interfaces from a DHCP server. These parame‐
19 ters may include a lease on an IP address, which gives the client
20 machine use of the address for the period of the lease, which may be
21 infinite. If the client wishes to use the IP address for a period
22 longer than the lease, it must negotiate an extension using DHCP. For
23 this reason, dhcpagent must run as a daemon, terminating only when the
24 client machine powers down.
25 For IPv4, the dhcpagent daemon is controlled through ifconfig(1M) in
28 much the same way that the init(1M) daemon is controlled by
29 telinit(1M). dhcpagent can be invoked as a user process, albeit one
30 requiring root privileges, but this is not necessary, as ifconfig(1M)
31 will start it automatically.
32 For IPv6, the dhcpagent daemon is invoked automatically by in.ndpd(1M).
35 It can also be controlled through ifconfig(1M), if necessary.
36 When invoked, dhcpagent enters a passive state while it awaits instruc‐
39 tions from ifconfig(1M) or in.ndpd(1M). When it receives a command to
40 configure an interface, it brings up the interface (if necessary) and
41 starts DHCP. Once DHCP is complete, dhcpagent can be queried for the
42 values of the various network parameters. In addition, if DHCP was used
43 to obtain a lease on an address for an interface, it configures the
44 address for use. When a lease is obtained, it is automatically renewed
45 as necessary. If the lease cannot be renewed, dhcpagent will unconfig‐
46 ure the address, but the interface will be left up and dhcpagent will
47 attempt to acquire a new address lease. dhcpagent monitors system sus‐
48 pend/resume events and will validate any non-permanent leases with the
49 DHCP server upon resume. Similarly, dhcpagent monitors link up/down
50 events and will validate any non-permanent leases with the DHCP server
51 when the downed link is brought back up. The lease validation mechanism
52 will restart DHCP if the server indicates that the existing lease is no
53 longer valid. If the server cannot be contacted, then the existing
54 lease will continue. This behavior can be modified with the VERI‐
55 FIED_LEASE_ONLY parameter in the /etc/default/dhcpagent file. See the
56 description of this parameter below.
57 For IPv4, if the configured interface is found to be unplumbed, or to
60 have a different IP address, subnet mask, or broadcast address from
61 those obtained from DHCP, the interface is abandoned from DHCP control.
62 For IPv6, dhcpagent automatically plumbs and unplumbs logical inter‐
65 faces as necessary for the IPv6 addresses supplied by the server. The
66 IPv6 prefix length (netmask) is not set by the DHCPv6 protocol, but is
67 instead set by in.ndpd(1M) using prefix information obtained by Router
68 Advertisements. If any of the logical interfaces created by dhcpagent
69 is unplumbed, or configured with a different IP address, it will be
70 abandoned from DHCP control. If the link-local interface is unplumbed,
71 then all addresses configured by DHCP on that physical interface will
72 be removed.
73 In addition to DHCP, dhcpagent also supports BOOTP (IPv4 only). See RFC
76 951, Bootstrap Protocol. Configuration parameters obtained from a BOOTP
77 server are treated identically to those received from a DHCP server,
78 except that the IP address received from a BOOTP server always has an
79 infinite lease.
80 DHCP also acts as a mechanism to configure other information needed by
83 the client, for example, the domain name and addresses of routers.
84 Aside from the IP address, and for IPv4 alone, the netmask, broadcast
85 address, and default router, the agent does not directly configure the
86 workstation, but instead acts as a database which may be interrogated
87 by other programs, and in particular by dhcpinfo(1).
88 On clients with a single interface, this is quite straightforward.
91 Clients with multiple interfaces may present difficulties, as it is
92 possible that some information arriving on different interfaces may
93 need to be merged, or may be inconsistent. Furthermore, the configura‐
94 tion of the interfaces is asynchronous, so requests may arrive while
95 some or all of the interfaces are still unconfigured. To handle these
96 cases, one interface may be designated as primary, which makes it the
97 authoritative source for the values of DHCP parameters in the case
98 where no specific interface is requested. See dhcpinfo(1) and ifcon‐
99 fig(1M) for details.
100 For IPv4, the dhcpagent daemon can be configured to request a particu‐
103 lar host name. See the REQUEST_HOSTNAME description in the FILES sec‐
104 tion. When first configuring a client to request a host name, you must
105 perform the following steps as root to ensure that the full DHCP nego‐
106 tiation takes place:
107 # pkill dhcpagent
109 # rm /etc/dhcp/interface.dhc
110 # reboot
111 All DHCP packets sent by dhcpagent include a vendor class identifier
116 (RFC 2132, option code 60; RFC 3315, option code 16). This identifier
117 is the same as the platform name returned by the uname -i command,
118 except:
119 o Any commas in the platform name are changed to periods.
121 o If the name does not start with a stock symbol and a comma,
123 it is automatically prefixed with SUNW.
124 Messages
126 The dhcpagent daemon writes information and error messages in five cat‐
127 egories:
128 critical
130 Critical messages indicate severe conditions that prevent proper
132 operation.
133 errors
136 Error messages are important, sometimes unrecoverable events due to
138 resource exhaustion and other unexpected failure of system calls;
139 ignoring errors may lead to degraded functionality.
140 warnings
143 Warnings indicate less severe problems, and in most cases, describe
145 unusual or incorrect datagrams received from servers, or requests
146 for service that cannot be provided.
147 informational
150 Informational messages provide key pieces of information that can
152 be useful to debugging a DHCP configuration at a site. Informa‐
153 tional messages are generally controlled by the -v option. However,
154 certain critical pieces of information, such as the IP address
155 obtained, are always provided.
156 debug
159 Debugging messages, which may be generated at two different levels
161 of verbosity, are chiefly of benefit to persons having access to
162 source code, but may be useful as well in debugging difficult DHCP
163 configuration problems. Debugging messages are only generated when
164 using the -d option.
165 When dhcpagent is run without the -f option, all messages are sent to
169 the system logger syslog(3C) at the appropriate matching priority and
170 with a facility identifier LOG_DAEMON. When dhcpagent is run with the
171 -f option, all messages are directed to standard error.
172 DHCP Events and User-Defined Actions
174 If an executable (binary or script) is placed at /etc/dhcp/eventhook,
175 the dhcpagent deamon will automatically run that program when any of
176 the following events occur:
177 BOUND and BOUND6
179 These events occur during interface configuration. The event pro‐
181 gram is invoked when dhcpagent receives the DHCPv4 ACK or DHCPv6
182 Reply message from the DHCP server for the lease request of an
183 address, indicating successful initial configuration of the inter‐
184 face. (See also the INFORM and INFORM6 events, which occur when
185 configuration parameters are obtained without address leases.)
186 EXTEND and EXTEND6
189 These events occur during lease extension. The event program is
191 invoked just after dhcpagent receives the DHCPv4 ACK or DHCPv6
192 Reply from the DHCP server for the DHCPv4 REQUEST (renew) message
193 or the DHCPv6 Renew or Rebind message.
194 Note that with DHCPv6, the server might choose to remove some
196 addresses, add new address leases, and ignore (allow to expire)
197 still other addresses in a given Reply message. The EXTEND6 event
198 occurs when a Reply is received that leaves one or more address
199 leases still valid, even if the Reply message does not extend the
200 lease for any address. The event program is invoked just before any
201 addresses are removed, but just after any new addresses are added.
202 Those to be removed will be marked with the IFF_DEPRECATED flag.
203 EXPIRE and EXPIRE6
206 These events occur during lease expiration. For DHCPv4, the event
208 program is invoked just before the leased address is removed from
209 an interface. For DHCPv6, the event program is invoked just before
210 the last remaining leased addresses are removed from the interface.
211 DROP and DROP6
214 These events occur during the period when an interface is dropped.
216 The event program is invoked just before the interface is removed
217 from DHCP control. If the interface has been abandoned due the user
218 unplumbing the interface, then this event will occur after the
219 user's action has taken place. The interface might not be present.
220 INFORM and INFORM6
223 These events occur when an interface acquires new or updated con‐
225 figuration information from a DHCP server by means of the DHCPv4
226 INFORM or the DHCPv6 Information-Request message. These messages
227 are sent using an ifconfig(1M) dhcp inform command or when the
228 DHCPv6 Router Advertisement O (letter 0) bit is set and the M bit
229 is not set. Thus, these events occur when the DHCP client does not
230 obtain an IP address lease from the server, and instead obtains
231 only configuration parameters.
232 LOSS6
235 This event occurs during lease expiration when one or more valid
237 leases still remain. The event program is invoked just before
238 expired addresses are removed. Those being removed will be marked
239 with the IFF_DEPRECATED flag.
240 Note that this event is not associated with the receipt of the
242 Reply message, which occurs only when one or more valid leases
243 remain, and occurs only with DHCPv6. If all leases have expired,
244 then the EXPIRE6 event occurs instead.
245 RELEASE and RELEASE6
248 This event occurs during the period when a leased address is
250 released. The event program is invoked just before dhcpagent relin‐
251 quishes the address on an interface and sends the DHCPv4 RELEASE or
252 DHCPv6 Release packet to the DHCP server.
253 The system does not provide a default event program. The file
257 /etc/dhcp/eventhook is expected to be owned by root and have a mode of
258 755.
259 The event program will be passed two arguments, the interface name and
262 the event name, respectively. For DHCPv6, the interface name is the
263 name of the physical interface.
264 The event program can use the dhcpinfo(1) utility to fetch additional
267 information about the interface. While the event program is invoked on
268 every event defined above, it can ignore those events in which it is
269 not interested. The event program runs with the same privileges and
270 environment as dhcpagent itself, except that stdin, stdout, and stderr
271 are redirected to /dev/null. Note that this means that the event pro‐
272 gram runs with root privileges.
273 If an invocation of the event program does not exit after 55 seconds,
276 it is sent a SIGTERM signal. If does not exit within the next three
277 seconds, it is terminated by a SIGKILL signal.
278 See EXAMPLES for an example event program.
281
283 The following options are supported:
284 -a
286 Adopt a configured IPv4 interface. This option is for use with
288 diskless DHCP clients. In the case of diskless DHCP, DHCP has
289 already been performed on the network interface providing the oper‐
290 ating system image prior to running dhcpagent. This option
291 instructs the agent to take over control of the interface. It is
292 intended primarily for use in boot scripts.
293 The effect of this option depends on whether the interface is being
295 adopted.
296 If the interface is being adopted, the following conditions apply:
298 dhcpagent uses the client id specified in /chosen:<client_id>, as
300 published by the PROM or as specified on a boot(1M) command line.
301 If this value is not present, the client id is undefined. The DHCP
302 server then determines what to use as a client id. It is an error
303 condition if the interface is an Infiniband interface and the PROM
304 value is not present.
305 If the interface is not being adopted:
307 dhcpagent uses the value stored in /etc/default/dhcpagent. If this
309 value is not present, the client id is undefined. If the interface
310 is Infiniband and there is no value in /etc/default/dhcpagent, a
311 client id is generated as described by the draft document on DHCP
312 over Infiniband, available at:
313 http://www.ietf.org
315 -d n
319 Set debug level to n. Two levels of debugging are currently avail‐
321 able, 1 and 2; the latter is more verbose.
322 -f
325 Run in the foreground instead of as a daemon process. When this
327 option is used, messages are sent to standard error instead of to
328 syslog(3C).
329 -v
332 Provide verbose output useful for debugging site configuration
334 problems.
335
338 Example 1 Example Event Program
339 The following script is stored in the file /etc/dhcp/eventhook, owned
342 by root with a mode of 755. It is invoked upon the occurrence of the
343 events listed in the file.
344 #!/bin/sh
347 (
349 echo "Interface name: " $1
350 echo "Event: " $2
351 case $2 in
353 "BOUND")
354 echo "Address acquired from server "\
355 `/sbin/dhcpinfo -i $1 ServerID`
356 ;;
357 "BOUND6")
358 echo "Addresses acquired from server " \
359 `/sbin/dhcpinfo -v6 -i $1 ServerID`
360 ;;
361 "EXTEND")
362 echo "Lease extended for " \
363 `sbin/dhcpinfo -i $1 LeaseTim`" seconds"
364 ;;
365 "EXTEND6")
366 echo "New lease information obtained on $i"
367 ;;
368 "EXPIRE" | "DROP" | "RELEASE")
369 ;;
370 esac
372 ) >/var/run/dhcp_eventhook_output 2>&1
373 Note the redirection of stdout and stderr to a file.
378
381 /etc/dhcp/if.dhc
382 /etc/dhcp/if.dh6
383 Contains the configuration for interface. The mere existence of
385 this file does not imply that the configuration is correct, since
386 the lease might have expired. On start-up, dhcpagent confirms the
387 validity of the address using REQUEST (for DHCPv4) or Confirm
388 (DHCPv6).
389 /etc/dhcp/duid
392 /etc/dhcp/iaid
393 Contains persistent storage for DUID (DHCP Unique Identifier) and
395 IAID (Identity Association Identifier) values. The format of these
396 files is undocumented, and applications should not read from or
397 write to them.
398 /etc/default/dhcpagent
401 Contains default values for tunable parameters. All values may be
403 qualified with the interface they apply to by prepending the inter‐
404 face name and a period (".") to the interface parameter name. The
405 parameters include: the interface parameter name.
406 To configure IPv6 parameters, place the string .v6 between the
408 interface name (if any) and the parameter name. For example, to set
409 the global IPv6 parameter request list, use .v6.PARAM_REQUEST_LIST.
410 To set the CLIENT_ID (DUID) on hme0, use hme0.v6.CLIENT_ID.
411 The parameters include:
413 VERIFIED_LEASE_ONLY
415 Indicates that a RELEASE rather than a DROP should be performed
417 on managed interfaces when the agent terminates. Release causes
418 the client to discard the lease, and the server to make the
419 address available again. Drop causes the client to record the
420 lease in /etc/dhcp/interface.dhc or /etc/dhcp/interface.dh6 for
421 later use. In addition, when the link status changes to up or
422 when the system is resumed after a suspend, the client will
423 verify the lease with the server. If the server is unreachable
424 for verification, then the old lease will be discarded (even if
425 it has time remaining) and a new one obtained.
426 Enabling this option is often desirable on mobile systems, such
428 as laptops, to allow the system to recover quickly from moves.
429 OFFER_WAIT
432 Indicates how long to wait between checking for valid OFFERs
434 after sending a DISCOVER. For DHCPv6, sets the time to wait
435 between checking for valid Advertisements after sending a
436 Solicit.
437 CLIENT_ID
440 Indicates the value that should be used to uniquely identify
442 the client to the server. This value can take one of three
443 basic forms:
444 decimal,data...
446 0xHHHHH...
447 "string...."
448 The first form is an RFC 3315 DUID. This is legal for both IPv4
451 DHCP and DHCPv6. For IPv4, an RFC 4361 Client ID is constructed
452 from this value. In this first form, the format of data...
453 depends on the decimal value. The following formats are defined
454 for this first form:
455 1,hwtype,time,lla
457 Type 1, DUID-LLT. The hwtype value is an integer in the
459 range 0-65535, and indicates the type of hardware. The time
460 value is the number of seconds since midnight, January 1st,
461 2000 UTC, and can be omitted to use the current system
462 time. The lla value is either a colon-separated MAC address
463 or the name of a physical interface. If the name of an
464 interface is used, the hwtype value can be omitted. For
465 example: 1,,,hme0
466 2,enterprise,hex...
469 Type 2, DUID-EN. The enterprise value is an integer in the
471 range 0-4294967295 and represents the SMI Enterprise number
472 for an organization. The hex string is an even-length
473 sequence of hexadecimal digits.
474 3,hwtype,lla
477 Type 3, DUID-LL. This is the same as DUID-LLT (type 1),
479 except that a time stamp is not used.
480 *,hex
483 Any other type value (0 or 4-65535) can be used with an
485 even-length hexadecimal string.
486 The second and third forms of CLIENT_ID are legal for IPv4
488 only. These both represent raw Client ID (without RFC 4361), in
489 hex, or NVT ASCII string format. Thus, "Sun" and 0x53756E are
490 equivalent.
491 PARAM_REQUEST_LIST
494 Specifies a list of comma-separated integer values of options
496 for which the client would like values, or symbolic Site or
497 Option option names. Symbolic option names for IPv4 are
498 resolved through /etc/dhcp/inittab. Option names for IPv6 are
499 resolved by means of /etc/dhcp/inittab6.
500 PARAM_IGNORE_LIST
503 Specifies a list of options (constructed in the same manner as
505 PARAM_REQUEST_LIST) that the DHCP client will ignore. Ignored
506 options are treated as though the server did not return the
507 options specified. Ignored options are not visible using
508 dhcpinfo(1) or acted on by the client. This parameter can be
509 used, for example, to disable an unwanted client name or
510 default router.
511 REQUEST_HOSTNAME
514 Indicates the client requests the DHCP server to map the
516 client's leased IPv4 address to the host name associated with
517 the network interface that performs DHCP on the client. The
518 host name must be specified in the /etc/hostname.interface file
519 for the relevant interface on a line of the form
520 inet hostname
522 where hostname is the host name requested.
525 This option works with DHCPv4 only.
527 /etc/dhcp/eventhook
531 Location of a DHCP event program.
533
536 See attributes(5) for descriptions of the following attributes:
537 ┌─────────────────────────────┬─────────────────────────────┐
542 │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
543 ├─────────────────────────────┼─────────────────────────────┤
544 │Availability │SUNWcsr │
545 ├─────────────────────────────┼─────────────────────────────┤
546 │Interface Stability │Committed │
547 └─────────────────────────────┴─────────────────────────────┘
548
550 dhcpinfo(1), ifconfig(1M), init(1M), in.mpathd(1M), in.ndpd(1M), sys‐
551 log(3C), attributes(5), dhcp(5)
552 Croft, B. and Gilmore, J.,Bootstrap Protocol (BOOTP)RFC 951, Network
558 Working Group, September 1985.
559 Droms, R., Dynamic Host Configuration Protocol, RFC 2131, Network Work‐
562 ing Group, March 1997.
563 Lemon, T. and B. Sommerfeld. RFC 4361, Node-specific Client Identifiers
566 for Dynamic Host Configuration Protocol Version Four (DHCPv4). Nominum
567 and Sun Microsystems. February 2006.
568 Droms, R. RFC 3315, Dynamic Host Configuration Protocol for IPv6
571 (DHCPv6). Cisco Systems. July 2003.
572
574 The dhcpagent daemon can be used on IPv4 logical interfaces, just as
575 with physical interfaces. When used on a logical interface, the daemon
576 automatically constructs a Client ID value based on the DUID and IAID
577 values, according to RFC 4361. The /etc/default/dhcpagent CLIENT_ID
578 value, if any, overrides this automatic identifier.
579 As with physical IPv4 interfaces, the /etc/hostname.hme0:1 and
582 /etc/dhcp.hme0:1 files must also be created in order for hme0:1 to be
583 automatically plumbed and configured at boot. In addition, unlike phys‐
584 ical IPv4 interfaces, dhcpagent does not add or remove default routes
585 associated with logical interfaces.
586 DHCP can be performed on IPMP IP interfaces to acquire and maintain
589 IPMP data addresses. Because an IPMP IP interface has no hardware
590 address, the daemon automatically constructs a Client ID using the same
591 approach described above for IPv4 logical interfaces. In addition, the
592 lack of a hardware address means the daemon must set the "broadcast"
593 flag in all DISCOVER and REQUEST messages on IPMP IP interfaces. Some
594 DHCP servers may refuse such requests.
595 DHCP can be performed on IP interfaces that are part of an IPMP group
598 (to acquire and maintain test addresses). The daemon will automatically
599 set the NOFAILOVER and DEPRECATED flags on each test address. Addition‐
600 ally, the daemon will not add or remove default routes in this case.
601 Note that the actual DHCP packet exchange may be performed over any
602 active IP interface in the IPMP group. It is strongly recommended that
603 test addresses have infinite leases. Otherwise, an extended network
604 outage detectable only by probes may cause test address leases to
605 expire, causing in.mpathd(1M) to revert to link-based failure detection
606 and trigger an erroneous repair.
607 With DHCPv6, the link-local interface must be configured using
610 /etc/hostname6.hme0 in order for DHCPv6 to run on hme0 at boot time.
611 The logical interfaces for each address are plumbed by dhcpagent auto‐
612 matically.
613SunOS 5.11 21 Sep 2009 dhcpagent(1M)