resolvconf

Documentation

Overview

Package resolvconf is used to generate a container's /etc/resolv.conf file.

Constructor Load and Parse read a resolv.conf file from the filesystem or a reader respectively, and return a ResolvConf object.

The ResolvConf object can then be updated with overrides for nameserver, search domains, and DNS options.

ResolvConf can then be transformed to make it suitable for legacy networking, a network with an internal nameserver, or used as-is for host networking.

This package includes methods to write the file for the container, along with a hash that can be used to detect modifications made by the user to avoid overwriting those updates.

Index

• func Path() string
• func UserModified(rcPath, rcHashPath string) (bool, error)
• type ExtDNSEntry
  • func (ed ExtDNSEntry) String() string
• type ResolvConf
  • func Load(path string) (ResolvConf, error)
  • func Parse(reader io.Reader, path string) (ResolvConf, error)
  • func (rc *ResolvConf) AddOption(option string)
  • func (rc *ResolvConf) Generate(comments bool) ([]byte, error)
  • func (rc *ResolvConf) NameServers() []netip.Addr
  • func (rc *ResolvConf) Option(search string) (string, bool)
  • func (rc *ResolvConf) Options() []string
  • func (rc *ResolvConf) OverrideNameServers(nameServers []netip.Addr)
  • func (rc *ResolvConf) OverrideOptions(options []string)
  • func (rc *ResolvConf) OverrideSearch(search []string)
  • func (rc *ResolvConf) Search() []string
  • func (rc *ResolvConf) SetHeader(c string)
  • func (rc *ResolvConf) TransformForIntNS(keepIPv6 bool, internalNS netip.Addr, reqdOptions []string) ([]ExtDNSEntry, error)
  • func (rc *ResolvConf) TransformForLegacyNw(ipv6 bool)
  • func (rc *ResolvConf) WriteFile(path, hashPath string, perm os.FileMode) error

Functions

func Path

func Path() string

Path returns the path to the resolv.conf file that libnetwork should use.

When /etc/resolv.conf contains 127.0.0.53 as the only nameserver, then it is assumed systemd-resolved manages DNS. Because inside the container 127.0.0.53 is not a valid DNS server, Path() returns /run/systemd/resolve/resolv.conf which is the resolv.conf that systemd-resolved generates and manages. Otherwise Path() returns /etc/resolv.conf.

Errors are silenced as they will inevitably resurface at future open/read calls.

More information at https://www.freedesktop.org/software/systemd/man/systemd-resolved.service.html#/etc/resolv.conf

TODO(robmry) - alternatePath is only needed for legacy networking ...

Host networking can use the host's resolv.conf as-is, and with an internal
resolver it's also possible to use nameservers on the host's loopback
interface. Once legacy networking is removed, this can always return
defaultPath.

func UserModified

func UserModified(rcPath, rcHashPath string) (bool, error)

UserModified can be used to determine whether the resolv.conf file has been modified since it was generated. It returns false with no error if the file matches the hash, true with no error if the file no longer matches the hash, and false with an error if the result cannot be determined.

Types

type ExtDNSEntry

type ExtDNSEntry struct {
	Addr         netip.Addr
	HostLoopback bool // The address is loopback, in the host's namespace.
}

ExtDNSEntry represents a nameserver address that was removed from the container's resolv.conf when it was transformed by TransformForIntNS(). These are addresses read from the host's file, or applied via an override ('--dns').

func (ExtDNSEntry) String

func (ed ExtDNSEntry) String() string

type ResolvConf

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

ResolvConf represents a resolv.conf file. It can be constructed by reading a resolv.conf file, using method Parse().

func Load

func Load(path string) (ResolvConf, error)

Load opens a file at path and parses it as a resolv.conf file. On error, the returned ResolvConf will be zero-valued.

func Parse

func Parse(reader io.Reader, path string) (ResolvConf, error)

Parse parses a resolv.conf file from reader. path is optional if reader is an *os.File. On error, the returned ResolvConf will be zero-valued.

func (*ResolvConf) AddOption

func (rc *ResolvConf) AddOption(option string)

AddOption adds a single DNS option.

func (*ResolvConf) Generate

func (rc *ResolvConf) Generate(comments bool) ([]byte, error)

Generate returns content suitable for writing to a resolv.conf file. If comments is true, the file will include header information if supplied, and a trailing comment that describes how the file was constructed and lists external resolvers.

func (*ResolvConf) NameServers

func (rc *ResolvConf) NameServers() []netip.Addr

NameServers returns addresses used in nameserver directives.

func (*ResolvConf) Option

func (rc *ResolvConf) Option(search string) (string, bool)

Option finds the last option named search, and returns (value, true) if found, else ("", false). Options are treated as "name:value", where the ":value" may be omitted.

For example, for "ndots:1 edns0":

Option("ndots") -> ("1", true)
Option("edns0") -> ("", true)

func (*ResolvConf) Options

func (rc *ResolvConf) Options() []string

Options returns the current options.

func (*ResolvConf) OverrideNameServers

func (rc *ResolvConf) OverrideNameServers(nameServers []netip.Addr)

OverrideNameServers replaces the current set of nameservers.

func (*ResolvConf) OverrideOptions

func (rc *ResolvConf) OverrideOptions(options []string)

OverrideOptions replaces the current DNS options.

func (*ResolvConf) OverrideSearch

func (rc *ResolvConf) OverrideSearch(search []string)

OverrideSearch replaces the current DNS search domains.

func (*ResolvConf) Search

func (rc *ResolvConf) Search() []string

Search returns the current DNS search domains.

func (*ResolvConf) SetHeader

func (rc *ResolvConf) SetHeader(c string)

SetHeader sets the content to be included verbatim at the top of the generated resolv.conf file. No formatting or checking is done on the string. It must be valid resolv.conf syntax. (Comments must have '#' or ';' in the first column of each line).

For example:

SetHeader("# My resolv.conf\n# This file was generated.")

func (*ResolvConf) TransformForIntNS

func (rc *ResolvConf) TransformForIntNS(
	keepIPv6 bool,
	internalNS netip.Addr,
	reqdOptions []string,
) ([]ExtDNSEntry, error)

TransformForIntNS makes sure the resolv.conf file will be suitable for use in a network sandbox that has an internal DNS resolver.

• Add internalNS as a nameserver.
• Remove other nameservers, stashing them as ExtNameServers for the internal resolver to use. (Apart from IPv6 nameservers, if keepIPv6.)
• Mark ExtNameServers that must be used in the host namespace.
• If no ExtNameServer addresses are found, use the defaults.
• Return an error if an "ndots" option inherited from the host's config, or supplied in an override is not valid.
• Ensure there's an 'options' value for each entry in reqdOptions. If the option includes a ':', and an option with a matching prefix exists, it is not modified.

func (*ResolvConf) TransformForLegacyNw

func (rc *ResolvConf) TransformForLegacyNw(ipv6 bool)

TransformForLegacyNw makes sure the resolv.conf file will be suitable for use in a legacy network (one that has no internal resolver).

• Remove loopback addresses inherited from the host's resolv.conf, because they'll only work in the host's namespace.
• Remove IPv6 addresses if !ipv6.
• Add default nameservers if there are no addresses left.

func (*ResolvConf) WriteFile

func (rc *ResolvConf) WriteFile(path, hashPath string, perm os.FileMode) error

WriteFile generates content and writes it to path. If hashPath is non-zero, it also writes a file containing a hash of the content, to enable UserModified() to determine whether the file has been modified.