`dhcp.client`

TCP/IP host configuration utility

You must be root to run this utility.

Syntax:

dhcp.client [-abdmnr] [-h hostname] [-I num]
            [-i interface] 
            [-P port] [-p port] [-s host]
            [-t num] [-u] &

Options:

-a

Apply the assigned IP address as an alias instead of overwriting the current configuration.

-b

Request the DHCP server to send its response packets only to the client where appropriate (default is to request the server to broadcast).

-d

Write debugging info to the system log.

-h hostname

Hostname of client (default is supplied by the server if the hostname is available).

-I num

The number of times to poll waiting for interface to be available (default 5). Polling is done every 2 seconds.

You can use this option to make dhcp.client wait until the interface it's to use is available. This is useful in a boot environment when you might not know when the driver is running and registered with the TCPIP stack. The exit status is 2 if no interface is found.

-i interface

Name of the interface to configure (e.g. en0, en1). The default is the first interface found.

-m

Instead of writing the domain and nameserver data to /etc/resolv.conf (the default), write the data to the _CS_DOMAIN and _CS_RESOLVE memory configuration-defined values (see confstr()), where:

_CS_DOMAIN: Domain name.
_CS_RESOLVE: Nameserver.

If -m and -n are specified together, the domain is added, but the nameservers aren't.

-n

Don't add the DHCP-supplied nameservers to /etc/resolv.conf or _CS_RESOLVE. If -m is also specified, the domain is added, but the nameservers aren't. If -m isn't specified, neither the domain nor the nameservers are added.

-P port

DHCP server port (default is dhcp port or port 67).

-p port

DHCP client port (default is dhcpc port or port 68).

-s host

Accept packets from this server only; ignore responses from other servers.

-t num

Attempt to reach the server num times before giving up and terminating (the default is forever). Each attempt lasts 1 minute.

You're likely to use this option in combination with the -u option so that dhcp.client times out after a specified number of attempts.

-u

Don't move dhcp.client to the background until the interface is configured.

This option is useful for spawning dhcp.client. The process doesn't move to the background until it has contacted a server and applied a TCP/IP configuration. The exit status is 3 if no server responds.

Description:

The dhcp.client obtains the TCP/IP configuration parameters dynamically from a DHCP (Dynamic Host Configuration Protocol) server, then automatically configures your TCP/IP host. You don't have to provide an IP address or any configuration parameters, or run any configuration utilities.

If dhcp.client is terminated, it will release the DHCP address assigned by the server back to the server. If the client is terminated with SIGPWR, the address will not be released: The lease will timeout or be continued at client restart (depending on server policies).

A TCP/IP stack (e.g. npm-tcpip.so) must be started before the dhcp.client.

The minimum commands to run under QNX Neutrino are:

io-net -dne2000 -ptcpip
if_up -p enx
dhcp.client &
if_up enx

Or,

io-net -dne2000 -ptcpip
dhcp.client -Ix -u

If you wish dhcp.client to apply the IP address as an alias instead of overwriting the currently assigned IP address, you must pass the -a option. This option is useful if you wish to assign multiple IP addresses to an interface. You must pass the -a option if you wish to use dhcp.client and AutoIP (nfm-autoip.so) on the same interface.

By default, dhcp.client searches for an unconfigured interface to provide service. If AutoIP is in use, an unconfigured interface will not be available, and the dhcp.client will terminate. In order for dhcp.client to provide service to an interface that already has an IP address assigned to it, use the -i option (in combination with -a), and the interface will have both a DHCP and AutoIP IP address assigned to it.

This utility obtains and implements the following information from the DHCP server:

Broadcast address (can't be set for the tiny stack).
Domain
Gateway (default route)
Hostname
IP address
Nameserver
Netmask

`/etc/dhcp/dhcp-up`

If this file exists, it is run after a DHCP server has been contacted and the configuration options above has been applied. This file can be a binary program, or a script, and must be executable (see chmod). If the file is a script, the first line must be the command interpretor. For example

#!/bin/sh

Environment variables, that contain the configuration that was obtained from the server, are passed to this file. When the file is spawned, it doesn't inherit the full environment. For example, the PATH environment variable is not available. If you wish to test the dhcp-up file functionality, a dhcp-up script as follows:

#!/bin/sh

env > /tmp/config

writes all the options that were supplied by the DHCP server to the /tmp/config file.

The environment definitions are:

INTERFACE: The interface that was configured (e.g. INTERFACE=en0).
IPADDRESS: The client IP address that was obtained from the server (e.g. IPADDRESS=10.0.0.1).
NETMASK: The client netmask that was obtained from the server (e.g. NETMASK=255.0.0.0).
HOSTNAME: The hostname of the client (e.g. HOSTNAME=node1).
BROADCAST: The client broadcast address that was obtained from the server (e.g. BROADCAST=10.255.255.255).
GATEWAY: The gateway that the client is to use (e.g. GATEWAY=10.0.0.2).
SERVER: The server's IP address (e.g. SERVER=10.0.0.3).
NAMESERVER1,
NAMESERVER2: The nameserver that the client is to use (e.g. NAMESERVER1=10.0.0.4).
LEASEOBTAINED: The time at which the lease was obtained (e.g. LEASEOBTAINED=Mon Oct 30 16:46:10 2000).
LEASEEXPIRES: The time at which the lease expires (e.g. LEASEEXPIRES=Mon Oct 31 16:46:10 2000).

The following options are available but not applied by the dhcp.client process:

FILENAME: The filename supplied in the server response (e.g. FILENAME=/bootimg).

Any other options are defined as environment variables OPTIONx, where x is the option number. If the option is known, dhcp.client tries to format it as readable information. If the option isn't known, dhcp.client displays each octet as hexadecimal (e.g. OPTION200= F1 AA 56 42).

Currently, dhcp.client is aware of options 1 to 61.

Files:

The dhcp.client utility requires the libsocket.so shared library.

Exit status:

0: Success.
1: An error occurred.
2: No interface was found.
3: No server responded.

Errors:

Errors that occur during configuration are reported to the system log.