dns

The dns family changes resolver configuration on the operator machine only. It sends nothing to the Gateway and changes no Route, Route scope, or private DNS record. Use it when a Mac must reach Route domains at a chosen address instead of through Orbit VPN DNS. Private DNS describes resolver selection on managed Nodes and the Router addresses that Orbit VPN DNS returns.

Commands

Command	Result
`dns:resolve`	Set or remove a local resolver override for one TLD or one Route name.

orbit dns:resolve

Send every name under a development TLD, or one Route name, to an IP address. --reset removes the override.

orbit dns:resolve <name> [target] [--reset] [--json]

Argument	Required	Meaning
`name`	yes	One lowercase DNS label, such as `test`, for a TLD override. A lowercase name with several labels, such as `shop.app.beast`, for a Route name override. No leading dot.
`target`	to set	The IPv4 or IPv6 address that the name resolves to. Not accepted with `--reset`.

Option	Meaning
`--reset`	Remove the local override for the name.
`--json`	Return one JSON object.

orbit dns:resolve beast 192.168.6.20
orbit dns:resolve shop.app.beast 192.168.1.40
orbit dns:resolve shop.app.beast --reset
orbit dns:resolve beast --reset

The command runs only on macOS with Homebrew dnsmasq installed. It writes address=/<name>/<target> to ~/.config/orbit/dnsmasq.d/<name>.conf and includes that directory from the Homebrew dnsmasq.conf. It installs /etc/resolver/<name> with nameserver 127.0.0.1 and restarts the Homebrew dnsmasq service. Then it checks that a lookup under the name returns the target, and flushes the macOS resolver cache. Writing the resolver file and restarting the service use sudo, so the command can ask for your administrator password. An override covers the name and every name under it. When a TLD override and a Route name override both exist, the Route name override answers its name, and the TLD override answers the other names under the TLD. Resetting one override leaves the other in place. Point a Route name at the Cluster Router address to keep the Router path for that Route. Point it at the workload Node’s address to reach the Route there directly. Repeating an identical set or reset changes nothing. A failure never overwrites unrelated resolver configuration.

Kind	Identity field	Other fields
TLD	`tld`	`target`, `status`, `changed`, `restart_browser`
Route name	`hostname`	`target`, `status`, `changed`, `restart_browser`

status is resolved, already_resolved, reset, or already_absent. restart_browser is true when the command changed the mapping.

Restart open browsers after a change. A browser reuses an open connection and keeps sending traffic to the old address until it reconnects.

Error code	Meaning
`dns.tld_required`	No name was given.
`dns.tld_invalid`	The TLD is not one lowercase DNS label.
`dns.hostname_invalid`	The Route name is not a lowercase DNS name with several labels.
`dns.target_invalid`	The target is not an IP address, or a target was given with `--reset`.
`dns.unsupported_platform`	The operator machine is not macOS. Nothing changes.
`dns.dnsmasq_missing`	Homebrew `dnsmasq` is not installed. Only a set checks this, and nothing changes. A `--reset` without `dnsmasq` removes the files and then fails with `dns.refresh_failed`.
`dns.write_failed`	The configuration or resolver file could not be written.
`dns.refresh_failed`	The files changed, but `dnsmasq` could not be restarted or does not answer with the target.

node sets a Node TLD with node:add --tld. Generated Route domains use it when no active Cluster TLD applies.
route lists the Route domains.

Using the CLI

Fleet

Applications

Operations

Commands

orbit dns:resolve

​Commands

​orbit dns:resolve

​Related

Commands

orbit dns:resolve

Related