dhcpsvc

Documentation

Overview

Package dhcpsvc contains the AdGuard Home DHCP service.

TODO(e.burkov): Add tests.

Index

• type Config
  • func (conf *Config) Validate() (err error)
• type DHCPServer
  • func New(ctx context.Context, conf *Config) (srv *DHCPServer, err error)
  • func (srv *DHCPServer) AddLease(ctx context.Context, l *Lease) (err error)
  • func (srv *DHCPServer) Enabled() (ok bool)
  • func (srv *DHCPServer) HostByIP(ip netip.Addr) (host string)
  • func (srv *DHCPServer) IPByHost(host string) (ip netip.Addr)
  • func (srv *DHCPServer) Leases() (leases []*Lease)
  • func (srv *DHCPServer) MACByIP(ip netip.Addr) (mac net.HardwareAddr)
  • func (srv *DHCPServer) RemoveLease(ctx context.Context, l *Lease) (err error)
  • func (srv *DHCPServer) Reset(ctx context.Context) (err error)
  • func (srv *DHCPServer) UpdateStaticLease(ctx context.Context, l *Lease) (err error)
• type Empty
  • func (Empty) AddLease(_ context.Context, _ *Lease) (err error)
  • func (Empty) Config() (conf *Config)
  • func (Empty) Enabled() (ok bool)
  • func (Empty) HostByIP(_ netip.Addr) (host string)
  • func (Empty) IPByHost(_ string) (ip netip.Addr)
  • func (Empty) Leases() (leases []*Lease)
  • func (Empty) MACByIP(_ netip.Addr) (mac net.HardwareAddr)
  • func (Empty) RemoveLease(_ context.Context, _ *Lease) (err error)
  • func (Empty) Reset(_ context.Context) (err error)
  • func (Empty) Shutdown(_ context.Context) (err error)
  • func (Empty) Start(_ context.Context) (err error)
  • func (Empty) UpdateStaticLease(_ context.Context, _ *Lease) (err error)
• type IPv4Config
• type IPv6Config
• type Interface
• type InterfaceConfig
• type Lease
  • func (l *Lease) Clone() (clone *Lease)

Types

type Config

type Config struct {
	// Interfaces stores configurations of DHCP server specific for the network
	// interface identified by its name.
	Interfaces map[string]*InterfaceConfig

	// Logger will be used to log the DHCP events.
	Logger *slog.Logger

	// LocalDomainName is the top-level domain name to use for resolving DHCP
	// clients' hostnames.
	LocalDomainName string

	// DBFilePath is the path to the database file containing the DHCP leases.
	DBFilePath string

	// ICMPTimeout is the timeout for checking another DHCP server's presence.
	ICMPTimeout time.Duration

	// Enabled is the state of the service, whether it is enabled or not.
	Enabled bool
}

Config is the configuration for the DHCP service.

func (*Config) Validate

func (conf *Config) Validate() (err error)

Validate returns an error in conf if any.

TODO(e.burkov): Unexport and rewrite the test.

type DHCPServer

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

DHCPServer is a DHCP server for both IPv4 and IPv6 address families.

func New

func New(ctx context.Context, conf *Config) (srv *DHCPServer, err error)

New creates a new DHCP server with the given configuration. It returns an error if the given configuration can't be used.

TODO(e.burkov): Use.

func (*DHCPServer) AddLease

func (srv *DHCPServer) AddLease(ctx context.Context, l *Lease) (err error)

AddLease implements the Interface interface for *DHCPServer.

func (*DHCPServer) Enabled

func (srv *DHCPServer) Enabled() (ok bool)

Enabled implements the Interface interface for *DHCPServer.

func (*DHCPServer) HostByIP

func (srv *DHCPServer) HostByIP(ip netip.Addr) (host string)

HostByIP implements the Interface interface for *DHCPServer.

func (*DHCPServer) IPByHost

func (srv *DHCPServer) IPByHost(host string) (ip netip.Addr)

IPByHost implements the Interface interface for *DHCPServer.

func (*DHCPServer) Leases

func (srv *DHCPServer) Leases() (leases []*Lease)

Leases implements the Interface interface for *DHCPServer.

func (*DHCPServer) MACByIP

func (srv *DHCPServer) MACByIP(ip netip.Addr) (mac net.HardwareAddr)

MACByIP implements the Interface interface for *DHCPServer.

func (*DHCPServer) RemoveLease

func (srv *DHCPServer) RemoveLease(ctx context.Context, l *Lease) (err error)

RemoveLease implements the Interface interface for *DHCPServer.

func (*DHCPServer) Reset

func (srv *DHCPServer) Reset(ctx context.Context) (err error)

Reset implements the Interface interface for *DHCPServer.

func (*DHCPServer) UpdateStaticLease

func (srv *DHCPServer) UpdateStaticLease(ctx context.Context, l *Lease) (err error)

UpdateStaticLease implements the Interface interface for *DHCPServer.

TODO(e.burkov): Support moving leases between interfaces.

type Empty

type Empty struct{}

Empty is an Interface implementation that does nothing.

func (Empty) AddLease

func (Empty) AddLease(_ context.Context, _ *Lease) (err error)

AddLease implements the Interface interface for Empty.

func (Empty) Config

func (Empty) Config() (conf *Config)

Config implements the [ServiceWithConfig] interface for Empty.

func (Empty) Enabled

func (Empty) Enabled() (ok bool)

Enabled implements the Interface interface for Empty.

func (Empty) HostByIP

func (Empty) HostByIP(_ netip.Addr) (host string)

HostByIP implements the Interface interface for Empty.

func (Empty) IPByHost

func (Empty) IPByHost(_ string) (ip netip.Addr)

IPByHost implements the Interface interface for Empty.

func (Empty) Leases

func (Empty) Leases() (leases []*Lease)

Leases implements the Interface interface for Empty.

func (Empty) MACByIP

func (Empty) MACByIP(_ netip.Addr) (mac net.HardwareAddr)

MACByIP implements the Interface interface for Empty.

func (Empty) RemoveLease

func (Empty) RemoveLease(_ context.Context, _ *Lease) (err error)

RemoveLease implements the Interface interface for Empty.

func (Empty) Reset

func (Empty) Reset(_ context.Context) (err error)

Reset implements the Interface interface for Empty.

func (Empty) Shutdown

func (Empty) Shutdown(_ context.Context) (err error)

Shutdown implements the [Service] interface for Empty.

func (Empty) Start

func (Empty) Start(_ context.Context) (err error)

Start implements the [Service] interface for Empty.

func (Empty) UpdateStaticLease

func (Empty) UpdateStaticLease(_ context.Context, _ *Lease) (err error)

UpdateStaticLease implements the Interface interface for Empty.

type IPv4Config

type IPv4Config struct {
	// GatewayIP is the IPv4 address of the network's gateway.  It is used as
	// the default gateway for DHCP clients and also used in calculating the
	// network-specific broadcast address.
	GatewayIP netip.Addr

	// SubnetMask is the IPv4 subnet mask of the network.  It should be a valid
	// IPv4 CIDR (i.e. all 1s followed by all 0s).
	SubnetMask netip.Addr

	// RangeStart is the first address in the range to assign to DHCP clients.
	RangeStart netip.Addr

	// RangeEnd is the last address in the range to assign to DHCP clients.
	RangeEnd netip.Addr

	// Options is the list of DHCP options to send to DHCP clients.  The options
	// having a zero value within the Length field are treated as deletions of
	// the corresponding options, either implicit or explicit.
	Options layers.DHCPOptions

	// LeaseDuration is the TTL of a DHCP lease.
	LeaseDuration time.Duration

	// Enabled is the state of the DHCPv4 service, whether it is enabled or not
	// on the specific interface.
	Enabled bool
}

IPv4Config is the interface-specific configuration for DHCPv4.

type IPv6Config

type IPv6Config struct {
	// RangeStart is the first address in the range to assign to DHCP clients.
	RangeStart netip.Addr

	// Options is the list of DHCP options to send to DHCP clients.  The options
	// with zero length are treated as deletions of the corresponding options,
	// either implicit or explicit.
	Options layers.DHCPv6Options

	// LeaseDuration is the TTL of a DHCP lease.
	LeaseDuration time.Duration

	// RASlaacOnly defines whether the DHCP clients should only use SLAAC for
	// address assignment.
	RASLAACOnly bool

	// RAAllowSlaac defines whether the DHCP clients may use SLAAC for address
	// assignment.
	RAAllowSLAAC bool

	// Enabled is the state of the DHCPv6 service, whether it is enabled or not
	// on the specific interface.
	Enabled bool
}

IPv6Config is the interface-specific configuration for DHCPv6.

type Interface

type Interface interface {
	agh.ServiceWithConfig[*Config]

	// Enabled returns true if DHCP provides information about clients.
	Enabled() (ok bool)

	// HostByIP returns the hostname of the DHCP client with the given IP
	// address.  The address will be netip.Addr{} if there is no such client,
	// due to an assumption that a DHCP client must always have an IP address.
	HostByIP(ip netip.Addr) (host string)

	// MACByIP returns the MAC address for the given IP address leased.  It
	// returns nil if there is no such client, due to an assumption that a DHCP
	// client must always have a MAC address.
	//
	// TODO(e.burkov):  Think of a contract for the returned value.
	MACByIP(ip netip.Addr) (mac net.HardwareAddr)

	// IPByHost returns the IP address of the DHCP client with the given
	// hostname.  The hostname will be an empty string if there is no such
	// client, due to an assumption that a DHCP client must always have a
	// hostname, either set or generated.
	IPByHost(host string) (ip netip.Addr)

	// Leases returns all the active DHCP leases.  The returned slice should be
	// a clone.  The order of leases is undefined.
	//
	// TODO(e.burkov):  Consider implementing iterating methods with appropriate
	// signatures instead of cloning the whole list.
	Leases() (ls []*Lease)

	// AddLease adds a new DHCP lease.  l must be valid.  It returns an error if
	// l already exists.
	AddLease(ctx context.Context, l *Lease) (err error)

	// UpdateStaticLease replaces an existing static DHCP lease.  l must be
	// valid.  It returns an error if the lease with the given hardware address
	// doesn't exist or if other values match another existing lease.
	UpdateStaticLease(ctx context.Context, l *Lease) (err error)

	// RemoveLease removes an existing DHCP lease.  l must be valid.  It returns
	// an error if there is no lease equal to l.
	RemoveLease(ctx context.Context, l *Lease) (err error)

	// Reset removes all the DHCP leases.
	//
	// TODO(e.burkov):  If it's really needed?
	Reset(ctx context.Context) (err error)
}

Interface is a DHCP service.

TODO(e.burkov): Separate HostByIP, MACByIP, IPByHost into a separate interface. This is also applicable to Enabled method.

TODO(e.burkov): Reconsider the requirements for the leases validity.

type InterfaceConfig

type InterfaceConfig struct {
	// IPv4 is the configuration of DHCP protocol for IPv4.
	IPv4 *IPv4Config

	// IPv6 is the configuration of DHCP protocol for IPv6.
	IPv6 *IPv6Config
}

InterfaceConfig is the configuration of a single DHCP interface.

type Lease

type Lease struct {
	// IP is the IP address leased to the client.
	IP netip.Addr

	// Expiry is the expiration time of the lease.
	Expiry time.Time

	// Hostname of the client.
	Hostname string

	// HWAddr is the physical hardware address (MAC address).
	HWAddr net.HardwareAddr

	// IsStatic defines if the lease is static.
	IsStatic bool
}

Lease is a DHCP lease.

TODO(e.burkov): Consider moving it to agh, since it also may be needed in [websvc].

TODO(e.burkov): Add validation method.

func (*Lease) Clone

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

Clone returns a deep copy of l.