In this article

Use this article to run built-in diagnostics and configure log output for the DNS Relay using Relay Manager.

Run diagnostics

Debug logs capture detailed information about Relay activity and help DNSFilter Support identify the cause of connectivity or configuration issues. Run the following three commands in order from the command line:

• relay-manager status
• relay-manager logs
• relay-manager troubleshoot

These commands perform basic checks and provide guidance where possible. If the issue persists, submit both the troubleshoot output and the generated logs in a Support request for further investigation.

Configure log output

For Relay Manager v0.1.8 and higher, binary installations include a default log file configuration automatically. Logs are written immediately after install without additional setup.

For Relay Manager versions older than v0.1.8, binary deployments where no console is attached—such as a Windows service—no log file is created unless explicitly configured.

To write logs to a file, add a file key under the [log] section of relay.conf:

[log]
# Console error log, defaults to "error"
level = "info"
file = "relay.log"

The file value can be a filename (saved to the default Relay directory) or a full file path. Once enabled, the Relay automatically rotates log files, retaining up to 10 files with a maximum of 100MB total.

After editing relay.conf, restart the Relay for changes to take effect:

relay-manager stop
relay-manager start

Stale or malformed relay image detected

When relay-manager status, relay-manager install, or relay-manager update detects that the Relay container is running from an image that does not match the current expected DNSFilter Relay image, a warning is displayed identifying the condition. The Relay continues to run—the warning surfaces the state so action can be taken.

Common causes include deployments that predate Relay Manager, or environments where a custom or manually built image was substituted for the standard DNSFilter image.

To resolve, the Relay must be replaced with the current image:

1. Run relay-manager stop to stop the Relay service
2. Run relay-manager uninstall to remove the existing Relay
3. Run relay-manager install to reinstall using the current DNSFilter Relay image
4. Run relay-manager status to confirm the Relay is running and the warning is no longer present

Related content

• Install and manage the DNS Relay with Relay Manager
• Resolve systemd-resolved conflicts with DNS Relay on Linux
• Relay Manager CLI commands