Device Information Log Enrichment

By default, DNS logs are only able to expose the public IP used to join the NextDNS edge servers. When many devices are sharing the same profile, logs are becoming less usable. NextDNS offers the ability to add information to identify the client.

All NextDNS official clients support those ways ways to pass device information. In this document, you will learn how to integrate the same capabilities with third-party clients / integrations.

Passing Device Information

DoT Hostname

Only the device name can be passed via the DoT protocol. This is done by prepending the name to the provided DoT hostname (the name should only contain a-z, A-Z, 0-9 and -). Use -- for spaces.

For "John Router" with the profile id abc123, the result is:

John--Router-abc123.dns.nextdns.io.

DoH URL Path

Similarly to DoT hostname, a NextDNS DoH URL can have the device name appended to the provided URL (the name should be URL encoded).

For "John's Firefox" with the profile id abc123, the result is:

https://dns.nextdns.io/abc123/John's%20Firefox

DoH Query-String Parameters (recommended)

More device information can be passed to a DoH URL by using the query-string. Here is the list of supported query-string parameters:

• device_id: a unique device identifier (unique to this profile).

• device_name: the device name (eg: Bob's iPhone)

• device_model: the device model (eg: iPhone 12 Pro)

• device_ip: the device private (LAN) IP

For "John Router" with the profile id abc123, the result is:

https://dns.nextdns.io/abc123?device_id=12345&device_name=John's%20Firefox&device_model=iPhone%2012%20Pro&device_ip=10.0.0.123

DoH HTTP Header

Similarly to DoH Query-String, HTTP headers can be used to pass the same device information. Using HTTP headers is recommended when multiple devices are tunneled through the same DoH connection, like in the case of a DNS proxy on a router. Using individual headers instead of query-string improves header compression.

• X-Device-Id: a unique device identifier (unique to this profile).

• X-Device-Name: the device name (eg: Bob's iPhone)

• X-Device-Model: the device model (eg: iPhone 12 Pro)

• X-Device-Ip: the device private (LAN) IP

The DoH URL remains unchanged.

Implementation Recommendations

Device ID

The device ID is used to avoid duplicated entries on the log/analytics dashboard for a given device that may change name over time.

When the device name is not known, a device ID can still be used to identify the device in the logs. In such case, a device name will be generated from the ID in the UI with the format Device #<id>.

The recommended format for device IDs is 5 upper-case characters.

The source for a device id may be a MAC address, a private client IP, some machine UUID or any ID that is stable over time for a given device.

It is recommended to hash this ID with the NextDNS profile ID in order to mitigate the risk of leaking a globally identifiable ID.