proclaim(1M) proclaim(1M) NAME proclaim - client for Dynamic Host Configuration Protocol (DHCP) SYNOPSIS /usr/etc/proclaim [ -B ] [ -b lease_time ] [ -d -s server_addr ] [ -E ] [ -e 2nd_interface ] [ -I ] [ -i ] [ -l lease_time ] [ -p ] [ -r lease_time -s server_addr ] [ -t repeat ] [ -x max_timeout ] [ -H hostname ] [ -w -h host_name -a ip_addr ] DESCRIPTION Proclaim is a client that communicates with a DHCP server to obtain configuration parameters, including at least an IP address. The format of DHCP messages is based on the format of bootp messages, described in RFC 951. A detailed protocol specification of DHCP is in RFC 2131, available from the Network Information Center. The DHCP protocol uses UDP/IP as its transport mechanism. The DHCP server receives service requests at the UDP port indicated in the bootp service description contained in the file /etc/services; see services(4). Proclaim can be used to setup and configure new systems automatically, and to move systems from one net to another without administrative intervention. It can also be used to automatically verify current configurations at reboot. Only the superuser can employ proclaim. If the primary network interface is changed, proclaim updates the netaddr variable in the NVRAM. In the absence of the DHCPoptionsToGet keyword, proclaim requests the following configuration parameters from an available DHCP server: an IP address the lease duration (3 year default) the subnet mask hostname (users may be allowed to choose their own) DNS domainname NIS domainname if the NIS option is installed. IP address of the DHCP server; see dhcp_bootp(1M). The DHCP server is started by inetd(1M), as configured in the inetd.conf file. The basic operation of the DHCP protocol is a series of packet exchanges as follows: 1) The client machine broadcasts a DHCPDISCOVER packet to the DHCP server's UDP port, using a UDP broadcast equivalent. The request packet includes the requester's network hardware address, and a list of desired configuration options as described above. 2) All the DHCP servers on the same network as the client machine receive the client's request as do the bootp relay agents, which forward the request to other subnets. 3) The server looks up the requester in its configuration files to determine if it is configured to serve clients from the requesting subnet. The server now looks in the propel database or the /etc/ethers file (see ethers(4)) for an entry with the client's network hardware address. If an entry is found, the server checks the hostname of that entry against the propel database or the /etc/hosts file (see hosts(4)) to complete the network hardware address to Internet address mapping. If no entry is found, the server generates an appropriate IP address and hostname using its configuration files; see dhcp_bootp(1M). 4) The server now returns a response in the form of a DHCPOFFER packet, which also includes other configuration information requested by the client. 5) The client accepts the first valid offer from a server and broadcasts back a DHCPREQUEST message, which includes all the configuration options from the DHCPDISCOVER message plus the address of the selected server. 6) The selected server makes a permanent mapping for the client's hostname, IP address, and hardware address, and responds with a DHCPACK message. 7) On receiving the DHCPACK message from the server, the client writes the configuration information into the appropriate configuration files and then executes the networking initialization scripts. If the server is configured in a manner where clients from specific subnets are allowed to choose their own hostname, then at the receipt of the DHCPOFFER message the client requests user input to either accept the offered hostname or specify a different one. This dialog between the server and client continues until a valid and unique mutually acceptable name is selected. Alternately, the -w option can be used to request a hostname and/or IP address non-interactively. The client will print an error and exit if the requested hostname or address is invalid. Proclaim sleeps after obtaining a new lease or after verifying an existing lease, until it is time to renew the lease. The client wakes up at times specified by the DHCP protocol and attempts to renew the lease until it succeeds or the current lease expires. If the client is unable to renew the lease then it can shutoff network access depending on the use of the -E option. OPTIONS The -B option broadcasts a BOOTP packet to a BOOTP 1533 server. This is useful when you just want to obtain the other configuration data, and the IP address is not otherwise known to the BOOTP or DHCP server. The data is placed in the file /var/adm/proclaim.data. proclaim does not change any networking state with this option. The -b lease_time option is used to manually rebind the lease; a lease_time in seconds must be specified. The -d option allows the client to surrender its address lease and shutdown all networking. This option can only be used in conjunction with the -s server_address option to specify the Proclaim server address. This usually is the server from where the original address lease was obtained. If there is a client running on the host use the /etc/init.d/run-proclaim surrender command to surrender the lease. The -E option is used to specify that network access should be shut off if the client is unable to renew the lease and the lease expires. The default behavior does not shut off network access if the lease expires. The -e 2nd_interface option is used to specify the device for a second network interface. The -I option is used to send a DHCPINFORM packet to a DHCP server. This is useful when an IP address was assigned to the host using some other means and it is required to obtain only other configuration parameters. The -i option is used where the client is seeking to verify a previously allocated, cached configuration. If the client receives a DHCPNAK response to this message, it means that either the 'requested IP address' parameter is incorrect or the client is on the wrong network. The client automatically requests a new address and lease and proceeds to install the new configuration. If there is no response, it means the server(s) has no record of this client. These messages are logged using the system logging daemon syslogd(1M). If a client is running on the host use the /etc/init.d/run-proclaim verify command to verify the lease. The -l lease_time option is used to request a different address lease duration than the default of 3 years. The lease time needs to be specified in number of seconds. The -p option is used to print the status of the current lease and other configuration parameters. This status is obtained from the /var/adm/proclaim.lease_info file created at the time the lease was obtained. The -r lease_time -s server_addr option is used to manually renew the lease; a lease_time in seconds must be specified. The server_addr specifies the server with which to renew the lease. The server address may be obtained by using the -p option of proclaim. The -t invocations option is used to specify the number of invocations of the client using the run-proclaim(1M) script, after which the autoconfig_ipaddress flag is set to off (see chkconfig(1M)). When this option is not specified the client may be run up to a default 2 (or as specified in the /etc/config/proclaim.options file) number of times using the script after which the flag is set to off. Use of the script to run the client requires the flag to be set to on. The -x max_timeout option is used to specify a maximum timeout (time to wait for a server to reply) in seconds. The current default is set to 6 seconds. Thw -H hostname option is used to specify a hostname using the DHCP Host Name Option. The run-proclaim(1M) script uses this option to request the current hostname of the client from the server. The -w -h host_name -a ip_addr option is used to choose a hostname and IP address without the user being prompted by the client. If no host_name or ip_addr is specified, the the hostname and IP address offered by the server will be used. If only the host_name is specified, the server will choose an appropriate IP address. This option was added to make it possible to run proclaim from a CGI script. Options File Options may also be specified in the /etc/config/proclaim.options file. Options specified on the command line supersede those specified in this file. Lines beginning with a '#' are treated as comments. The option keywords in this file must be followed immediately by a colon, then by any number of tabs or spaces, and finally by the value of the option. Here are the supported keywords: Invocations equivalent to -t option MaxTimeout equivalent to -x option ServerAddress equivalent to -s option ShutdownOnExpiry equivalent to -E option Lease equivalent to -l option DHCPoptionsToGet additional options to request from DHCP server DHCPoptionsRenew options to request for lease renewal/rebind The values for DHCPoptionsToGet and DHCPoptionsRenew are specified by listing the option numbers separated only by a comma. Example: DHCPoptionsToGet: 3,6,26,27,41 DHCPoptionsToGet lists options to get in addition to the standard (default) configuration. This affects the initial lease request. NOTE: Options obtained by default (1,12,15,40,50,51,54) should NOT be listed in DHCPoptionsToGet - this could lead to duplicate lines in the proclaim.lease_info_ascii.xxx file. See RFC 2132 for a complete list of the options. DHCPoptionsRenew specifies what options should be included in the renew/rebind request. DHCPoptionsRenew is expected to be a subset of the options requested when the lease is acquired (the standard configuration parameters plus the additional ones listed in DHCPoptionsToGet). Options returned from a renew/rebind request will be checked. If basic values have changed (IP address, host name, subnet mask, DNS domain, NIS domain) the host will be reconfigured and the /usr/etc/dhcpcopt script will be run. If only non-basic values have changed only the script will be run. The dhcpcopt script file contains processing of the gateway, DNS domain and NIS domain. A script file /usr/etc/dhcpcopt.local may be created to add processing of options. If this file exists, dhcpcopt calls it for additional actions for the options returned. Additional options which are not keywords specify whether the run- proclaim script should try to obtain configuration parameters for all the network interfaces on the system. If none of these options are present then the proclaim client is invoked for the primary interface only. The options are: Primary on|off Interface interface on|off The presence of an on invokes the proclaim client and off does not invoke it for the specified interface when the run-proclaim script is executed with a start argument. The value of interface is the name, for example, ec1, xpi1, etc. FILES /etc/hosts /etc/ethers /etc/config/ifconfig-1.options /.rhosts /etc/sys_id /usr/etc/yp/ypdomain /etc/init.d/network /var/adm/proclaim.lease_info /var/adm/proclaim.data /etc/config/proclaim.options /etc/init.d/run-proclaim /usr/etc/dhcpcopt /usr/etc/dhcpcopt.local SEE ALSO bootp(1M), dhcp_bootp(1M), inetd(1M), propel(1M), run-proclaim(1M), syslogd(1M), ethers(4), hosts(4) Page 5