Appearance
Use private device names #
Private DNS lets applications on a connector host reach an authorised device by its full name rather than a virtual IP. Use the canonical name for automation: it stays tied to the device identity across renames and connector upgrades, including when an address range change moves the device to another IP.
Readable aliases contain the device name and an identity suffix. They change when the device is renamed. Replacement hardware has a different identity and name. Bare device names and automatic short-name search are unsupported.
Find and test a name #
Run this on the installed host:
bash
dataplicity-connector devices
dataplicity-connector dns statusUse a full canonical name from your authorised device inventory. In the following commands, replace DEVICE_FQDN with that exact name:
bash
dataplicity-connector dns query DEVICE_FQDN --type A
dataplicity-connector dns query DEVICE_FQDN --type A --tcp
getent ahostsv4 DEVICE_FQDN
ssh deviceuser@DEVICE_FQDNThe first two commands test the local DNS responder over UDP and TCP. getent tests the Linux application's resolver path. A successful direct DNS query alone does not show that applications can resolve the name. Finally, connect to the required service: a DNS answer grants no access by itself.
Automatic Linux integration #
Automatic setup requires an existing systemd-resolved stub configuration, with /etc/resolv.conf pointing to /run/systemd/resolve/stub-resolv.conf. Inspect it with:
bash
readlink -f /etc/resolv.conf
resolvectl status
dataplicity-connector doctorThe connector answers DNS only on 127.0.0.153:53, over UDP and TCP. It does not listen on the LAN or forward queries to public DNS. A separate connector-owned link, dpdns0, routes the fleet namespace dp.dataplicity.com and the supported benchmark reverse namespace 18.198.in-addr.arpa to this local responder. The traffic tunnel is dpconn0.
Unrelated DNS continues through the host's existing configuration. The connector does not replace /etc/resolv.conf, claim all DNS with ~., install a search suffix or change global DNS servers. With custom fleet IP ranges, check reverse lookup behaviour separately; automatic reverse routing is scoped to the benchmark namespace above.
The helper reconciles owned resolver settings every 15 seconds, including after a resolver restart. If another application owns the link or installs a competing private DNS route, the connector reports a conflict rather than overwriting its settings.
Manual configuration and containers #
A static or uplink /etc/resolv.conf, another DNS manager, and many containers require manual configuration. Amazon Linux hosts using a legacy/uplink resolver configuration can also report manual_required. Keep IP-based device access while arranging DNS with the host's administrator; changing the whole resolver stack just for Connector can disrupt other services.
The root-owned file /etc/dataplicity-connector/dns.conf accepts one mode:
| Mode | Behaviour |
|---|---|
auto | Local responder plus supported automatic systemd-resolved integration |
manual | Local responder; the administrator supplies scoped resolver routing |
off | DNS responder disabled; authorised IP-based TCP access remains available |
After editing the mode, apply it with:
bash
sudo dataplicity-connector service restart
sudo systemctl start dataplicity-connector-dns.service
dataplicity-connector dns statusInvalid mode values disable the responder. In manual mode, configure your DNS manager to route only the private namespaces to 127.0.0.153, without upstream fallback for those namespaces. Keep unrelated DNS unchanged. Use commands appropriate to that resolver manager; replacing the host's global nameserver is not a safe substitute.
Containers usually have a separate network namespace and loopback. The host's 127.0.0.153 is not automatically the container's resolver. Use virtual IPs or arrange explicit resolver integration for that namespace. DNS is scoped to the host, rather than a separate access list for each local process.
Interpret responses #
| Response | Meaning and next check |
|---|---|
| A record | An authorised IPv4 address is present; verify the TCP grant and device service |
| PTR record | Reverse answer points to the canonical name; application reverse routing also depends on the host's DNS routes |
| No AAAA data | Device transport is IPv4; use its A record |
| NXDOMAIN | That private name is not in this connector's authorised inventory; check the full name, tags and plan allowance |
| SERVFAIL | Fleet DNS authority is absent or expired; check connector status and its latest policy refresh |
| REFUSED | The query is outside the owned namespaces or requests an unsupported operation |
Records are kept in memory and withdrawn on failed refresh, malformed metadata, shutdown or loss of authority. The authority lease is 45 seconds, with positive TTL at most 30 seconds and negative TTL at most 5 seconds. Restarting clears the snapshot. Application caches may retain an earlier answer, but the transport still checks current device and port authority.
Fleet records are not published in public DNS. The responder provides no recursion, forwarding or zone transfers. Private query names are not written to Activity or connector logs.
Opt out or retire DNS #
Package removal retains the owned DNS link until reboot or explicit cleanup. While the listener is unavailable, this preserves private-domain routing on supported resolver paths and makes private lookups fail rather than fall back to ordinary DNS.
Before explicit cleanup, stop the reconciliation timer. Set mode to off if the package will remain installed, stop the connector when retiring it, and run cleanup while the binary still exists:
bash
sudo systemctl disable --now dataplicity-connector-dns.timer
sudo dataplicity-connector service stop
sudo dataplicity-connector dns-helper cleanupIf the package is already removed, ask the host administrator to inspect ip -d link show dpdns0. Revert the link's resolved settings and delete it only when it is a dummy link bearing the exact ownership alias dataplicity-connector-private-dns-v1.
After opt-out, cleanup or reboot, private-name queries can reach the ordinary resolver again. Custom DoH clients, separate containers, boot-time gaps and other DNS managers can also bypass the host's scoped routing. Treat these as resolver configuration boundaries when planning private-name handling.