dhcp

README

Testing against a local DHCP server

These instructions will run a DHCP server locally on your computer for testing the DHCP client.

Run qemu with Fuchsia. We'll give Fuchsia two NICs so that we can test the interaction between them and DHCP. Make all the tunnels:

sudo ip tuntap add dev qemu       mode tap user $(whoami)
sudo ip tuntap add dev qemu-extra mode tap user $(whoami)
sudo ip link set qemu up
sudo ip link set qemu-extra up

Now build and run Fuchsia with those two ports:

fx build && fx qemu -kN -- -nic tap,ifname=qemu-extra,model=e1000

Now install a DHCP server.

sudo apt-get install isc-dhcp-server
ps aux | grep dhcp

If dhcpd was started as part of that, kill it:

sudo systemctl disable isc-dhcp-server.service

Make a file called /tmp/dhcpd.conf with these contents:

default-lease-time 3600;
max-lease-time 7200;
authoritative;
subnet 172.18.0.0 netmask 255.255.0.0 {
  option routers                  172.18.0.1;
  option subnet-mask              255.255.0.0;
  option domain-search            "testdomain18.lan";
  option domain-name-servers      172.18.0.1;
  range   172.18.0.10   172.18.0.100;
}
subnet 172.19.0.0 netmask 255.255.0.0 {
  option routers                  172.19.0.1;
  option subnet-mask              255.255.0.0;
  option domain-search            "testdomain19.lan";
  option domain-name-servers      172.19.0.1;
  range   172.19.0.10   172.19.0.100;
}

dhcpd knows which addresses to serve on which nics based on matching the existing IP address on the NIC so you need to set those:

sudo ip addr add dev qemu       172.18.0.1
sudo ip addr add dev qemu-extra 172.19.0.1

Now we'll run dhcpd. You can use the filenames below or modify them.

If the leases file doesn't already exist, dhcpd might complain. Go ahead and create the file first:

sudo touch /tmp/dhcpd.leases

Now run:

sudo dhcpd -4 -f -d -cf /tmp/dhcpd.conf -lf /tmp/dhcpd.leases qemu qemu-extra

Now Fuchsia should get DHCP addresses and you'll see debug output for each step in the dhcpd output.

Documentation

Overview

Package dhcp implements a DHCP client and server as described in RFC 2131.

Index

• Constants
• type AcquiredFunc
• type Client
  • func NewClient(s *stack.Stack, nicid tcpip.NICID, linkAddr tcpip.LinkAddress, ...) *Client
  • func (c *Client) Info() Info
  • func (c *Client) Run(ctx context.Context)
  • func (c *Client) StateRecentHistory() []util.LogEntry
  • func (c *Client) Stats() *Stats
  • func (c *Client) StoreInfo(info *Info)
• type Config
• type Info
• type PacketDiscardStats
• type Seconds
  • func (s Seconds) Duration() time.Duration
  • func (s Seconds) String() string
• type Server
  • func NewServer(ctx context.Context, c conn, addrs []tcpip.Address, cfg Config) (*Server, error)
• type Stats

Constants

const (
	// ServerPort is the well-known UDP port number for a DHCP server.
	ServerPort = 67
	// ClientPort is the well-known UDP port number for a DHCP client.
	ClientPort = 68
)

Types

type AcquiredFunc

type AcquiredFunc func(lost, acquired tcpip.AddressWithPrefix, cfg Config)

type Client

type Client struct {
	// contains filtered or unexported fields
}

Client is a DHCP client.

func NewClient

func NewClient(
	s *stack.Stack,
	nicid tcpip.NICID,
	linkAddr tcpip.LinkAddress,
	acquisition,
	backoff,
	retransmission time.Duration,
	acquiredFunc AcquiredFunc,
) *Client

NewClient creates a DHCP client.

acquiredFunc will be called after each DHCP acquisition, and is responsible for making necessary modifications to the stack state.

func (*Client) Info

func (c *Client) Info() Info

Info returns a copy of the synchronized state of the Info.

func (*Client) Run

func (c *Client) Run(ctx context.Context)

Run runs the DHCP client.

The function periodically searches for a new IP address.

func (*Client) StateRecentHistory

func (c *Client) StateRecentHistory() []util.LogEntry

func (*Client) Stats

func (c *Client) Stats() *Stats

Stats returns a reference to the Client`s stats.

func (*Client) StoreInfo

func (c *Client) StoreInfo(info *Info)

StoreInfo updates the synchronized copy of the DHCP Info and if the client's state changed, it will log it in the state recent history.

Because of the size of Info, it is passed as a pointer to avoid an extra unnecessary copy.

type Config

type Config struct {
	ServerAddress tcpip.Address     // address of the server
	SubnetMask    tcpip.AddressMask // client address subnet mask
	Router        []tcpip.Address   // client router addresses
	DNS           []tcpip.Address   // client DNS server addresses
	UpdatedAt     time.Time         // monotonic time at which lease was last updated
	LeaseLength   Seconds           // time until lease expires, relative to the value of UpdatedAt
	RenewTime     Seconds           // time until client enters RENEWING state, relative to the value of UpdatedAt
	RebindTime    Seconds           // time until client enters REBINDING state, relative to the value of UpdatedAt
	Declined      bool              // server sent a NAK
}

Config is standard DHCP configuration.

type Info

type Info struct {
	// NICID is the identifer to the associated NIC.
	NICID tcpip.NICID
	// LinkAddr is the link-address of the associated NIC.
	LinkAddr tcpip.LinkAddress
	// Acquisition is the duration within which a complete DHCP transaction must
	// complete before timing out.
	Acquisition time.Duration
	// Backoff is the duration for which the client must wait before starting a
	// new DHCP transaction after a failed transaction.
	Backoff time.Duration
	// Retransmission is the duration to wait before resending a DISCOVER or
	// REQUEST within an active transaction.
	Retransmission time.Duration
	// Acquired is the network address most recently acquired by the client.
	Acquired tcpip.AddressWithPrefix
	// State is the DHCP client state.
	State dhcpClientState
	// Assigned is the network address added by the client to its stack.
	Assigned tcpip.AddressWithPrefix
	// LeaseExpiration is the time at which the client's current lease will
	// expire.
	LeaseExpiration time.Time
	// RenewTime is the at which the client will transition to its renewing state.
	RenewTime time.Time
	// RebindTime is the time at which the client will transition to its rebinding
	// state.
	RebindTime time.Time
	// Config is the last DHCP configuration assigned to the client by the server.
	Config Config
}

type PacketDiscardStats

type PacketDiscardStats struct {
	InvalidPort       tcpip.IntegralStatCounterMap
	InvalidTransProto tcpip.IntegralStatCounterMap
	InvalidPacketType tcpip.IntegralStatCounterMap
}

type Seconds

type Seconds uint32

Seconds represents a time duration in seconds.

RFC 2131 Section 3.3 https://tools.ietf.org/html/rfc2131#section-3.3

Throughout the protocol, times are to be represented in units of seconds.

Representing relative times in units of seconds in an unsigned 32 bit
word gives a range of relative times from 0 to approximately 100 years,
which is sufficient for the relative times to be measured using DHCP.

func (Seconds) Duration

func (s Seconds) Duration() time.Duration

func (Seconds) String

func (s Seconds) String() string

type Server

type Server struct {
	// contains filtered or unexported fields
}

Server is a DHCP server.

func NewServer

func NewServer(ctx context.Context, c conn, addrs []tcpip.Address, cfg Config) (*Server, error)

NewServer creates a new DHCP server and begins serving. The server continues serving until ctx is done.

type Stats

type Stats struct {
	PacketDiscardStats          PacketDiscardStats
	InitAcquire                 tcpip.StatCounter
	RenewAcquire                tcpip.StatCounter
	RebindAcquire               tcpip.StatCounter
	SendDiscovers               tcpip.StatCounter
	RecvOffers                  tcpip.StatCounter
	SendRequests                tcpip.StatCounter
	RecvAcks                    tcpip.StatCounter
	RecvNaks                    tcpip.StatCounter
	SendDiscoverErrors          tcpip.StatCounter
	SendRequestErrors           tcpip.StatCounter
	RecvOfferErrors             tcpip.StatCounter
	RecvOfferUnexpectedType     tcpip.StatCounter
	RecvOfferOptsDecodeErrors   tcpip.StatCounter
	RecvOfferTimeout            tcpip.StatCounter
	RecvOfferAcquisitionTimeout tcpip.StatCounter
	RecvAckErrors               tcpip.StatCounter
	RecvNakErrors               tcpip.StatCounter
	RecvAckOptsDecodeErrors     tcpip.StatCounter
	RecvAckAddrErrors           tcpip.StatCounter
	RecvAckUnexpectedType       tcpip.StatCounter
	RecvAckTimeout              tcpip.StatCounter
	RecvAckAcquisitionTimeout   tcpip.StatCounter
	ReacquireAfterNAK           tcpip.StatCounter
}

Stats collects DHCP statistics per client.