Skip to content

dns

ibox.dns in the library, ibox dns in the CLI.

DNS resolver status, settings, and cache.

status

status() -> str

Get DNS status

mode

mode() -> str

Get the DNS mode: "Custom" when the router asks the servers set in the web UI or with set_upstream_servers(), "All" when it asks the internet provider's.

settings

settings() -> str

Get the DNS servers the router itself asks: the provider's ("dataV4_1", ...) and those set in the web UI or with set_upstream_servers() ("webuidns1" and "webuidns2"). mode() says which ones it uses.

set_upstream_servers

set_upstream_servers(servers: list[str]) -> str

Set the DNS servers the router itself asks, like the DNS server settings in the web UI's network settings.

Devices ask the router, which asks these servers (unless set_device_servers() gives devices other servers). If they don't answer, devices on the home network can't look up names, so the internet seems down.

Parameters:

Name Type Description Default
servers list[str]

up to 2 IPv4 addresses, e.g. ["1.1.1.1", "9.9.9.9"]. A private address must be in your network, e.g. a Pi-hole. An empty list goes back to the internet provider's servers (the default).

required

Returns:

Name Type Description
str str

response content

Raises:

Type Description
ValueError

if the web UI would refuse a server.

metrics

metrics() -> str

Count the DNS queries the router answered: from its cache or itself ("dns_local_answered"), or by passing them on ("dns_queries_forwarded"), with the queries sent to each DNS server and how many failed.

user

user() -> str

Get the DNS servers the router gives devices on the local network (IPv4). Empty: the router itself.

set_device_servers

set_device_servers(servers: list[str]) -> str

Set the DNS servers the router gives devices on the local network, like the DNS fields in the web UI's DHCP settings.

Devices ask these servers instead of the router once they renew their address, e.g. when they reconnect.

Parameters:

Name Type Description Default
servers list[str]

up to 2 IPv4 addresses, e.g. ["1.1.1.1", "9.9.9.9"]. An empty list gives devices the router again (the default).

required

Returns:

Name Type Description
str str

response content

user_ipv6

user_ipv6() -> str

Get the IPv6 DNS servers the router gives devices on the local network. Empty: the router itself.

set_device_servers_ipv6

set_device_servers_ipv6(servers: list[str]) -> str

Set the IPv6 DNS servers the router gives devices on the local network, like the DNS fields in the web UI's IPv6 settings.

Parameters:

Name Type Description Default
servers list[str]

up to 2 IPv6 addresses, e.g. ["2606:4700:4700::1111"]. An empty list gives devices the router again (the default).

required

Returns:

Name Type Description
str str

response content

cache

cache() -> str

Get whether the router's DNS cache is on ("Enable") and how many answers it keeps ("MaxEntries").

set_cache_enabled

set_cache_enabled(enable: bool) -> str

Turn the router's DNS cache on or off, like the DNS cache switch in the web UI.

With the cache on, the router keeps answers for a while and gives them to devices straight away. Like the web UI, this also empties the cache.

Parameters:

Name Type Description Default
enable bool

True to turn the cache on, False to turn it off.

required

Returns:

Name Type Description
str str

response content

flush_cache

flush_cache() -> str

Empty the router's DNS cache, so names are looked up again. Only matters while the cache is on (see cache()).