# Compaq TCP/IP Services for OpenVMS
Management

Previous | Contents | Index

## 8.2.2 Configuration Files

DHCP client uses the following files to control its environment:

- Configuration
- Interface
- Host name
- DHCPTAGS

### 8.2.2.1 Client Configuration File

DHCP client has one configuration file that controls DHCP client behavior. This optional file, named CLIENT.PCY, is an ASCII file located in the DHCP home directory, which is either SYS$SYSDEVICE:[TCPIP$DHCP] or a directory pointed to by the system logical TCPIP$DHCP_CONFIG. If CLIENT.PCY does not exist, DHCP client uses default values for each of the configurable parameters.

Example 8-1 shows the contents of a typical CLIENT.PCY file.

Example 8-1 Client Startup File

    $ TYPE CLIENT.PCY
    class_id TCPVMS
    lease_desired 86400          #   24 hour lease
    request routers
    request host_name
    request dns_servers
    request dns_domain_name

The format of the configuration file must adhere to the following rules:

- Blank lines are ignored.
- The pound (#) character introduces a comment that continues to the next newline character.
- Each new policy option must begin and end on a separate line.
- Policy options are introduced by a keyword and may be Boolean, or they may take a value separated from the keyword by white space (but not a newline character).
- If an option is present more than once, only the value attached to the last occurrence will be take effect; earlier values are ignored.

Table 8-1 describes the configuration keywords.

Table 8-1 Configuration Keywords
Keyword | Description
--- | ---
`class_id` | Specifies the client's class identification. Consult RFC 2131 for details. The only class supported by TCP/IP Services is TCPVMS.
`lease_desired seconds` | Specifies that a client may request a lease of a particular duration, although DHCP servers are not bound to honor the request. If the client does not want a lease of a particular duration, seconds should be set to 0. If an infinite lease is required, set seconds to -1. Otherwise, specify (in seconds) the lease duration required. The default value is 0 seconds. A DHCP server grants a client permission to use an IP address for a fixed period of time, which may be infinite. In the language of DHCP, the client is granted a lease on the IP address.
`retries` | Specifies the maximum number of DHCPDISCOVER, DHCPOFFER, DHCP_REQUEST, DHCPNAK sequences the client attempts. An offer received and then refused is an unusual event; if it occurs more than once, this indicates a problem with the server. If you do not want to limit the number of bad offers that a client is willing to accept, set the value of this parameter to 0 (zero) or a negative value. The default value is 2 attempts.
`start_delay seconds` | Specifies the maximum time (in seconds) the client delays before broadcasting DHCP packets. When the DHCP client is invoked to configure an interface it will delay for a short time before broadcasting the first DHCP packet. The delay time is randomized from a value of 0 up to the value specified by seconds. The TCP/IP commands SET INTERFACE/DHCP and the START COMMUNICATION/INITIALZE command (executed at product startup time) both execute `dhcpconf` start commands and experience the randomized delay. The default value for seconds is 10 seconds.
`timeouts value,value,value....` | Specifies how long the client should wait for replies before timing out and retrying the broadcast. The DHCP protocol requires clients to implement an exponential retransmission and backoff when broadcasting discover or request packets. Each time the client sends a DHCP protocol packet, it waits for a response until a timeout occurs after an interval (in seconds) given by a member of the list of values. If a timeout occurs, the packet retransmits with the same XID (see RFC 1541), and the timeout is set to the next positive value in the comma-separated list. The last element in the list is negative or 0 (zero). At this point, the next action depends on options to the `DHCPCONF` program. One option is to fail. Another option is to retry forever. If the last value in the list is negative, DHCP suspends configuration of the interface for an amount of time given by the negative number terminating the list of values. During this time, the interface is considered idle---the client is not expecting responses destined for the interface and will ignore any that arrive. When the idle time is over, the client begins retransmitting with a new XID, and a timeout value is given by the first element in the array of values. If the last value is 0 (zero), the client continues to use the same XID and timeout of the last positive value in the list of values. The default list of values is 4, 8, 16, 32, 0.
`use_saved_config` | Specifies to use the configuration stored in `ifname.DHC` from a previous invocation of the protocol if the following conditions exist: The lease is still valid. There is no reply to DHCP. `use_saved_config` is set.
`request parameter_name` | Specifies the parameter to request from the DHCP server. There may be many instances of the request keyword, each with a different parameter_name. Each parameter which is configurable through DHCP is identified by a unique parameter. Limited size of DHCP packets dictates that a client should not request data which it cannot use. Different implementations of DHCP servers or differing DHCP server policies can dictate that a server return more configuration parameters than a client requests. On the other hand, some DHCP servers will not send a parameter to a client unless the client explicitly requests it. If your DHCP server is configured to deliver a particular parameter to your TCP/IP Services DHCP client and the client is not receiving the information, verify that the DHCP client has a request statement for the information in its CLIENT.PCY file. Table 8-2 lists the DHCP parameters that a TCP/IP Services DHCP client may request from a server. Note that vendor-specific options, like the ones marked with TCPVMS in columns 3 and 4 of the DHCPTAGS. file entries, may not appear in a request statement.

Table 8-2 lists the Request statement parameters supported by the TCP/IP Services DHCP client implementation.

Table 8-2 Supported Request Parameters
Parameter Name | DHCP Option Code | This parameter requests...
--- | --- | ---
Interface-specific parameters
`broadcast_address` | 28 | The broadcast address in use on the client's subnet.
`interface_mtu` | 26 | The MTU size to use when performing Path MTU discovery.
`subnet_mask` | 1 | The client's subnet mask.
Systemwide parameters
`dns_domain_name` | 15 | The domain name that the client should use when resolving host names using the Domain Name System (DNS).
`dns_servers` | 6 | A list of DNS name servers available to the client.
`host_name` | 12 | The host name of the client.
`ip_time_to_live` | 23 | The default time-to-live value the client should use on outgoing datagrams.
`ip_forwarding` | 19 | How the client should configure its IP layer for packet forwarding.
`keepalive_interval` | 38 | The time interval (in seconds) that the client TCP should wait before sending a keepalive message on a TCP connection.
`routers` | 3 | A list of IP addresses for routers on the client's subnet. Routers are listed in the order of preference.
`static_routes` | 33 | A list of static routes the client should install in its routing cache. If multiple routes to the same destination are specified, they are listed in descending order of priority. The routes consist of a list of IP address pairs. The first address is the destination address and the second address is the router for the destination.
`tcp_default_time_to_live` | 37 | The default time-to-live value that the client uses when sending TCP segments.

### 8.2.2.2 The Interface File

When the DHCP client receives parameters to configure the interface on the client, it stores them in a file named ifname.DHC along with the IP address lease information. The ifname part of the file name is the name of the interface on which the parameters were received. For example, the file created for parameters received on interface SE0 is SE0.DHC. There is one file per interface, and the files are placed in the directory specified by the system logical name TCPIP$DHCP_CONFIG (if it is defined) or in the SYS$SYSDEVICE:[TCPIP$DHCP] directory.

The interface file is a binary file, and you can display its contents by using the SHOWDHC utility. See Section 8.6 for information on how to use the SHOWDHC utility.

### 8.2.2.3 The Host Name File

You can configure the DHCP client to suggest a host name of your choice to the DHCP server by entering the name into a file named HOSTNAME.ifname. This file contains one line of text that contains the unqualified host name to suggest. You store the file in directory specified by the system logical TCPIP$DHCP_CONFIG, if defined, or in the SYS$SYSDEVICE:[TCPIP$DHCP] directory.

If you have multiple interfaces and want to suggest a different host name for each one, put the desired interface host names into separate files called HOSTNAME.ifname, where ifname is the name of the interface. For example, if you have two interfaces, WF0 and WE0, and you want the WF0 interface to receive the host name `myhostfiber` and the WE0 interface to receive the name `myhostether` , enter the following commands:

    $ CREATE SYS$SYSDEVICE:[TCPIP$DHCP]HOSTNAME.WF0
      myhostfiber
      <CTRL-Z>
    $ CREATE SYS$SYSDEVICE:[TCPIP$DHCP]HOSTNAME.WE0
      myhostether
      <CTRL-Z>

When configuring an interface, the DHCP client will first check for a HOSTNAME.ifname file and then, if that is not found, for the HOSTNAME. file.

When you initially configure the DHCP client the value of your node's SCSNODE parameter is placed into a file called HOSTNAME. with no .ifname extension.

If you change the HOSTNAME.ifname file, you must delete the interface.DHC file for the change to take effect.

### 8.2.2.4 The DHCPTAGS. File

The DHCPTAGS. file identifies the type of each parameter returned to the DHCP client by the DHCP server. Each supported option consists of the following:

- Option code number
- A two digit mnemonic code
- A short mnemonic text string for use in the DHCPCAP database
- A description of each option

The options are defined as follows:

- Standard
  The semantics on which all client and server DHCP implementations agree. These options are administered by the Internet Assigned Numbers Authority (IANA). They are numbered from 1 to 127, and 255.
- Site specific
  Within a specific site all client and server implementations agree on the semantics, but at another site the type and meaning of an option may differ. These options are numbered from 128 to 254.
- Vendor specific
  Each vendor may define 256 options unique to that vendor. The vendor is identified within a DHCP packet by the Vendor Class option (#60). An option with a specific numeric identifier belonging to one vendor will, in general, have a type and semantics different from those of another vendor. Vendor options are super encapsulated into the vendor field (#43); within a specific DHCP packet there may be several instances of option #43.
- Pseudotags
  These are fields of the BOOTP packet and are not defined in RFC2131. Do not change these fields.

In general, the DHCP server knows little about the semantics of the first three options. Its only duty is to deliver those values to clients that need them. The responsibility for understanding and using the data rests with the client. Pseudotags have a meaning specific to TCP/IP Services.

## 8.2.3 Command Files

Table 8-3 lists the command files that the DHCP client uses to start up and shut down the component.

Table 8-3 DHCP Client Command Files
Command File Name | Description
--- | ---
TCPIP$DHCP_CLIENT_STARTUP.COM | Installs the DHCP client image.
TCPIP$DHCP_CLIENT_SHUTDOWN.COM | Stops DHCP client.

## 8.2.4 System Logicals

Use the logicals listed in Table 8-4 to alter the behavior of the DHCP client.

Table 8-4 DHCP Client System Logicals
Logical Name | Purpose
--- | ---
TCPIP$DHCP_DEBUG | Turns on DHCP client diagnostics. Refer to Section 7.2.4 for a description of this logical.
TCPIP$DHCP_CONFIG directory | Specifies the directory from which to read input files (CLIENT.PCY, DHCPTAGS. and HOSTNAME.) and to which to write output files ( `ifname` .DHC). Note that DHCP client log files will still go to the default directory of the DHCP client account.
TCPIP$LOG_LEVEL value | Writes the specified level of diagnostic information to the log file. Ignored if TCPIP$DHCP_DEBUG is defined. Valid numeric values are:
0 | No logging (default).
1 | Log warning messages.
2 | Log all messages.

## 8.2.5 Log Files

DHCP client creates a log file named TCPIP$DHCP_CLIENT_RUN.LOG in the directory SYS$SYSDEVICE:[TCPIP$DHCP].

# 8.3 DHCP Client Startup and Shutdown

The DHCP client can be shut down and started independently of TCP/IP Services. This is useful when you change parameters or logical names that require the service to be restarted.

The following files are provided:

- SYS$STARTUP:TCPIP$DHCP_CLIENT_STARTUP.COM allows you to start up the DHCP client service.
- SYS$STARTUP:TCPIP$DHCP_CLIENT_SHUTDOWN.COM allows you to shut down the DHCP client service.

To preserve site-specific parameter settings and commands, create the following files. These files are not overwritten when you reinstall TCP/IP Services:

- SYS$STARTUP:TCPIP$DHCP_CLIENT_SYSTARTUP.COM can be used as a repository for site-specific definitions and parameters to be invoked when DHCP client is started.
- SYS$STARTUP:TCPIP$DHCP_CLIENT_SYSHUTDOWN.COM can be used as a repository for site-specific definitions and parameters to be invoked when DHCP client is shut down.

# 8.4 Configuring the DHCP Client

In order for the DHCP client to run, you must perform the following steps:

1. Put at least one interface under DHCP control.
2. Configure the DHCP client software.

## 8.4.1 Putting Interfaces under DHCP Control

For the DHCP client to execute, at least one interface on your host must be designated as being under DHCP control. This means that the interface IP address, subnet mask, and broadcast address are set automatically by DHCP when the system invokes the command procedure TCPIP$STARTUP.COM.

To place interfaces under DHCP control, you have these options:

- Use DHCP client autoconfigure for new TCP/IP Services installations.
- Use TCPIP$CONFIG to put interfaces under DHCP control.

### 8.4.1.1 Using Autoconfigure on a New TCP/IP Installation

If you have never installed a previous version of UCX or TCP/IP Services, you may simply install TCP/IP Services and manually invoke the SYS$STARTUP:TCPIP$STARTUP.COM procedure. TCPIP$STARTUP.COM detects that you have never run TCPIP$CONFIG and asks whether you want DHCP client to configure your host for you. If you answer Yes, TCPIP$STARTUP.COM invokes TCPIP$CONFIG to configure a small set of services and sets any unconfigured interfaces to be under DHCP control. This process is done in silent mode and asks you no questions.

The services enabled when you autoconfigure are:

- FTP client
- TELNET client
- TELNET server

If you want more than the set of services configured by this option, you can configure your host with the subset of TCP/IP Services and at a later time run TCPIP$CONFIG to configure other services.

DHCP client autoconfigure puts each unconfigured IP interface under DHCP control. It employs the following rules to decide which, if any, interface should be marked as the primary interface. (See Section 8.1.1 for an explanation of the DHCP primary interface.)

- If any interface currently has a permanent IP address, then TCPIP$CONFIG will not mark any of the interfaces under DHCP control as primary.
- If no interfaces are currently configured, then the first interface that TCPIP$CONFIG sees and marks as under DHCP control becomes the primary DHCP interface.

### 8.4.1.2 Using TCPIP$CONFIG to Configure an Existing Installation

If you have an existing TCP/IP installation, use TCPIP$CONFIG to place interfaces under DHCP control. To do this, perform the following steps:

1. From the TCPIP$CONFIG main menu, choose the Core Environment option and then choose the Interfaces option.
2. TCPIP$CONFIG presents a menu for each interface that it finds and gives you the option to:
   - Configure the interface manually.
   - Allow DHCP client to configure the interface.
   - Leave the interface unchanged.
   The following example illustrates this procedure:

       INTERFACE Configuration

               The Ethernet device(s) on your system are: ESA0:

               Start of configuration questions for Internet interface SE0.

               SE0 is the Ethernet device ESA0:
        Interface: SE0
          IP_Addr: 10.0.0.1          NETWRK: 255.0.0.0         BRDCST: 10.255.255.255
           C_Addr:                 C_NETWRK:                 C_BRDCST:

          Flags:
          Receive buffer:            0

               Compaq TCP/IP Services for OpenVMS Interface SE0 Reconfiguration Menu

               Reconfiguration options:

                        1  -  Configure interface manually       (Current default)
                        2  -  Let DHCP configure interface

                       [E] -  Exit menu (Do not reconfigure interface SE0)

       Enter configuration option: 2

       End of configuration questions for Internet interface SE0

3. If the system has multiple interfaces, DHCP client displays information about each existing interface and gives you the option to configure the interface manually or to allow DHCP configure the interface.
4. The next phase in the configuration process allows you to designate an interface as the primary DHCP interface.

              Primary DHCP Interface Configuration

               DHCP Client configures system-wide parameters and
               interface-specific parameters.  Only one interface, the
               DHCP "primary" interface, can receive system-wide
               parameters.

       Which interface? (SE0,NONE,HELP) [NONE]:SE0

5. At this point, TCPIP$CONFIG sets up the account for the DHCP client and default directory and initial copies of the required configuration and data files. For more information, see Section 8.4.2.

## 8.4.2 Configuring the Software

In order for the DHCP client to function, DHCP client software must be configured. As with any TCP/IP service, configuration involves:

- Creation of a default directory and an account in which the software can run
- Creation of data files

TCPIP$CONFIG.COM provides a menu option under the client menu called DHCP client. This option configures the DHCP client for you. You may choose this option explicitly, but if you put an interface under DHCP control from the Interfaces menu in TCPIP$CONFIG, this step is automatically done for you.

The DHCP client software configuration does the following:

- Creates the TCPIP$DHCP account, if it is not present.
- Creates the SYS$SYSDEVICE:[TCPIP$DHCP] directory, if it is not present.
- Enables the DHCP client service, if it is not present in the configuration database.
  Note that there is no service database entry for the DHCP client.
- Creates the initial versions of the following required configuration and data files.
  - DHCPTAGS.
    TCPIP$CONFIG extracts a copy of the DHCPTAGS. file from the librarian file, TCPIP$TEMPLATES.TLB. This file generally does not require modification. For a description of the DHCPTAGS. file, see Section 8.2.2.4.
  - CLIENT.PCY
    TCPIP$CONFIG extracts a copy of the CLIENT.PCY file TCPIP$TEMPLATES.TLB. This file governs the behavior of the DHCP client. Among other things, it tells the DHCP client which DHCP configurable parameters to request from the DHCP server. The file, as it comes from TCPIP$TEMPLATES.TLB, requests the most essential parameters from the server, including:

    > Default route
    > Host name
    > DNS servers IP addresses
    > DNS domain name

    See Section 8.2.2.1 for more information about this file.
  - HOSTNAME.[ifname]
    This file contains a host name that you want to suggest that the DHCP server use as the system's host name. TCPIP$CONFIG puts the value of the cluster system parameter SCSNODE from the client system into this file. For more information about this file, see Section 8.2.2.3.
  After extracting the files, TCPIP$CONFIG places the files into the directory pointed to by the TCPIP$DHCP_CONFIG logical, if it is defined. If TCPIP$DHCP_CONFIG is not defined, then the files are put into the SYS$SYSDEVICE:[TCPIP$DHCP] directory. No files are created if a version already exists.

Note The DHCP client may not coexist on the same system as a DHCP server. TCPIP$CONFIG will not allow you to configure the DHCP client on a system with DHCP server configured.

Previous | Next | Contents | Index