client

package
v0.107.53 Latest Latest
Warning

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

 Go to latest Published: Oct 3, 2024 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 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): It's an exact copy of the [dnsforward.ValidateClientID] to avoid the import cycle. Remove it.

Types

type AddressProcessor 

type AddressProcessor interface {
	Process(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(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 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(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(_ 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 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 {
	// UpstreamConfig is the custom upstream configuration for this client.  If
	// it's nil, it has not been initialized yet.  If it's non-nil and empty,
	// there are no valid upstreams.  If it's non-nil and non-empty, these
	// upstream must be used.
	UpstreamConfig *proxy.CustomUpstreamConfig

	// 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.
	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 []string

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

	// UpstreamsCacheSize is the cache size for custom upstreams.
	UpstreamsCacheSize uint32

	// UpstreamsCacheEnabled specifies whether custom upstreams are used.
	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) CloseUpstreams added in v0.107.46 

func (c *Persistent) CloseUpstreams() (err error)

CloseUpstreams closes the client-specific upstream config of c if any.

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) IDs added in v0.107.46 

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

IDs returns a list of client IDs containing at least one element.

func (*Persistent) IDsLen added in v0.107.46 

func (c *Persistent) IDsLen() (n int)

IDsLen returns a length of client ids.

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) SetSafeSearch added in v0.107.46 

func (c *Persistent) SetSafeSearch(
	conf filtering.SafeSearchConfig,
	cacheSize uint,
	cacheTTL time.Duration,
) (err error)

SetSafeSearch initializes and sets the safe search filter for this client.

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(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(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) 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) Find added in v0.107.52 

func (s *Storage) Find(id string) (p *Persistent, ok bool)

Find finds persistent client by string representation of the client ID, IP address, or MAC. And returns its shallow copy.

TODO(s.chzhen): Accept ClientIDData structure instead, which will contain the parsed IP address, if any.

func (*Storage) FindByMAC added in v0.107.52 

func (s *Storage) FindByMAC(mac net.HardwareAddr) (p *Persistent, ok bool)

FindByMAC finds persistent client by MAC and returns its shallow copy. s.mu is expected to be locked.

func (*Storage) FindByName added in v0.107.52 

func (s *Storage) FindByName(name string) (p *Persistent, ok bool)

FindByName finds persistent client by name. And returns its shallow copy.

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.

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()

ReloadARP reloads runtime clients from ARP, if configured.

func (*Storage) RemoveByName added in v0.107.52 

func (s *Storage) RemoveByName(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(_ 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(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(ip netip.Addr, host string, info *whois.Info)

UpdateAddress implements the AddressUpdater interface for *Storage

func (*Storage) UpdateDHCP added in v0.107.53 

func (s *Storage) UpdateDHCP()

UpdateDHCP updates SourceDHCP runtime client information.

type StorageConfig added in v0.107.53 

type StorageConfig struct {
	// 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.