Parental Control

Parental Control is a DNS-level content-filtering feature you can switch on per subscriber. When enabled, the subscriber’s DNS traffic is redirected on their NAS to a filtering resolver, and lookups for blocked categories, apps, or domains are refused. This page covers the operator/admin side. The subscriber-facing portal tab is documented separately — see Parental Controls (customer portal).

The same underlying state (categories, services, toggles, schedule, digest) is shared between the admin API and the customer portal. An admin can enable the feature and set defaults; the customer can then self-manage their own filtering from the portal if you expose it.

How to get here

There are two entry points:

1. Per subscriber — open Subscriber Detail and use the Parental Control section. This is where you enable/disable filtering for one subscriber and view their current status (categories, services, denylist/allowlist, toggles, schedule, digest).
2. System-wide — Settings has a Parental Control area where you choose the filter engine and, for the NextDNS engine, store and test the API key. The master “expose in portal” preference also lives here.

Note

The customer portal hides the Parental tab entirely unless the system-wide preference parental_control_enabled is true. If a customer reports a missing Parental tab, check that preference first.

Filter engine

Parental Control runs on one of two engines, selected by the parental_engine system preference:

Engine	Preference value	DNS target port	External dependency
Self-hosted (default)	selfhosted (or unset)	5354 (local proisp-dns filter)	None
NextDNS	nextdns	5353 (local DoH proxy → NextDNS)	NextDNS API key

Self-hosted is the default and the safer choice — it has no external dependency and the local DB is always the source of truth. The NextDNS engine additionally syncs each subscriber’s settings to a remote NextDNS profile (best-effort) so NextDNS analytics are populated; if the NextDNS API call fails, the change is still written locally and enforcement is unaffected.

The local database is the source of truth regardless of engine. Category/service/toggle/schedule changes are always mirrored into the subscriber’s columns so that switching engines never loses state.

NextDNS API key

When the engine is nextdns, store the NextDNS API key as the nextdns_api_key preference in Settings. You can validate it with Test Connection (POST /api/settings/nextdns/test), which calls the NextDNS API and reports whether the key works. Without a valid key the customer status endpoint returns configured: false with the API error message, and enabling a subscriber will fail.

What you can configure

Master toggle (enable / disable per subscriber)

Enabling a subscriber (POST /api/subscribers/:id/parental/enable) does the following:

1. (NextDNS engine only) Creates a NextDNS profile named sub-<id>-<username> if the subscriber doesn’t already have one, and seeds default categories + toggles on it.
2. Writes defaults into the subscriber’s own columns regardless of engine: categories porn, dating, gambling; Safe Search on; YouTube Restricted Mode off; Block Bypass on; and records the subscriber’s current IP as the linked IP.
3. Installs the MikroTik DNS redirect on the subscriber’s NAS so their DNS is steered to the filter (see Enforcement).
4. Flushes the DoH-proxy and DNS-filter caches so the next query re-reads state.

Disabling (POST /api/subscribers/:id/parental/disable) removes the MikroTik DNS redirect (so queries flow back to the ISP’s normal resolver and no policy is applied), clears the linked IP, and sets parental_control_enabled = false. On the NextDNS engine the remote profile is left intact so re-enabling is instant and preserves the customer’s categories, services, and schedule.

Note

YouTube Restricted Mode defaults to off on enable. It is unreliable on modern HTTPS and can block all of YouTube rather than filtering it, so parents opt in manually if they want that trade-off.

The admin status endpoint (GET /api/subscribers/:id/parental) returns the full picture: enabled flag, NextDNS profile ID, linked IP, categories map, services list, denylist/allowlist, the three toggles, schedule, and digest settings.

Categories

Built-in content categories that can be blocked. The valid category slugs are:

porn, gambling, dating, piracy, social-networks, video-streaming, gaming, online-gaming, file-sharing.

Categories are stored as a CSV list in the subscriber’s parental_categories column. On the NextDNS engine they are also pushed to the remote profile (best-effort).

Services / apps

Named apps/services (for example tiktok, instagram, youtube) can be individually blocked. They are stored as a CSV list in parental_apps, and synced to NextDNS when that engine is active.

Feature toggles

Three boolean toggles, each mirrored to a subscriber column:

Toggle	Column	Notes
Safe Search	parental_safesearch	Forces safe search on supported search engines. On by default.
YouTube Restricted Mode	parental_youtube_restricted	Off by default (see note above).
Block Bypass	parental_block_bypass	Blocks DNS-over-HTTPS / VPN bypass services. On by default.

Custom domains (denylist / allowlist)

Per subscriber you can add custom domain rules to either the deny list (block this domain) or the allow list (always permit it). Rules are stored in the parental_custom_rules table keyed by subscriber, domain, and list. Domains must contain a dot and are lowercased. On the NextDNS engine they sync to the profile’s denylist/allowlist.

Device profiles

For subscribers with a managed TR-069 CPE (see CPE / Routers), the system discovers devices behind the home router and lets you assign a named device profile (its own categories, apps, etc.) to a specific device. This means different rules for, say, a child’s phone versus the household default.

• Discovered devices live in parental_devices; profiles live in parental_device_profiles.
• A ParentalDeviceSync background service polls CPE hosts every 5 minutes and upserts discovered devices. It only runs for subscribers whose CPE is linked (cpe_devices.subscriber_id set) — per-device rules are not available for subscribers without a managed CPE.
• A device with no profile assigned (profile_id null / 0) falls back to the subscriber-level rules.

Schedule

A weekly time window during which filtering is active. The schedule stores an enabled flag, a start time, an end time, and a list of weekdays in the subscriber’s columns (parental_schedule_enabled, parental_schedule_start, parental_schedule_end, parental_schedule_weekdays). The self-hosted DNS filter reads these directly; on the NextDNS engine the schedule is also pushed to the profile.

Daily digest

An opt-in WhatsApp report of blocked activity, controlled per subscriber via three columns:

Setting	Column	Notes
Enabled	parental_digest_enabled	Turns the daily digest on.
Time	parental_digest_time	HH:MM, defaults to 09:00.
Realtime threshold	parental_realtime_threshold	Blocks-per-hour count that triggers a real-time alert. 0 disables real-time alerts.

The ParentalDigestService runs two background scanners:

1. Daily digest — every minute it looks for subscribers whose parental_digest_time matches the current HH:MM (and who have a phone number and parental control enabled), then sends a WhatsApp summary of the last 24 hours: total blocked requests, top blocked apps, top blocked categories, and top blocked domains (drawn from parental_block_log). If nothing was blocked it sends a short “all clear” message.
2. Real-time alerts — hourly, it counts each opted-in subscriber’s blocks in the last hour; if the count meets or exceeds their parental_realtime_threshold, it sends a WhatsApp alert. Alerts are rate-limited to at most one per subscriber every 4 hours to avoid spam.

Both rely on the WhatsApp gateway being configured (see Communication / Notification settings).

Enforcement

Blocking is enforced entirely at the DNS layer — there is no per-device agent.

1. On enable, ProxRad installs a DNS-redirect (dst-nat) rule on the subscriber’s NAS via the MikroTik API, targeting the subscriber’s IP. The redirect points at DOH_PROXY_IP (falling back to SERVER_IP) on the engine’s port (5354 for self-hosted, 5353 for NextDNS).
2. The subscriber’s DNS queries are forced to the filtering resolver, which evaluates them against the subscriber’s (or matched device’s) categories, apps, custom rules, toggles, and schedule.
3. Blocked lookups are refused and recorded in parental_block_log, which powers the customer portal’s activity view and the daily digest.
4. On disable, the redirect is removed and DNS flows to the normal ISP resolver, so no policy is applied — even on NextDNS, where the remote profile is left intact but no longer in the query path.

Caution

The MikroTik redirect needs API credentials on the subscriber’s NAS and a non-empty DOH_PROXY_IP/SERVER_IP. If the NAS has no API credentials, or the proxy host env var is unset, enabling still updates the database and (on NextDNS) the remote profile, but the DNS redirect is not installed — so traffic is not actually filtered. The failure is logged, not surfaced as an error to the caller.

Audit

Every change — enable, disable, category/service/feature toggle, schedule update, domain add/remove, profile create/delete, device update, digest update — is written to parental_control_audit with the actor (admin, reseller, customer, or system), actor name, action, target, and metadata. Admin and reseller actions record the acting user; customer self-service actions record the subscriber username.

Permissions

The per-subscriber admin endpoints are gated by two permissions:

Permission	Effect
parental.view	Read a subscriber’s parental status (GET /api/subscribers/:id/parental).
parental.manage	Enable or disable parental control for a subscriber (POST .../parental/enable, POST .../parental/disable).

Admins always pass these checks. The NextDNS Test Connection endpoint lives under the Settings group and is gated by settings.view. Customer-portal parental actions use the customer’s own session, not these admin permissions.

Related pages

• Parental Controls (customer portal) — the subscriber-facing tab where customers self-manage categories, services, schedules, devices, and view what was blocked.
• Subscriber Detail — where the per-subscriber Parental Control section lives.
• CPE / Routers — TR-069 device discovery that powers per-device profiles.
• Settings — filter engine selection, NextDNS API key, and the master expose-in-portal preference.
• Communication — WhatsApp gateway used by the parental daily digest and real-time alerts.