Hans.Message.Dhcp4

The Dhcp4 module defines the various messages and transitions used in the DHCPv4 protocol. This module provides both a high-level view of the message types as well as a low-level intermediate form which is closely tied to the binary format.

References: RFC 2131 - Dynamic Host Configuration Protocol http://www.faqs.org/rfcs/rfc2131.html

High-level client types

data RequestMessage

RequestMessage is a sum of the client request messages.

Constructors

RequestMessage Request

DiscoverMessage Discover

Instances

Show RequestMessage

data Request

Request is used by the client to accept an offered lease.

Constructors

Request

Fields

requestXid :: Xid

Transaction ID of offer

requestBroadcast :: Bool

Set True to instruct server to send to broadcast hardware address

requestServerAddr :: IP4

requestClientHardwareAddress :: Mac

Hardware address of the client

requestParameters :: [Dhcp4OptionTag]

Used to specify the information that client needs

requestAddress :: Maybe IP4

Used to specify the address which was accepted

Instances

Show Request

data Discover

Discover is used by the client to discover what servers are available. This message is sent to the IPv4 broadcast.

Constructors

Discover

Fields

discoverXid :: Xid

Transaction ID of this and subsequent messages

discoverBroadcast :: Bool

Set True to instruct the server to send to broadcast hardware address

discoverClientHardwareAddr :: Mac

Hardware address of the client

discoverParameters :: [Dhcp4OptionTag]

Used to specify the information that client needs in the offers

Instances

Show Discover

High-level server types

data ServerSettings

ServerSettings define all of the information that would be needed to act as a DHCP server for one client. The server is defined to be able to issue a single "lease" whose parameters are defined below.

Constructors

Settings

Fields

staticServerAddr :: IP4

The IPv4 address of the DHCP server

staticTimeOffset :: Word32

Lease: timezone offset in seconds from UTC

staticClientAddr :: IP4

Lease: client IPv4 address on network

staticLeaseTime :: Word32

Lease: duration in seconds

staticSubnet :: SubnetMask

Lease: subnet mask on network

staticBroadcast :: IP4

Lease: broadcast address on network

staticRouters :: [IP4]

Lease: gateway routers on network

staticDomainName :: String

Lease: client's assigned domain name

staticDNS :: [IP4]

Lease: network DNS servers

Instances

Show ServerSettings

data ReplyMessage

ReplyMessage is a sum of the server response messages.

Constructors

AckMessage Ack

OfferMessage Offer

Instances

Show ReplyMessage

data Ack

Ack is sent by the DHCPv4 server to acknowledge a sucessful Request message. Upon receiving this message the client has completed the exchange and has successfully obtained a lease.

Constructors

Ack

Fields

ackHops :: Word8

The maximum number of relays this message can use.

ackXid :: Xid

Transaction ID for this exchange

ackYourAddr :: IP4

Lease: assigned client address

ackServerAddr :: IP4

DHCP server's IPv4 address

ackRelayAddr :: IP4

DHCP relay server's address

ackClientHardwareAddr :: Mac

Client's hardware address

ackLeaseTime :: Word32

Lease: duration of lease in seconds

ackOptions :: [Dhcp4Option]

Subset of information requested in previous Request

Instances

Show Ack

data Offer

Offer is sent by the DHCPv4 server in response to a Discover. This offer is only valid for a short period of time as the client might receive many offers. The client must next request a lease from a specific server using the information in that server's offer.

Constructors

Offer

Fields

offerHops :: Word8

The maximum number of relays this message can use.

offerXid :: Xid

Transaction ID of this exchange

offerYourAddr :: IP4

The IPv4 address that this server is willing to lease

offerServerAddr :: IP4

The IPv4 address of the DHCPv4 server

offerRelayAddr :: IP4

The IPv4 address of the DHCPv4 relay server

offerClientHardwareAddr :: Mac

The hardware address of the client

offerOptions :: [Dhcp4Option]

The options that this server would include in a lease

Instances

Show Offer

Low-level message types

data Dhcp4Message

Dhcp4Message is a low-level message container that is very close to the binary representation of DHCPv4 message. It is suitable for containing any DHCPv4 message. Values of this type should only be created using the publicly exported functions.

Constructors

Dhcp4Message

Fields

dhcp4Op :: Dhcp4Op

Message op code / message type. 1 = BOOTREQUEST, 2 = BOOTREPLY

dhcp4Hops :: Word8

Client sets to zero, optionally used by relay agents when booting via a relay agent.

dhcp4Xid :: Xid

Transaction ID, a random number chosen by the client, used by the client and server to associate messages and responses between a client and a server.

dhcp4Secs :: Word16

Filled in by client, seconds elapsed since client began address acquisition or renewal process.

dhcp4Broadcast :: Bool

Client requests messages be sent to hardware broadcast address

dhcp4ClientAddr :: IP4

Client IP address; only filled in if client is in BOUND, RENEW or REBINDING state and can respond to ARP requests.

dhcp4YourAddr :: IP4

your (client) address

dhcp4ServerAddr :: IP4

IP address of next server to use in bootstrap; returned in DHCPOFFER, DHCPACK by server

dhcp4RelayAddr :: IP4

Relay agent IP address, used in booting via a relay agent

dhcp4ClientHardwareAddr :: Mac

Client hardware address

dhcp4ServerHostname :: String

Optional server host name, null terminated string

dhcp4BootFilename :: String

Boot file name, full terminated string; "generic" name of null in DHCPDISCOVER, fully qualified directory-path name in DHCPOFFER

dhcp4Options :: [Dhcp4Option]

Optional parameters field.

Instances

Eq Dhcp4Message

Show Dhcp4Message

newtype Xid

Xid is a Transaction ID, a random number chosen by the client, used by the client and server to associate messages and responses between a client and a server.

Constructors

Xid Word32

Instances

Eq Xid

Show Xid

CodecAtom Xid

Server message transition logic

requestToAck

Arguments

:: ServerSettings

DHCPv4 server settings

-> Request

Client's request message

-> Ack

requestToAck creates Ack messages suitable for responding to Request messages given a static ServerSettings configuration.

discoverToOffer

Arguments

:: ServerSettings

DHCPv4 server settings

-> Discover

Client's discover message

-> Offer

discoverToOffer creates a suitable Offer in response to a client's Discover message using the configuration settings specified in the given ServerSettings.

Client message transition logic

mkDiscover

Arguments

:: Xid

New randomly generated transaction ID

-> Mac

The client's hardware address

-> Discover

mkDiscover creates a new Discover message with a set of options suitable for configuring a basic network stack.

offerToRequest

Arguments

:: Offer

The offer as received from the server

-> Request

offerToRequest creates a Request message suitable for accepting an Offer from the DHCPv4 server.

Convert high-level message types to low-level format

requestToMessage :: Request -> Dhcp4Message

requestToMessage embeds Request messages in the low-level Dhcp4Message type, typically for the purpose of serialization.

ackToMessage :: Ack -> Dhcp4Message

ackToMessage embeds Ack messages in the low-level Dhcp4Message type, typically for the purpose of serialization.

offerToMessage :: Offer -> Dhcp4Message

offerToMessage embeds Offer messages in the low-level Dhcp4Message type, typically for the purpose of serialization.

discoverToMessage :: Discover -> Dhcp4Message

discoverToMessage embeds Discover messages in the low-level Dhcp4Message type, typically for the purpose of serialization.

Convert low-level message type to high-level format

parseDhcpMessage :: Dhcp4Message -> Maybe (Either RequestMessage ReplyMessage)

parseDhcpMessage attempts to find a valid high-level message contained in a low-level message. The Dhcp4Message is a large type and can encode invalid combinations of options.

Convert low-level message type to binary format

getDhcp4Message :: ByteString -> Either String Dhcp4Message

getDhcp4Message is the binary decoder for parsing Dhcp4Message values.

putDhcp4Message :: Dhcp4Message -> ByteString

getDhcp4Message is the binary encoder for rendering Dhcp4Message values.