Skip to main content

DNS

The DNS resolvers of each interface of the host. osapi behavior get --name dns and osapi behavior method get show the same. Its chain shows each call that its examples make.

Behavior​

Namedns
DescriptionThe DNS resolvers of each interface of the host
Placementnode
Groupnetwork
Internalno
APIyes
CLIyes
Nextno
Platformsdebian, linux, darwin
Sudonone
Runsnone
Writes/etc/netplan/osapi-dns-*.yaml
Keeps stateno
Usesnetplan
Used bynone

Methods (3)​

NAMEVERBHTTPROUTEPERMISSIONDESCRIPTION
getreadGET/api/node/{hostname}/network/dns/{interface_name}network:readGet the DNS resolvers of an interface
updatewritePUT/api/node/{hostname}/network/dns/{interface_name}network:writeSet the DNS resolvers of an interface
deletewriteDELETE/api/node/{hostname}/network/dns/{interface_name}network:writeDrop the DNS resolvers osapi set on an interface

Types (3)​

NAMEINPUTOUTPUT
getGetInput { interface_name* }Entry { servers, search_domains }
updateUpdateInput { interface_name*, servers, search_domains, override_dhcp }Result { interface_name, changed }
deleteDeleteInput { interface_name* }Result { interface_name, changed }

Settings (0)​

None. Declare them with behavior.Config.

Telemetry​

Spanbehavior.dns.<method>
Child spansbehavior.netplan.<method>, behavior.managedfile.<method>, exec resolvectl, exec ip, exec scutil, exec ethtool, exec netplan, exec chown, exec stat, file.write, file.remove, file.chmod, kv.get, kv.put
Metricsosapi_behavior_calls_total, osapi_behavior_duration_seconds, osapi_behavior_changes_total
Attributesosapi.behavior.name, osapi.behavior.method, osapi.behavior.verb, osapi.behavior.outcome, osapi.behavior.changed
Recorded inputsinterface_name (get, update, delete)

Method get​

Nameget
Verbread
DescriptionGet the DNS resolvers of an interface
DetailReads the servers and the search domains of the interface: resolvectl on Linux, with resolv.conf on a host that has no resolvers per interface, such as a container, and scutil on macOS.
HTTPGET
Route/api/node/{hostname}/network/dns/{interface_name}
Permissionnetwork:read
Commandosapi client node network dns get
Input typeGetInput
Output typeEntry

Input (1)​

FIELDTYPEREQUIREDCONSTRAINTSDESCRIPTION
interface_namestringyespattern ^(@fact.[a-z0-9_.]+|[a-zA-Z0-9][a-zA-Z0-9._-]{0,14})$The interface, such as eth0, or a fact such as @fact.interface.primary

Output (2)​

FIELDTYPEDESCRIPTION
serversarrayThe DNS servers
search_domainsarrayThe search domains

Examples (3)​

EXAMPLEINPUTOUTPUT
An interface with servers and a domaininterface_name=eth0servers=[1.1.1.1 8.8.8.8], search_domains=[example.com]
A container with no resolvers per interfaceinterface_name=eth0servers=[10.0.0.2], search_domains=[svc.local]
A Macinterface_name=en0servers=[1.1.1.1], search_domains=[]

Method update​

Nameupdate
Verbwrite
DescriptionSet the DNS resolvers of an interface
DetailWrites a netplan file of the interface's own, such as /etc/netplan/osapi-dns-eth0.yaml for eth0, under the netplan definition that matches the interface, and applies it. A definition that matches several interfaces, such as cloud-init's all for en*, gives each of them the resolvers. An empty list keeps the interface's servers or domains, and an interface with no resolvers yet starts from none. override_dhcp drops the servers DHCP gives. It runs on the Debian family, and elsewhere, and in a container, reports skipped.
HTTPPUT
Route/api/node/{hostname}/network/dns/{interface_name}
Permissionnetwork:write
Commandosapi client node network dns update
Input typeUpdateInput
Output typeResult

Input (4)​

FIELDTYPEREQUIREDCONSTRAINTSDESCRIPTION
interface_namestringyespattern ^(@fact.[a-z0-9_.]+|[a-zA-Z0-9][a-zA-Z0-9._-]{0,14})$The interface, such as eth0, or a fact such as @fact.interface.primary
serversarraynoThe DNS servers, IPv4 or IPv6; the interface's own when empty
search_domainsarraynoThe search domains; the interface's own when empty
override_dhcpbooleannoUse only these servers: drop the ones DHCP gives

Output (2)​

FIELDTYPEDESCRIPTION
interface_namestringThe interface
changedbooleanWhether the host changed

Examples (3)​

EXAMPLEINPUTOUTPUT
Set the servers of an interfaceinterface_name=eth0, servers=[9.9.9.9]interface_name=eth0, changed=true
Set the search domains, and keep the serversinterface_name=eth0, search_domains=[corp.example], override_dhcp=trueinterface_name=eth0, changed=true
An interface with no resolvers yetinterface_name=eth0, servers=[9.9.9.9]interface_name=eth0, changed=true

Method delete​

Namedelete
Verbwrite
DescriptionDrop the DNS resolvers osapi set on an interface
DetailRemoves the interface's netplan file and applies what is left. An interface osapi set nothing on does not change.
HTTPDELETE
Route/api/node/{hostname}/network/dns/{interface_name}
Permissionnetwork:write
Commandosapi client node network dns delete
Input typeDeleteInput
Output typeResult

Input (1)​

FIELDTYPEREQUIREDCONSTRAINTSDESCRIPTION
interface_namestringyespattern ^(@fact.[a-z0-9_.]+|[a-zA-Z0-9][a-zA-Z0-9._-]{0,14})$The interface, such as eth0, or a fact such as @fact.interface.primary

Output (2)​

FIELDTYPEDESCRIPTION
interface_namestringThe interface
changedbooleanWhether the host changed

Examples (2)​

EXAMPLEINPUTOUTPUT
An interface osapi setinterface_name=eth0interface_name=eth0, changed=true
An interface osapi set nothing oninterface_name=eth0interface_name=eth0, changed=false