DHCP
[User Protocols]

Collaboration diagram for DHCP:

Detailed Description

Dynamic host configuration protocol.

Data Structures

struct bootp

BOOTP message structure. More...

struct dyn_cfg

Dynamic configuration structure. More...

DHCP Client States.

Applications can request the current state of the DHCP client by calling NutDhcpStatus().

#define DHCPST_IDLE

DHCP state: Stopped.

#define DHCPST_INIT

DHCP state: Starting.

#define DHCPST_SELECTING

DHCP state: Selecting.

#define DHCPST_REQUESTING

DHCP state: Requesting.

#define DHCPST_REBOOTING

DHCP state: Rebooting.

#define DHCPST_BOUND

DHCP state: Bound.

#define DHCPST_RENEWING

DHCP state: Renewing.

#define DHCPST_REBINDING

DHCP state: Rebinding.

#define DHCPST_INFORMING

DHCP state: Informing.

#define DHCPST_RELEASING

DHCP state: Releasing.

DHCP Error Codes

Applications can request the lastest error code of the DHCP client by calling NutDhcpError().

#define DHCPERR_TIMEOUT

DHCP timeout error.

#define DHCPERR_NOMAC

DHCP MAC error.

#define DHCPERR_STATE

DHCP state error.

#define DHCPERR_BADDEV

DHCP error: Bad device.

#define DHCPERR_SYSTEM

DHCP system error.

#define DHCPERR_TRANSMIT

DHCP transmit error.

#define DHCPERR_RECEIVE

DHCP receive error.

DHCP Client Configuration

The Nut/OS Configurator may be used to override the default values.

#define DHCP_SERVERPORT   67

UDP port of DHCP server.

#define DHCP_CLIENTPORT   68

UDP port of DHCP client.

#define MAX_DHCP_MSGSIZE   576

Maximum DHCP message size we can accept.

#define MIN_DHCP_MSGSIZE   300

Minimum DHCP message length.

#define MAX_DHCP_BUFSIZE   1728

Maximum UDP buffer size used by the DHCP client.

#define MIN_DHCP_WAIT   4000

Minimum number of milliseconds to wait for a response.

#define MAX_DHCP_WAIT   64000

Maximum number of milliseconds to wait for a response.

#define MAX_DCHP_RETRIES   3

Maximum number of request retries.

#define MAX_DCHP_RELEASE_RETRIES   0

Maximum number of release retries.

#define DHCP_DEFAULT_LEASE   43200

Default lease time in seconds.

#define MAX_DHCP_NAPTIME   4294967

Maximum sleep time in seconds.

#define NUT_THREAD_DHCPSTACK   512

Stack size of the DHCP client thread.

DHCP Message Types

See RFC 2131.

#define DHCP_DISCOVER

Client broadcast to locate available servers.

#define DHCP_OFFER

Server to client in response to DHCP_DISCOVER.

#define DHCP_REQUEST

Client message to servers.

#define DHCP_DECLINE

Client to server indicating network address is already in use.

#define DHCP_ACK

Server to client with configuration parameters.

#define DHCP_NAK

Server to client indicating client's notion of network address is incorrect.

#define DHCP_RELEASE

Client to server relinquishing network address and cancelling remaining lease.

#define DHCP_INFORM

Client to server, asking only for local configuration parameters.

DHCP Options

Nut/Net recognizes a subset of options defined in RFC 2132.

#define DHCPOPT_PAD

DHCP pad option.

#define DHCPOPT_NETMASK

DHCP subnet mask option.

#define DHCPOPT_GATEWAY

DHCP router option.

#define DHCPOPT_DNS

DHCP domain name server option.

#define DHCPOPT_HOSTNAME

DHCP host name option.

#define DHCPOPT_DOMAIN

DHCP domain name option.

#define DHCPOPT_BROADCAST

DHCP broadcast address option.

#define DHCPOPT_REQESTIP

DHCP requested IP address option.

#define DHCPOPT_LEASETIME

DHCP IP address lease time option.

#define DHCPOPT_MSGTYPE

DHCP message type option.

#define DHCPOPT_SID

DHCP server identifier option.

#define DHCPOPT_PARAMREQUEST

DHCP parameter request list option.

#define DHCPOPT_MAXMSGSIZE

Maximum DHCP message size option.

#define DHCPOPT_RENEWALTIME

DHCP renewal time option.

#define DHCPOPT_REBINDTIME

DHCP rebinding time option.

#define DHCPOPT_END

DHCP end option.

Typedefs

typedef dyn_cfg DYNCFG

Dynamic configuration structure type.

Functions

NutDhcpClient (void *arg)

DHCP client thread.

int NutDhcpIfConfig (CONST char *name, u_char *mac, u_long timeout)

Automatically configure an Ethernet network interface.

int NutDhcpRelease (CONST char *name, u_long timeout)

Relinguish our DHCP lease.

int NutDhcpInform (CONST char *name, u_long timeout)

Inform DHCP about an allocated address.

int NutDhcpStatus (CONST char *name)

Return DHCP client status.

int NutDhcpError (CONST char *name)

Return DHCP error code.

int NutDhcpIsConfigured (void)

Check if DHCP has configured our interface.

Define Documentation

#define DHCP_ACK

Server to client with configuration parameters.
Contains committed network address.

#define DHCP_DECLINE

Client to server indicating network address is already in use.
Not used by Nut/Net.

#define DHCP_DEFAULT_LEASE 43200

Default lease time in seconds.
This value is used if the server doesn't provide a lease time.

#define DHCP_INFORM

Client to server, asking only for local configuration parameters.
Used, if the client already has externally configured network address.

#define DHCP_NAK

Server to client indicating client's notion of network address is incorrect.
May be caused by the client's move to new subnet or by expiration of the client's lease.

#define DHCP_OFFER

Server to client in response to DHCP_DISCOVER.
Contains an offer of configuration parameters.

#define DHCP_REQUEST

Client message to servers.
Used for

requesting offered parameters from one server and implicitly declining offers from all others.
confirming correctness of previously allocated address after, e.g., system reboot.
extending the lease on a particular network address.

#define DHCPERR_BADDEV

DHCP error: Bad device.
The specified device name hasn't been registered or is not an Ethernet device.

#define DHCPERR_NOMAC

DHCP MAC error.
No Ethernet MAC address found in the non-volatile configuration memory and none specified by calling NutDhcpIfConfig().

#define DHCPERR_RECEIVE

DHCP receive error.
Failed to receive an UDP datagram. The DHCP client considers it a fatal error if NutUdpReceiveFrom() fails.

#define DHCPERR_STATE

DHCP state error.
Either NutDhcpInform() has been called while not in state DHCPST_IDLE or NutDhcpRelease() has been called while not in state DHCPST_BOUND.

#define DHCPERR_SYSTEM

DHCP system error.
A system error occured during DHCP processing. Most probably the system ran out of memory.

#define DHCPERR_TIMEOUT

DHCP timeout error.
No server response within the specified number of milliseconds. Either the timeout value has been too low or no DHCP server is available in the local network.

#define DHCPERR_TRANSMIT

DHCP transmit error.
Failed to send an UDP datagram. The DHCP client considers it a fatal error if NutUdpSendTo() to the broadcast address fails.

#define DHCPOPT_PAD

DHCP pad option.
The pad option can be used to cause subsequent fields to align on word boundaries.

#define DHCPST_BOUND

DHCP state: Bound.
This state indicates, that the DHCP client has successfully allocated a network address. Any thread blocked in NutDhcpIfConfig() will be woken up.
The client remains in this state until the renewal time elapses, in which case it moves to DHCPST_RENEWING.
In order to save heap memory, the client will close the UDP socket while in bound state.

#define DHCPST_IDLE

DHCP state: Stopped.
Indicates that the DHCP client is inactive. Either it just started, gave up the lease or ran into an error. In the latter case the application may call NutDhcpError() to retrieve the specific error code.
In order to save heap memory, the client will not open the UDP socket while inactive.

#define DHCPST_INFORMING

DHCP state: Informing.
The client enters this state when the application calls NutDhcpInform().

#define DHCPST_INIT

DHCP state: Starting.
Indicates that the DHCP client started to request a configuration from the DHCP server. If any previously allocated IP address is available in the non-volatile configuration memory, then the client will continue with DHCPST_REBOOTING. Otherwise it will move to DHCPST_SELECTING.

#define DHCPST_REBINDING

DHCP state: Rebinding.
The client enters this state after the no acknowledge has been received during DHCPST_RENEWING and the rebind time elapsed. It will broadcast a request to extend its lease.
If no acknowledge is received until the lease time elapsed, the client will move to DHCPST_START.

#define DHCPST_REBOOTING

DHCP state: Rebooting.
The client enters this state to request a previously assigned configuration.

#define DHCPST_RELEASING

DHCP state: Releasing.
The client enters this state when the application calls NutDhcpRelease().

#define DHCPST_RENEWING

DHCP state: Renewing.
In this state the client tries to extend its lease by sending a request to the DHCP server. If the server responds with an acknowledge, the client returns to DHCPST_BOUND.
If no acknowledge is received until the rebind time elapses, the client moves to DHCPST_REBINDING.

#define DHCPST_REQUESTING

DHCP state: Requesting.
Indicates that the client received and selected an offer from a DHCP server. It is now sending a request for an offered configuration and waiting for an acknowledge, which will change the client's state to DHCPST_BOUND.

#define DHCPST_SELECTING

DHCP state: Selecting.
In this state the client will transmit a DHCP discover message and collect incoming offers from DHCP servers. If at least one acceptable offer has been received, it will change to DHCPST_REQUESTING.

#define MAX_DCHP_RELEASE_RETRIES 0

Maximum number of release retries.
RFC 2131 doesn't specify a server response to release messages from the client. If the message gets lost, then the lease isn't released.

#define MAX_DCHP_RETRIES 3

Maximum number of request retries.
We will give up after resending this number of requests without receiving a response.

#define MAX_DHCP_BUFSIZE 1728

Maximum UDP buffer size used by the DHCP client.
If this item is not equal zero, the DHCP client will use its value to set SO_RCVBUF by calling NutUdpSetSockOpt().
If this item is set to zero, NutUdpSetSockOpt() is not called and the UDP socket interface will buffer the last incoming datagram on the DHCP_CLIENTPORT socket port only. Any previously received datagram is silently discarded. As long as one DHCP server is expected in the local network, this will be fine and save some heap memory while DHCP is active.

#define MAX_DHCP_MSGSIZE 576

Maximum DHCP message size we can accept.
RFC 2131 demands, that a DHCP client must be prepared to receive DHCP messages with an options field length of at least 312 octets. This implies that we must be able to accept messages of up to 576 octets.

#define MAX_DHCP_WAIT 64000

Maximum number of milliseconds to wait for a response.
The timeout value for receiving server responses will be doubled on each retry but limited by this value.

#define MIN_DHCP_MSGSIZE 300

Minimum DHCP message length.
Used to maintain BOOTP compatibility of outgoing messages.

#define MIN_DHCP_WAIT 4000

Minimum number of milliseconds to wait for a response.
If we receive no response from a DHCP server within this time, we will double this value up to MAX_DHCP_WAIT and repeat our request up to MAX_DCHP_RETRIES times before giving up.

Function Documentation

NutDhcpClient ( void * arg )

DHCP client thread.
This thread implements a DHCP state machine and is automatically started when calling NutDhcpIfConfig() or NutDhcpInform().

int NutDhcpError ( CONST char * name )

Return DHCP error code.
Possible error codes are

DHCPERR_TIMEOUT
DHCPERR_NOMAC
DHCPERR_BADDEV
DHCPERR_SYSTEM
DHCPERR_TRANSMIT
DHCPERR_RECEIVE

The error will be cleared upon return.

Parameters:

name Name of the registered Ethernet device, currently ignored.

Returns:
DHCP error code or 0 if no error occured.

int NutDhcpIfConfig ( CONST char * name,

u_char * mac,

u_long timeout

)

Automatically configure an Ethernet network interface.
If no MAC address is specified, this routine will try to read a previously stored configuration from the EEPROM. If this retrieves a fixed IP configuration, then the network interface will be immediately configured with these values by calling NutNetIfConfig(). If no valid IP configuration has been read, then this routine will start the DHCP client thread and wait upto a given number of milliseconds for an acknowledged configuration from a DHCP server.
If a MAC address has been specified, this routine will not read the EEPROM configuration. If the application has set the global CONFNET structure to a valid IP configuration before calling this function, then the network interface will be immediately configured with these values by calling NutNetIfConfig(). Otherwise the DHCP client thread will be started and this routine will wait upto a given number of milliseconds for an acknowledged configuration from a DHCP server.

Parameters:

name Name of the registered Ethernet device.

mac MAC address of the destination. Set NULL to use the configuration stored in the EEPROM.

timeout Maximum number of milliseconds to wait. To disable timeout, set this parameter to NUT_WAIT_INFINITE. Otherwise the value must be larger than 3 times of MIN_DHCP_WAIT to enable collection of offers from multiple servers.

Returns:
0 if the interface had been successfully configured. In most cases this information is sufficient, because the application will not care whether the configuration had been provided by a DHCP server or EEPROM values. However, if EEPROM values had been used, then no DNS servers had been set. The application can call NutDhcpStatus() to check the DHCP bound state. -1 is returned if the interface configuration failed. In this case NutDhcpError() can be called to get a more specific error code.

API Usage Example
The following code shows a typical usage of the DHCP API.

NutRegisterDevice(&DEV_ETHER, 0, 0); if(NutDhcpIfConfig("eth0", 0, 60000)) { printf("Ethernet interface not configured. Error %d\n", NutDhcpError()); }

Here is the call graph for this function:

int NutDhcpInform ( CONST char * name,

u_long timeout

)

Inform DHCP about an allocated address.
The client must reside in state DHCPST_IDLE.

Parameters:

name Name of the registered Ethernet device, currently ignored.

timeout Maximum number of milliseconds to wait.

Returns:
0 on success or -1 in case of an error.

int NutDhcpIsConfigured ( void )

Check if DHCP has configured our interface.

Deprecated:
Applications should use NutDhcpStatus().

Returns:
0 if DHCP is in bound state.

int NutDhcpRelease ( CONST char * name,

u_long timeout

)

Relinguish our DHCP lease.
This function may be called by the application if we are moving to another network. It helps the DHCP server to tidy up his allocation table, but is not a required DHCP function.
Upon return, the system should be shut down within 20 seconds.
The client must reside in state DHCPST_BOUND.

Parameters:

name Name of the registered Ethernet device, currently ignored.

timeout Maximum number of milliseconds to wait.

Returns:
0 on success or -1 in case of an error.

int NutDhcpStatus ( CONST char * name )

Return DHCP client status.

Parameters:

name Name of the registered Ethernet device, currently ignored.

Returns:
DHCP status code, which may be any of the following:

DHCPST_INIT
DHCPST_SELECTING
DHCPST_REQUESTING
DHCPST_REBOOTING
DHCPST_BOUND
DHCPST_RENEWING
DHCPST_REBINDING
DHCPST_INFORMING
DHCPST_RELEASING
DHCPST_IDLE

Programmable Gateways

DHCP [User Protocols]

Detailed Description

Data Structures

DHCP Client States.

DHCP Error Codes

DHCP Client Configuration

DHCP Message Types

DHCP Options

Typedefs

Functions

Define Documentation

Function Documentation

DHCP
[User Protocols]