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, 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 --- EOF ---