Dashboard Guide
The VeloGuardian DNS web dashboard provides full visibility into your network’s DNS activity. Access it at https://<appliance-ip> from any device on your network. Your browser will warn about the self-signed certificate on first visit — accept it to continue.
Dashboard
Section titled “Dashboard”The dashboard is built to be read at a glance: is filtering working, how much was blocked, what kind of thing was blocked, and which devices it came from. Every block covers the range you pick at the top right (1h, 24h, 7d or 30d), so all the numbers agree with each other, and the page refreshes itself every 30 seconds.
Header and attention banner
Section titled “Header and attention banner”The header shows the filtering status (Filtering on, Filtering off or Blocklists stale), the appliance name and address, and when the blocklists last updated. A yellow banner appears above the numbers only when something needs your attention, with a button to the page that fixes it:
- filtering is turned off
- blocklists are failing to download, or have not updated for more than 2 days
- CPU, memory or disk is running high
- lookups are slow or failing
If a refresh fails (for example the appliance restarted), the last numbers stay on screen with a note saying how old they are, and a Retry button.
Key numbers
Section titled “Key numbers”| Number | What it shows |
|---|---|
| Queries | DNS lookups in the range, with the change against the previous period of the same length |
| Blocked | The share of lookups that were blocked, and how many |
| Threats blocked | Lookups blocked in a security category (malware, phishing and similar), and on how many devices. Turns red when there are any |
| Response time | Average response time, and the share answered from the appliance’s cache |
Next to each number, a small graphic shows how it moved over the range: a line for queries and for the blocked share, bars for threats, and a ring for the share answered from cache.
Traffic
Section titled “Traffic”A bar chart of lookups over the range, split into resolved (green), from cache (cyan) and blocked (red), with a red dot above any bar that contains a blocked threat. Hover a bar for its exact counts, including failed lookups. Bars for 7 days and 30 days start at local midnight.
What got blocked
Section titled “What got blocked”The categories behind the blocks in the range: threat categories are pinned on top in red, followed by the busiest other categories with their share of all blocks. Custom block rules collects blocks from a profile’s deny rules, and Uncategorised collects blocks from a blocklist that has no category.
Top blocked sites and devices
Section titled “Top blocked sites and devices”- Top blocked sites groups hosts by site (
ads.example.comandtracker.example.comcount asexample.com) and shows each site’s category. Threat sites are marked red. - Devices lists the busiest devices with a bar showing how much of their traffic was blocked, and a red badge when a device tried to reach a threat. A device shows the name and icon of the client that covers it on the Clients page; otherwise it shows its IP address.
Opening the Query Log from the dashboard
Section titled “Opening the Query Log from the dashboard”Click any category, site or device to open the Query Log filtered to it, from the start of the range the dashboard shows. Use this to see exactly which lookups were blocked and why.
Clients
Section titled “Clients”Under Filtering > Clients, each client entry links devices to a filtering profile and gives them a name and an icon on the dashboard.
| Field | Description |
|---|---|
| Profile | The filtering profile these devices use |
| Match type and value | Which devices this entry covers: one IP address, a subnet (192.168.1.0/24) or an IP range (192.168.1.100-192.168.1.150) |
| Description | The name shown on the dashboard, for example “Living room TV” |
| Device type | The icon shown on the dashboard and in the Clients list |
Device type is picked from a set of icons: phone, tablet, laptop, computer, TV, console, speaker, watch, network, printer, camera, server, or smart home / other. Leave it on Automatic and the icon is guessed from the description (“Sam’s iPhone” shows a phone, “MacBook” a laptop).
Which entry applies to a device: an entry for the device’s exact IP address wins. Otherwise the first subnet or IP range that contains the address applies, and devices covered by none use the default profile. The same entry gives the device its profile, its name and its icon on the dashboard, so a device in a named subnet shows that subnet’s name, with its own address underneath.
Query Log
Section titled “Query Log”A searchable, paginated log of the DNS lookups the appliance has processed, newest first, 50 per page.
Columns:
| Column | Description |
|---|---|
| Time | When the query was received |
| Domain | The requested domain name |
| Type | DNS record type (A, AAAA, CNAME, MX, etc.) |
| Client | IP address of the requesting device |
| Profile | The filtering profile that handled the query |
| Status | Allowed, Blocked, Cached, or Error |
| Category | For a blocked query, the category that blocked it |
| Response | Time taken in milliseconds |
| Reason | Why a query was blocked (blocklist, category or custom rule) |
Filters (combined with AND logic): domain (substring), client IP, status, profile and category. The category filter also offers Custom block rules and Uncategorised. Links from the dashboard add a time filter (the start of the dashboard’s range), shown as a chip you can remove.
The filters are kept in the page address, so a filtered view can be bookmarked or shared with someone else who can sign in to the appliance.
Queries from a profile with query logging turned off are not recorded here. Entries older than the query log retention (Settings, default 30 days) are removed.
Local DNS
Section titled “Local DNS”Create custom DNS records that override upstream resolution. Useful for internal hostnames, split DNS, or testing.
Supported record types:
| Type | Value format | Example |
|---|---|---|
| A | IPv4 address | 192.168.1.50 |
| AAAA | IPv6 address | fd00::1 |
| CNAME | Target domain | server.internal.example.com |
Local DNS records are checked before the filter engine and upstream resolvers. CNAME records are automatically chased — the appliance resolves the target to include A/AAAA answers.
Each record has an Enabled toggle so you can temporarily disable it without deleting.
Reports
Section titled “Reports”Generate PDF reports summarizing DNS activity over a time period, optionally scoped to specific clients.
IP Groups
Section titled “IP Groups”Group client IPs together (e.g., “Kids devices”, “Office workstations”) so you can scope reports to specific sets of devices.
Report configurations
Section titled “Report configurations”Each report configuration defines:
| Setting | Options |
|---|---|
| Time range | Last 24 hours, 7 days, 30 days, or custom date range |
| Scope | All clients, specific IPs, or an IP group |
| Schedule | None (manual), daily, weekly, or monthly |
| Email delivery | Send the PDF to an email address on generation |
| Retention | Maximum reports to keep (default 10, oldest auto-deleted) |
Click Generate to create a report immediately, or let the schedule run automatically.
PDF report contents
Section titled “PDF report contents”The first page answers three questions on its own: is the appliance healthy, how much was blocked, and what was blocked. It opens with a one-line verdict, then:
- System health — DNS response time (median, 95th percentile, cache share, failed share), CPU, memory and disk, each marked OK or flagged
- Blocked queries — the blocked count against the previous period, a per-day chart, and a table of the categories that had blocks, with a note on security threats
- Most blocked sites — the top sites, grouped by site, with their category and share of all blocks
The following pages carry the detail: traffic over the period, day by day, busiest hours, how queries were answered (cache, upstream, blocked, failed), most queried sites, devices, security threats (domains and the devices that tried to reach them), and a short explanation of each term.
Totals come from the appliance’s statistics; the lists come from the Query Log, so they cover only profiles with query logging on and only the query log retention period.
Reports are available for download from the dashboard or delivered by email if SMTP is configured.
Settings
Section titled “Settings”Upstream DNS
Section titled “Upstream DNS”Configure which DNS servers the appliance queries for domains that aren’t blocked or cached.
| Type | Description | Example |
|---|---|---|
plain |
Standard DNS (UDP/TCP) | 1.1.1.1:53 |
doh |
DNS-over-HTTPS | https://cloudflare-dns.com/dns-query |
dot |
DNS-over-TLS | tls://1.1.1.1 |
Multiple upstreams are tried in order. Changes take effect immediately — no restart needed.
Blocklist update schedule
Section titled “Blocklist update schedule”A cron expression controlling when blocklists are re-downloaded and the filter index is rebuilt. Default: 0 4 * * * (daily at 4 AM).
Runtime settings
Section titled “Runtime settings”| Setting | Description | Default |
|---|---|---|
| Log level | Verbosity: debug, info, warn, error | info |
| Blocking mode | How blocked queries are answered | nxdomain |
| Custom blocking IP | IP to return when blocking mode is custom_ip |
— |
| Safe search | Force safe search on Google, Bing, YouTube | Off |
| YouTube restrict | Safe search level for YouTube: moderate or strict | — |
| Rate limit | Max queries per second per client | 100 |
| Query log retention | Days to keep query logs | 30 |
| Anonymize clients | Mask the last octet of client IPs in logs | Off |
Blocking modes:
| Mode | Behavior |
|---|---|
nxdomain |
Respond with NXDOMAIN (domain does not exist) |
null_ip |
Respond with 0.0.0.0 / :: |
custom_ip |
Respond with a custom IP address |
Password
Section titled “Password”Change the dashboard login password. Enter your current password and the new password twice to confirm.
DNS cache
Section titled “DNS cache”View the current cache size and flush the entire cache. Flushing forces all subsequent queries to go to upstream resolvers until the cache rebuilds naturally.
DNS service control
Section titled “DNS service control”Restart DNS performs a graceful restart — the DNS listener rebinds without dropping the web dashboard. Use this after major configuration changes or if DNS resolution seems stuck.
Backup and restore
Section titled “Backup and restore”- Download backup: exports the configuration as a
.vgbackupfile: settings, users, profiles, custom rules, schedules, clients, blocklists and local DNS records - Restore from backup: upload a
.vgbackupfile to replace the current configuration with it
A backup does not contain the query log, statistics, report configurations or IP groups. A backup can be restored on the same version or a newer one that has not changed the backed-up data; the appliance tells you if a backup is too old or too new to restore.
Configure email delivery for reports and test emails.
| Setting | Description |
|---|---|
| Host | SMTP server hostname |
| Port | SMTP port (default: 587) |
| Username | SMTP authentication username |
| Password | SMTP authentication password |
| From address | Sender email address |
| Security | none, starttls, or ssl |
| Skip TLS verification | Bypass certificate validation (for self-signed certs) |
Use the Test Email button to verify your configuration before relying on scheduled report delivery.
System Status
Section titled “System Status”Shows the appliance’s health:
- Hostname, uptime, CPU cores, Go version and app version as tiles at the top
- Memory and Disk: the share in use, with a meter that turns yellow above 75% and red above 90%
- Load averages: 1, 5 and 15 minutes, across the CPU cores
- Software updates: the current version, the last update and the last check. Check for updates looks for a new signed release online, which you can then download and apply; Upload package installs a
.vgupdatefile by hand
System Logs
Section titled “System Logs”The appliance’s system log (journalctl output). Pick how many lines to show (50, 100, 200 or 500) and use Refresh to load the latest. Log lines are color-coded by level: red for errors, yellow for warnings.