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
| Name | dns |
| Description | The DNS resolvers of each interface of the host |
| Placement | node |
| Group | network |
| Internal | no |
| API | yes |
| CLI | yes |
| Next | no |
| Platforms | debian, linux, darwin |
| Sudo | none |
| Runs | none |
| Writes | /etc/netplan/osapi-dns-*.yaml |
| Keeps state | no |
| Uses | netplan |
| Used by | none |
Methods (3)
| NAME | VERB | HTTP | ROUTE | PERMISSION | DESCRIPTION |
|---|---|---|---|---|---|
| get | read | GET | /api/node/{hostname}/network/dns/{interface_name} | network:read | Get the DNS resolvers of an interface |
| update | write | PUT | /api/node/{hostname}/network/dns/{interface_name} | network:write | Set the DNS resolvers of an interface |
| delete | write | DELETE | /api/node/{hostname}/network/dns/{interface_name} | network:write | Drop the DNS resolvers osapi set on an interface |
Types (3)
| NAME | INPUT | OUTPUT |
|---|---|---|
| get | GetInput { interface_name* } | Entry { servers, search_domains } |
| update | UpdateInput { interface_name*, servers, search_domains, override_dhcp } | Result { interface_name, changed } |
| delete | DeleteInput { interface_name* } | Result { interface_name, changed } |
Settings (0)
None. Declare them with behavior.Config.
Telemetry
| Span | behavior.dns.<method> |
| Child spans | behavior.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 |
| Metrics | osapi_behavior_calls_total, osapi_behavior_duration_seconds, osapi_behavior_changes_total |
| Attributes | osapi.behavior.name, osapi.behavior.method, osapi.behavior.verb, osapi.behavior.outcome, osapi.behavior.changed |
| Recorded inputs | interface_name (get, update, delete) |
Method get
| Name | get |
| Verb | read |
| Description | Get the DNS resolvers of an interface |
| Detail | Reads 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. |
| HTTP | GET |
| Route | /api/node/{hostname}/network/dns/{interface_name} |
| Permission | network:read |
| Command | osapi client node network dns get |
| Input type | GetInput |
| Output type | Entry |
Input (1)
| FIELD | TYPE | REQUIRED | CONSTRAINTS | DESCRIPTION |
|---|---|---|---|---|
| interface_name | string | yes | pattern ^(@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)
| FIELD | TYPE | DESCRIPTION |
|---|---|---|
| servers | array | The DNS servers |
| search_domains | array | The search domains |
Examples (3)
| EXAMPLE | INPUT | OUTPUT |
|---|---|---|
| An interface with servers and a domain | interface_name=eth0 | servers=[1.1.1.1 8.8.8.8], search_domains=[example.com] |
| A container with no resolvers per interface | interface_name=eth0 | servers=[10.0.0.2], search_domains=[svc.local] |
| A Mac | interface_name=en0 | servers=[1.1.1.1], search_domains=[] |
Method update
| Name | update |
| Verb | write |
| Description | Set the DNS resolvers of an interface |
| Detail | Writes 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. |
| HTTP | PUT |
| Route | /api/node/{hostname}/network/dns/{interface_name} |
| Permission | network:write |
| Command | osapi client node network dns update |
| Input type | UpdateInput |
| Output type | Result |
Input (4)
| FIELD | TYPE | REQUIRED | CONSTRAINTS | DESCRIPTION |
|---|---|---|---|---|
| interface_name | string | yes | pattern ^(@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 |
| servers | array | no | The DNS servers, IPv4 or IPv6; the interface's own when empty | |
| search_domains | array | no | The search domains; the interface's own when empty | |
| override_dhcp | boolean | no | Use only these servers: drop the ones DHCP gives |
Output (2)
| FIELD | TYPE | DESCRIPTION |
|---|---|---|
| interface_name | string | The interface |
| changed | boolean | Whether the host changed |
Examples (3)
| EXAMPLE | INPUT | OUTPUT |
|---|---|---|
| Set the servers of an interface | interface_name=eth0, servers=[9.9.9.9] | interface_name=eth0, changed=true |
| Set the search domains, and keep the servers | interface_name=eth0, search_domains=[corp.example], override_dhcp=true | interface_name=eth0, changed=true |
| An interface with no resolvers yet | interface_name=eth0, servers=[9.9.9.9] | interface_name=eth0, changed=true |
Method delete
| Name | delete |
| Verb | write |
| Description | Drop the DNS resolvers osapi set on an interface |
| Detail | Removes the interface's netplan file and applies what is left. An interface osapi set nothing on does not change. |
| HTTP | DELETE |
| Route | /api/node/{hostname}/network/dns/{interface_name} |
| Permission | network:write |
| Command | osapi client node network dns delete |
| Input type | DeleteInput |
| Output type | Result |
Input (1)
| FIELD | TYPE | REQUIRED | CONSTRAINTS | DESCRIPTION |
|---|---|---|---|---|
| interface_name | string | yes | pattern ^(@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)
| FIELD | TYPE | DESCRIPTION |
|---|---|---|
| interface_name | string | The interface |
| changed | boolean | Whether the host changed |
Examples (2)
| EXAMPLE | INPUT | OUTPUT |
|---|---|---|
| An interface osapi set | interface_name=eth0 | interface_name=eth0, changed=true |
| An interface osapi set nothing on | interface_name=eth0 | interface_name=eth0, changed=false |