# DHCP and Dynamic IP Client Administration

DHCP and Dynamic IP Client Administration

## Table of Contents

About This Information

- Who Should Use This Information
- What This Information Describes
- Conventions Used in This Information
- What Is New in this Release
- For More Information

  Using TCP/IP to Configure a Dynamic IP Client

- Configuring Dynamic IP Client Mode of Operation
- Configuring for DDNS Support

  Monitoring the DHCP and Dynamic IP Client

  Using Messages and Codes

- Client Error Messages
- nsupdate Error Codes

  Controlling DHCP Clients

- Starting a DHCP Client
- Monitoring a DHCP Client
- Requesting a Lease for a DHCP Client
- Releasing a Lease for a DHCP Client
- Terminating the DHCP Client

  Obtaining Information for a Static Client

  Customizing DHCP Client Operation

- Using Client Configuration Keywords
- Defining DHCP Log Files
- Defining Network Interface Parameters
- Configuring Dynamic DNS Support
- Defining DHCP Option Requests and Processing
- Reusing Previous Client Configuration
- Using command script DHCPLPR.CMD
- Defining DHCP User and Vendor Classes
- Client Configuration File Example

  Notices

- Copyright Notices
- Disclaimers
- Acknowledgments
- Trademarks

  # About This Information

  This information describes client use of Dynamic Host Configuration Protocol (DHCP) services and Dynamic Domain Name Server (DDNS) services.

  This section describes:

  - Primary users of this information

  - Content of each major information division

  - Conventions such as syntax highlighting

  - New function in this release of the product

  - Where to find more information

  ## Who Should Use This Information

  The introductory sections in this information are intended for DHCP client users who obtain an IP address from a DHCP server and register a client host name with a DDNS server. Additional, expert-level information is also provided.

  ## What This Information Describes

  This information describes:

  - Using TCP/IP to configure a dynamic IP client

  - Monitoring DHCP client operation

  - Using diagnostic messages and codes

  - Controlling DHCP clients

  - Customizing DHCP client operation

  ## Conventions Used in This Information

  Syntax descriptions in this information use highlighting or special characters to indicate:

  - Commands and kewords appear as: commands keywords

  - Required variables appear as: variables

  - Optional variables are enclosed in square brackets: [variables]

  - Mutually exclusive choices are indicated by a vertical separator: |

  For example, the following statement releases client information at the DDNS server:

  releaseDNS string

  ## What Is New in this Release

  The following function is new in this release:

  - Improved control of host name and IP address record updatess. For more information, see Configuring Dynamic DNS Support.

  - Text records that allow the systems administrator to request and update additional end-user information such as name, phone, and location. For more information, see Updating the Client TXT Record at the DDNS Server.

  - Additional controls to release a client host name and IP address at the DDNS server. For more information, see Releasing the Client Host Name and Releasing the Client IP Address.

  - Changes in the level of DHCPLPR.CMD support for previously-supported options. DHCPLPR.CMD was previously titled DHCPIBM.CMD. For more information on this REXX command script, see Using Command Script DHCPLPR.CMD.

  ## For More Information

  For more information about:

  - DHCP and dynamic IP, see DHCP and Dynamic IP Introduction.

  - Monitoring a DHCP client, see the DHCP Client Monitor program.

  # Using TCP/IP to Configure a Dynamic IP Client

  In a network with DHCP and DDNS services, a client computer may:

  - Configure TCP/IP network parameters from a DHCP server rather than manually configure from parameter values provided by your network administrator.

  - Register a host name and DHCP-assigned IP address with a DDNS server for discovery by other hosts in the network.

  ## Configuring Dynamic IP Client Mode of Operation

  Before you start, obtain your DDNS domain configuration information. To configure a client computer for Dynamic IP operation:

  1. If you have TCP/IP Application Services installed on your computer, open the TCP/IP Configuration Notebook program, located in your TCP/IP Services folder, to the Network page, "Configure Network Interface Parameters". Otherwise, open the MPTS Adapters and Protocol Services program located in the System Setup folder inside the System folder, and select "Configure" and then "TCP/IP Configuration" to find the network interface configuration menu.

  2. Select Automatically, using DHCP for the LAN interface you want to enable.

  3. If your client computer is mobile, ensure there is a checkmark (the default) in the Mobile checkbox.

  4. To also operate your client computer using DDNS, select also, using DDNS.

  5. While in the TCP/IP configuration panels, enter any other TCP/IP configuration information as needed. Save the configuration and exit the program.

  Your computer is now configured. On restart, your computer automatically uses DHCP to configure itself for IP network access.

  ## Configuring for DDNS Support

  If you operate the client with DDNS, your computer asks for the following information as it restarts:

  - Host name

    The name your computer is known by in your domain.

  - Domain name

    The name for the dynamic domain to which your host is assigned. If DHCP provides the domain name, the domain name value appears in this field. Alternatively, enter a domain name provided by your network administrator.

  - DDNS server for domain

    The fully-qualified host name or IP address of the DDNS server which is primary for your computer's domain. This value defaults to the host name "ns-updates.<domain name>". Accept the default or manually enter a value provided by your network administrator.

  - Other user information

    Additional information can be required by the system administrator, using DHCP option 192. This information is saved in the client TXT record on the DDNS server.

  Once configured, the DDNS and DHCP client programs automatically register and, when appropriate, update your DDNS server with the host name information you entered, the IP address obtained by the DHCP client, and any information entered in the TXT record.

  To change your host name or reconfigure other DDNS client program parameters, re-invoke the DDNS Client Configuration Program with one of the following:

  - Executing DDNSCFG from a command prompt

  - Opening the DDNS Client Configuration program object

    Click the DDNS Client Configuration program object located in the System Setup folder inside the System folder.

  # Monitoring the DHCP and Dynamic IP Client

  To view DHCP client configuration status and events, use the DHCP Client Monitor program, DHCPMON.EXE, which displays current lease and options values. For more detailed information about using the DHCP Client Monitor program, select Getting Started or General Help from the DHCP Client Monitor Help pull-down menu.

  To start the DHCP Client Monitor program, click the DHCP Client Monitor icon located in the System Setup folder inside the System folder. Alternatively, start the DHCP Client Monitor program by entering the dhcpmon command at a command prompt.

  # Using Messages and Codes

  The DHCP Client Monitor program (DHCPMON.EXE) and the DDNS Client Configuration program (DDNSCFG.EXE) display messages to help you diagnose error conditions, listed in Client Error Messages. DDNSCFG displays messages in windows following the execution of a CONFIGURE action. DHCPMON displays messages through the Message log window of the Details view.

  A signed number which appears at the end of a DHCP log message indicates an error code from the DDNS client program, nsupdate, listed in nsupdate Return Codes.

  ## Client Error Messages

  After a Configuration action, the DDNS Client Configuration program displays one of these messages:

  MSG00 Configuration failed: The DHCP configuration file was not found.

  Explanation:

  The DDNS Client Configuration program could not find the DHCPCD.CFG file in the directory specified by the ETC environment variable. This file, which is usually created during installation, contains DDNS information that is needed by the DHCP client. Check to see if you can use the sample file, which is in the TCPIP\ETC\SAMPLES directory.

  MSG01 Configuration failed: The DHCP configuration file was not updated.

  Explanation:

  The DDNS Client Configuration program could not update the DHCPCD.CFG file in the directory specified by the ETC environment variable with a valid updatednsa or updatednstxt statement. This file, which is usually created during installation, contains DDNS information that is needed by the DHCP client.

  MSG02 Configuration failed: Your workstation memory has been exceeded.

  Explanation:

  Not enough memory is available. Try closing some other programs to free memory.

  MSG03 Each label in the host name must not exceed 63 alphanumeric characters.

  Explanation:

  One or more of the labels in the host name is longer than 63 alphanumeric characters. Reduce the number of characters in any labels that are too long.

  MSG04 Configuration failed: DHCP client is not running.

  Explanation:

  The DDNS client configuration program could not read from the DHCP client shared memory, probably because the DHCP client is not running.

  MSG05 Configuration failed: DHCP client is not running.

  Explanation:

  The DDNS client configuration program could not signal the DHCP client program with the new host name entered, probably because the DHCP client is not running.

  MSG06 Configuration succeeded.

  Explanation:

  Your host name has been registered with the DDNS server. Other users can now contact you using your host name (as well as your IP address).

  MSG07 Configuration failed: DHCP client has not been initialized by a DHCP server.

  Explanation:

  The DDNS client configuration program could not obtain DHCP-served parameters required for DDNS name registration because the DHCP client has not received a response from a DHCP server. The DHCP client might not have a connection to the server(s) or the server(s) might be down.

  MSG08 Each label in the domain name must not exceed 63 alphanumeric characters.

  Explanation:

  One or more of the labels in the domain name is longer than 63 alphanumeric characters. Reduce the number of characters in any labels that are too long.

  MSG09 Configuration failed: DHCP client is not running.

  Explanation:

  The DDNS client configuration program could not update the shared memory segment used to communicate information between the DHCP and DDNS client programs. The DHCP client is not running or is failing.

  MSG10 You must specify a host name.

  Explanation:

  The host name is missing. Enter a host name. This is a name of your choosing, a name by which you would like your system to be known.

  MSG11 You must specify a domain name.

  Explanation:

  The domain name is missing. Enter the domain name. If you do not know the domain name, contact your system administrator.

  MSG12 Each label in the DDNS server name must not exceed 63 alphanumeric characters.

  Explanation:

  One or more of the labels in the DDNS server name is longer than 63 alphanumeric characters. Reduce the number of characters in any labels that are too long.

  MSG13 Host name must consist of one or more labels separated by a single dot character (.). Each label may be alphanumeric, but the fully qualified name must contain at least 1 letter.

  Explanation:

  The name entered is not valid. Some examples of valid names are:

      myhost
      host123
      secretary
      9999999c

  MSG14 Domain name must consist of one or more labels separated by a single dot character (.). Each label may be alphanumeric, but the fully qualified name must contain at least 1 letter.

  Explanation:

  The name entered is not valid. Some examples of valid names are:

      raleigh.ibm.com
      eng.mit.edu
      sailclub.org

  MSG15 DDNS server name must consist of one or more labels separated by a single dot character (.). Each label may be alphanumeric, but the fully qualified name must contain at least 1 letter.

  Explanation:

  The name entered is not valid. Some examples of valid names are:

      ddns10.raleigh.ibm.com
      nserver2.eng.mit.edu
      names.sailclub.org

  Note:

  > The IP address is also valid and can be used instead of the name.

  MSG16 Configuration failed: DDNS server did not respond. The DDNS server specified is either unreachable or does not exist.

  Explanation:

  The DDNS client program (NSUPDATE) failed with error code -12.

  This error code indicates that no response was received from the specified DDNS server.

  MSG17 Configuration failed: You are not authorized to update the host name.

  Explanation:

  The DDNS client program (NSUPDATE) failed with error code -11.

  This error code indicates that the DDNS server rejected the DDNS client program's update request because the digital signature for the message failed authentication, that is, because the key in the DDNS.DAT file in the directory specified by the ETC environment variable is not valid.

  This happens when your private security key, used to generate the digital signature for the message, does not pair with the corresponding public key registered at the server for the specified host name. NSUPDATE obtains the security key information from DDNS.DAT. If the file is corrupted or deleted, your DDNS update requests will fail authentication.

  MSG18 Configuration failed: You are not authorized to create the host name because it already exists and is owned by another host. Select an alternate host name and re-configure.

  Explanation:

  The DDNS client program (NSUPDATE) failed with error code -10.

  This error code indicates that no key was found in the DDNS.DAT file in the directory specified by the ETC environment variable. If public security key information is already registered with the DDNS server for the specified host name or the -f parameter was specified on the NSUPDATE command, your DDNS.DAT file must contain the necessary key information. Either your DDNS.DAT file has been deleted or corrupted or the appropriate wildcard entry has not been correctly generated.

  MSG19 Configuration failed: General DDNS update failure.

  Explanation:

  The DDNS client program (NSUPDATE) failed with error code -2.

  This error code indicates an error in the parameters specified. Make sure that the updatednsa or updatednstxt statement in the DHCPCD.CFG file has not been corrupted. If either has been corrupted, delete the entire statement from the client configuration file (DHCPCD.CFG) and re-run the DDNS client configuration program (DDNSCFG.EXE), which will automatically reinsert a valid updatednsa or updatednstxt statement.

  MSG20 Configuration failed: General DDNS update failure.

  Explanation:

  The DDNS client program (NSUPDATE) failed with error code -1.

  This error code indicates an unexpected internal error.

  MSG21 Configuration failed: DDNS server did not understand the request.

  Explanation:

  The DDNS client program (NSUPDATE) failed with error code 1.

  This error code indicates a format error. The DDNS name server was unable to interpret the request.

  MSG22 Configuration failed: DDNS server failure.

  Explanation:

  The DDNS client program (NSUPDATE) failed with error code 2.

  This error code indicates a server error. The DDNS name server was unable to process this request because of a problem with the name server.

  MSG23 Configuration failed: The domain name specified does not exist.

  Explanation:

  The DDNS client program (NSUPDATE) failed with error code 3.

  This error code indicates a name error. The DDNS server did not recognize the fully-qualified host name specified in the request.

  MSG24 Configuration failed: DDNS server did not understand the request.

  Explanation:

  The DDNS client program (NSUPDATE) failed with error code 4.

  This error code indicates that the DDNS server did not recognize the operation in the update request.

  MSG25 Configuration failed: DDNS server rejected the request.

  Explanation:

  The DDNS client program (NSUPDATE) failed with error code 5.

  This error code indicates that the DDNS server refused the requested operation for security or policy reasons, for example, when attempting to update a zone that is not dynamic.

  MSG26 Configuration failed: The domain name specified is an alias. Please specify a non-aliased domain name.

  Explanation:

  The DDNS client program (NSUPDATE) failed with error code 6.

  This error code indicates an alias error. The DDNS server refused the requested operation because the fully-qualified host name specified is an alias for another host name.

  MSG27 Configuration failed: The host name specified is not available. Please specify another host name.

  Explanation:

  The DDNS client program (NSUPDATE) failed with error code 7.

  This error code indicates a name error. The DDNS server refused the ADDNAMENEW request operation because the host name specified already exists.

  MSG28 Configuration failed: The host name specified could not be deleted.

  Explanation:

  The DDNS client program (NSUPDATE) failed with error code 8.

  This error code indicates that a resource record for this host does not exist. The DDNS server refused the requested DELETE operation because the host name specified does not exist.

  MSG29 Configuration failed: The DDNS server specified is not authoritative for the domain.

  Explanation:

  The DDNS client program (NSUPDATE) failed with error code 9.

  This error code indicates a zone error. The DDNS server refused the requested operation because the server is not authoritative for the domain name specified or because the records to be updated exist in more than one zone.

  MSG30 Configuration failed: DDNS server rejected the request because of a sequencing error.

  Explanation:

  The DDNS client program (NSUPDATE) failed with error code 10.

  This error code indicates a timestamp problem. The DDNS server refused the requested operation because the timestamp preceded that used in an earlier request.

  MSG31 Configuration failed: The DDNS client program encountered an unexpected error.

  Explanation:

  The DDNS client configuration program encountered an unexpected internal processing error.

  MSG32 The maximum allowable length for a fully-qualified domain name is 255 characters. The host name and domain name you entered exceed this length when combined.

  Explanation:

  The fully qualified domain name is too long. Try using a shorter host name.

  MSG34 Open DDNS key file failed: unexpected system return code. (The local key file will be used.)

  Explanation:

  The key file could not be opened because the general file dialog could not be displayed.

  MSG35 Replace DDNS key file failed: Copy of the specified key file failed. (The local key file will be used.)

  Explanation:

  The key file could not be copied. Either the file is being used by another process or it cannot be copied due to insufficent space.

  MSG36 Import key file error: Open file failed.

  Explanation:

  The key file cannot be opened. The file specified does not exist, has an error, or is already is use.

  MSG37 Import key file warning: The file contains at least one entry with invalid syntax. Do you wish to continue importing the file?

  Explanation:

  The program encountered something unexpected in the key file. Click Yes to continue or No to stop.

  MSG38 Usage: -?hpql# where: -h = fully qualified host name (required); -p = fully qualified host name/IP address of name server (required); -l# = user values for system administrator required fields (#=1-4); -? = print this message; -q = quiet mode

  Explanation:

  The syntax of the ddnscfg command is incorrect. Retype the command, specifying the parameters as shown, where:

  -h host_name
    Specifies the host.

  -p name_server
    Specifies the name or IP address of the primary DDNS name server.

  -l# value
    Specifies the value of an identification information field required by the system administrator. Up to 4 fields can be required. # indicates which field this value is for and is 1 to 4.

    Note:

    > This value cannot contain colons (:) or semicolons (;).

  MSG39 Configuration error: You must supply information for all the required fields.

  Explanation:

  Information is missing for one or more fields. Type the required information in each field.

  ## nsupdate Error Codes

  This list describes the nsupdate error codes.

  0

  Explanation:

  Successful.

  -12

  Explanation:

  This error code indicates that no response was received from the specified DDNS server.

  -11

  Explanation:

  This error code indicates that the DDNS server rejected the DDNS client program's update request because the digital signature for the message failed authentication, that is, because the key in the DDNS.DAT file in the directory specified by the ETC environment variable is not valid.

  This happens when your private security key, used to generate the digital signature for the message, does not pair with the corresponding public key registered at the server for the specified host name. NSUPDATE obtains the security key information from DDNS.DAT. If the file is corrupted or deleted, your DDNS update requests will fail authentication.

  -10

  Explanation:

  This error code indicates that no key was found in the DDNS.DAT file in the directory specified by the ETC environment variable. If public security key information is already registered with the DDNS server for the specified host name or the -f parameter was specified on the NSUPDATE command, your DDNS.DAT file must contain the necessary key information. Either your DDNS.DAT file has been deleted or corrupted or the appropriate wildcard entry has not been correctly generated.

  -2

  Explanation:

  This error code indicates an error in the parameters specified. Make sure that the updatednsa or updatednstxt statement in the DHCPCD.CFG file has not been corrupted. If either has been corrupted, delete the entire statement from the client configuration file (DHCPCD.CFG) and re-run the DDNS client configuration program (DDNSCFG.EXE), which will automatically reinsert a valid updatednsa or updatednstxt statement.

  -1

  Explanation:

  This error code indicates an unexpected internal error.

  1

  Explanation:

  This error code indicates a format error. The DDNS name server was unable to interpret the request.

  2

  Explanation:

  This error code indicates a server error. The DDNS name server was unable to process this request because of a problem with the name server.

  3

  Explanation:

  This error code indicates a name error. The DDNS server did not recognize the fully-qualified host name specified in the request.

  4

  Explanation:

  This error code indicates that the DDNS server did not recognize the operation in the update request.

  5

  Explanation:

  This error code indicates that the DDNS server refused the requested operation for security or policy reasons, for example, when attempting to update a zone that is not dynamic.

  6

  Explanation:

  This error code indicates an alias error. The DDNS server refused the requested operation because the fully-qualified host name specified is an alias for another host name.

  7

  Explanation:

  This error code indicates a name error. The DDNS server refused the ADDNAMENEW request operation because the host name specified already exists.

  8

  Explanation:

  This error code indicates that a resource record for this host does not exist. The DDNS server refused the requested DELETE operation because the host name specified does not exist.

  9

  Explanation:

  This error code indicates a zone error. The DDNS server refused the requested operation because the server is not authoritative for the domain name specified or because the records to be updated exist in more than one zone.

  10

  Explanation:

  This error code indicates a timestamp problem. The DDNS server refused the requested operation because the timestamp preceded that used in an earlier request.

  # Controlling DHCP Clients

  The DHCP Client Monitor graphical user interface provides menus to control DHCP clients. Any actions allowed by the graphic interface (and other actions) may also be performed with command line parameters. For more information about controlling a DHCP client, see help provided by the DHCP Client Monitor program.

  Tasks that control DHCP clients include:

  - Starting the DHCP client program

  - Monitoring a DHCP client

  - Requesting a Lease for a DHCP Client

  - Releasing a Lease for a DHCP Client

  - Terminating a DHCP Client

  - Obtaining Options Information About a DHCP Client

  ## Starting a DHCP Client

  Manually start the DHCP client program, using:

  dhcpstrt

  Note:

  > The client normally starts in the background when the computer boots. You may prefer to use the dhcpcd command to start the DHCP client program in a foreground session, which is visible in the task list. The dhcpstrt command starts the DHCP client program in a background session, which is not visible in the task list.

  ## Monitoring a DHCP Client

  The DHCP Client Monitor program monitors a DHCP client, displaying client lease information. Start the DHCP Client Monitor graphical user interface, using:

  dhcpmon

  ## Requesting a Lease for a DHCP Client

  To request a lease for a DHCP client, using the DHCP Client Monitor graphical user interface, click Request Lease on the Actions pull-down. At a command prompt, you can also type:

  dhcpmon -r

  -r
    Requests a lease. You do not normally need to request a lease for your IP address. Since the DHCP client will automatically request to renew its lease at appropriate time intervals, request a lease only for special circumstances, such as bringing a computer out of hibernation mode and accessing your lease to an IP address. Request lease renews a valid lease or begins discovery of a new IP address and normal lease renewal.

  ## Releasing a Lease for a DHCP Client

  To release a lease for a DHCP client, using the DHCP Client Monitor graphical user interface, click Release Lease on the Actions pull-down. At a command prompt, you can also type:

  dhcpmon -l

  -l
    Releases a lease. Release a lease only for special circumstances to end the current lease of an IP address. When a lease is released, your computer will not automatically rediscover an available IP address. Request lease starts IP address discovery and normal lease renewal.

  ## Terminating the DHCP Client

  Terminates the DHCP client, regardless of how the DHCP client was started. Use:

  dhcpmon -t

  -t
    Terminates the DHCP client.

    Attention: The terminated DHCP client will not attempt to renew its lease. The interface remains configured for the IP address the client has been assigned until the computer is shut down.

  # Obtaining Information for a Static Client

  When you specify options for a statically-configured client with an IP address, it can be helpful to locate information about other dynamically-configured DHCP clients, such as a local printer specified by the LPR printer option. You can then specify that option for the statically-configured client.

  Obtain DHCP client information, using:

  dhcpcd -inform ip_address

  -inform
    Writes DHCP client information to an active log file such as \DHCPCD.LOG. Ensure the log file is active by uncommenting the log statement in the DHCPCD.CFG configuration file.

  ip_address
    The IP address of a DHCP client

  # Customizing DHCP Client Operation

  To obtain operational and protocol configuration parameters, the DHCP client program uses the file \DHCPCD.CFG located in the directory specified by the ETC environment variable. Modifying this file changes the operation and behavior of the DHCP client.

  Attention: Incorrect configuration of the DHCP client program may result in the failure of your host to access the IP network. Only network administrators and authorized, informed network programmers should modify the contents of this file.

  Before editing this configuration file, review the information in this section carefully. Before making changes to the file, make a backup copy of \DHCPCD.CFG. An alternate configuration filename may be used if you start the client from the command line with the dhcpcd command and the -c option.

  You can:

  - Debug using DHCP log files

  - Customize default DHCP option handling

  - Alter Network interface parameters

  - Modify DDNS parameters

  - Configure the LPR server option.

  - Specify DHCP User and Vendor classes

  ## Using Client Configuration Keywords

  Configuration keywords, which are not case sensitive, and basic DHCP client parameters are described as comment lines in the \DHCPCD.CFG file. Keywords include:

  Keyword
    Description

  numLogFiles
    The number of desired log files.

  logFileSize
    The maximum size, in kilobytes, of the log files.

  logFileName
    The name of the most recent log file.

  logItem
    The type of information to be logged. Possible values are listed in the next section.

  interface
    The network interface that will be configured by DHCP. The default value is lan0.

  clientid
    The client identifier that is included in all packets sent to the DHCP server. MAC is the only allowable value.

  updateDNSA
    When executed, information in this command string updates the Dynamic DNS server with the current IP address for the specified host name.

  updateDNSTxt
    When executed, information in this command string updates the client TXT record at the DDNS server with information requested by a system administrator using a non-architected option such as option 192, TXT RR, and information from the DDNS client configuration program.

  releaseDNS
    When executed, information in this command string specifies the actions to take when releasing the client A record and TXT record at the DDNS server. DNS records for an IP address are automatically deleted when the lease is terminated.

  releaseADDR
    This sends a DHCPRELEASE from the DHCP client to the DHCP server to automatically terminate the lease for the client's IP address when certain events occur, such as shutdown.

  option
    An option requested by the client host. Refer to RFC 2132 for more information about options.

  vendor
    A vendor extension option.

  reject
    Specifies that the respective option will be ignored by the DHCP client if it is sent by the DHCP server.

  otherOptions
    Specifies that options not specifically requested or rejected in this DHCP client configuration file will be processed.

  ifconfig_options
    Specifies advanced interface options.

  previousCFG
    Allows the DHCP client to use the most recent configuration parameters.

  ### Defining DHCP Log Files

  Tasks that define log files include:

  - Defining the Number of DHCP Log Files

  - Defining the size of DHCP log files

  - Naming DHCP log files

  - Specifying information types to log

  #### Defining the number of DHCP log files

  Specify the number of log files maintained, using:

  numLogFiles value

  value
    The maximum number of log files maintained.

    Notes:

    1. If the value for numLogFiles is 0 or the statement is omitted, no logging occurs.

    2. If a new log file is created after the maximum number is reached, the oldest log file is removed.

    3. The maximum number of files is specified by the file system. For example, 999 files is the maximum value on a FAT file system.

    4. If the value for numLogFiles is greater than 1, when the size of the most current log file reaches the maximum size, it is renamed by removing the initial filetype of LOG and appending an integer as the filetype to the log file name. A new log file is created as the current log. All older files are renamed by incrementing the previously appended integer filetype by 1. The larger the file type extension, the older the log file. For example, DHCPLOG.003 is an older log file than DHCPLOG.001.

  #### Defining the size of DHCP log files

  Specify the size of the log file, using:

  logFileSize value

  value
    Maximum log file size in kilobytes. The minimum size is 1KB.

  #### Naming DHCP log files

  Name the log file, using:

  logFileName file_path

  file_path
    The fully-qualified name that you assign to the current log file. The file name is a maximum of 8 characters. A file type is allowed for a DHCP log file.

    If no directory is specified, the default is the directory specified by the ETC environment variable. If the specified path is not valid, the DHCP client continues to operate but does not log any information. If no log file name is specified, the logged information is displayed on the screen.

  #### Specifying information types to log

  Some problems may not halt the DHCP client, but still cause difficulties. Logging can identify such problems. Specify information types to log, using:

  logItem object

  object
    Types include:

    SYSERR

    Errors at the interface to the operating system

    OBJERR

    Errors between objects in the DHCP client program, such as missing records or records in inconsistent states

    PROTERR

    Protocol errors between the client and server

    WARNING

    Warnings that warrant the user's attention

    EVENT

    Events in the DHCP client program

    ACTION

    Actions taken by the DHCP client program

    INFO

    Useful information

    ACNTING

    Accounting information, such as who was served and when

    TRACE

    Trace information

  ### Defining Network Interface Parameters

  Use this parameter to specify network parameters not assigned through DHCP, such as which network interface the DHCP client uses. Tasks include:

  - Specifying the interface

  - Specifying the type of client ID

  - Specifying client options

  #### Specifying the Interface

  Specify the interface, using:

  interface ifName

  ifName
    Name of the network interface, such as lan0

  #### Specifying the Type of Client ID

  Specify the type of client ID for all communication with the server, using:

  clientID value

  value
    MAC is the only allowable value, indicating the hardware address for the particular interface is used as the client ID.

  #### Specifying Options

  Specify advanced options accepted by the ifconfig command, using:

  ifconfig_options option_list

  option_list
    List of options. Separate each option with a blank space, and enclose the entire group of requested options in double quotes (").

  ### Configuring Dynamic DNS Support

  The DHCP client program and the DDNSCFG program communicate, when necessary, with the DDNS client program nsupdate.

  DDNS client communication tasks include:

  - Updating the current host name

  - Updating the client host name and/or TXT record at the DDNS server

  - Releasing the client host name and/or TXT record at the DDNS server

  - Releasing the client IP address at the DHCP server

  #### Updating the Current Host Name

  Update the Dynamic DNS server with the current host name to IP address mapping for the specified host name, using:

  updateDNSA string

  string
    A string specifying the program to update the DDNS server with the host name to IP address mapping for your host. An updateDNSA statement is generated automatically by the DDNS Client Configuration program, DDNSCFG.EXE, if a valid statement does not already exist.

    Note:

    > Only one updateDNSA string is allowed in the DHCPCD.CFG file. If multiple instances occur, the last valid statement found in the file is used.

    > To have the server update A and PTR records:

    > 1. The non-dynamic client is required to pass option 12 (hostname) and option 15 (domain name) to the server, or use DHCP-DNS option 81.

    > 2. In the IBM DHCP server configuration file, enter updateDNSA, releaseDNSA, updateDNSP, releaseDNSP, and proxyARec parameters.

  The following is an example of an updateDNSA keyword and update string:

      updateDNSA "nsupdate -h%s -s"d;a;*;a;a;%s;s;%s;3110400;q""

  -h%s
    The host name, which is the value of option 12. If the value is specified by using DDNSCFG or the client specified a value in this file, that value is used. If not, the value returned by the server is used. If the client does not specify a host name or the DHCP server does not provide one, this exec string will be ignored.

  -s string
    The sample string contains the required IP address leased to this client by the server and the required lease time granted by the server. The IP address is in dotted decimal notation. The lease time is a decimal number representing the number of seconds of the lease.

    The string contains:

    - d;a;*;

      Delete all A (hostname-to-IP-address) records for this host.

    - a;a;%s;

      Add an A record using an IP address (%s) provided by the server.

    - s;%s;

      Send a lease time (%s) provided by the server for the IP address.

    - 3110400;

      The effect of this value is to reserve the host name for an additional time interval after the A record expiration. In this case, an interval of 36 days (3110400 seconds) is added to the A record expiration time. This value works to preserve a user's host name during times when the name-to-address mapping might expire, such as holidays, vacation, or other times of inactivity.

    - q

      Quit delimiter for the command string

  #### Updating the Client Host Name and/or TXT Record

  Several steps are necessary to obtain additional information from a DHCP client user:

  1. The system administrator specifies DHCP option 192, TXT RR. For example, option 192 can contain the TXT string "IBMDDNS:Name;Phone;Address;"

  2. The DHCP client provides option 192 TXT RR required fields to the DDNS Configuration - Required Information process (DDNSCFG command).

  3. If no values for the required fields are found in the DHCP client configuration file \DHCPCD.CFG, the DDNS Configuration - Required Information process prompts the DHCP client user with a display requesting the information.

  4. An updateDNSTxt statement stores the user-supplied values in the DDNSCLI.CFG file on the DHCP client. This file contains the host name, domain name and TXT RR field information for use by the DDNSCFG command.

  The DHCPCD.CFG file can be installed remotely. For more information on specifying installation and configuration parameters remotely, using TCP/IP remote installation response files, refer to the TCP/IP readme file, or to the TCP/IP User's Guide.

  To update the DDNS server with the current TXT record for the specified host name, use:

  updateDNSTxt string

  string
    The command string allows the systems administrator to specify up to four pairs of field labels and data that fit within a single TXT resource record. For example:

    updateDNSTxt "nsupdate -f -h%s -s"d;txt;%s;a;txt;%s;s;%s;3110400;q""

    Fields such as txt are text strings defined by the system administrator, requiring the client user to enter a value such as a host name, a room number, or other identifying information.

    The example string contains:

    - d;txt;%s;

      Delete the host's previous TXT resource record

    - a;txt;%s;

      Add a new text record for the host

    - s;%s;

      Send the lease time plus an additional interval

    - 3110400;

      The effect of this value is to reserve the host name for an additional time interval after the A record expiration. In this case, an interval of 36 days (3110400 seconds) is added to the A record expiration time. This value works to preserve a user's host name during times when the name-to-address mapping might expire, such as holidays, vacation, or other times of inactivity.

    - q

      Quit delimiter for the command string

  #### Releasing the Client Host Name and/or TXT Record

  Release the client host name and TXT information at the DDNS server, using:

  releaseDNS string

  string
    Information in this command string specifies detailed actions to take when releasing the client host name and TXT information at the DDNS server. If the lease is terminated or expired, the A record will always be released. If releaseDNS is not specified, a default command will be used.

    The following is an example of a releaseDNS string:

        releaseDNS "nsupdate -h%s -s"d;a;%s;d;txt;%s;s;%s;0;q""

    This example deletes the A record and (optionally) also the text record that the DHCP client and DDNSCFG programs have created on the DNS name server.

    The string contains:

    - d;a;%s;

      Delete the A (hostname-to-IP-address) record for this host.

    - d;txt;%s;

      Delete the TXT record previously updated by DDNSCFG or the DHCP client for this host. Deleting the TXT record is necessary only if you use option 192 to obtain additional information to store in the TXT record.

    - s;%s;

      Send a lease time (%s) provided by the server for the IP address.

    - 0;

      The signature expiration pad time for the A resource record. In this case, the value is zero because the record is deleted.

    - q

      Quit delimiter for the command string

  #### Releasing the Client IP Address at the DHCP Server

  Release the client IP address at the DHCP server, using:

  releaseADDR shutdown

  shutdown
    When a DHCP client shuts down, this statement sends a DHCPRELEASE message from the DHCP client to the DHCP server to terminate the lease for the client's IP address.

  ### Defining DHCP Option Requests and Processing

  You can define what options the DHCP client will request of DHCP servers and how the options and values returned from DHCP servers will be processed. Tasks include:

  - Defining an option for a request

  - Rejecting an option

  - Handling options not requested

  #### Defining an Option for a Request

  Define an option for a request, using:

  option code [value] [exec string]

  code
    DHCP option number

  value
    Value for the option requested (optional)

  exec string
    [exec string] is an optional parameter, unless you are specifying IBM-specific option 200.

    - Command string format

      The command string specified after the exec keyword is expected to be an executable shell script or program. A %s in the string represents the served value.

      The format of the served value depends on which option is passed from the server. For architected options, the value is formatted according to its type, such as a character string. On non-architected options, the value is formatted as a hexadecimal string and enclosed in double quotes (") and prefixed with the word "hex", as shown in the following example:

          hex "ab 01 35 36 ......."

    - Synchronous versus asynchronous execution

      Synchronous: If multiple options are requested, the respective exec string executes before the next option is processed. This is the default. Use synchronous execution when you have option processing interdependencies.

      Asynchronous: To specify asynchronous execution, you must place an @ sign in front of the command.

      For example:

          option 200 exec "@dhcplpr.cmd 200 %s"

      This indicates that the client should continue to the next option without waiting for the DHCPLPR program to complete execution. Consider using asynchronous execution if the specified command will take a long time to execute.

    - REXX or Presentation Manager program processing

      To specify processing for a REXX program you provide, place a dollar sign ($) before the command filename. For example:

          option 208 exec "$myrexx.cmd %s"

      To specify processing for a Presentation Manager program you provide, place an ampersand (&) before the command filename. For example:

          option 208 exec "&mypm.exe %s"

  string
    A command string, in double quotes, executed upon receipt of the option

    For example, the following option statement specifies the DHCP client will request that the DHCP server return a value for option 200, the default LPR Printer, and that the program DHCPLPR.CMD be invoked to process the value.

    option 200 exec "dhcplpr.cmd 200 %s"

    You can also configure option 9 using the IBM command DHCPLPR.CMD to specify the IP address of the default LPR server. For example:

        option 9 9.67.96.15

    An OS/2 client stores the updated option value in the TCPOS2.INI file.

  #### Rejecting an Option

  Reject an option offered to the client, using:

  reject code

  code
    The DHCP option number is ignored if received from the server. A separate statement is required for each rejected code.

  #### Handling Options Not Requested

  Handle options not explicitly requested, using:

  otherOptions value

  value
    Enter ACCEPT to accept options received, though not necessarily used, unless otherwise specified. REJECT specifies that options received should be rejected unless otherwise specified.

  ### Reusing Previous Client Configuration

  To re-use your previously-stored client information when the client cannot reach the DHCP server but still has a valid lease, use:

  previousCFG

  If this keyword is specified, when a DHCP server is down and a DHCP client still has a valid lease, the last set of configuration parameters which were in the client database file, are set by the DHCP client. The previous configuration parameters remain active on the DHCP client until the lease expires. If the DHCP client is not a mobile client, as specified in the TCP/IP configuration notebook, this is the default behavior.

  If the lease has not expired, the client continues to try to reach a DHCP server. Types of information which are re-used include:

  - Option

  - Exec string for options

  - IP address

  - Lease

  ### Using command script DHCPLPR.CMD

  IBM provides a REXX command script, DHCPLPR.CMD, with the DHCP client to configure the default LPR server using DHCP option 9, and the default LPR printer using DHCP option 200.

  Option code 200 is a user-defined option.

  The following options were previously supported by the command script DHCPIBM.CMD, but are no longer shipped or supported:

  - 71, NewsReader/2 server

  - 201, Gopher Server

  - 202, Default WWW Server

  - 203, Default WWW Proxy Server

  - 204, Default WWW News Server

  - 206, NFS Servers and Mount Points

  - 207, Window System Default Font Path

  - 208, scmcp Command-line Parameters

  Additionally, DHCPLPR.CMD no longer supports option 205, Default SOCKS Server.

  ### Defining DHCP User and Vendor Classes

  DHCP classing refers to mechanisms in DHCP to administer groups of hosts independent of where they are located in a network. You can specify a membership in a user class and add DHCP site-specific options and processing. Tasks include:

  - Defining user classing

  - Defining vendor classing

  #### Defining User Classing

  The client tells the DHCP server in what class the client belongs. "Classing" is a general mechanism for network administrators to define groups of users with common configuration requirements. For example, create a class called "bigbatch" so that hosts that identify themselves as belonging to that class are served a separate LPR printer (option 9) from others on the same subnet or across many subnets.

  DHCP clients use option 77 to indicate to DHCP servers what class the host is a member of. The user class must be manually entered in the \DHCPCD.CFG file as the value for option 77 in order to receive parameters defined for the class at a DHCP server.

  #### Defining Vendor Classing

  Vendor classing is a special-purpose mechanism for DHCP vendors to specify the "make and model" of the requesting client software. Vendors may use this option to optimize the operation of DHCP when both the client and server are their own brand.

  DHCP clients use DHCP option 60 to indicate to DHCP servers what vendor type they are. The vendor class is specified in the default file \DHCPCD.CFG.

  The IBM vendor class is provided as "IBMWARP_V41". You should not change this value.

  Option 43, Vendor-specific Information, is used by clients and servers to exchange information. It allows for the expansion of the number of options that can be supported, and is used in conjunction with Option 60, the vendor class identifier.

  The following example illustrates the use of the vendor keyword in the \DHCPCD.CFG file:

      vendor exec "dhcpopt.exe %s"
             {
                option 63
                option 70
                option 200
             }

  The option numbers you specify within the braces can be any number from 0 to 255. The option numbers in this environment do not correlate to the architected option numbers specified in RFC 2132. The exec parameter is used only in the vendor statement, not on option statements within braces.

  ## Client Configuration File Example

  The following file is an example of DHCPCD.CFG, used by DHCP clients for servers that require clients to explicitly request options:

  \DHCPCD.CFG
    Default client configuration file.

        #

        #   Default DHCP Client configuration file -- dhcpcd.cfg

        #

        #

        #   This file must be placed in the directory specified by the ETC

        #   environment variable.

        #

        # Basic options required

        clientid   MAC

        interface lan0

        # Uncomment as desired for logging

        #numLogFiles   4

        #logFileSize   100

        #logFileName   dhcpcd.log

        #logItem       SYSERR

        #logItem       OBJERR

        #logItem       PROTERR

        #logItem       WARNING

        #logItem       EVENT

        #logItem       ACTION

        #logItem       INFO

        #logItem       ACNTING

        #logItem       TRACE

        # The following are requested for interoperability with some servers which

        # need explicit requests.

        option 1                                  # Subnet Mask

        option 3                                  # Router

        option 6                                  # Domain Name Server

        option 15                                # Domain Name

        option 28                                # Broadcast Address

        option 33                                # Static Routes

        option 60 "IBMWARP_V4.1"         # Vendor Class

        option 77 "IBMWARP_V4.1"         # User Class

        updateDNSA "nsupdate -h%s -s"d;a;*;a;a;%s;s;%s;3110400;q""

        updateDNSTxt "nsupdate -h%s -s"d;txt;%s;a;txt;%s;s;%s3110400;q""

        # The following are options for which IBM supplies an instantiation script,

        # dhcplpr.cmd, to automatically configure the remote print application

        # with a printer and server name.  Uncomment them if desired.

        option 200 exec "dhcplpr.cmd 200 %s"     # Default LPR Printer

  # Notices

  Second Edition (September 1997)

  The following paragraph does not apply to the United Kingdom or any country where such provisions are inconsistent with local law: INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS PUBLICATION "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of express or implied warranties in certain transactions; therefore, this statement may not apply to you.

  This publication might include technical inaccuracies or typographical errors. Changes are periodically made to the information herein; these changes will be incorporated in new editions of the publication. IBM may make improvements and/or changes in the product(s) and/or the program(s) described in this publication at any time.

  This publication was developed for products and services offered in the United States of America. IBM may not offer the products, services, or features discussed in this document in other countries, and the information is subject to change without notice. Consult your local IBM representative for information on the products, services, and features available in your area.

  Requests for technical information about IBM products should be made to your IBM reseller or IBM marketing representative.

  ## Copyright Notices

  © Copyright International Business Machines Corporation 1996, 1997. All rights reserved.

  Note to U.S. government Users -- Documentation related to restricted rights -- Use, duplication or disclosure is subject to restrictions set forth in GSA ADP Schedule Contract with IBM Corp.

  IBM is required to include the following statements in order to distribute portions of this document and the software described herein.

  __________________________________

  The TCP/IP client and server software included herein contains network security technology licensed from RSA Data Security, Inc. This technology is licensed solely for use with software using technology previously licensed from RSA Data Security, Inc.

  ## Disclaimers

  References in this publication to IBM products, programs, or services do not imply that IBM intends to make these available in all countries in which IBM operates. Any reference to an IBM product, program or service is not intended to state or imply that only IBM's product, program, or service may be used. Subject to IBM's valid intellectual property or other legally protectable rights, any functionally equivalent product, program, or service may be used instead of the IBM product, program, or service. Evaluation and verification of operation in conjunction with other products, programs, or services, except those expressly designated by IBM, are the user's responsibility.

  IBM may have patents or pending patent applications covering subject matter in this document. The furnishing of this document does not give you any license to these patents. You can send license inquiries, in writing, to:

         IBM Director of Licensing
         IBM Corporation
         500 Columbus Avenue
         Thornwood, NY 10594
         U.S.A.

  Licensees of this program who wish to have information about it for the purpose of enabling: (i) the exchange of information between independently created programs and other programs (including this one) and (ii) the mutual use of the information which has been exchanged, should contact IBM Corporation, Department LZKS, 11400 Burnet Road, Austin, TX 78758, U.S.A. Such information may be available, subject to appropriate terms and conditions, including in some cases, payment of a fee.

  ## Acknowledgments

  TCP/IP for OS/2 incorporates compression code by the Info-ZIP group. There are no extra charges or costs due to the use of this code, and the original compression sources are freely available from Compuserve in the OS2USER forum and by anonymous ftp from the Internet site ftp.uu.net:/pub/archiving/zip.

  ## Trademarks

  The following terms are trademarks of the IBM Corporation in the United States or other countries or both:

  - IBM
  - Operating System 2
  - OS/2

  Other company, product, and service names which may be denoted by a double asterisk (**), may be trademarks or service marks of others.