proclaim(1M)proclaim(1M)NAMEproclaim - 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.
Page 1
proclaim(1M)proclaim(1M)
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.
Page 2
proclaim(1M)proclaim(1M)
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.
Page 3
proclaim(1M)proclaim(1M)
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).
Page 4
proclaim(1M)proclaim(1M)
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 ALSObootp(1M), dhcp_bootp(1M), inetd(1M), propel(1M), run-proclaim(1M),
syslogd(1M), ethers(4), hosts(4)
Page 5
