DHCP
[ProtocolsUser Protocols]


Detailed Description

Dynamic host configuration protocol.


Data Structures

struct  dyn_cfg
 Dynamic configuration structure. More...

DHCP Message Types

See RFC 2131.

#define DHCP_ACK   5
 Server to client with configuration parameters.
#define DHCP_DECLINE   4
 Client to server indicating network address is already in use.
#define DHCP_DISCOVER   1
 Client broadcast to locate available servers.
#define DHCP_INFORM   8
 Client to server, asking only for local configuration parameters.
#define DHCP_NAK   6
 Server to client indicating client's notion of network address is incorrect.
#define DHCP_OFFER   2
 Server to client in response to DHCP_DISCOVER.
#define DHCP_RELEASE   7
 Client to server relinquishing network address and cancelling remaining lease.
#define DHCP_REQUEST   3
 Client message to servers.

DHCP Client Configuration

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

#define DHCP_CLIENTPORT   68
 UDP port of DHCP client.
#define DHCP_DEFAULT_LEASE   43200
 Default lease time in seconds.
#define DHCP_SERVERPORT   67
 UDP port of DHCP server.
#define MAX_DCHP_RELEASE_RETRIES   0
 Maximum number of release retries.
#define MAX_DCHP_RETRIES   3
 Maximum number of request retries.
#define MAX_DHCP_BUFSIZE   1728
 Maximum UDP buffer size used by the DHCP client.
#define MAX_DHCP_MSGSIZE   576
 Maximum DHCP message size we can accept.
#define MAX_DHCP_NAPTIME   4294967
 Maximum sleep time in seconds.
#define MAX_DHCP_WAIT   64000
 Maximum number of milliseconds to wait for a response.
#define MIN_DHCP_MSGSIZE   300
 Minimum DHCP message length.
#define MIN_DHCP_WAIT   4000
 Minimum number of milliseconds to wait for a response.
#define NUT_THREAD_DHCPSTACK   512
 Stack size of the DHCP client thread.

DHCP Error Codes

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

#define DHCPERR_BADDEV   17
 DHCP error: Bad device.
#define DHCPERR_NOMAC   2
 DHCP MAC error.
#define DHCPERR_RECEIVE   20
 DHCP receive error.
#define DHCPERR_STATE   3
 DHCP state error.
#define DHCPERR_SYSTEM   18
 DHCP system error.
#define DHCPERR_TIMEOUT   1
 DHCP timeout error.
#define DHCPERR_TRANSMIT   19
 DHCP transmit error.

DHCP Options

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

#define DHCPOPT_BROADCAST   28
 DHCP broadcast address option.
#define DHCPOPT_DNS   6
 DHCP domain name server option.
#define DHCPOPT_DOMAIN   15
 DHCP domain name option.
#define DHCPOPT_END   255
 DHCP end option.
#define DHCPOPT_GATEWAY   3
 DHCP router option.
#define DHCPOPT_HOSTNAME   12
 DHCP host name option.
#define DHCPOPT_LEASETIME   51
 DHCP IP address lease time option.
#define DHCPOPT_MAXMSGSIZE   57
 Maximum DHCP message size option.
#define DHCPOPT_MSGTYPE   53
 DHCP message type option.
#define DHCPOPT_NETMASK   1
 DHCP subnet mask option.
#define DHCPOPT_PAD   0
 DHCP pad option.
#define DHCPOPT_PARAMREQUEST   55
 DHCP parameter request list option.
#define DHCPOPT_REBINDTIME   59
 DHCP rebinding time option.
#define DHCPOPT_RENEWALTIME   58
 DHCP renewal time option.
#define DHCPOPT_REQESTIP   50
 DHCP requested IP address option.
#define DHCPOPT_SID   54
 DHCP server identifier option.

DHCP Client States.

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

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

Typedefs

typedef dyn_cfg DYNCFG
 Dynamic configuration structure type.

Functions

struct __attribute__ ((packed))
 Operating system configuration type.
int NutDhcpError (CONST char *name)
 Return DHCP error code.
int NutDhcpIfConfig (CONST char *name, u_char *mac, u_long timeout)
 Automatically configure an Ethernet network interface.
int NutDhcpInform (CONST char *name, u_long timeout)
 Inform DHCP about an allocated address.
int NutDhcpIsConfigured (void)
 Check if DHCP has configured our interface.
int NutDhcpRelease (CONST char *name, u_long timeout)
 Relinguish our DHCP lease.
int NutDhcpStatus (CONST char *name)
 Return DHCP client status.
 THREAD (NutDhcpClient, arg)


Define Documentation

#define DHCP_ACK   5

Server to client with configuration parameters.

Contains committed network address.

#define DHCP_DECLINE   4

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   8

Client to server, asking only for local configuration parameters.

Used, if the client already has externally configured 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_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

#define DHCPERR_BADDEV   17

DHCP error: Bad device.

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

#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_RECEIVE   20

DHCP receive error.

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

#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_SYSTEM   18

DHCP system error.

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

#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_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 DHCPOPT_PAD   0

DHCP pad option.

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

#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_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_INFORMING   8

DHCP state: Informing.

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

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

DHCP state: Rebooting.

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

#define DHCPST_RELEASING   9

DHCP state: Releasing.

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

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

struct __attribute__ ( (packed)   ) 

Operating system configuration type.

Once created, this structure will never change if it points to another directory. Except if the entry is removed.

< Packet opcode type: 1=request, 2=reply

< Hardware address type: 1=Ethernet

< Hardware address length: 6 for Ethernet

< Gateway hops

< Transaction ID

< Seconds since boot began

< RFC1532 broadcast, etc.

< Client IP address

< 'Your' IP address

< Server IP address

< Gateway IP address

< Client hardware address

< Server host name

< Boot file name

< Vendor-specific area

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


Generated on Tue Jan 23 21:12:26 2007 for BTnut System Software by doxygen 1.4.7