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