Logging

Logging

Even when you are not browsing any websites, devices constantly send a large amount of DNS traffic.

dnscrypt-proxy let you watch in real time what DNS queries are being sent, so you can block the ones you don't trust.

These logs stay on your computer: they are just saved as local files, and are not sent to any servers.

Query log

The configuration file includes a [query_log] section:

[query_log]
file = '/var/log/dnscrypt-proxy/query.log'
format = 'tsv'
ignored_qtypes = ['DNSKEY', 'NS']

This can be used to log individual queries.

If the file property is not defined, no logs will be stored.

format can be either tsv or ltsv.

The tsv format is a simple list of Tab-Separated Values, easy to parse but also easy to read.

ltsv is a structured format that is less human-readable, but has more information, is simple to parse and is usually a better fit for log processors.

By default, all types of DNS queries are logged. In order to reduce the noise, the optional ignored_qtypes property can contain a list of record types to be ignored.

NX log

The [nx_log] section:

[nx_log]
file = 'nx.log`

can be used to log queries that were sent by clients to domains that don't exist.

Such queries can be due to obsolete software, misconfigured software, or even by malware trying to call home. They are important to review from time to time.

Blocked names

[blocked_names]
log_file = 'blocked-names.log`

This section can be used to log names that have been blocked using block lists.

Blocked IP addresses

[blocked_ips]
log_file = 'blocked-ips.log'

Names for which at least one IP address matches a block list can be blocked. They can be logged by uncommenting the log_file line in the dedicated section.

Allowed names

[allowed_names]
log_file = 'allowed-names.log'

The [allowed_names] section contains "exceptions": names that should not be blocked even though they may match block lists.

Logging these is mainly only useful for debugging purposes.

Allowed IPs

[allowed_ips]
log_file = 'allowed-ips.log'

Similarly, a set of IP addresses to never block can be provided. If at least one IP addreses in that list is present in a response, the response wil not be blocked.

This can be logged, even though this is also mainly only useful for debugging purposes.

Custom log format / log processors

Instead of being directly stored to a file, logs can be pushed to named pipes:

1. Create a named pipe

mkfifo /tmp/query.log.pipe

Check that it is be writable by the user dnscrypt-proxy will be running as.

Then, configure dnscrypt-proxy to write to that pipe instead of an actual file:

[query_log]
file = '/tmp/query.log.pipe'

Such logs can be read and processed on the fly by other applications such as flowgger for filtering, long-term storage, observability or analytics.

They can also be transformed to different formats. For example, the following shell command removes the IP address from TSV logs:

#! /bin/sh
exec cut -f1,3- /tmp/query.log.pipe >> /tmp/query.log.noips

All log produced by dnscrypt-proxy, including blocked queries and nonexistent domains can be redirected to other applications that way.

IP address encryption and obfuscation

IP addresses are considered private personal information. If you allow third parties to connect to your dnscrypt-proxy servers, storing real client IP addresses in log files may not be a good idea, especially if these logs are sent to cloud services. It may even be illegal to do so without explicit user consent.

dnscrypt-proxy can encrypt client IP addresses before they are stored in log files. Only the owner of the secret key can decrypt them. Otherwise, by looking at log files, it's possible to see what queries were made, but impossible to know who made them. Encryption can be either deterministic or non-deterministic.

Deterministic encryption

With deterministic encryption, log files will contain IP addresses, but these will not be the real ones. Every possible IP address will be remapped to a different one. If the same encrypted IP address appears in the files, it means that the same real client IP address was used. So it remains possible to link queries to users and to perform accurate log analysis, without processing the real client IP addresses.

Non-deterministic encryption

With non-deterministic encryption, the encrypted IP addresses are not IP addresses anymore, but short hexadecimal strings. Unlike deterministic encryption, if multiple queries from the same real client IP address are received, the encrypted IP will look different for every query, so it is not possible to link queries to IP addresses.

Configuration

Encryption can be configured in the dnscrypt-proxy.toml file:

###############################################################################
#                           IP Encryption                                      #
###############################################################################

[ip_encryption]

## Encrypt client IP addresses in plugin logs using IPCrypt
## This provides privacy for client IP addresses while maintaining
## the ability to distinguish between different clients in logs

## Encryption algorithm (default: "none")
## - "none": No encryption (default)
## - "ipcrypt-deterministic": Deterministic encryption (same IP always encrypts to same value) - requires 16-byte key
## - "ipcrypt-nd": Non-deterministic encryption with 8-byte tweak - requires 16-byte key
## - "ipcrypt-ndx": Non-deterministic encryption with 16-byte tweak (extended) - requires 32-byte key

algorithm = "none"

## Encryption key in hexadecimal format (required if algorithm is not "none")
## Key size depends on algorithm:
## - ipcrypt-deterministic: 32 hex chars (16 bytes) - Generate with: openssl rand -hex 16
## - ipcrypt-nd: 32 hex chars (16 bytes) - Generate with: openssl rand -hex 16
## - ipcrypt-ndx: 64 hex chars (32 bytes) - Generate with: openssl rand -hex 32
## Example for deterministic/nd: key = "1234567890abcdef1234567890abcdef"
## Example for ndx: key = "1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef"
## IMPORTANT: Keep this key secret

key = ""

Set algorithm to ipcrypt-deterministic for deterministic encryption, or set algorithm to ipcrypt-nd for non-deterministic encryption.

Then create a 16-byte key with the openssl rand -hex 16 command, and copy the output into the key property.

ipcrypt-ndx is another option for non-deterministic encryption that requires a 32-byte key and produces longer output for more theoretical security. But ipcrypt-nd is generally recommended as it is plenty secure, more compact, and faster.

For more information, see the IPCrypt website.

Note that this feature only encrypts client IP addresses in the log files produced by dnscrypt-proxy. This is different from hiding IP addresses from DNS resolvers. To hide your IP address from resolvers, use Anonymized DNSCrypt. Do not use plain DNSCrypt or DoH.