Clearview IPMP manpages
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 --- EOF ---