dhcpd

README

DHCP server

Contents:

• Test setup with Virtual Box

Test setup with Virtual Box

To set up a test environment for DHCP server you need:

• Linux host machine
• Virtual Box
• Virtual machine (guest OS doesn't matter)

Configure client

1. Install Virtual Box and run the following command to create a Host-Only network:

    $ VBoxManage hostonlyif create
   

   You can check its status by ip a command.

   You can also set up Host-Only network using Virtual Box menu:

    File -> Host Network Manager...
   

2. Create your virtual machine and set up its network:

    VM Settings -> Network -> Host-only Adapter
   

3. Start your VM, install an OS. Configure your network interface to use DHCP and the OS should ask for a IP address from our DHCP server.

4. To see the current IP address on client OS you can use ip a command on Linux or ipconfig on Windows.

5. To force the client OS to request an IP from DHCP server again, you can use dhclient on Linux or ipconfig /release on Windows.

Configure server

1. Edit server configuration file 'AdGuardHome.yaml', for example:

    dhcp:
      enabled: true
      interface_name: vboxnet0
      dhcpv4:
        gateway_ip: 192.168.56.1
        subnet_mask: 255.255.255.0
        range_start: 192.168.56.2
        range_end: 192.168.56.2
        lease_duration: 86400
        icmp_timeout_msec: 1000
        options: []
      dhcpv6:
        range_start: 2001::1
        lease_duration: 86400
        ra_slaac_only: false
        ra_allow_slaac: false
   

2. Start the server

    ./AdGuardHome
   

   There should be a message in log which shows that DHCP server is ready:

    [info] DHCP: listening on 0.0.0.0:67
   

Documentation

Overview

Package dhcpd provides a DHCP server.

Index

• Constants
• type DHCPServer
• type GetLeasesFlags
• type Lease
  • func (l *Lease) Clone() (clone *Lease)
  • func (l *Lease) IsBlocklisted() (ok bool)
  • func (l *Lease) IsStatic() (ok bool)
  • func (l Lease) MarshalJSON() ([]byte, error)
  • func (l *Lease) UnmarshalJSON(data []byte) (err error)
• type OnLeaseChangedT
• type Server
  • func Create(conf ServerConfig) (s *Server, err error)
  • func (s *Server) AddStaticLease(l *Lease) error
  • func (s *Server) Enabled() (ok bool)
  • func (s *Server) FindMACbyIP(ip net.IP) net.HardwareAddr
  • func (s *Server) Leases(flags GetLeasesFlags) (leases []*Lease)
  • func (s *Server) SetOnLeaseChanged(onLeaseChanged OnLeaseChangedT)
  • func (s *Server) Start() (err error)
  • func (s *Server) Stop() (err error)
  • func (s *Server) WriteDiskConfig(c *ServerConfig)
• type ServerConfig
• type ServerInterface
• type V4ServerConf
• type V6ServerConf

Constants

const (
	LeaseChangedAdded = iota
	LeaseChangedAddedStatic
	LeaseChangedRemovedStatic
	LeaseChangedRemovedAll

	LeaseChangedDBStore
)

flags for onLeaseChanged()

const (
	// DefaultDHCPLeaseTTL is the default time-to-live for leases.
	DefaultDHCPLeaseTTL = uint32(timeutil.Day / time.Second)
	// DefaultDHCPTimeoutICMP is the default timeout for waiting ICMP responses.
	DefaultDHCPTimeoutICMP = 1000
)

Types

type DHCPServer

type DHCPServer interface {
	// ResetLeases resets leases.
	ResetLeases(leases []*Lease) (err error)
	// GetLeases returns deep clones of the current leases.
	GetLeases(flags GetLeasesFlags) (leases []*Lease)
	// AddStaticLease - add a static lease
	AddStaticLease(l *Lease) (err error)
	// RemoveStaticLease - remove a static lease
	RemoveStaticLease(l *Lease) (err error)
	// FindMACbyIP - find a MAC address by IP address in the currently active DHCP leases
	FindMACbyIP(ip net.IP) net.HardwareAddr

	// WriteDiskConfig4 - copy disk configuration
	WriteDiskConfig4(c *V4ServerConf)
	// WriteDiskConfig6 - copy disk configuration
	WriteDiskConfig6(c *V6ServerConf)

	// Start - start server
	Start() (err error)
	// Stop - stop server
	Stop() (err error)
	// contains filtered or unexported methods
}

DHCPServer - DHCP server interface

type GetLeasesFlags

type GetLeasesFlags uint8

GetLeasesFlags are the flags for GetLeases.

const (
	LeasesDynamic GetLeasesFlags = 0b0001
	LeasesStatic  GetLeasesFlags = 0b0010

	LeasesAll = LeasesDynamic | LeasesStatic
)

GetLeasesFlags values

type Lease

type Lease struct {
	// Expiry is the expiration time of the lease.  The unix timestamp value
	// of 1 means that this is a static lease.
	Expiry time.Time `json:"expires"`

	Hostname string           `json:"hostname"`
	HWAddr   net.HardwareAddr `json:"mac"`
	IP       net.IP           `json:"ip"`
}

Lease contains the necessary information about a DHCP lease

func (*Lease) Clone

func (l *Lease) Clone() (clone *Lease)

Clone returns a deep copy of l.

func (*Lease) IsBlocklisted

func (l *Lease) IsBlocklisted() (ok bool)

IsBlocklisted returns true if the lease is blocklisted.

TODO(a.garipov): Just make it a boolean field.

func (*Lease) IsStatic

func (l *Lease) IsStatic() (ok bool)

IsStatic returns true if the lease is static.

TODO(a.garipov): Just make it a boolean field.

func (Lease) MarshalJSON

func (l Lease) MarshalJSON() ([]byte, error)

MarshalJSON implements the json.Marshaler interface for Lease.

func (*Lease) UnmarshalJSON

func (l *Lease) UnmarshalJSON(data []byte) (err error)

UnmarshalJSON implements the json.Unmarshaler interface for *Lease.

type OnLeaseChangedT

type OnLeaseChangedT func(flags int)

OnLeaseChangedT is a callback for lease changes.

type Server

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

Server - the current state of the DHCP server

func Create

func Create(conf ServerConfig) (s *Server, err error)

Create - create object

func (*Server) AddStaticLease

func (s *Server) AddStaticLease(l *Lease) error

AddStaticLease - add static v4 lease

func (*Server) Enabled

func (s *Server) Enabled() (ok bool)

Enabled returns true when the server is enabled.

func (*Server) FindMACbyIP

func (s *Server) FindMACbyIP(ip net.IP) net.HardwareAddr

FindMACbyIP - find a MAC address by IP address in the currently active DHCP leases

func (*Server) Leases

func (s *Server) Leases(flags GetLeasesFlags) (leases []*Lease)

Leases returns the list of active IPv4 and IPv6 DHCP leases. It's safe for concurrent use.

func (*Server) SetOnLeaseChanged

func (s *Server) SetOnLeaseChanged(onLeaseChanged OnLeaseChangedT)

SetOnLeaseChanged - set callback

func (*Server) Start

func (s *Server) Start() (err error)

Start will listen on port 67 and serve DHCP requests.

func (*Server) Stop

func (s *Server) Stop() (err error)

Stop closes the listening UDP socket

func (*Server) WriteDiskConfig

func (s *Server) WriteDiskConfig(c *ServerConfig)

WriteDiskConfig - write configuration

type ServerConfig

type ServerConfig struct {
	Enabled       bool   `yaml:"enabled"`
	InterfaceName string `yaml:"interface_name"`

	Conf4 V4ServerConf `yaml:"dhcpv4"`
	Conf6 V6ServerConf `yaml:"dhcpv6"`

	WorkDir    string `yaml:"-"`
	DBFilePath string `yaml:"-"` // path to DB file

	// Called when the configuration is changed by HTTP request
	ConfigModified func() `yaml:"-"`

	// Register an HTTP handler
	HTTPRegister func(string, string, func(http.ResponseWriter, *http.Request)) `yaml:"-"`
}

ServerConfig - DHCP server configuration field ordering is important -- yaml fields will mirror ordering from here

type ServerInterface

type ServerInterface interface {
	Enabled() (ok bool)
	Leases(flags GetLeasesFlags) (leases []*Lease)
	SetOnLeaseChanged(onLeaseChanged OnLeaseChangedT)
}

ServerInterface is an interface for servers.

type V4ServerConf

type V4ServerConf struct {
	Enabled       bool   `yaml:"-" json:"-"`
	InterfaceName string `yaml:"-" json:"-"`

	GatewayIP  net.IP `yaml:"gateway_ip" json:"gateway_ip"`
	SubnetMask net.IP `yaml:"subnet_mask" json:"subnet_mask"`

	// The first & the last IP address for dynamic leases
	// Bytes [0..2] of the last allowed IP address must match the first IP
	RangeStart net.IP `yaml:"range_start" json:"range_start"`
	RangeEnd   net.IP `yaml:"range_end" json:"range_end"`

	LeaseDuration uint32 `yaml:"lease_duration" json:"lease_duration"` // in seconds

	// IP conflict detector: time (ms) to wait for ICMP reply
	// 0: disable
	ICMPTimeout uint32 `yaml:"icmp_timeout_msec" json:"-"`

	// Custom Options.
	//
	// Option with arbitrary hexadecimal data:
	//     DEC_CODE hex HEX_DATA
	// where DEC_CODE is a decimal DHCPv4 option code in range [1..255]
	//
	// Option with IP data (only 1 IP is supported):
	//     DEC_CODE ip IP_ADDR
	Options []string `yaml:"options" json:"-"`
	// contains filtered or unexported fields
}

V4ServerConf - server configuration

type V6ServerConf

type V6ServerConf struct {
	Enabled       bool   `yaml:"-" json:"-"`
	InterfaceName string `yaml:"-" json:"-"`

	// The first IP address for dynamic leases
	// The last allowed IP address ends with 0xff byte
	RangeStart net.IP `yaml:"range_start" json:"range_start"`

	LeaseDuration uint32 `yaml:"lease_duration" json:"lease_duration"` // in seconds

	RASLAACOnly  bool `yaml:"ra_slaac_only" json:"-"`  // send ICMPv6.RA packets without MO flags
	RAAllowSLAAC bool `yaml:"ra_allow_slaac" json:"-"` // send ICMPv6.RA packets with MO flags
	// contains filtered or unexported fields
}

V6ServerConf - server configuration