1 System Administration Commands dhcpagent(1M)
2
3
4
5 NAME
6 dhcpagent - Dynamic Host Configuration Protocol (DHCP)
7 client daemon
8
9 SYNOPSIS
10 dhcpagent [-a] [ -d n] [-f] [-v]
11
12
13 DESCRIPTION
14 dhcpagent implements the client half of the Dynamic Host
15 Configuration Protocol (DHCP) for machines running Solaris
16 software.
17
18
19 The dhcpagent daemon obtains configuration parameters for
20 the client (local) machine's network interfaces from a DHCP
21 server. These parameters may include a lease on an IP
22 address, which gives the client machine use of the address
23 for the period of the lease, which may be infinite. If the
24 client wishes to use the IP address for a period longer than
25 the lease, it must negotiate an extension using DHCP. For
26 this reason, dhcpagent must run as a daemon, terminating
27 only when the client machine powers down.
28
29
30 For IPv4, the dhcpagent daemon is controlled through
31 ifconfig(1M) in much the same way that the init(1M) daemon
32 is controlled by telinit(1M). dhcpagent can be invoked as a
33 user process, albeit one requiring root privileges, but this
34 is not necessary, as ifconfig(1M) will start it automati-
35 cally.
36
37
38 For IPv6, the dhcpagent daemon is invoked automatically by
39 in.ndpd(1M). It can also be controlled through ifconfig(1M),
40 if necessary.
41
42
43 When invoked, dhcpagent enters a passive state while it
44 awaits instructions from ifconfig(1M) or in.ndpd(1M). When
45 it receives a command to configure an interface, it brings
46 up the interface (if necessary) and starts DHCP. Once DHCP
47 is complete, dhcpagent can be queried for the values of the
48 various network parameters. In addition, if DHCP was used
49 to obtain a lease on an address for an interface, it con-
50 figures the address for use. When a lease is obtained, it
51 is automatically renewed as necessary. If the lease cannot
52 be renewed, dhcpagent will unconfigure the address, but the
53 interface will be left up and dhcpagent will attempt to
54 acquire a new address lease. dhcpagent monitors system
55 suspend/resume events and will validate any non-permanent
56 leases with the DHCP server upon resume. Similarly,
57
58
59
60 SunOS 5.11 Last change: 15 May 2008 1
61
62
63
64
65
66
67 System Administration Commands dhcpagent(1M)
68
69
70
71 dhcpagent monitors link up/down events and will validate
72 any non-permanent leases with the DHCP server when the
73 downed link is brought back up.
74
75
76 For IPv4, if the configured interface is found to be
77 unplumbed, marked down, or to have a different IP address,
78 subnet mask, or broadcast address from those obtained from
79 DHCP, the interface is abandoned by DHCP control.
80
81
82 For IPv6, dhcpagent automatically plumbs and unplumbs logi-
83 cal interfaces as necessary for the IPv6 addresses supplied
84 by the server. The IPv6 prefix length (netmask) is not set
85 by the DHCPv6 protocol, but is instead set by in.ndpd(1M)
86 using prefix information obtained by Router Advertisements.
87 If any of the logical interfaces created by dhcpagent is
88 unplumbed, marked down, or configured with a different IP
89 address, it will be abandoned by DHCP control. If the link-
90 local interface is unplumbed, then all addresses configured
91 by DHCP on that physical interface will be removed.
92
93
94 In addition to DHCP, dhcpagent also supports BOOTP (IPv4
95 only). See RFC 951, Bootstrap Protocol. Configuration param-
96 eters obtained from a BOOTP server are treated identically
97 to those received from a DHCP server, except that the IP
98 address received from a BOOTP server always has an infinite
99 lease.
100
101
102 DHCP also acts as a mechanism to configure other information
103 needed by the client, for example, the domain name and
104 addresses of routers. Aside from the IP address, and for
105 IPv4 alone, the netmask, broadcast address, and default
106 router, the agent does not directly configure the worksta-
107 tion, but instead acts as a database which may be interro-
108 gated by other programs, and in particular by dhcpinfo(1).
109
110
111 On clients with a single interface, this is quite straight-
112 forward. Clients with multiple interfaces may present diffi-
113 culties, as it is possible that some information arriving on
114 different interfaces may need to be merged, or may be incon-
115 sistent. Furthermore, the configuration of the interfaces is
116 asynchronous, so requests may arrive while some or all of
117 the interfaces are still unconfigured. To handle these
118 cases, one interface may be designated as primary, which
119 makes it the authoritative source for the values of DHCP
120 parameters in the case where no specific interface is
121 requested. See dhcpinfo(1) and ifconfig(1M) for details.
122
123
124
125
126 SunOS 5.11 Last change: 15 May 2008 2
127
128
129
130
131
132
133 System Administration Commands dhcpagent(1M)
134
135
136
137 For IPv4, the dhcpagent daemon can be configured to request
138 a particular host name. See the REQUEST_HOSTNAME description
139 in the FILES section. When first configuring a client to
140 request a host name, you must perform the following steps as
141 root to ensure that the full DHCP negotiation takes place:
142
143 # pkill dhcpagent
144 # rm /etc/dhcp/interface.dhc
145 # reboot
146
147
148
149
150 All DHCP packets sent by dhcpagent include a vendor class
151 identifier (RFC 2132, option code 60; RFC 3315, option code
152 16). This identifier is the same as the platform name
153 returned by the uname -i command, except:
154
155 o Any commas in the platform name are changed to
156 periods.
157
158 o If the name does not start with a stock symbol and
159 a comma, it is automatically prefixed with SUNW.
160
161 Messages
162 The dhcpagent daemon writes information and error messages
163 in five categories:
164
165 critical
166
167 Critical messages indicate severe conditions that
168 prevent proper operation.
169
170
171 errors
172
173 Error messages are important, sometimes unrecoverable
174 events due to resource exhaustion and other unexpected
175 failure of system calls; ignoring errors may lead to
176 degraded functionality.
177
178
179 warnings
180
181 Warnings indicate less severe problems, and in most
182 cases, describe unusual or incorrect datagrams received
183 from servers, or requests for service that cannot be
184 provided.
185
186
187 informational
188
189
190
191
192 SunOS 5.11 Last change: 15 May 2008 3
193
194
195
196
197
198
199 System Administration Commands dhcpagent(1M)
200
201
202
203 Informational messages provide key pieces of information
204 that can be useful to debugging a DHCP configuration at
205 a site. Informational messages are generally controlled
206 by the -v option. However, certain critical pieces of
207 information, such as the IP address obtained, are always
208 provided.
209
210
211 debug
212
213 Debugging messages, which may be generated at two dif-
214 ferent levels of verbosity, are chiefly of benefit to
215 persons having access to source code, but may be useful
216 as well in debugging difficult DHCP configuration prob-
217 lems. Debugging messages are only generated when using
218 the -d option.
219
220
221
222 When dhcpagent is run without the -f option, all messages
223 are sent to the system logger syslog(3C) at the appropriate
224 matching priority and with a facility identifier LOG_DAEMON.
225 When dhcpagent is run with the -f option, all messages are
226 directed to standard error.
227
228 DHCP Events and User-Defined Actions
229 If an executable (binary or script) is placed at
230 /etc/dhcp/eventhook, the dhcpagent deamon will automatically
231 run that program when any of the following events occur:
232
233 BOUND and BOUND6
234
235 These events occur during interface configuration. The
236 event program is invoked when dhcpagent receives the
237 DHCPv4 ACK or DHCPv6 Reply message from the DHCP server
238 for the lease request of an address, indicating success-
239 ful initial configuration of the interface. (See also
240 the INFORM and INFORM6 events, which occur when confi-
241 guration parameters are obtained without address
242 leases.)
243
244
245 EXTEND and EXTEND6
246
247 These events occur during lease extension. The event
248 program is invoked just after dhcpagent receives the
249 DHCPv4 ACK or DHCPv6 Reply from the DHCP server for the
250 DHCPv4 REQUEST (renew) message or the DHCPv6 Renew or
251 Rebind message.
252
253 Note that with DHCPv6, the server might choose to remove
254 some addresses, add new address leases, and ignore
255
256
257
258 SunOS 5.11 Last change: 15 May 2008 4
259
260
261
262
263
264
265 System Administration Commands dhcpagent(1M)
266
267
268
269 (allow to expire) still other addresses in a given Reply
270 message. The EXTEND6 event occurs when a Reply is
271 received that leaves one or more address leases still
272 valid, even if the Reply message does not extend the
273 lease for any address. The event program is invoked just
274 before any addresses are removed, but just after any new
275 addresses are added. Those to be removed will be marked
276 with the IFF_DEPRECATED flag.
277
278
279 EXPIRE and EXPIRE6
280
281 These events occur during lease expiration. For DHCPv4,
282 the event program is invoked just before the leased
283 address is removed from an interface and the interface
284 is marked as down. For DHCPv6, the event program is
285 invoked just before the last remaining leased addresses
286 are removed from the interface.
287
288
289 DROP and DROP6
290
291 These events occur during the period when an interface
292 is dropped. The event program is invoked just before the
293 interface is removed from DHCP control. If the interface
294 has been abandoned due the user unplumbing the inter-
295 face, then this event will occur after the user's action
296 has taken place. The interface might not be present.
297
298
299 INFORM and INFORM6
300
301 These events occur when an interface acquires new or
302 updated configuration information from a DHCP server by
303 means of the DHCPv4 INFORM or the DHCPv6 Information-
304 Request message. These messages are sent using an
305 ifconfig(1M) dhcp inform command or when the DHCPv6
306 Router Advertisement O (letter 0) bit is set and the M
307 bit is not set. Thus, these events occur when the DHCP
308 client does not obtain an IP address lease from the
309 server, and instead obtains only configuration parame-
310 ters.
311
312
313 LOSS6
314
315 This event occurs during lease expiration when one or
316 more valid leases still remain. The event program is
317 invoked just before expired addresses are removed. Those
318 being removed will be marked with the IFF_DEPRECATED
319 flag.
320
321
322
323
324 SunOS 5.11 Last change: 15 May 2008 5
325
326
327
328
329
330
331 System Administration Commands dhcpagent(1M)
332
333
334
335 Note that this event is not associated with the receipt
336 of the Reply message, which occurs only when one or more
337 valid leases remain, and occurs only with DHCPv6. If all
338 leases have expired, then the EXPIRE6 event occurs
339 instead.
340
341
342 RELEASE and RELEASE6
343
344 This event occurs during the period when a leased
345 address is released. The event program is invoked just
346 before dhcpagent relinquishes the address on an inter-
347 face and sends the DHCPv4 RELEASE or DHCPv6 Release
348 packet to the DHCP server.
349
350
351
352 The system does not provide a default event program. The
353 file /etc/dhcp/eventhook is expected to be owned by root and
354 have a mode of 755.
355
356
357 The event program will be passed two arguments, the inter-
358 face name and the event name, respectively. For DHCPv6, the
359 interface name is the name of the physical interface.
360
361
362 The event program can use the dhcpinfo(1) utility to fetch
363 additional information about the interface. While the event
364 program is invoked on every event defined above, it can
365 ignore those events in which it is not interested. The event
366 program runs with the same privileges and environment as
367 dhcpagent itself, except that stdin, stdout, and stderr are
368 redirected to /dev/null. Note that this means that the event
369 program runs with root privileges.
370
371
372 If an invocation of the event program does not exit after 55
373 seconds, it is sent a SIGTERM signal. If does not exit
374 within the next three seconds, it is terminated by a SIGKILL
375 signal.
376
377
378 See EXAMPLES for an example event program.
379
380 OPTIONS
381 The following options are supported:
382
383 -a
384
385 Adopt a configured IPv4 interface. This option is for
386 use with diskless DHCP clients. In the case of diskless
387
388
389
390 SunOS 5.11 Last change: 15 May 2008 6
391
392
393
394
395
396
397 System Administration Commands dhcpagent(1M)
398
399
400
401 DHCP, DHCP has already been performed on the network
402 interface providing the operating system image prior to
403 running dhcpagent. This option instructs the agent to
404 take over control of the interface. It is intended pri-
405 marily for use in boot scripts.
406
407 The effect of this option depends on whether the inter-
408 face is being adopted.
409
410 If the interface is being adopted, the following condi-
411 tions apply:
412
413 dhcpagent uses the client id specified in
414 /chosen:<client_id>, as published by the PROM or as
415 specified on a boot(1M) command line. If this value is
416 not present, the client id is undefined. The DHCP server
417 then determines what to use as a client id. It is an
418 error condition if the interface is an Infiniband inter-
419 face and the PROM value is not present.
420
421 If the interface is not being adopted:
422
423 dhcpagent uses the value stored in
424 /etc/default/dhcpagent. If this value is not present,
425 the client id is undefined. If the interface is Infini-
426 band and there is no value in /etc/default/dhcpagent, a
427 client id is generated as described by the draft docu-
428 ment on DHCP over Infiniband, available at:
429
430 http://www.ietf.org
431
432
433
434 -d n
435
436 Set debug level to n. Two levels of debugging are
437 currently available, 1 and 2; the latter is more ver-
438 bose.
439
440
441 -f
442
443 Run in the foreground instead of as a daemon process.
444 When this option is used, messages are sent to standard
445 error instead of to syslog(3C).
446
447
448 -v
449
450 Provide verbose output useful for debugging site confi-
451 guration problems.
452
453
454
455
456 SunOS 5.11 Last change: 15 May 2008 7
457
458
459
460
461
462
463 System Administration Commands dhcpagent(1M)
464
465
466
467 EXAMPLES
468 Example 1 Example Event Program
469
470
471 The following script is stored in the file
472 /etc/dhcp/eventhook, owned by root with a mode of 755. It is
473 invoked upon the occurrence of the events listed in the
474 file.
475
476
477 #!/bin/sh
478
479 (
480 echo "Interface name: " $1
481 echo "Event: " $2
482
483 case $2 in
484 "BOUND")
485 echo "Address acquired from server "\
486 `/sbin/dhcpinfo -i $1 ServerID`
487 ;;
488 "BOUND6")
489 echo "Addresses acquired from server " \
490 `/sbin/dhcpinfo -v6 -i $1 ServerID`
491 ;;
492 "EXTEND")
493 echo "Lease extended for " \
494 `sbin/dhcpinfo -i $1 LeaseTim`" seconds"
495 ;;
496 "EXTEND6")
497 echo "New lease information obtained on $i"
498 ;;
499 "EXPIRE" | "DROP" | "RELEASE")
500 ;;
501
502 esac
503 ) >/var/run/dhcp_eventhook_output 2>&1
504
505
506
507
508 Note the redirection of stdout and stderr to a file.
509
510
511 FILES
512 /etc/dhcp/if.dhc
513 /etc/dhcp/if.dh6
514
515 Contains the configuration for interface. The mere
516 existence of this file does not imply that the confi-
517 guration is correct, since the lease might have expired.
518 On start-up, dhcpagent confirms the validity of the
519
520
521
522 SunOS 5.11 Last change: 15 May 2008 8
523
524
525
526
527
528
529 System Administration Commands dhcpagent(1M)
530
531
532
533 address using REQUEST (for DHCPv4) or Confirm (DHCPv6).
534
535
536 /etc/dhcp/duid
537 /etc/dhcp/iaid
538
539 Contains persistent storage for DUID (DHCP Unique Iden-
540 tifier) and IAID (Identity Association Identifier)
541 values. The format of these files is undocumented, and
542 applications should not read from or write to them.
543
544
545 /etc/default/dhcpagent
546
547 Contains default values for tunable parameters. All
548 values may be qualified with the interface they apply to
549 by prepending the interface name and a period (".") to
550 the interface parameter name. The parameters include:
551 the interface parameter name.
552
553 To configure IPv6 parameters, place the string .v6
554 between the interface name (if any) and the parameter
555 name. For example, to set the global IPv6 parameter
556 request list, use .v6.PARAM_REQUEST_LIST. To set the
557 CLIENT_ID (DUID) on hme0, use hme0.v6.CLIENT_ID.
558
559 The parameters include:
560
561 RELEASE_ON_SIGTERM
562
563 Indicates that a RELEASE rather than a DROP should
564 be performed on managed interfaces when the agent
565 terminates. Release causes the client to discard the
566 lease, and the server to make the address available
567 again. Drop causes the client to record the lease in
568 /etc/dhcp/interface.dhc or /etc/dhcp/interface.dh6
569 for later use.
570
571
572 OFFER_WAIT
573
574 Indicates how long to wait between checking for
575 valid OFFERs after sending a DISCOVER. For DHCPv6,
576 sets the time to wait between checking for valid
577 Advertisements after sending a Solicit.
578
579
580 CLIENT_ID
581
582 Indicates the value that should be used to uniquely
583 identify the client to the server. This value can
584 take one of three basic forms:
585
586
587
588 SunOS 5.11 Last change: 15 May 2008 9
589
590
591
592
593
594
595 System Administration Commands dhcpagent(1M)
596
597
598
599 decimal,data...
600 0xHHHHH...
601 "string...."
602
603
604 The first form is an RFC 3315 DUID. This is legal
605 for both IPv4 DHCP and DHCPv6. For IPv4, an RFC 4361
606 Client ID is constructed from this value. In this
607 first form, the format of data... depends on the
608 decimal value. The following formats are defined for
609 this first form:
610
611 1,hwtype,time,lla
612
613 Type 1, DUID-LLT. The hwtype value is an integer
614 in the range 0-65535, and indicates the type of
615 hardware. The time value is the number of
616 seconds since midnight, January 1st, 2000 UTC,
617 and can be omitted to use the current system
618 time. The lla value is either a colon-separated
619 MAC address or the name of a physical interface.
620 If the name of an interface is used, the hwtype
621 value can be omitted. For example: 1,,,hme0
622
623
624 2,enterprise,hex...
625
626 Type 2, DUID-EN. The enterprise value is an
627 integer in the range 0-4294967295 and represents
628 the SMI Enterprise number for an organization.
629 The hex string is an even-length sequence of
630 hexadecimal digits.
631
632
633 3,hwtype,lla
634
635 Type 3, DUID-LL. This is the same as DUID-LLT
636 (type 1), except that a time stamp is not used.
637
638
639 *,hex
640
641 Any other type value (0 or 4-65535) can be used
642 with an even-length hexadecimal string.
643
644 The second and third forms of CLIENT_ID are legal
645 for IPv4 only. These both represent raw Client ID
646 (without RFC 4361), in hex, or NVT ASCII string for-
647 mat. Thus, Sun and 0x53756E are equivalent.
648
649
650
651
652
653
654 SunOS 5.11 Last change: 15 May 2008 10
655
656
657
658
659
660
661 System Administration Commands dhcpagent(1M)
662
663
664
665 PARAM_REQUEST_LIST
666
667 Specifies a list of comma-separated integer values
668 of options for which the client would like values.
669
670
671 REQUEST_HOSTNAME
672
673 Indicates the client requests the DHCP server to map
674 the client's leased IPv4 address to the host name
675 associated with the network interface that performs
676 DHCP on the client. The host name must be specified
677 in the /etc/hostname.interface file for the relevant
678 interface on a line of the form
679
680 inet hostname
681
682
683 where hostname is the host name requested.
684
685 This option works with DHCPv4 only.
686
687
688
689 /etc/dhcp/eventhook
690
691 Location of a DHCP event program.
692
693
694 ATTRIBUTES
695 See attributes(5) for descriptions of the following attri-
696 butes:
697
698
699
700 ____________________________________________________________
701 | ATTRIBUTE TYPE | ATTRIBUTE VALUE |
702 |_____________________________|_____________________________|
703 | Availability | SUNWcsr |
704 |_____________________________|_____________________________|
705 | Interface Stability | Committed |
706 |_____________________________|_____________________________|
707
708
709 SEE ALSO
710 dhcpinfo(1), ifconfig(1M), init(1M), in.ndpd(1M),
711 syslog(3C), attributes(5), dhcp(5)
712
713
714 Croft, B. and Gilmore, J.,Bootstrap Protocol (BOOTP)RFC 951,
715 Network Working Group, September 1985.
716
717
718
719
720 SunOS 5.11 Last change: 15 May 2008 11
721
722
723
724
725
726
727 System Administration Commands dhcpagent(1M)
728
729
730
731 Droms, R., Dynamic Host Configuration Protocol, RFC 2131,
732 Network Working Group, March 1997.
733
734
735 Lemon, T. and B. Sommerfeld. RFC 4361, Node-specific Client
736 Identifiers for Dynamic Host Configuration Protocol Version
737 Four (DHCPv4). Nominum and Sun Microsystems. February 2006.
738
739
740 Droms, R. RFC 3315, Dynamic Host Configuration Protocol for
741 IPv6 (DHCPv6). Cisco Systems. July 2003.
742
743 NOTES
744 The dhcpagent daemon can be used on IPv4 logical interfaces,
745 just as with physical interfaces. When used on a logical
746 interface, the daemon automatically constructs a Client ID
747 value based on the DUID and IAID values, according to RFC
748 4361. The /etc/default/dhcpclient CLIENT_ID value, if any,
749 overrides this automatic identifier.
750
751
752 As with physical IPv4 interfaces, the /etc/hostname.hme0:1
753 and /etc/dhcp.hme0:1 files must also be created in order for
754 hme0:1 to be automatically plumbed and configured at boot.
755 In addition, unlike physical IPv4 interfaces, dhcpagent does
756 not add or remove default routes associated with logical
757 interfaces.
758
759
760 With DHCPv6, the link-local interface must be configured
761 using /etc/hostname6.hme0 in order for DHCPv6 to run on hme0
762 at boot time. The logical interfaces for each address are
763 plumbed by dhcpagent automatically.
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786 SunOS 5.11 Last change: 15 May 2008 12
787
788
789