Main Page | Modules | Alphabetical List | Data Structures | Directories | File List | Data Fields | Globals | Related Pages | Examples

DHCP
[User Protocols]

Collaboration diagram for DHCP:

Detailed Description

Dynamic host configuration protocol.

Hosts running Nut/Net can make use of DHCP, if the local network provides this facility.

To use this feature, applications must call NutDhcpIfConfig().

 #include <pro/dhcp.h>

 ...

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

Application programmers often get confused by the fact, that NutDhcpIfConfig() is somewhat more general. It also checks non-volatile memory (e.g. EEPROM contents for the AVR devices). If a fixed IP address has been configured, it will use this and will not query DHCP for an IP configuration. The Ethernut Software Manual explains this in more detail.

Typical DHCP servers offer more than just the IP configuration. The following items are recognized by Nut/Net:

However, only the first three are used for the Nut/Net IP configuration. The broadcast address is internally created by the IP layer.

If provided by the DHCP server, the IP addresses of the primary and the secondary DNS are passed by the DHCP client to NutDnsConfig2().

The last two items, host and domain name, are currently discarded.

When an application wants to shut down the system, it may call NutDhcpRelease(). This lowers the burden on some busy DHCP servers with long lease times.

Applications doing their own IP configuration, e.g. using a user interface for their configuration and storing the values in non-volatile memory, may call NutDhcpInform() to inform DHCP servers about the address allocation.

The function NutDhcpStatus() is provided to enable applications to track the progress and the current status of the DHCP client.


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   0
 DHCP state: Stopped.
#define DHCPST_INIT   1
 DHCP state: Starting.
#define DHCPST_SELECTING   2
 DHCP state: Selecting.
#define DHCPST_REQUESTING   3
 DHCP state: Requesting.
#define DHCPST_REBOOTING   4
 DHCP state: Rebooting.
#define DHCPST_BOUND   5
 DHCP state: Bound.
#define DHCPST_RENEWING   6
 DHCP state: Renewing.
#define DHCPST_REBINDING   7
 DHCP state: Rebinding.
#define DHCPST_INFORMING   8
 DHCP state: Informing.
#define DHCPST_RELEASING   9
 DHCP state: Releasing.

DHCP Error Codes

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

#define DHCPERR_TIMEOUT   1
 DHCP timeout error.
#define DHCPERR_NOMAC   2
 DHCP MAC error.
#define DHCPERR_STATE   3
 DHCP state error.
#define DHCPERR_BADDEV   17
 DHCP error: Bad device.
#define DHCPERR_SYSTEM   18
 DHCP system error.
#define DHCPERR_TRANSMIT   19
 DHCP transmit error.
#define DHCPERR_RECEIVE   20
 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   1
 Client broadcast to locate available servers.
#define DHCP_OFFER   2
 Server to client in response to DHCP_DISCOVER.
#define DHCP_REQUEST   3
 Client message to servers.
#define DHCP_DECLINE   4
 Client to server indicating network address is already in use.
#define DHCP_ACK   5
 Server to client with configuration parameters.
#define DHCP_NAK   6
 Server to client indicating client's notion of network address is incorrect.
#define DHCP_RELEASE   7
 Client to server relinquishing network address and cancelling remaining lease.
#define DHCP_INFORM   8
 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   0
 DHCP pad option.
#define DHCPOPT_NETMASK   1
 DHCP subnet mask option.
#define DHCPOPT_GATEWAY   3
 DHCP router option.
#define DHCPOPT_DNS   6
 DHCP domain name server option.
#define DHCPOPT_HOSTNAME   12
 DHCP host name option.
#define DHCPOPT_DOMAIN   15
 DHCP domain name option.
#define DHCPOPT_BROADCAST   28
 DHCP broadcast address option.
#define DHCPOPT_REQESTIP   50
 DHCP requested IP address option.
#define DHCPOPT_LEASETIME   51
 DHCP IP address lease time option.
#define DHCPOPT_MSGTYPE   53
 DHCP message type option.
#define DHCPOPT_SID   54
 DHCP server identifier option.
#define DHCPOPT_PARAMREQUEST   55
 DHCP parameter request list option.
#define DHCPOPT_MAXMSGSIZE   57
 Maximum DHCP message size option.
#define DHCPOPT_RENEWALTIME   58
 DHCP renewal time option.
#define DHCPOPT_REBINDTIME   59
 DHCP rebinding time option.
#define DHCPOPT_END   255
 DHCP end option.

Typedefs

typedef bootp BOOTP
 BOOTP message structure type.
typedef dyn_cfg DYNCFG
 Dynamic configuration structure type.

Functions

void 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 DHCPST_IDLE   0
 

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_INIT   1
 

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_SELECTING   2
 

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 DHCPST_REQUESTING   3
 

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_REBOOTING   4
 

DHCP state: Rebooting.

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

#define DHCPST_BOUND   5
 

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_RENEWING   6
 

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_REBINDING   7
 

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_INIT.

#define DHCPST_INFORMING   8
 

DHCP state: Informing.

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

#define DHCPST_RELEASING   9
 

DHCP state: Releasing.

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

#define DHCPERR_TIMEOUT   1
 

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_NOMAC   2
 

DHCP MAC error.

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

#define DHCPERR_STATE   3
 

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_BADDEV   17
 

DHCP error: Bad device.

The specified device name hasn't been registered or is not an Ethernet device.

#define DHCPERR_SYSTEM   18
 

DHCP system error.

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

#define DHCPERR_TRANSMIT   19
 

DHCP transmit error.

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

#define DHCPERR_RECEIVE   20
 

DHCP receive error.

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

#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 MIN_DHCP_MSGSIZE   300
 

Minimum DHCP message length.

Used to maintain BOOTP compatibility of outgoing messages.

#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 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.

#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 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_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 DHCP_DEFAULT_LEASE   43200
 

Default lease time in seconds.

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

#define DHCP_OFFER   2
 

Server to client in response to DHCP_DISCOVER.

Contains an offer of configuration parameters.

#define DHCP_REQUEST   3
 

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 DHCP_DECLINE   4
 

Client to server indicating network address is already in use.

Not used by Nut/Net.

#define DHCP_ACK   5
 

Server to client with configuration parameters.

Contains committed network address.

#define DHCP_NAK   6
 

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_INFORM   8
 

Client to server, asking only for local configuration parameters.

Used, if the client already has externally configured network address.

#define DHCPOPT_PAD   0
 

DHCP pad option.

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

Function Documentation

NutDhcpClient (  void *  arg  ) 
 

DHCP client thread.

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

Bug:
We are not able to shutdown our interface, which may cause problems if out original DHCP server dies.

Todo:
We are using a bunch of global variables, which must be associated to a specific interfase if we want to support more than one Ethernet port.

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.

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 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 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:

int NutDhcpError (  CONST char *  name  ) 
 

Return DHCP error code.

Possible error codes are

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 NutDhcpIsConfigured (  void   ) 
 

Check if DHCP has configured our interface.

Deprecated:
Applications should use NutDhcpStatus().
Returns:
0 if DHCP is in bound state.

© 2000-2006 by egnite Software GmbH - visit http://www.ethernut.de/