Settings

The Settings page contains global application preferences and the DNS resolution system configuration. DNS resolution is a core feature that translates raw IP addresses in flow data into human-readable hostnames, making traffic analysis significantly easier to interpret.

Appearance

Dark Mode

Toggles between the light and dark UI themes. The selected theme persists across sessions and applies globally to all pages, dashboards, and components. Dark mode is recommended for NOC environments and extended monitoring sessions.

DNS Cache Statistics

The DNS Cache Statistics panel provides a real-time snapshot of the resolver's performance. These counters reflect activity since the last service restart.

Metric	Description
Cache Size	Total number of IP-to-hostname mappings currently stored in Redis. Each entry represents a unique IP address that has been resolved (or attempted).
Successful	Number of reverse DNS lookups that returned a valid hostname (e.g., 8.8.8.8 → dns.google).
NXDOMAIN	Number of lookups where the DNS server confirmed no PTR record exists for the IP. These are cached with a shorter TTL (default 1 hour) to avoid repeatedly querying for IPs that don't resolve. NXDOMAIN responses are expected — many public IPs simply don't have reverse DNS configured.
Failed	Number of lookups that failed due to DNS server errors, timeouts, or network issues. A high failure count may indicate DNS server connectivity problems. This counter should normally remain at or near zero.

Refresh

Re-fetches the current statistics from the backend. Use this to see updated counters after a sync cycle completes (the resolver runs every 30 seconds by default).

Clear Cache

Removes all entries from the Redis DNS cache. After clearing, the resolver will re-resolve all IPs it encounters in subsequent cycles. This is useful when DNS records have changed (e.g., after renaming hosts or changing internal DNS) and you want to force fresh lookups rather than waiting for TTLs to expire. This action cannot be undone.

DNS Resolver Settings

These toggles control the behavior of the background DNS resolver service. Changes take effect after clicking Save Settings.

DNS Resolver

The master enable/disable switch for the entire DNS resolution system. When disabled, no new lookups are performed and existing cache entries are left intact but will eventually expire. The Go flow enricher will still check Redis for cached entries, so previously resolved hostnames continue to appear until their TTL expires.

Public IPs

When enabled, the resolver performs reverse DNS lookups on public (internet-routable) IP addresses. Public IP resolution reveals the hostnames of external services your network communicates with, such as ec2-54-227-205-48.compute-1.amazonaws.com or dns.google. Disabling this reduces DNS query volume if you only care about identifying internal hosts.

Private IPs

When enabled, the resolver performs reverse DNS lookups on RFC1918 and other private address ranges, including 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16, 127.0.0.0/8 (loopback), and 169.254.0.0/16 (link-local). This is particularly useful in environments with internal DNS that maps device IPs to meaningful hostnames (e.g., 192.168.100.132 → vmware.home.local). If your internal DNS does not have PTR records configured, disabling this avoids unnecessary NXDOMAIN responses.

Advanced Settings

The expandable Advanced Settings section exposes tuning parameters for the resolver:

Setting	Default	Description
Minimum Flow Count	3	Number of flows an IP must appear in before the resolver will look it up. Prevents wasting lookups on transient single-packet scanners or noise.
Batch Size	500	Maximum number of IPs to process per resolver cycle.
Lookup Interval	30,000 ms	Time between resolver cycles. The resolver queries ClickHouse for new unique IPs at this interval.
Success TTL	86,400 s (24h)	How long a successfully resolved hostname stays cached in Redis before being re-queried.
NXDOMAIN TTL	3,600 s (1h)	How long a failed (NXDOMAIN) result stays cached. Shorter than success TTL so that newly configured PTR records are picked up sooner.
Max Concurrent Lookups	50	Maximum number of parallel DNS queries. Higher values resolve IPs faster but generate more load on your DNS servers.
DNS Timeout	5,000 ms	Per-query timeout. If a DNS server doesn't respond within this window, the query fails and the next server in the priority list is tried.

Save Settings

Persists all DNS Resolver Settings (including Advanced Settings) to the PostgreSQL dns_resolver_config table. The running resolver service reloads the configuration automatically.

DNS Servers

The DNS Servers section manages the list of DNS servers used for reverse lookups. The resolver tries servers in priority order (lowest number first) and falls back to the next server if one fails.

Server Properties

Each configured server displays the following information:

• Name — A friendly label for the server (e.g., "Google DNS", "Cloudflare DNS").
• Priority — Numeric priority controlling the order in which servers are tried. Lower numbers are tried first. In the default configuration, the System Default resolver (priority 0) is tried first, followed by Google DNS (100/101), then Cloudflare (200/201).
• Address — The server's IP address (e.g., 8.8.8.8, 1.1.1.1). Use the special value system to use the container's built-in DNS resolver, which inherits the host's /etc/resolv.conf configuration.
• Response Time — Average response time in milliseconds, displayed inline (e.g., 29ms). This is tracked automatically and helps identify slow or overloaded servers.
• Scope — Which IP types this server is used for. Displayed as All, Public, or Private. Configurable per server when adding or editing.
• Health Indicator — The green dot next to each server name indicates it is healthy. Servers that fail 3 consecutive lookups are automatically marked unhealthy (shown with a red dot) and skipped for 5 minutes before being retried.

Server Actions

Button	Description
+ Add Server	Opens a form to add a new DNS server with name, address, priority, and scope configuration.
Test	Sends a test reverse DNS query through the selected server (typically resolving 8.8.8.8) and reports success or failure with response time. Use this to verify connectivity before relying on a server.
Disable	Temporarily removes the server from the resolver rotation without deleting its configuration. Disabled servers can be re-enabled at any time.
Delete	Permanently removes the server from the configuration.

Server Priority and Failover

The resolver implements automatic failover across configured servers:

1. Servers are sorted by priority (ascending). Lower priority numbers are tried first.
2. For each IP lookup, the resolver tries the first healthy server.
3. If the lookup fails (timeout, network error), it moves to the next server in the list.
4. After 3 consecutive failures, a server is marked unhealthy and skipped.
5. Unhealthy servers are automatically retried after 5 minutes.
6. NXDOMAIN responses are treated as successful DNS responses (the server answered correctly; the IP simply has no PTR record) and do not count against server health.

Best Practice

Configure at least two DNS servers for redundancy. For environments with internal DNS, set your internal DNS server at the lowest priority number so it is tried first for private IP resolution, with public resolvers like Google or Cloudflare as fallback.

How DNS Resolution Works

The DNS resolution system operates as an asynchronous pipeline that never blocks flow processing:

1. Background Resolver (Node.js service, every 30 seconds) — Queries ClickHouse for unique IP addresses seen in recent flows, filters them based on public/private settings, checks Redis for existing cache entries, and performs reverse DNS lookups for any uncached IPs. Results are stored in Redis with the key format rdns:<ip>.

2. Flow Enricher (Go service, real-time) — As flows arrive from Kafka, the Go enricher performs a bulk Redis pipeline lookup for src_addr and dst_addr. If a cached hostname exists, it is added to the flow as src_hostname / dst_hostname before the flow is written to ClickHouse. If no cache entry exists, the hostname field is left empty — the flow is never delayed waiting for DNS.

3. Redis Cache (redis:7-alpine) — Serves as the bridge between the resolver and the enricher. Configured with a 512 MB memory limit and allkeys-lru eviction policy. Successful lookups are cached for 24 hours; NXDOMAIN responses are cached for 1 hour.

This design achieves 90%+ cache hit rates in steady-state operation with sub-millisecond lookup overhead per flow.

Troubleshooting

All statistics show zero

If Cache Size, Successful, NXDOMAIN, and Failed are all 0, the resolver may not have run its first cycle yet (wait 30 seconds) or may not be receiving IPs from ClickHouse. Verify that flow data is being ingested and that the DNS Resolver toggle is enabled.

High NXDOMAIN count

A high NXDOMAIN count is normal, especially with Public IPs enabled. Many internet IPs do not have reverse DNS (PTR) records configured. If NXDOMAIN counts are high for private IPs, verify that your internal DNS server has PTR records configured for your network devices.

DNS server marked unhealthy

Check network connectivity between the Chompy backend container and the DNS server. Use the Test button to verify. Common causes include firewall rules blocking UDP port 53, or the DNS server being unreachable from the Docker network. If using the system resolver, ensure the host's /etc/resolv.conf is properly configured.

Hostnames not appearing in flow data

The resolver and enricher operate asynchronously. A new IP address may take up to 60 seconds to appear with a hostname (one resolver cycle to discover and resolve it, then subsequent flows will be enriched). Also verify that the Go flow enricher has REDIS_URL configured in its environment and can reach the Redis service.

Stale hostnames after DNS changes

If a device's hostname changed in DNS, the old name will persist in the cache until the TTL expires (default 24 hours). Use Clear Cache to force immediate re-resolution, or reduce the Success TTL in Advanced Settings for environments with frequently changing DNS records.