16. DHCP Client

Introduction

This chapter describes the Dynamic Host Configuration Protocol (DHCP) client.

 

General Description

The DHCP client resides on the client host and dynamically sets the network configuration. The MultiNet DHCP client communicates with a DHCP server to get an IPv4 address and other configuration information. It uses this information to configure the network parameters of the host and to start up the network.

When the network starts on the host, the DHCP client communicates dynamically and automatically with the DHCP server in case reconfiguration is needed. The configuration information the client uses is defined by the policy stored in the DHCP server.

For more general DHCP information, see RFC2132 and RFC2131. Also, see Chapter 21 of this guide for general DHCP process and MultiNet DHCP server information.

MultiNet provides support for a DHCP client. Because it supports a single network interface on the host, you can only use the DHCP client to configure a single network line in MultiNet.

Process Software recommends that you do not use the DHCP client with other MultiNet components that usually need a static IPv4 address on the same host, such as DHCP server, authoritative DNS server, and GateD.

 

Setting DHCP Client Parameters

The DHCP Client service uses the parameters listed in the below table.

Parameters

Description

CONFIGFILE

The name of the configuration file. The default is MULTINET:DHCLIENT.CONF.

DEBUG

A decimal integer that is a bitmask of debugging levels used to select messages to pass to OPCOM and the debug log file specified in the DEBUG-FILE parameter. The debugging levels are (in decimal):

 

1 Fatal Errors
3 Errors and Warnings
7 Informationals
15 Debug Messages
31 Dump Packets (formatted)
63 Dump Packets (hex)

 

By default, Fatal Errors, Errors, and Warnings are logged.

DEBUG-FILE

The name of the debug log file. Use this parameter to capture debug logging in a file. The default is that debug logging is not written to any file if LOG-TO-OPCOM is 1. If LOG-TO-OPCOM is 0 (zero), the default file is MULTINET:DHCLIENT.LOG

INTERFACE-ROUTE

A decimal integer 1 (one). Use this parameter to add a static IP route to the MultiNet Kernel routing table. The optional INTERFACE keyword forces the routing to be for a locally connected interface. If the parameter is not set, the default is to create a gateway route.

LEASEFILE

The name of the file DHCP uses to save client lease information to survive across reboots. To completely clear the lease information, delete the file specified and create an empty version. The default is MULTINET:DHCLIENT.DB. This is not used if DHCP Safe-failover is used.

LOG-DATE

This parameter determines whether the date is included in each entry in the debug log file. The default is 0 (zero); the date is not included.

LOG-TO-OPCOM

This parameter determines whether debug logging messages are written to OPCOM. Debug messages are also written to DEBUG-FILE parameter value if DEBUG-FILE is specified or this parameter is 0 (zero). Severe errors and warnings are always logged to OPCOM. The default is 1, everything is logged to OPCOM.

 

Setting Up the DHCP Client

Before setting up a DHCP client, you should talk to your network administrator. The administrator may want to assign a host name to your DHCP client

If this is your first time using the DHCP client on the host, you need to do the following:

$ COPY MULTINET:DHCLIENT_CONF.DEFAULT MULTINET:DHCLIENT.CONF

Then, edit the file MULTINET:DHCLIENT.CONF to replace this line:

#Send host-name “testing”;

with this line:

Send host-name “any hostname you want”;

You can configure your local host to use the DHCP client when you run the MultiNet configuration utility SERVER-CONFIG.

To enable the DHCP client service and to set a parameter, use:

$ MULTINET CONFIGURE /SERVER

After configuring the local host to use the DHCP client, you can run @MULTINET:START_SERVER to start MultiNet. You can use the same method to disable the DHCP client on the host. Here are two examples:

$ MULTINET CONFIGURE /SERVER
MultiNet Server Configuration Utility v5.5(nn)
[Reading in configuration from MULTINET:SERVICES.MASTER_SERVER]
SERVER-CONFIG>SELECT DHCLIENT
[The Selected SERVER entry is now DHCLIENT]
SERVER-CONFIG>SET PARAMETERS
Delete parameter “DEBUG 3”? [NO] RETURN
You can now add new parameters for DHCLIENT. An empty line terminates.
Add Parameter: DEBUG-FILE MULTINET:DHCLIENT.LOG
Add Parameter: RETURN
[Service specific parameters for DHCLIENT changed]
SERVER-CONFIG>ENABLE DHCLIENT
SERVER-CONFIG>EXIT
[Writing configuration to MULTINET_COMMON_ROOT:[MULTINET]SERVICES.MASTER_SERVER]
[Configuration not modified, so no update needed]
$

This procedure creates the Network configuration data file, MULTINET:NETWORK_DEVICES.CONFIGURATION, as well as creating the Network Startup file, MULTINET:START_MULTINET.COM to reflect your system’s configuration.

To activate your DHCP Client interface on a running system, use this command:

$ DEFINE/SYSTEM/EXECUTIVE MULTINET_DHCP_CLIENT “1”

After enabling the DHCP client, start the DHCP client service by restarting the MultiNet Master Server. If the DHCP client service is already running, shut it down first by issuing this command:

$ MULTINET NETCONTROL DHCLIENT SHUTDOWN

Then start the MultiNet Master Server with this command:

$ @MULTINET:START_SERVER

 

Disabling the DHCP Client

To disable the DHCP Client, do the following:

1.       Run

$ MULTINET CONFIGURE/SERVER

2.       Issue the command:

SERVER-CONFIG>DISABLE DHCLIENT

3.       Save the configuration with the WRITE command and EXIT.

4.       Reboot the system.

To avoid rebooting the system, deassign the logical MULTINET_DHCP_CLIENT after disabling the interface and restart the MultiNet server with the @MULTINET:START_SERVER command.

 

DHCP Client Functions and Logicals

The DHCP Client is started as a VMS detached process (MULTINET_DHCLIENT) when MultiNet starts.

When the client starts, it configures the network interface (the line) with an IP address of "0.0.0.0", and then sends a DHCP discover packet to contact any DHCP server on the net. After getting an IP address and other net configuration information back from a DHCP server, it restarts the network interface with the IP address and configures MultiNet on the host with the information it received. That information may include the default gateway, DNS domain name, host name, DNS servers’ IP addresses, and other things. After the network interface is configured and started, the DHCP client goes to sleep and waits for specified events (lease expired, renewal time reached) to wake it up again for possible re-configuration.

If the DHCP client cannot get the information it needs from the DHCP server, it may re-try until it succeeds. The re-try frequency can be controlled by the configuration file.

The DHCP client process sets the following items only when configuring the network interface, if it received the appropriate information from the DHCP server:

·         IP address of the network interface

·         Host name of the network interface

·         Domain Name

·         DNS client (Resolver)

·         Routes/Gateway

It may change or set the following MultiNet logical:

·         MULTINET_NAMESERVERS

It may change the following related OpenVMS logicals:

·         UCX$BIND_DOMAIN

·         UCX$BIND_SERVER00x

·         UCX$INET_HOST

·         UCX$BIND_SERVER000

·         UCX$INET_DOMAIN

·         UCX$INET_HOSTADDR

·         TCPIP$BIND_DOMAIN

·         TCPIP$BIND_SERVER000

·         TCPIP$BIND_SERVER00x

·         TCPIP_DOMAINNAME

·         TCPIP_NAMESERVERS

 

DHCP Client Configuration

The MultiNet DHCP client uses the configuration file MULTINET:DHCLIENT.CONF to control the behavior of the client. Use the template file MULTINET:DHCLIENT_CONF.DEFAULT to start with.

To explore more configuration possibilities, read the following dhclient.conf descriptions. The descriptions are based on the ISC's descriptions for the UNIX version of the DHCP client configuration file. The original document can be found on the ISC's website at http://www.isc.org/isc.

The dhclient.conf file is a free-form ASCII text file. The file may contain extra tabs and new lines for formatting purposes. Keywords in the file are case-insensitive. Comments begin with the # character and end at the end of the line and may be placed anywhere within the file (except within quotation marks). You can use the dhclient.conf file to configure the behavior of the client in the following ways:

·         Protocol timing

·         Information requested from the server

·         Information required of the server

·         Defaults to use if the server does not provide certain information

·         Values with which to override information provided by the server

·         Values to prepend or append to information provided by the server

The configuration file can also be preloaded with addresses to use on networks that do not have DHCP servers.

 

Protocol Timing

The timing behavior of the client need not be configured by the user. If no timing configuration is provided by the user, a reasonable timing behavior will be used by default — one which results in timely updates without placing an inordinate load on the server. The following statements can be used to adjust the timing behavior of the DHCP client if required.

Statement

Description

backoff-cutoff time

The client uses an exponential backoff algorithm with some randomness, so that if many clients try to configure themselves at the same time, they will not make their requests in lockstep. The backoff-cutoff statement determines the maximum amount of time the client is allowed to backoff. The default is two minutes

initial-interval time

The initial-interval statement sets the amount of time between the first attempt to reach a server and the second attempt to reach a server by recalculating the interval between messages. It is incremented by twice the current interval multiplied by a random number between zero and one. If it is greater than the backoff-cutoff amount, it is set to that amount. The default is ten seconds.

reboot time

When the client is restarted, it first tries to reacquire the last address it had. This is called the INIT-REBOOT state. This is the quickest way to get started if it is still attached to the same network it was attached to when it last ran. The reboot statement sets the time that must elapse after the client first tries to reacquire its old address before it gives up and tries to discover a new address. The reboot timeout default is ten seconds.

retry time

The retry statement determines the time that must pass after the client has determined that there is no DHCP server present before it tries again to contact a DHCP server. By default, this is 5 minutes.

select-timeout time

It is possible to have more than one DHCP server serving any given network. It is also possible that a client may receive more than one offer in response to its initial lease discovery message. It may be that one of these offers is preferable to the other (e.g., one offer may have the address the client previously used, and the other may not). The select-timeout is the time after the client sends its first lease discovery request at which it stops waiting for offers from servers, assuming that it has received at least one such offer. If no offers have been received by the time the select-timeout has expired, the client will accept the first offer that arrives. By default, the select-timeout is zero seconds — that is, the client will take the first offer it sees.

timeout time

The timeout statement determines the amount of time that must pass between when the client begins to try to determine its address and the time it decides that it is not going to be able to contact a server. The default is 60 seconds. After the timeout has passed, if there are any static leases defined in the configuration file, or any leases remaining in the lease database that have not yet expired, the client loops through these leases attempting to validate them. If it finds one that appears to be valid, it uses that lease’s address. If there are no valid static leases or unexpired leases in the lease database, the client restarts the protocol after the defined retry interval.

 

 

Lease Requirements and Requests

The DHCP protocol allows the client to request the server to send it specific information. The protocol also allows the client to reject offers from servers if they do not contain information the client needs, or if the information provided is not satisfactory. There is a variety of data contained in offers that DHCP servers send to DHCP clients. The DHCP client can request any of the DHCP options, see the table below for a list of options.

Lease Option

Description

request [option] [, ... option];

The request statement causes the client to request that any server responding to the client send the client its values for the specified options. Only the option names should be specified in the request statement, not option parameters. For example,

request subnet-mask, routers;

require [option] [, ... option];

The require statement lists options that must be sent in order for an offer to be accepted. Offers that do not contain all the listed options are ignored.

send  {[ option declaration]
[, ... option declaration]}

The send statement causes the client to send the specified options to the server with the specified values. These are full option declarations as described in Chapter 21 in this guide. Options that are always sent in the DHCP protocol should not be specified here. The one exception is that the client can specify a requested-lease-time option other than the default requested lease time, which is two hours. The other obvious use for this statement is to send information to the server that allows it to differentiate between this client and other clients or kinds of clients. For example,

 

send host-name “my-name”;

 

Option Modifiers

In some cases, a client may receive option data from the server that is not appropriate for that client, or may not receive information that it needs, and for which a useful default value exists. It may also receive information that is useful, but needs to be supplemented with local information. To handle these needs, these option modifiers are available. 

Modifier

Description

append [option declaration];

Use the append statement if the client should use the values supplied by the server followed by a value you supply. The append statement can only be used for options that allow more than one value to be given. This restriction is not enforced. If you ignore it, the behavior is unpredictable.

default [option declaration];

Use the default statement to specify a default value if no value was supplied by the server.

prepend [option declaration];

Use the prepend statement if the client should use a value you supply followed by the values supplied by the server. The prepend statement can only be used for options that allow more than one value to be given. This restriction is not enforced. If you ignore it, the behavior is unpredictable.

supersede [option declaration];

Use the supersede statement if the client should always use a locally-configured value or values rather than whatever is supplied by the server.

 

 

Lease Declarations

A lease statement consists of the lease keyword, followed by a left curly brace ( { ), followed by one or more lease declaration statements, followed by a right curly brace ( } ).

lease { lease-declaration [ ... lease-declaration ] }

The DHCP client may decide after some period of time (see Protocol Timing) that it is not going to succeed in contacting a server. At that time, it consults its own database of old leases and tests each one that has not yet timed out by pinging the listed router for that lease to see if that lease could work. It is possible to define one or more fixed leases in the client configuration file for networks where there is no DHCP or BOOTP service, so that the client can still configure its address automatically. This is done with the lease statement.

Note! The lease statement is also used in the dhclient.db file in order to record leases that have been received from DHCP servers. Some of the syntax for leases as described below is only needed in the dhclient.db file. Such syntax is documented here for completeness.

The following lease declarations are possible:

Declaration

Description

bootp;

The bootp statement indicates that the lease was acquired using the BOOTP protocol rather than the DHCP protocol. It is never necessary to specify this in the client configuration file. The client uses this syntax in its lease database file.

filename "string";

The filename statement specifies the name of the boot filename to use. This is not used by the standard client configuration script, but is included for completeness.

fixed-address ip-address;

The fixed-address statement sets the IP address of a particular lease. This is required for all lease statements. The IP address must be specified as a dotted quad (e.g., 12.34.56.78).

interface "string";

The interface statement indicates the interface on which the lease is valid. If set, this lease will be tried only on a particular interface. When the client receives a lease from a server, it always records the interface number on which it received that lease. If predefined leases are specified in the dhclient.conf file, the interface should also be specified, although this is not required.

option option-declaration;

The option statement specifies the value of an option supplied by the server, or, in the case of predefined leases declared in dhclient.conf, the value that the user wants the client configuration script to use if the predefined lease is used.

renew date;
rebind date;
expire date;

The renew statement defines the time at which the DHCP client should begin trying to contact its server to renew a lease that it is using.

 

The rebind statement defines the time at which the DHCP client should begin to try to contact any DHCP server in order to renew its lease.

 

The expire statement defines the time at which the DHCP client must stop using a lease if it has not been able to contact a server in order to renew it.

 

These declarations are set automatically in leases acquired by the DHCP client, but must be configured in predefined leases: a predefined lease whose expiration time has passed will not be used by the DHCP client. Dates are specified as follows:

 

<weekday> <year>/<month>/<day> <hour>:<minute>:<second>

 

W YYYY/MM/DD HH:MM:SS

 

W is the day of the week, from zero (Sunday) to six (Saturday).
YYYY is the year, including the century.
MM is the number of the month, from 01 to 12.
DD is the day of the month, counting from 01.
HH is the hour, from 00 to 23.
MM is the minute, from 00 to 59.
SS is the second, from 00 to 59.

 

The time is always in Greenwich Mean Time, not local time.

server-name "string";

The server-name statement specifies the name of the boot server name to use. This is not used by the standard client configuration script.

script "script-name";

The script statement specifies the file name of the DHCP client configuration script. This script is used by the DHCP client to set the interface's initial configuration prior to requesting an address, to test the address once it has been offered, and to set the interface's final configuration once a lease has been acquired. If no lease is acquired, the script is used to test predefined leases, if any, and also called once if no valid lease can be identified. The default value for “script-name” is “MULTINET:DHCLIENT-SCRIPT.COM”.

 

Other Declarations

Declaration

Description

reject ip-address;

The reject statement causes the DHCP client to reject offers from servers who use the specified address as a server identifier. This can be used to avoid being configured by rogue or misconfigured DHCP servers, although it should be a last resort; better to track down the bad DHCP server and fix it.

 

Example

The following configuration file is used on an ALPHA machine with VMS 7.1. 

# template of MULTINET:DHCLIENT.CONF
send host-name "lambda2";
send dhcp-lease-time 3600;
prepend domain-name-servers 127.0.0.1;
request subnet-mask, broadcast-address, time-offset, routers,
        domain-name, domain-name-servers, host-name;
require subnet-mask, domain-name-servers;
timeout 60;
retry 60;
reboot 10;
select-timeout 5;
initial-interval 2;
script "multinet:dhclient-script.com";
reject 10.10.10.10;  # reject the offer from this DHCP server

The first line, starting with the #, is a comment line. The last line rejects the offer from the DHCP server with an IP address of 10.10.10.10.  This is not a simple dhclient.conf file. In many cases, it is sufficient to just create an empty dhclient.conf file and let the DHCP client use default values.

 

Troubleshooting the DHCP Client

How do I know the DHCP client has configured my network successfully?

There are two ways to do it:

Check if the MULTINET_DHCP_CLIENT logical is equal to "1":

$ SHOW LOGICAL MULTINET_DHCP_CLIENT

"MULTINET_DHCP_CLIENT" = "1" (LNM$SYSTEM_TABLE)

$

Run the MULTINET CONFIGURE /INTERFACE command.

1.       Check the line DHCP client for which the interface is enabled.

2.       Check that the line DHCP Client Flag is set.

$ MULTINET CONFIGURE /INTERFACE

MultiNet Network Configuration Utility v5.5(nn)
[Reading in MAXIMUM configuration from MULTINET:MULTINET.EXE]
[Reading in configuration from MULTINET:NETWORK_DEVICES.CONFIGURATION]
NET-CONFIG>SHOW
Interface                        Adapter        CSR Address  Flags/Vector
---------                        -------        -----------  ------------
se0 (Shared VMS Ethernet/FDDI)   -NONE-         -NONE-       -NONE-
    [TCP/IP: 10.10.10.10]
    [VMS Device: EWA0, Link Level: Ethernet]
    DHCP Client for the interface is enabled
Official Host Name:              dumdum.fuges.com
Domain Nameserver:               127.0.0.1
Timezone:                        EST
Timezone Rules:                  US/EASTERN
Load UCX $QIO driver:            TRUE
Load PWIP (Pathworks) driver:    TRUE
DHCP Client Flag:                1
NET-CONFIG>QUIT
$

 

What if I cannot ping an IP address on the internet?

If you can ping the same IP address from another host and the network interface has been configured by the DHCP client, check the gateway and route configuration on the host.

 

What if I can ping a host by its IP address but not by its name?

·         The DNS client on the host may not be configured right. Type

$ SHOW LOGICAL MULTINET_NAMESERVERS

to make sure the DNS client information is correct.

·         The DNS server may be down.

 

Why is the local address "0.0.0.0" when I use "$ multinet configure /interface" and then use “show”?

The DHCP client has failed to allocate an IP address. The possible reasons and solutions are:

Reason

Solution

There is no DHCP server on the net.

Set up a DHCP server.

The DHCP server is not configured correctly.

Modify the DHCP server configuration.

The DHCP client is configured to reject the DHCP server.

Reconfigure the DHCP client to not reject the DHCP server.

The hostname selection process failed.

Use another host name.

There are no IP addresses available in the DHCP server.

Increase the IP address on the DHCP pool server.

 

 

Where can I find the status information of the DHCP client?

·         The file MULTINET:DHCLIENT-SCRIPT-ENV.TMP contains the most recent environment variables used by the DHCP client script file to configure the network.

·         The file MULTINET:DHCLIENT.DB contains the DHCP client lease history.

·         The file MULTINET:DHCLIENT.LOG contains information about the DHCP client process.

The MULTINET:DHCLIENT.LOG file is not created by the default setting of the DHCP client. To create this log file, configure the DHCP client to enable the error and debug logging:

$ MULTINET CONFIGURE /SERVER
SERVER-CONFIG>SELECT DHCLIENT
SERVER-CONFIG>SET PARAMETERS
Add Parameter:DEBUG 7
Add Parameter:
SERVER-CONFIG>WRITE
SERVER-CONFIG>RESTART