SGI Techpubs Library

IRIX 6.5  »  Man Pages
find in page

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)




home/search | what's new | help