Companions#

Services → Companions: the services the router runs besides routing — DNS forwarding, the DHCP server and UPnP. For each one the page shows what the service is set to do and what it is doing, and it can turn a service off or on and restart it. Each service's settings are edited on its own page.

The page refreshes every 15 seconds and after changes are applied. If the router cannot be read, the page shows "Could not read from the router" with the reason and a Retry button. It does not report the services as not configured.

The panels#

Offers from installed apps appear at the top of the page. Below them is one panel per service, in the order DNS forwarding, DHCP server, UPnP.

The badge beside a panel's title is the service's setting:

Badge	Means
on	The service is configured and turned on.
off	The service is configured and turned off.
not configured	The service has no configuration.
not available	This router does not have the service. The panel says so, and has no other badge and no controls.

The badge at the right of the title is what the service is doing. Hover over it for the reason.

Badge	Means	Hover shows
running	The service's process is running.	The process.
not running	No process for the service is running.	The process names that were looked for.
unknown	The router's process list could not be read. It does not mean the service has stopped.	Why the list could not be read.

When the two disagree, the panel shows a drift badge and one of two sentences:

"Turned on, but not running." The service is configured and on, but its process is not running. The not running badge turns red.
"Running, but not configured." The process is running, but the service has no configuration.

Settings#

Under the badges, the panel lists the service's main settings, one row each:

Service	Rows, where set
DNS forwarding	Upstream servers, Allowed networks, Listen addresses, Cache size, DNSSEC, Local domains, Forwarded domains, Uses the router’s DNS servers
DHCP server	Networks, each with its subnets; Reservations, the number of reservations across all networks; Names from leases
UPnP	WAN interface, LAN interface, Client subnets, Mode

Other settings appear under their own names. A list shows its values. A setting that is either present or absent, such as Uses the router’s DNS servers, reads "On". A setting with named entries lists their names, or how many there are when there are more than four.

Below the administrator role, secret values read "Hidden", and the panel says "Some values are hidden for your role."
A configured service with no settings of its own reads "Configured with default settings." A service with no configuration reads, for example, "DNS forwarding is not configured."
In Advanced mode, the panel also shows the service's configuration as the router holds it, under Configuration.

Controls#

Under the settings are the panel's controls:

Turn off, or Turn on for a service that is off. Only the one that changes the service's state is shown, and neither is shown for a service with no configuration.
Restart, for a configured service.
Edit settings →, or Set up DNS forwarding → (with the service's name) for a service with no configuration. It opens the service's own page: DNS, DHCP or UPnP.

Turning a service off or on and restarting it need the operator role and a licence. A button that cannot be used is shown disabled; hover over it for the reason, such as "Your role is read-only" or "DHCP server cannot be turned off on this router."

Turning a service off or on#

On the service's panel, press Turn off, or Turn on for a service that is off. The page confirms, for example, "Turning off DNS forwarding saved" and "It takes effect when you apply pending changes."
Press Apply changes in the bar at the bottom of the page.

Turning a service off keeps its settings, and turning it back on uses them again.

Restarting a service#

Press Restart. The service restarts at once. Its settings do not change, and nothing is added to the pending changes. The page confirms "DNS forwarding restarted" and "DNS forwarding was restarted. Its settings did not change."

A service that is turned off is not restarted. The page says, for example, "DNS forwarding is turned off. Turn it on instead of restarting it."
If the restart fails, the page says "Could not restart DNS forwarding" and gives the router's reason.
If the router cannot restart the service directly, nothing is changed, and the panel says: "This router cannot restart DNS forwarding directly. To restart it, turn it off and apply the change, then turn it on and apply again."

UPnP#

UPnP is part of Wheelhouse: Wheelhouse itself answers UPnP and NAT-PMP requests from devices on the network. Its panel shows the UPnP settings, not the router's configuration.

It reads not configured until UPnP has been turned on, or a WAN interface, LAN interface or client subnet has been saved. It then reads on or off.
It reads running while any of its listeners is open: discovery, port mapping over UPnP, or port mapping over NAT-PMP. The hover lists the addresses it is listening on. When UPnP is turned off, or a listener could not open, the hover says so.
Once UPnP is configured, its Turn on or Turn off button and Restart are shown disabled. Their hovers say "UPnP is turned on and off on the UPnP page." and "UPnP is part of Wheelhouse and has nothing to restart."

Setting up UPnP#

UPnP is set up on the UPnP page, which Set up UPnP → and Edit settings → open. The page is listed under Services once UPnP / NAT-PMP has been installed from the Apps catalogue, or while UPnP is on. UPnP describes the page: turning UPnP on, its limits, and approving, removing and forgetting mappings.

Offers from installed apps#

An installed app that is not stopped can add an offer to the top of this page. dnsmasq, from the app catalogue, adds "Wildcard DNS, per-device DHCP options and PXE", which says what dnsmasq provides that the router's own services do not. It has no button. An offer that includes a change has Add this change, which adds the change to the pending changes, and Show what this changes, which lists it. See integration offers.

What the router's own services do not do#

Wildcard and split-horizon DNS. DNS forwarding cannot hold wildcard names.
DHCP options for individual devices. The DHCP server cannot give one device options of its own, such as a different DNS server.
A PXE boot file for each client architecture. The DHCP server cannot choose a boot file by the client's architecture.

dnsmasq, installed from Apps, provides all three. On the DNS page it offers a change that forwards a domain to it.

For automation#

Method	Path	Role	What it does
GET	`/api/daemons`	viewer	Every service's state: `status` (`configured`, `not-configured` or `unsupported`), `enabled`, `live` (`running`, `stopped` or `unknown`) with `live_detail`, `config`, and `actions`. Secret values are redacted below administrator. `502` when the router cannot be read.
POST	`/api/daemons/{name}/restart`	operator, with a licence	Restarts `dns` or `dhcp`. `409` for a service that is not configured or is turned off. `501` for `upnp`, for a service this router does not have, and when the router cannot restart the service directly. `502` when the restart failed.

Turning a service off or on sends the operations in actions.disable.ops or actions.enable.ops through the pending changes, like any other change: Stage and commit from a script. The UPnP settings are read with GET /api/upnp and saved with PUT /api/upnp (administrator, with a licence).