Module resty.dns.utils

DNS utility module.

Parses the /etc/hosts and /etc/resolv.conf configuration files, caches them, and provides some utility functions.

NOTE: parsing the files is done using blocking i/o file operations.

Info:

  • Copyright: 2016-2020 Kong Inc.
  • License: Apache 2.0
  • Author: Thijs Schreijer

Fields

DEFAULT_HOSTS Default filename to parse for the hosts file.
DEFAULT_RESOLV_CONF Default filename to parse for the resolv.conf file.
MAXNS Maximum number of nameservers to parse from the resolv.conf file
MAXSEARCH Maximum number of entries to parse from search parameter in the resolv.conf file

Parsing configuration files and variables

applyEnv (config) Will parse LOCALDOMAIN and RES_OPTIONS environment variables.
parseHosts (filename) Parses a hosts file or table.
parseResolvConf (filename) Parses a resolv.conf file or table.

Caching configuration files and variables

getHosts (ttl) returns the parseHosts results, but cached.
getResolv (ttl) returns the applyEnv results, but cached.

Miscellaneous

hostnameType (name) checks the hostname type; ipv4, ipv6, or name.
parseHostname (name) parses a hostname with an optional port.


Fields

DEFAULT_HOSTS
Default filename to parse for the hosts file.
  • DEFAULT_HOSTS Defaults to /etc/hosts
DEFAULT_RESOLV_CONF
Default filename to parse for the resolv.conf file.
  • DEFAULT_RESOLV_CONF Defaults to /etc/resolv.conf
MAXNS
Maximum number of nameservers to parse from the resolv.conf file
  • MAXNS Defaults to 3
MAXSEARCH
Maximum number of entries to parse from search parameter in the resolv.conf file
  • MAXSEARCH Defaults to 6

Parsing configuration files and variables

applyEnv (config)
Will parse LOCALDOMAIN and RES_OPTIONS environment variables. It will insert them into the given resolv.conf based configuration table.

NOTE: if the input is nil+error it will return the input, to allow for pass-through error handling

Parameters:

  • config Options table, as parsed by parseResolvConf, or an empty table to get only the environment options

Returns:

    modified table

See also:

Usage:

    -- errors are passed through, so this;
local config, err = utils.parseResolvConf()
if config then
  config, err = utils.applyEnv(config)
end

-- Is identical to;
local config, err = utils.applyEnv(utils.parseResolvConf())
parseHosts (filename)
Parses a hosts file or table. Does not check for correctness of ip addresses nor hostnames. Might return nil + error if the file cannot be read.

NOTE: All output will be normalized to lowercase, IPv6 addresses will always be returned in brackets.

Parameters:

  • filename (optional) Filename to parse, or a table with the file contents in lines (defaults to '/etc/hosts' if omitted)

Returns:

  1. 1; reverse lookup table, ip addresses (table with ipv4 and ipv6 fields) indexed by their canonical names and aliases
  2. 2; list with all entries. Containing fields ip, canonical and family, and a list of aliasses

Usage:

    local lookup, list = utils.parseHosts({
  "127.0.0.1   localhost",
  "1.2.3.4     someserver",
  "192.168.1.2 test.computer.com",
  "192.168.1.3 ftp.COMPUTER.com alias1 alias2",
})

print(lookup["localhost"])         --> "127.0.0.1"
print(lookup["ftp.computer.com"])  --> "192.168.1.3" note: name in lowercase!
print(lookup["alias1"])            --> "192.168.1.3"
parseResolvConf (filename)
Parses a resolv.conf file or table. Does not check for correctness of ip addresses nor hostnames, bad options will be ignored. Might return nil + error if the file cannot be read.

Parameters:

  • filename (optional) File to parse (defaults to '/etc/resolv.conf' if omitted) or a table with the file contents in lines.

Returns:

    a table with fields nameserver (table), domain (string), search (table), sortlist (table) and options (table)

See also:

Caching configuration files and variables

getHosts (ttl)
returns the parseHosts results, but cached. Once ttl has been provided, only after it expires the file will be parsed again.

NOTE: if cached, the SAME tables will be returned, so do not modify them unless you know what you are doing!

Parameters:

  • ttl cache time-to-live in seconds (can be updated in following calls)

Returns:

    reverse and list tables, same as parseHosts.

See also:

getResolv (ttl)
returns the applyEnv results, but cached. Once ttl has been provided, only after it expires it will be parsed again.

NOTE: if cached, the SAME table will be returned, so do not modify them unless you know what you are doing!

Parameters:

  • ttl cache time-to-live in seconds (can be updated in following calls)

Returns:

    configuration table, same as parseResolveConf.

See also:

Miscellaneous

hostnameType (name)
checks the hostname type; ipv4, ipv6, or name. Type is determined by exclusion, not by validation. So if it returns 'ipv6' then it can only be an ipv6, but it is not necessarily a valid ipv6 address.

Parameters:

  • name the string to check (this may contain a port number)

Returns:

    string either; 'ipv4', 'ipv6', or 'name'

Usage:

    hostnameType("123.123.123.123")  -->  "ipv4"
hostnameType("127.0.0.1:8080")   -->  "ipv4"
hostnameType("::1")              -->  "ipv6"
hostnameType("[::1]:8000")       -->  "ipv6"
hostnameType("some::thing")      -->  "ipv6", but invalid...
parseHostname (name)
parses a hostname with an optional port. Does not validate the name/ip. IPv6 addresses are always returned in square brackets, even if the input wasn't.

Parameters:

  • name the string to check (this may contain a port number)

Returns:

    name/ip + port (or nil) + type (one of: "ipv4", "ipv6", or "name")
generated by LDoc 1.4.6 Last updated 2021-07-06 11:55:24