client

package
v0.107.63 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jun 26, 2025 License: GPL-3.0 Imports: 27 Imported by: 0

Documentation

Overview

Package client contains types and logic dealing with AdGuard Home's DNS clients.

TODO(a.garipov): Expand.

Index

Constants

View Source 
const ErrBadIdentifier errors.Error = "bad client identifier"

ErrBadIdentifier is returned by FindParams.Set when it cannot parse the provided client identifier.

View Source 
const ErrClosed errors.Error = "use of closed address processor"

ErrClosed is returned from [AddressProcessor.Close] if it's closed more than once.

Variables

This section is empty.

Functions

func ValidateClientID added in v0.107.46 

func ValidateClientID(id string) (err error)

ValidateClientID returns an error if id is not a valid ClientID.

TODO(s.chzhen): Consider implementing [validate.Interface] for ClientID.

Types

type AddressProcessor 

type AddressProcessor interface {
	Process(ctx context.Context, ip netip.Addr)
	Close() (err error)
}

AddressProcessor is the interface for types that can process clients.

type AddressUpdater 

type AddressUpdater interface {
	// UpdateAddress updates information about an IP address, setting host (if
	// not empty) and WHOIS information (if not nil).
	UpdateAddress(ctx context.Context, ip netip.Addr, host string, info *whois.Info)
}

AddressUpdater is the interface for storages of DNS clients that can update information about them.

TODO(a.garipov): Consider using the actual client storage once it is moved into this package.

type ClientID added in v0.107.62 

type ClientID string

ClientID is a unique identifier for a persistent client used in DNS-over-HTTPS, DNS-over-TLS, and DNS-over-QUIC queries.

TODO(s.chzhen): Use everywhere.

type CommonUpstreamConfig added in v0.107.58 

type CommonUpstreamConfig struct {
	Bootstrap               upstream.Resolver
	UpstreamTimeout         time.Duration
	BootstrapPreferIPv6     bool
	EDNSClientSubnetEnabled bool
	UseHTTP3Upstreams       bool
}

CommonUpstreamConfig contains common settings for custom client upstream configurations.

type DHCP added in v0.107.53 

type DHCP interface {
	// Leases returns all the DHCP leases.
	Leases() (leases []*dhcpsvc.Lease)

	// HostByIP returns the hostname of the DHCP client with the given IP
	// address.  host will be empty if there is no such client, due to an
	// assumption that a DHCP client must always have a hostname.
	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.
	MACByIP(ip netip.Addr) (mac net.HardwareAddr)
}

DHCP is an interface for accessing DHCP lease data the Storage needs.

type DefaultAddrProc 

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

DefaultAddrProc processes incoming client addresses with rDNS and WHOIS, if configured, and updates that information in a client storage.

func NewDefaultAddrProc 

func NewDefaultAddrProc(c *DefaultAddrProcConfig) (p *DefaultAddrProc)

NewDefaultAddrProc returns a new running client address processor. c must not be nil.

func (*DefaultAddrProc) Close 

func (p *DefaultAddrProc) Close() (err error)

Close implements the AddressProcessor interface for *DefaultAddrProc.

func (*DefaultAddrProc) Process 

func (p *DefaultAddrProc) Process(ctx context.Context, ip netip.Addr)

Process implements the AddressProcessor interface for *DefaultAddrProc.

type DefaultAddrProcConfig 

type DefaultAddrProcConfig struct {
	// BaseLogger is used to create loggers with custom prefixes for sources of
	// information about runtime clients.  It must not be nil.
	BaseLogger *slog.Logger

	// DialContext is used to create TCP connections to WHOIS servers.
	// DialContext must not be nil if [DefaultAddrProcConfig.UseWHOIS] is true.
	DialContext aghnet.DialContextFunc

	// Exchanger is used to perform rDNS queries.  Exchanger must not be nil if
	// [DefaultAddrProcConfig.UseRDNS] is true.
	Exchanger rdns.Exchanger

	// PrivateSubnets are used to determine if an incoming IP address is
	// private.  It must not be nil.
	PrivateSubnets netutil.SubnetSet

	// AddressUpdater is used to update the information about a client's IP
	// address.  It must not be nil.
	AddressUpdater AddressUpdater

	// InitialAddresses are the addresses that are queued for processing
	// immediately by [NewDefaultAddrProc].
	InitialAddresses []netip.Addr

	// CatchPanics, if true, makes the address processor catch and log panics.
	//
	// TODO(a.garipov): Consider better ways to do this or apply this method to
	// other parts of the codebase.
	CatchPanics bool

	// UseRDNS, if true, enables resolving of client IP addresses using reverse
	// DNS.
	UseRDNS bool

	// UsePrivateRDNS, if true, enables resolving of private client IP addresses
	// using reverse DNS.  See [DefaultAddrProcConfig.PrivateSubnets].
	UsePrivateRDNS bool

	// UseWHOIS, if true, enables resolving of client IP addresses using WHOIS.
	UseWHOIS bool
}

DefaultAddrProcConfig is the configuration structure for address processors.

type EmptyAddrProc 

type EmptyAddrProc struct{}

EmptyAddrProc is an AddressProcessor that does nothing.

func (EmptyAddrProc) Close 

func (EmptyAddrProc) Close() (_ error)

Close implements the AddressProcessor interface for EmptyAddrProc.

func (EmptyAddrProc) Process 

func (EmptyAddrProc) Process(_ context.Context, _ netip.Addr)

Process implements the AddressProcessor interface for EmptyAddrProc.

type EmptyDHCP added in v0.107.53 

type EmptyDHCP struct{}

EmptyDHCP is the empty DHCP implementation that does nothing.

func (EmptyDHCP) HostByIP added in v0.107.53 

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

HostByIP implements the DHCP interface for emptyDHCP.

func (EmptyDHCP) Leases added in v0.107.53 

func (EmptyDHCP) Leases() (leases []*dhcpsvc.Lease)

Leases implements the DHCP interface for emptyDHCP.

func (EmptyDHCP) MACByIP added in v0.107.53 

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

MACByIP implements the DHCP interface for emptyDHCP.

type FindParams added in v0.107.62 

type FindParams struct {
	// ClientID is a unique identifier for the client used in DoH, DoT, and DoQ
	// DNS queries.
	ClientID ClientID

	// RemoteIP is the IP address used as a client search parameter.
	RemoteIP netip.Addr

	// Subnet is the CIDR used as a client search parameter.
	Subnet netip.Prefix

	// MAC is the physical hardware address used as a client search parameter.
	MAC net.HardwareAddr

	// UID is the unique ID of persistent client used as a search parameter.
	//
	// TODO(s.chzhen):  Use this.
	UID UID
}

FindParams represents the parameters for searching a client. At least one field must be non-empty.

func (*FindParams) Set added in v0.107.62 

func (p *FindParams) Set(id string) (err error)

Set clears the stored search parameters and parses the string representation of the search parameter into typed parameter, storing it. In some cases, it may result in storing both an IP address and a MAC address because they might have identical string representations. It returns ErrBadIdentifier if id cannot be parsed.

TODO(s.chzhen): Add support for UID.

type HostsContainer added in v0.107.53 

type HostsContainer interface {
	Upd() (updates <-chan *hostsfile.DefaultStorage)
}

HostsContainer is an interface for receiving updates to the system hosts file.

type Persistent added in v0.107.46 

type Persistent struct {
	// SafeSearch handles search engine hosts rewrites.
	SafeSearch filtering.SafeSearch

	// BlockedServices is the configuration of blocked services of a client.  It
	// must not be nil after initialization.
	BlockedServices *filtering.BlockedServices

	// Name of the persistent client.  Must not be empty.
	Name string

	// Tags is a list of client tags that categorize the client.
	Tags []string

	// Upstreams is a list of custom upstream DNS servers for the client.  If
	// it's empty, the custom upstream cache is disabled, regardless of the
	// value of UpstreamsCacheEnabled.
	Upstreams []string

	// IPs is a list of IP addresses that identify the client.  The client must
	// have at least one ID (IP, subnet, MAC, or ClientID).
	IPs []netip.Addr

	// Subnets identifying the client.  The client must have at least one ID
	// (IP, subnet, MAC, or ClientID).
	//
	// TODO(s.chzhen):  Use netutil.Prefix.
	Subnets []netip.Prefix

	// MACs identifying the client.  The client must have at least one ID (IP,
	// subnet, MAC, or ClientID).
	MACs []net.HardwareAddr

	// ClientIDs identifying the client.  The client must have at least one ID
	// (IP, subnet, MAC, or ClientID).
	ClientIDs []ClientID

	// UID is the unique identifier of the persistent client.
	UID UID

	// UpstreamsCacheSize defines the size of the custom upstream cache.
	UpstreamsCacheSize uint32

	// UpstreamsCacheEnabled specifies whether the custom upstream cache is
	// used.  If true, the list of Upstreams should not be empty.
	UpstreamsCacheEnabled bool

	// UseOwnSettings specifies whether custom filtering settings are used.
	UseOwnSettings bool

	// FilteringEnabled specifies whether filtering is enabled.
	FilteringEnabled bool

	// SafeBrowsingEnabled specifies whether safe browsing is enabled.
	SafeBrowsingEnabled bool

	// ParentalEnabled specifies whether parental control is enabled.
	ParentalEnabled bool

	// UseOwnBlockedServices specifies whether custom services are blocked.
	UseOwnBlockedServices bool

	// IgnoreQueryLog specifies whether the client requests are logged.
	IgnoreQueryLog bool

	// IgnoreStatistics  specifies whether the client requests are counted.
	IgnoreStatistics bool

	// SafeSearchConf is the safe search filtering configuration.
	//
	// TODO(d.kolyshev): Make SafeSearchConf a pointer.
	SafeSearchConf filtering.SafeSearchConfig
}

Persistent contains information about persistent clients.

func (*Persistent) EqualIDs added in v0.107.46 

func (c *Persistent) EqualIDs(prev *Persistent) (equal bool)

EqualIDs returns true if the ids of the current and previous clients are the same.

func (*Persistent) Identifiers added in v0.107.62 

func (c *Persistent) Identifiers() (ids []string)

Identifiers returns a list of client identifiers containing at least one element.

func (*Persistent) SetIDs added in v0.107.46 

func (c *Persistent) SetIDs(ids []string) (err error)

SetIDs parses a list of strings into typed fields and returns an error if there is one.

func (*Persistent) ShallowClone added in v0.107.46 

func (c *Persistent) ShallowClone() (clone *Persistent)

ShallowClone returns a deep copy of the client, except upstreamConfig, safeSearchConf, SafeSearch fields, because it's difficult to copy them.

type Runtime added in v0.107.44 

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

Runtime is a client information from different sources.

func NewRuntime added in v0.107.49 

func NewRuntime(ip netip.Addr) (r *Runtime)

NewRuntime constructs a new runtime client. ip must be valid IP address.

TODO(s.chzhen): Validate IP address.

func (*Runtime) Addr added in v0.107.49 

func (r *Runtime) Addr() (ip netip.Addr)

Addr returns an IP address of the client.

func (*Runtime) Info added in v0.107.44 

func (r *Runtime) Info() (cs Source, host string)

Info returns a client information from the highest-priority source.

func (*Runtime) WHOIS added in v0.107.44 

func (r *Runtime) WHOIS() (info *whois.Info)

WHOIS returns a copy of WHOIS client information.

type Source added in v0.107.37 

type Source uint8

Source represents the source from which the information about the client has been obtained. 

const (
	SourceWHOIS Source = iota + 1
	SourceARP
	SourceRDNS
	SourceDHCP
	SourceHostsFile
	SourcePersistent
)

Clients information sources. The order determines the priority.

func (Source) MarshalText added in v0.107.37 

func (cs Source) MarshalText() (text []byte, err error)

MarshalText implements encoding.TextMarshaler for the Source.

func (Source) String added in v0.107.37 

func (cs Source) String() (s string)

String returns a human-readable name of cs.

type Storage added in v0.107.52 

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

Storage contains information about persistent and runtime clients.

func NewStorage added in v0.107.52 

func NewStorage(ctx context.Context, conf *StorageConfig) (s *Storage, err error)

NewStorage returns initialized client storage. conf must not be nil.

func (*Storage) Add added in v0.107.52 

func (s *Storage) Add(ctx context.Context, p *Persistent) (err error)

Add stores persistent client information or returns an error.

func (*Storage) AllowedTags added in v0.107.53 

func (s *Storage) AllowedTags() (tags []string)

AllowedTags returns the list of available client tags. tags must not be modified.

func (*Storage) ApplyClientFiltering added in v0.107.58 

func (s *Storage) ApplyClientFiltering(id string, addr netip.Addr, setts *filtering.Settings)

ApplyClientFiltering retrieves persistent client information using the ClientID or client IP address, and applies it to the filtering settings. setts must not be nil.

func (*Storage) ClearUpstreamCache added in v0.107.58 

func (s *Storage) ClearUpstreamCache()

ClearUpstreamCache implements the [dnsforward.ClientsContainer] interface for *Storage

func (*Storage) ClientRuntime added in v0.107.52 

func (s *Storage) ClientRuntime(ip netip.Addr) (rc *Runtime)

ClientRuntime returns a copy of the saved runtime client by ip. If no such client exists, returns nil.

func (*Storage) CustomUpstreamConfig added in v0.107.58 

func (s *Storage) CustomUpstreamConfig(
	id string,
	addr netip.Addr,
) (prxConf *proxy.CustomUpstreamConfig)

CustomUpstreamConfig implements the [dnsforward.ClientsContainer] interface for *Storage

func (*Storage) Find added in v0.107.52 

func (s *Storage) Find(params *FindParams) (p *Persistent, ok bool)

Find represents the parameters for searching a client. params must not be nil and must have at least one non-empty field.

func (*Storage) FindLoose added in v0.107.52 

func (s *Storage) FindLoose(ip netip.Addr, id string) (p *Persistent, ok bool)

FindLoose is like Storage.Find but it also tries to find a persistent client by IP address without zone. It strips the IPv6 zone index from the stored IP addresses before comparing, because querylog entries don't have it. See TODO on [querylog.logEntry.IP].

Note that multiple clients can have the same IP address with different zones. Therefore, the result of this method is indeterminate.

TODO(s.chzhen): Consider accepting FindParams.

func (*Storage) RangeByName added in v0.107.52 

func (s *Storage) RangeByName(f func(c *Persistent) (cont bool))

RangeByName calls f for each persistent client sorted by name, unless cont is false.

func (*Storage) RangeRuntime added in v0.107.52 

func (s *Storage) RangeRuntime(f func(rc *Runtime) (cont bool))

RangeRuntime calls f for each runtime client in an undefined order.

func (*Storage) ReloadARP added in v0.107.53 

func (s *Storage) ReloadARP(ctx context.Context)

ReloadARP reloads runtime clients from ARP, if configured.

func (*Storage) RemoveByName added in v0.107.52 

func (s *Storage) RemoveByName(ctx context.Context, name string) (ok bool)

RemoveByName removes persistent client information. ok is false if no such client exists by that name.

func (*Storage) Shutdown added in v0.107.53 

func (s *Storage) Shutdown(_ context.Context) (err error)

Shutdown gracefully stops the client storage.

TODO(s.chzhen): Pass context.

func (*Storage) Size added in v0.107.52 

func (s *Storage) Size() (n int)

Size returns the number of persistent clients.

func (*Storage) Start added in v0.107.53 

func (s *Storage) Start(ctx context.Context) (err error)

Start starts the goroutines for updating the runtime client information.

TODO(s.chzhen): Pass context.

func (*Storage) Update added in v0.107.52 

func (s *Storage) Update(ctx context.Context, name string, p *Persistent) (err error)

Update finds the stored persistent client by its name and updates its information from p.

func (*Storage) UpdateAddress added in v0.107.53 

func (s *Storage) UpdateAddress(ctx context.Context, ip netip.Addr, host string, info *whois.Info)

UpdateAddress implements the AddressUpdater interface for *Storage

func (*Storage) UpdateCommonUpstreamConfig added in v0.107.58 

func (s *Storage) UpdateCommonUpstreamConfig(conf *CommonUpstreamConfig)

UpdateCommonUpstreamConfig implements the [dnsforward.ClientsContainer] interface for *Storage

func (*Storage) UpdateDHCP added in v0.107.53 

func (s *Storage) UpdateDHCP(ctx context.Context)

UpdateDHCP updates SourceDHCP runtime client information.

type StorageConfig added in v0.107.53 

type StorageConfig struct {
	// Logger is used for logging the operation of the client storage.  It must
	// not be nil.
	Logger *slog.Logger

	// Clock is used by [upstreamManager] to retrieve the current time.  It must
	// not be nil.
	Clock timeutil.Clock

	// DHCP is used to match IPs against MACs of persistent clients and update
	// [SourceDHCP] runtime client information.  It must not be nil.
	DHCP DHCP

	// EtcHosts is used to update [SourceHostsFile] runtime client information.
	EtcHosts HostsContainer

	// ARPDB is used to update [SourceARP] runtime client information.
	ARPDB arpdb.Interface

	// InitialClients is a list of persistent clients parsed from the
	// configuration file.  Each client must not be nil.
	InitialClients []*Persistent

	// ARPClientsUpdatePeriod defines how often [SourceARP] runtime client
	// information is updated.
	ARPClientsUpdatePeriod time.Duration

	// RuntimeSourceDHCP specifies whether to update [SourceDHCP] information
	// of runtime clients.
	RuntimeSourceDHCP bool
}

StorageConfig is the client storage configuration structure.

type UID added in v0.107.46 

type UID uuid.UUID

UID is the type for the unique IDs of persistent clients.

func MustNewUID added in v0.107.46 

func MustNewUID() (uid UID)

MustNewUID is a wrapper around NewUID that panics if there is an error.

func NewUID added in v0.107.46 

func NewUID() (uid UID, err error)

NewUID returns a new persistent client UID. Any error returned is an error from the cryptographic randomness reader.

func (UID) MarshalText added in v0.107.46 

func (uid UID) MarshalText() ([]byte, error)

MarshalText implements the encoding.TextMarshaler for UID.

func (*UID) UnmarshalText added in v0.107.46 

func (uid *UID) UnmarshalText(data []byte) error

UnmarshalText implements the encoding.TextUnmarshaler interface for UID.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.