# SafeDNS Shield
# Overview
SafeDNS Shield is an on-premises web filtering and security solution that operates as a DNS proxy. It processes every DNS query to identify the requesting user, evaluates the queried domain against that user’s filtering policy, and then allows or blocks the request.
When a domain is blocked, the proxy resolves it to the IP address of a block page instead of returning the actual IP. The block page can be a custom corporate page hosted outside the solution, or the default block page built into SafeDNS Shield, which can also be customized.
If a domain is allowed, the proxy forwards the DNS request to the next server in the resolution chain. This server can be a local corporate DNS server, an ISP’s caching DNS resolver, or any public DNS service (for example, Google Public DNS or Cloudflare).
Because SafeDNS Shield inspects all DNS traffic, it enables comprehensive, per‑user traffic analysis. Every request is logged, providing access to detailed statistical information.
# Architecture and deployment
### Components
[](https://docs.safedns.com/uploads/images/gallery/2026-03/MuD0Wr8fD6cCi4bA-image-1772786479925.png)
SafeDNS Shield is composed of the following components:
- **DNS Proxy Module**
The core filtering engine. It receives DNS requests from end users, identifies the requesting user, applies the configured filtering policy, and returns either the resolved IP address or the IP address of a block page.
- **Internal Database**
Stores all configuration and policy data: user identifiers (subnet, IP, port), filtering profiles, block pages, user groups, and their assignments.
- **Block pages**
HTTP/S pages served to the users instead of blocked websites. Can be hosted alongside Shield or on an external server.
- **REST API**
Provides a management interface for administrators to update the Internal Database. It supports creation and modification of:
- User identifiers (subnet, IP, port)
- Filtering profiles (categories to block)
- Block pages
- **Binary Log Parsing Module (StatsLoader)**
Processes the binary log files generated by the DNS Proxy. It parses the DNS query logs, extracts statistics, and sends them to the ClickHouse cluster for storage and analysis.
- **ClickHouse Cluster**
A distributed database for storing and analyzing DNS request statistics. The cluster is divided into shards, each containing multiple mirrored nodes for fault tolerance and high‑performance parallel reads and writes.
- **Load Balancer**
Receives statistics data from StatsLoader and distributes it evenly across the ClickHouse cluster nodes.
- **ZooKeeper**
Manages coordination and configuration of the ClickHouse cluster, ensuring data consistency and system reliability.
The DNS Proxy writes its binary query logs to a designated host path (`HostPATH`), from which StatsLoader reads them.
**External dependencies**
The following elements are not part of SafeDNS Shield but are required for operation:
- **User** – The end‑user device that sends DNS requests to SafeDNS Shield.
- **Caching DNS Server** – A recursive resolver deployed on the organization’s network that performs upstream DNS resolution for allowed queries.
### Deployment options
SafeDNS Shield supports multiple deployment options to accommodate different network topologies. This section describes the most common scenarios.
##### For ISPs
##### ****
This deployment option is used in ISP networks, where NAT separates end users from the on-premises DNS infrastructure, making it impossible to identify them solely by their individual IP addresses.
##### For corporate clients
[](https://docs.safedns.com/uploads/images/gallery/2026-03/eNEcaAFBnndiMMt5-image-1772786346085.png)
or
[](https://docs.safedns.com/uploads/images/gallery/2026-03/wUXsLWAApQ8PeBDb-image-1772786395390.png)
This deployment option is used in corporate networks where end users can be identified by their individual IP addresses at the point where SafeDNS Shield is deployed. Depending on whether the organization has its own caching DNS server, requests are forwarded to that server or to an external resolver, such as an ISP’s DNS or a public DNS service (e.g., 1.1.1.1 or 8.8.8.8).
### User Identification
**User Identification**
To apply filtering policies and to separate statistics on a per‑user basis, SafeDNS Shield must identify each end user. Identification is based on the source address of the DNS request and can be configured using one of the following methods:
- **IP address** – Use when each user has a unique IP address.
- **IP subnet** – Use when per‑user granularity is not required and all users in a subnet can share the same policy.
- **IP:port** – Use when multiple users share a single IP address (for example, behind NAT44 or CGNAT). The source port distinguishes individual users.
- **IP:port range** – Use when users can be identified by a range of source ports on a shared IP address.
The appropriate method depends on the network topology and the level of user separation required.
# Setup and requirements
### Product setup and support
##### Custom Local Deployment
Setup, maintenance, and support for an on-premises deployment are managed entirely by SafeDNS specialists, establishing a clear division of responsibilities. The client provides the required hardware and full remote access, after which SafeDNS performs the complete turnkey installation.
Following deployment, SafeDNS specialists work with the client to configure the initial filtering rules and provide training to enable the client’s staff to make future adjustments independently. A dedicated support line is available for clients using on-premises solutions.
##### VM Deployment via ISO Image
As an alternative to a physical server installation, SafeDNS Shield can be deployed as a virtual appliance by mounting the provided ISO image in a virtual machine. This method streamlines deployment in environments that rely on virtualization infrastructure.
### System requirements
The following specifications apply to a server running the SafeDNS Shield components. All deployments require Debian 12 (x86‑64).
##### DNS Proxy Module
Choose a configuration based on the expected peak query load.
CPU: Intel 12th‑generation or later, Intel Xeon Silver/Gold, or equivalent AMD Ryzen/Epyc.
##### ClickHouse Cluster (Statistics Storage)
The ClickHouse cluster stores and analyzes DNS request logs. A single node meets the following minimum:
- CPU: **6** cores (x86‑64)
- RAM: **16** GB
- Storage: **500** GB NVMe
- Expandable up to **6** TB depending on traffic volume and retention needs
*Example configuration for **75,000** QPS and one year of log retention:*
- **4** ClickHouse data nodes
- CPU: **6** cores
- RAM: **16** GB
- Storage: **6** TB NVMe
- **3** ClickHouse Keeper nodes (coordination service)
- CPU: **2** cores
- RAM: **4** GB
- Storage: **60** GB SSD
We recommend a minimum cluster of 4 data servers arranged as 2 shards × 2 replicas. This provides parallel read/write operations and redundancy. A load balancer distributes incoming statistics across the nodes.
For lower traffic volumes, a standalone ClickHouse server can be deployed without ClickHouse Keeper, eliminating the need for the coordination layer.
# Miscellaneous
### Working with statistics
The DNS Proxy generates binary logs, which are stored directly on the SafeDNS Shield server. A dedicated parsing module processes these logs and exports the resulting data to an external DBMS for analysis and report generation. The module includes a connector for ClickHouse, which provides the best performance for this data type, but logs can also be exported to other databases if required.
The local binary log storage acts as a buffer: if the connection to ClickHouse is temporarily lost, logs generated during the outage are retained on disk and automatically exported once connectivity is restored. No data is lost during short interruptions, provided the local storage on the Shield server does not become completely full.
Although the statistics module is not essential for the core filtering functionality, it is indispensable for assessing system performance and investigating incidents effectively.
### Note on HTTPS block pages
To display the built‑in block page for HTTPS requests, the SafeDNS root certificate must be added to the trusted certificate store on every end user device. Without the certificate, web browsers cannot validate the block page’s TLS certificate; instead of the block page, users will see a TLS/SSL error. Access to the requested resource will still be denied.
Displaying the block page over HTTP does not require the certificate.
If an externally hosted block page is used, certificate requirements depend on your own hosting configuration.
# REST API overview
SafeDNS Shield filtering configuration is managed through its REST API. The API address is deployment-specific. The default management API port is `8080`, but the host, protocol, and port may be changed during deployment.
Use the following placeholder throughout this guide:
```text
= http[s]://:
```
For example:
```text
http://192.0.2.10:8080
```
Access is normally restricted to source addresses approved during deployment.
## Using the API
**Authentication**
All client-facing API requests require an HTTP bearer token.
```http
Authorization: Bearer
Content-Type: application/json
```
Example:
```bash
curl \
--header "Authorization: Bearer " \
--header "Content-Type: application/json" \
"/profiles/"
```
Use the token and management API address assigned to the Shield deployment.
**General behavior**
- Successfully completed configuration changes take effect immediately. No service restart or separate activation request is required.
- Successful create operations normally return `201 Created`.
- Successful update and retrieval operations normally return `200 OK`.
- Successful deletion and initialization operations return `204 No Content` with no response body.
- Invalid request data may return `422 Unprocessable Entity` with validation details.
- IPv4 addresses are supplied as dotted-decimal strings in request bodies, but some resource paths identify an IPv4 address by its unsigned integer representation.
- The examples use trailing slashes where they appear in the API specification.
## Profiles and filtering
A filtering profile combines category rules, application rules, block-page behavior, and several profile-level options.
**Profile fields**
| Field | Type | Description |
|---|---|---|
| `id` | integer | Client-supplied profile identifier. Required when creating a profile. |
| `page_id` | integer or `null` | Identifier of the block page assigned to the profile. |
| `white_list_only` | boolean | When enabled, only domains on the allowlist and explicitly allowed applications are permitted. Default: `false`. |
| `empty_dns_answer` | boolean | When enabled, Shield returns an empty DNS answer for a blocked domain instead of directing the client to a block page. Default: `false`. |
| `appaware_priority_over_bwlists` | boolean | When enabled, application rules take priority over explicit domain allow/deny-list rules. Default: `false`. |
A profile request also supports:
| Field | Type | Description |
|---|---|---|
| `cat_ids` | array of integers | Complete collection of filtering category IDs assigned to the profile. |
| `apps` | array of objects | Complete collection of application rules assigned to the profile. |
Each application rule contains:
```json
{
"app_id": 12,
"status": "deny"
}
```
Supported statuses are:
- `deny` — blocks domains associated with the application.
- `allow` — explicitly permits resolution of domains associated with the application, including when those domains would otherwise be blocked by the profile's category rules.
Application IDs can be obtained from:
```text
GET /app_aware/application/
```
Category IDs are listed in the [SafeDNS category reference](https://docs.safedns.com/books/installation-guides/page/list-of-safedns-categories).
**Replacement semantics**
When `cat_ids` or `apps` is included in:
```text
PATCH /profiles/{profile_id}
```
it replaces the complete existing collection. It is not merged with the current configuration.
- Omitting `cat_ids` leaves the category collection unchanged.
- Sending `"cat_ids": []` removes all category assignments.
- Omitting `apps` leaves the application-rule collection unchanged.
- Sending `"apps": []` removes all application rules.
**Initial configuration example**
The `/init/` operation creates the initial Shield configuration in one request.
- **Method:** `POST`
- **URL:** `/init/`
```json
{
"blockpages": [
{
"id": 1,
"type": 0
},
{
"id": 2,
"type": 1
}
],
"profiles": [
{
"profile": {
"id": 1,
"page_id": 1,
"white_list_only": false,
"empty_dns_answer": false,
"appaware_priority_over_bwlists": false
},
"cat_ids": [3, 4, 12],
"apps": [
{
"app_id": 1,
"status": "deny"
},
{
"app_id": 12,
"status": "deny"
},
{
"app_id": 93,
"status": "deny"
}
]
}
],
"bw_lists": [
{
"profile_id": 1,
"type": "deny",
"domains": [
"example1.com",
"example2.com",
"example3.com"
]
}
],
"napts": [],
"nets": [
{
"ip": "100.100.100.100",
"profile_id": 1,
"prefix_len": 32
},
{
"ip": "100.110.110.0",
"profile_id": 1,
"prefix_len": 24
},
{
"ip": "100.120.0.0",
"profile_id": 1,
"prefix_len": 16
}
],
"nets6": []
}
```
All six top-level arrays are required. Include an empty array when a resource type is not used:
- `blockpages`
- `profiles`
- `bw_lists`
- `napts`
- `nets`
- `nets6`
The example creates:
1. Two block-page records:
- Type `0`: default block page.
- Type `1`: custom block page.
2. Profile `1`, assigned to block page `1`.
3. Three blocked content/security categories.
4. Three denied applications.
5. Three explicitly denied domains.
6. One IPv4 host assignment and two IPv4 subnet assignments.
Custom block-page content is configured outside the Shield REST API. The API only creates and assigns the block-page record.
A successful initialization returns:
```text
204 No Content
```
## Profile configuration examples
**Modifying filtering categories**
To change categories assigned to a profile, send the complete desired category collection.
The following request replaces the existing categories of profile `1` with six categories:
- **Method:** `PATCH`
- **URL:** `/profiles/1`
```json
{
"cat_ids": [3, 4, 12, 66, 70, 71]
}
```
Because `apps` and `profile` are omitted, only the category collection is changed.
To remove all category assignments:
```json
{
"cat_ids": []
}
```
**Replacing application rules for a profile**
Application rules can be replaced together through the profile endpoint.
- **Method:** `PATCH`
- **URL:** `/profiles/1`
```json
{
"apps": [
{
"app_id": 1,
"status": "deny"
},
{
"app_id": 12,
"status": "allow"
}
]
}
```
This request removes any other application rules previously assigned to profile `1`. It denies application `1` and explicitly permits domains associated with application `12`, even if category rules would otherwise block them.
To remove all application rules:
```json
{
"apps": []
}
```
**Managing individual application rules**
**Retrieve the application catalogue**
- **Method:** `GET`
- **URL:** `/app_aware/application/`
Example response:
```json
[
{
"id": 1,
"name": "Application name"
}
]
```
**Retrieve all application rules for a profile**
- **Method:** `GET`
- **URL:** `/profile/1/app_aware`
Example response:
```json
[
{
"profile_id": 1,
"app_id": 12,
"status": "allow"
}
]
```
**Add one application rule**
- **Method:** `POST`
- **URL:** `/profile/1/app_aware`
```json
{
"app_id": 12,
"status": "allow"
}
```
**Add several application rules with the same status**
- **Method:** `POST`
- **URL:** `/profile/1/app_aware/batch`
```json
{
"app_ids": [1, 12, 93],
"status": "deny"
}
```
**Delete an application rule**
The final path value is the application ID. The current OpenAPI parameter name is `app_aware_id`, but it identifies the same value as `app_id`.
- **Method:** `DELETE`
- **URL:** `/profile/1/app_aware/12`
No request body is required.
**Adding a domain to the allowlist**
To exempt a domain from category-based blocking, add it to the allowlist of the relevant profile.
- **Method:** `POST`
- **URL:** `/profile/1/bw_list`
```json
{
"type": "allow",
"domain": "example4.com"
}
```
**Adding domains to the denylist**
To block several domains directly, use the batch operation.
- **Method:** `POST`
- **URL:** `/profile/1/bw_list/batch`
```json
{
"type": "deny",
"domains": [
"example5.com",
"example6.com",
"example7.com",
"example8.com",
"example9.com"
]
}
```
**Allow/deny-list storage limitation**
Shield stores allowlist and denylist domains as hashes. The API therefore cannot retrieve or enumerate the original domain names after they have been submitted.
API clients should retain their own copy of configured allowlists and denylists when later inspection, reconciliation, or synchronization is required.
Update and delete operations still accept the original domain name. Shield calculates its hash internally to locate the stored rule.
**Creating a new filtering profile**
- **Method:** `POST`
- **URL:** `/profiles/`
```json
{
"profile": {
"id": 2,
"page_id": 1,
"white_list_only": false,
"empty_dns_answer": false,
"appaware_priority_over_bwlists": false
},
"cat_ids": [3, 4, 12, 13, 66, 70, 71],
"apps": [
{
"app_id": 1,
"status": "deny"
},
{
"app_id": 12,
"status": "deny"
},
{
"app_id": 93,
"status": "deny"
}
]
}
```
This creates profile `2`, assigns block page `1`, enables the listed filtering categories, and adds three denied application rules.
## Subscriber assignments
**Assigning an IPv4 address or subnet**
To assign an IPv4 host to profile `1`, create a `/32` network record.
- **Method:** `POST`
- **URL:** `/net/`
```json
{
"ip": "100.100.100.101",
"profile_id": 1,
"prefix_len": 32
}
```
To assign a `/24` subnet:
```json
{
"ip": "100.100.101.0",
"profile_id": 1,
"prefix_len": 24
}
```
Supported IPv4 prefix lengths are `/10` through `/32`.
**Retrieve all IPv4 assignments**
- **Method:** `GET`
- **URL:** `/net/`
Example response:
```json
[
{
"ip": "100.100.100.101",
"profile_id": 1,
"prefix_len": 32
},
{
"ip": "100.100.101.0",
"profile_id": 1,
"prefix_len": 24
}
]
```
**IPv4 integer representation**
Individual IPv4 resource paths identify an address by its unsigned 32-bit integer representation.
For example:
```text
100.100.100.101 = 1684300901
100.100.101.0 = 1684301056
```
Python conversion example:
```python
from ipaddress import IPv4Address
int_ip = int(IPv4Address("100.100.100.101"))
print(int_ip) # 1684300901
```
**Reassign an IPv4 address or subnet**
- **Method:** `PATCH`
- **URL:** `/net/1684301056`
```json
{
"ip": "100.100.101.0",
"profile_id": 2,
"prefix_len": 24
}
```
**Remove an IPv4 address or subnet**
- **Method:** `DELETE`
- **URL:** `/net/1684301056`
No request body is required.
**Assigning an IPv6 address or subnet**
- **Method:** `POST`
- **URL:** `/net6/`
```json
{
"ip": "2001:db8:100::",
"profile_id": 1,
"prefix_len": 64
}
```
Supported IPv6 prefix lengths are `/16` through `/128`.
**Retrieve all IPv6 assignments**
- **Method:** `GET`
- **URL:** `/net6/`
Example response:
```json
[
{
"ip": "2001:db8:100::",
"profile_id": 1,
"prefix_len": 64
}
]
```
**Identifying subscribers through NAPT port ranges**
NAPT records assign different source-port ranges on a shared IPv4 address to different filtering profiles.
Port boundaries are inclusive. A range from `10000` to `19999` includes both port `10000` and port `19999`.
**Create a NAPT assignment**
- **Method:** `POST`
- **URL:** `/napt/`
```json
{
"ip": "203.0.113.10",
"lower_port_bound": 10000,
"upper_port_bound": 19999,
"profile_id": 1
}
```
Port values must be between `0` and `65535`. The complete port range is `0` through `65535`.
**Create several NAPT assignments**
- **Method:** `POST`
- **URL:** `/napt/batch`
```json
[
{
"ip": "203.0.113.10",
"lower_port_bound": 10000,
"upper_port_bound": 19999,
"profile_id": 1
},
{
"ip": "203.0.113.10",
"lower_port_bound": 20000,
"upper_port_bound": 29999,
"profile_id": 2
}
]
```
**Retrieve all NAPT assignments for an IPv4 address**
The path uses the integer representation of the IPv4 address.
- **Method:** `GET`
- **URL:** `/napt/3405803786`
`3405803786` is the integer representation of `203.0.113.10`.
**Delete several NAPT assignments**
Unlike individual NAPT resource paths, the batch-deletion body uses dotted-decimal IPv4 strings.
- **Method:** `DELETE`
- **URL:** `/napt/batch`
```json
[
{
"ip": "203.0.113.10",
"lower_port_bound": 10000,
"upper_port_bound": 19999
},
{
"ip": "203.0.113.10",
"lower_port_bound": 20000,
"upper_port_bound": 29999
}
]
```
`profile_id` is not included in the batch-deletion request.
## Profile schedules
A schedule temporarily switches one profile to another during specified periods.
The profile identified in the URL is the source profile. `target_profile_id` identifies the profile used during scheduled periods. A profile cannot target itself.
**Supported day formats**
Both weekday names and integers are accepted:
| Integer | Weekday |
|---:|---|
| `0` | Monday |
| `1` | Tuesday |
| `2` | Wednesday |
| `3` | Thursday |
| `4` | Friday |
| `5` | Saturday |
| `6` | Sunday |
Weekday names must be lowercase:
```text
monday, tuesday, wednesday, thursday, friday, saturday, sunday
```
Examples in this guide use weekday names for readability.
Times use `HH:MM` format and must fall on 30-minute boundaries, such as `08:00`, `12:30`, or `18:00`. `00:00` represents the start of a day and `24:00` represents the end of a day.
**Create a schedule**
- **Method:** `POST`
- **URL:** `/profile/1/schedule`
```json
{
"target_profile_id": 2,
"periods": [
{
"start": {
"day": "monday",
"time": "18:00"
},
"end": {
"day": "tuesday",
"time": "08:00"
}
},
{
"start": {
"day": 5,
"time": "00:00"
},
"end": {
"day": 5,
"time": "24:00"
}
}
]
}
```
This example switches profile `1` to profile `2` from Monday evening through Tuesday morning and for the whole of Saturday.
**Update a schedule**
- **Method:** `PATCH`
- **URL:** `/profile/1/schedule`
To change the target profile for all existing periods:
```json
{
"target_profile_id": 3
}
```
To replace all existing periods:
```json
{
"periods": [
{
"start": {
"day": "friday",
"time": "18:00"
},
"end": {
"day": "monday",
"time": "08:00"
}
}
]
}
```
When `periods` is supplied, all previously configured periods are deleted and replaced by the submitted collection.
**Delete a schedule**
- **Method:** `DELETE`
- **URL:** `/profile/1/schedule`
No request body is required.
## Block pages
Block-page records use two types:
| Type | Meaning |
|---:|---|
| `0` | Default block page |
| `1` | Custom block page |
Example creation request:
- **Method:** `POST`
- **URL:** `/blockpage/`
```json
{
"id": 2,
"type": 1
}
```
Custom block-page content is configured outside the Shield REST API.
# REST API reference
This reference describes the client-facing operations exposed by the current SafeDNS Shield REST API.
## Using the API
**Base URL**
SafeDNS Shield does not have a universal API hostname. The management API address is assigned during deployment.
```text
= http[s]://:
```
The default management API port is `8080`, but it may be changed for a particular deployment.
**Authentication**
All operations in this reference require HTTP bearer authentication.
```http
Authorization: Bearer
Content-Type: application/json
```
Example:
```bash
curl \
--header "Authorization: Bearer " \
--header "Content-Type: application/json" \
"/profiles/"
```
Access may additionally be restricted by source IP address according to the deployment configuration.
**General conventions**
**Immediate application**
Successfully completed changes take effect immediately. No service restart, reload, or separate activation operation is required.
**Success status codes**
| Status | Typical use |
|---:|---|
| `200 OK` | Successful retrieval or update |
| `201 Created` | Successful resource creation |
| `204 No Content` | Successful deletion or initialization; no response body |
**Validation errors**
Invalid request data may return `422 Unprocessable Entity`.
Example response:
```json
{
"detail": [
{
"loc": [
"body",
"field_name"
],
"msg": "Validation error message",
"type": "validation_error"
}
]
}
```
The current OpenAPI specification formally describes validation errors but does not provide complete response schemas for every possible authentication, authorization, conflict, or not-found condition.
**IPv4 representations**
IPv4 addresses appear in two forms:
- **Dotted-decimal string**, for example `"100.100.100.101"`, in request and response bodies.
- **Unsigned 32-bit integer**, for example `1684300901`, in individual IPv4 and NAPT resource paths.
Python conversion example:
```python
from ipaddress import IPv4Address
int_ip = int(IPv4Address("100.100.100.101"))
ip = str(IPv4Address(1684300901))
```
**Category IDs**
Filtering profiles refer to categories by numeric `cat_ids`. See the [SafeDNS category reference](https://docs.safedns.com/books/installation-guides/page/list-of-safedns-categories).
**Application IDs**
Application IDs can be retrieved through:
```text
GET /app_aware/application/
```
**Allow/deny-list storage**
Shield stores allowlist and denylist domains as hashes. The original domain names cannot be retrieved or enumerated through the API after submission.
Clients that need to inspect or synchronize these lists must retain their own copy of the original domains. Update and delete requests still use the original domain name; Shield calculates the corresponding hash internally.
## Endpoint summary
| Group | Method | Path | Purpose |
|---|---|---|---|
| Initialization | `POST` | `/init/` | Create the initial configuration in one request |
| Profiles | `GET` | `/profiles/` | Retrieve all profiles |
| Profiles | `POST` | `/profiles/` | Create a profile |
| Profiles | `GET` | `/profiles/{profile_id}` | Retrieve one profile |
| Profiles | `PATCH` | `/profiles/{profile_id}` | Update a profile and replace selected collections |
| Profile applications | `GET` | `/profile/{profile_id}/app_aware` | Retrieve application rules for a profile |
| Profile applications | `POST` | `/profile/{profile_id}/app_aware` | Add one application rule |
| Profile applications | `POST` | `/profile/{profile_id}/app_aware/batch` | Add several application rules with one status |
| Profile applications | `DELETE` | `/profile/{profile_id}/app_aware/{app_id}` | Delete an application rule |
| Application catalogue | `GET` | `/app_aware/application/` | Retrieve all available applications |
| Block pages | `GET` | `/blockpage/` | Retrieve all block-page records |
| Block pages | `POST` | `/blockpage/` | Create a block-page record |
| Block pages | `GET` | `/blockpage/{page_id}` | Retrieve one block-page record |
| Block pages | `PATCH` | `/blockpage/{page_id}` | Update a block-page record |
| Block pages | `DELETE` | `/blockpage/{page_id}` | Delete a block-page record |
| Domain lists | `POST` | `/profile/{profile_id}/bw_list` | Add one allowlist or denylist domain |
| Domain lists | `POST` | `/profile/{profile_id}/bw_list/batch` | Add several allowlist or denylist domains |
| Domain lists | `PATCH` | `/profile/{profile_id}/bw_list/{domain}` | Change a stored domain rule |
| Domain lists | `DELETE` | `/profile/{profile_id}/bw_list/{domain}` | Delete a stored domain rule |
| IPv4 networks | `GET` | `/net/` | Retrieve all IPv4 assignments |
| IPv4 networks | `POST` | `/net/` | Create an IPv4 assignment |
| IPv4 networks | `GET` | `/net/{int_ip}` | Retrieve an IPv4 assignment |
| IPv4 networks | `PATCH` | `/net/{int_ip}` | Update an IPv4 assignment |
| IPv4 networks | `DELETE` | `/net/{int_ip}` | Delete an IPv4 assignment |
| IPv6 networks | `GET` | `/net6/` | Retrieve all IPv6 assignments |
| IPv6 networks | `POST` | `/net6/` | Create an IPv6 assignment |
| IPv6 networks | `GET` | `/net6/{ipv6}` | Retrieve an IPv6 assignment |
| IPv6 networks | `PATCH` | `/net6/{ipv6}` | Update an IPv6 assignment |
| IPv6 networks | `DELETE` | `/net6/{ipv6}` | Delete an IPv6 assignment |
| NAPT | `POST` | `/napt/` | Create a NAPT assignment |
| NAPT | `POST` | `/napt/batch` | Create several NAPT assignments |
| NAPT | `GET` | `/napt/{int_ip}` | Retrieve all NAPT assignments for an IPv4 address |
| NAPT | `GET` | `/napt/{int_ip}/{lower_port_bound}/{upper_port_bound}` | Retrieve one NAPT assignment |
| NAPT | `PATCH` | `/napt/{int_ip}/{lower_port_bound}/{upper_port_bound}` | Update one NAPT assignment |
| NAPT | `DELETE` | `/napt/{int_ip}/{lower_port_bound}/{upper_port_bound}` | Delete one NAPT assignment |
| NAPT | `DELETE` | `/napt/batch` | Delete several NAPT assignments |
| Schedules | `GET` | `/profile/{profile_id}/schedule` | Retrieve a profile schedule |
| Schedules | `POST` | `/profile/{profile_id}/schedule` | Create a profile schedule |
| Schedules | `PATCH` | `/profile/{profile_id}/schedule` | Update a profile schedule |
| Schedules | `DELETE` | `/profile/{profile_id}/schedule` | Delete a profile schedule |
## Data models
**Profile object**
```json
{
"id": 1,
"page_id": 1,
"white_list_only": false,
"empty_dns_answer": false,
"appaware_priority_over_bwlists": false
}
```
| Field | Type | Description |
|---|---|---|
| `id` | integer | Profile identifier. Required on creation. |
| `page_id` | integer or `null` | Assigned block-page identifier. |
| `white_list_only` | boolean | Allows only allowlisted domains and explicitly allowed applications. Default: `false`. |
| `empty_dns_answer` | boolean | Returns an empty DNS answer instead of a block-page response for blocked domains. Default: `false`. |
| `appaware_priority_over_bwlists` | boolean | Gives application rules priority over domain allow/deny lists. Default: `false`. |
**Profile with categories and applications**
```json
{
"profile": {
"id": 1,
"page_id": 1,
"white_list_only": false,
"empty_dns_answer": false,
"appaware_priority_over_bwlists": false
},
"cat_ids": [3, 4, 12],
"apps": [
{
"app_id": 12,
"status": "allow"
}
]
}
```
`cat_ids` contains filtering category IDs. `apps` contains application rules.
**Application rule**
```json
{
"app_id": 12,
"status": "allow"
}
```
| Field | Type | Description |
|---|---|---|
| `app_id` | integer | Application identifier. |
| `status` | string | `allow` or `deny`. Default in the schema: `deny`. |
Behavior:
- `deny` blocks domains associated with the application.
- `allow` permits resolution of application-associated domains even when category rules would otherwise block them.
**Application-rule response**
```json
{
"profile_id": 1,
"app_id": 12,
"status": "allow"
}
```
**Block-page object**
```json
{
"id": 1,
"type": 0
}
```
| Type | Meaning |
|---:|---|
| `0` | Default block page |
| `1` | Custom block page |
Custom block-page content is configured outside the REST API.
**IPv4 network object**
```json
{
"ip": "100.100.100.101",
"profile_id": 1,
"prefix_len": 32
}
```
| Field | Type | Constraints |
|---|---|---|
| `ip` | IPv4 string | Dotted-decimal IPv4 address or network address |
| `profile_id` | integer | Assigned filtering profile |
| `prefix_len` | integer | `10` through `32`; default `32` |
**IPv6 network object**
```json
{
"ip": "2001:db8:100::",
"profile_id": 1,
"prefix_len": 64
}
```
| Field | Type | Constraints |
|---|---|---|
| `ip` | IPv6 string | IPv6 address or network address |
| `profile_id` | integer | Assigned filtering profile |
| `prefix_len` | integer | `16` through `128`; default `128` |
**NAPT object**
```json
{
"ip": "203.0.113.10",
"lower_port_bound": 10000,
"upper_port_bound": 19999,
"profile_id": 1
}
```
| Field | Type | Constraints |
|---|---|---|
| `ip` | IPv4 string | Dotted-decimal IPv4 address |
| `lower_port_bound` | integer | `0` through `65535`; default `0` |
| `upper_port_bound` | integer | `0` through `65535`; default `65535` |
| `profile_id` | integer | Assigned filtering profile |
Port boundaries are inclusive.
**Schedule object**
```json
{
"target_profile_id": 2,
"periods": [
{
"start": {
"day": "monday",
"time": "18:00"
},
"end": {
"day": "tuesday",
"time": "08:00"
}
}
]
}
```
`day` accepts either a lowercase weekday name or an integer:
| Integer | Weekday |
|---:|---|
| `0` | Monday |
| `1` | Tuesday |
| `2` | Wednesday |
| `3` | Thursday |
| `4` | Friday |
| `5` | Saturday |
| `6` | Sunday |
Times use `HH:MM` and must be divisible into 30-minute intervals. `00:00` and `24:00` are supported day boundaries.
## Initialization
**Initialize configuration**
```text
POST /init/
```
Creates the initial Shield configuration from a single request containing block pages, profiles, domain rules, NAPT assignments, IPv4 networks, and IPv6 networks.
**Request body**
All six top-level arrays are required, including arrays that are empty.
```json
{
"blockpages": [
{
"id": 1,
"type": 0
}
],
"profiles": [
{
"profile": {
"id": 1,
"page_id": 1,
"white_list_only": false,
"empty_dns_answer": false,
"appaware_priority_over_bwlists": false
},
"cat_ids": [3, 4, 12],
"apps": [
{
"app_id": 12,
"status": "deny"
}
]
}
],
"bw_lists": [
{
"profile_id": 1,
"type": "deny",
"domains": [
"example1.com",
"example2.com"
]
}
],
"napts": [],
"nets": [
{
"ip": "100.100.100.101",
"profile_id": 1,
"prefix_len": 32
}
],
"nets6": []
}
```
**Success response**
```text
204 No Content
```
## Profiles
**Retrieve all profiles**
```text
GET /profiles/
```
Returns all profiles, including profile settings, category IDs, and application rules.
**Success response**
```text
200 OK
```
```json
[
{
"profile": {
"id": 1,
"page_id": 1,
"white_list_only": false,
"empty_dns_answer": false,
"appaware_priority_over_bwlists": false
},
"cat_ids": [3, 4, 12],
"apps": [
{
"app_id": 12,
"status": "deny"
}
]
}
]
```
**Create a profile**
```text
POST /profiles/
```
**Request body**
```json
{
"profile": {
"id": 2,
"page_id": 1,
"white_list_only": false,
"empty_dns_answer": false,
"appaware_priority_over_bwlists": false
},
"cat_ids": [3, 4, 12, 13],
"apps": [
{
"app_id": 12,
"status": "allow"
},
{
"app_id": 93,
"status": "deny"
}
]
}
```
**Success response**
```text
201 Created
```
The response body contains the created profile with its categories and application rules.
**Retrieve a profile**
```text
GET /profiles/{profile_id}
```
**Path parameters**
| Parameter | Type | Description |
|---|---|---|
| `profile_id` | integer | Profile identifier |
**Success response**
```text
200 OK
```
The response body uses the **Profile with categories and applications** model.
**Update a profile**
```text
PATCH /profiles/{profile_id}
```
Updates profile-level settings and optionally replaces the profile's complete category or application collections.
**Path parameters**
| Parameter | Type | Description |
|---|---|---|
| `profile_id` | integer | Profile identifier |
**Request body**
All top-level fields are optional. Include only the areas to be changed.
```json
{
"profile": {
"page_id": 2,
"white_list_only": false,
"empty_dns_answer": true,
"appaware_priority_over_bwlists": true
},
"cat_ids": [3, 4, 12, 66],
"apps": [
{
"app_id": 12,
"status": "allow"
}
]
}
```
**Collection replacement rules**
- When `cat_ids` is present, it replaces the complete existing category collection.
- `"cat_ids": []` removes all category assignments.
- When `apps` is present, it replaces the complete existing application-rule collection.
- `"apps": []` removes all application rules.
- Omitted collections remain unchanged.
**Success response**
```text
200 OK
```
The response body contains the updated profile with its current categories and application rules.
## Application catalogue and profile application rules
**Retrieve all available applications**
```text
GET /app_aware/application/
```
Returns the application catalogue used to obtain valid `app_id` values.
**Success response**
```text
200 OK
```
```json
[
{
"id": 12,
"name": "Application name"
}
]
```
**Retrieve all application rules for a profile**
```text
GET /profile/{profile_id}/app_aware
```
**Path parameters**
| Parameter | Type | Description |
|---|---|---|
| `profile_id` | integer | Profile identifier |
**Success response**
```text
200 OK
```
```json
[
{
"profile_id": 1,
"app_id": 12,
"status": "allow"
},
{
"profile_id": 1,
"app_id": 93,
"status": "deny"
}
]
```
**Add one application rule**
```text
POST /profile/{profile_id}/app_aware
```
**Path parameters**
| Parameter | Type | Description |
|---|---|---|
| `profile_id` | integer | Profile identifier |
**Request body**
```json
{
"app_id": 12,
"status": "allow"
}
```
`status` may be `allow` or `deny`. The schema default is `deny`, but clients should set the value explicitly.
**Success response**
```text
201 Created
```
```json
{
"profile_id": 1,
"app_id": 12,
"status": "allow"
}
```
**Add several application rules**
```text
POST /profile/{profile_id}/app_aware/batch
```
All submitted applications receive the same status.
**Request body**
```json
{
"app_ids": [1, 12, 93],
"status": "deny"
}
```
**Success response**
```text
201 Created
```
```json
[
{
"profile_id": 1,
"app_id": 1,
"status": "deny"
},
{
"profile_id": 1,
"app_id": 12,
"status": "deny"
},
{
"profile_id": 1,
"app_id": 93,
"status": "deny"
}
]
```
**Delete an application rule**
```text
DELETE /profile/{profile_id}/app_aware/{app_id}
```
The current OpenAPI document names the final parameter `app_aware_id`, but the API uses the application ID itself.
**Path parameters**
| Parameter | Type | Description |
|---|---|---|
| `profile_id` | integer | Profile identifier |
| `app_id` | integer | Application identifier |
**Success response**
```text
204 No Content
```
There is no request body.
To replace or change the complete application configuration predictably, use `PATCH /profiles/{profile_id}` with the full desired `apps` collection.
## Block pages
**Retrieve all block pages**
```text
GET /blockpage/
```
**Success response**
```text
200 OK
```
```json
[
{
"id": 1,
"type": 0
},
{
"id": 2,
"type": 1
}
]
```
**Create a block page**
```text
POST /blockpage/
```
**Request body**
```json
{
"id": 2,
"type": 1
}
```
`type` must be `0` or `1`.
**Success response**
```text
201 Created
```
```json
{
"id": 2,
"type": 1
}
```
**Retrieve a block page**
```text
GET /blockpage/{page_id}
```
**Path parameters**
| Parameter | Type | Description |
|---|---|---|
| `page_id` | integer | Block-page identifier |
**Success response**
```text
200 OK
```
The response body contains a block-page object.
**Update a block page**
```text
PATCH /blockpage/{page_id}
```
**Request body**
```json
{
"type": 0
}
```
**Success response**
```text
200 OK
```
The response body contains the updated block-page object.
**Delete a block page**
```text
DELETE /blockpage/{page_id}
```
**Success response**
```text
204 No Content
```
There is no request body.
## Domain allowlists and denylists
Shield stores submitted domains as hashes. There is no GET operation for listing the original domains in a profile's allowlist or denylist.
Supported rule types are:
- `allow`
- `deny`
Clients should always send `type` explicitly.
**Add one domain**
```text
POST /profile/{profile_id}/bw_list
```
**Path parameters**
| Parameter | Type | Description |
|---|---|---|
| `profile_id` | integer | Profile identifier |
**Request body**
```json
{
"type": "allow",
"domain": "example.com"
}
```
**Success response**
```text
201 Created
```
The API returns the stored database representation:
```json
{
"profile_id": 1,
"domain_hash": 123456789,
"cat_id": 0
}
```
**Add several domains**
```text
POST /profile/{profile_id}/bw_list/batch
```
**Request body**
```json
{
"type": "deny",
"domains": [
"example1.com",
"example2.com",
"example3.com"
]
}
```
**Success response**
```text
201 Created
```
The response is an array of stored database representations.
**Update a domain rule**
```text
PATCH /profile/{profile_id}/bw_list/{domain}
```
Changes the allow/deny state of a stored domain rule.
**Path parameters**
| Parameter | Type | Description |
|---|---|---|
| `profile_id` | integer | Profile identifier |
| `domain` | string | Original submitted domain |
**Request body**
The current API schema includes the domain and profile ID in the body as well as the path:
```json
{
"type": "allow",
"domain": "example.com",
"profile_id": 1
}
```
**Success response**
```text
200 OK
```
The response uses the stored domain-rule representation containing `profile_id`, `domain_hash`, and `cat_id`.
**Delete a domain rule**
```text
DELETE /profile/{profile_id}/bw_list/{domain}
```
**Path parameters**
| Parameter | Type | Description |
|---|---|---|
| `profile_id` | integer | Profile identifier |
| `domain` | string | Original submitted domain |
**Success response**
```text
204 No Content
```
There is no request body.
## IPv4 networks
Supported prefix lengths are `/10` through `/32`.
**Retrieve all IPv4 assignments**
```text
GET /net/
```
**Success response**
```text
200 OK
```
```json
[
{
"ip": "100.100.100.101",
"profile_id": 1,
"prefix_len": 32
},
{
"ip": "100.100.101.0",
"profile_id": 2,
"prefix_len": 24
}
]
```
**Create an IPv4 assignment**
```text
POST /net/
```
**Request body**
Host assignment:
```json
{
"ip": "100.100.100.101",
"profile_id": 1,
"prefix_len": 32
}
```
Subnet assignment:
```json
{
"ip": "100.100.101.0",
"profile_id": 1,
"prefix_len": 24
}
```
**Success response**
```text
201 Created
```
The response body contains the created IPv4 network object.
**Retrieve an IPv4 assignment**
```text
GET /net/{int_ip}
```
`int_ip` is the unsigned integer representation of the address or network address.
Example:
```text
GET /net/1684301056
```
retrieves the record identified by `100.100.101.0`.
**Success response**
```text
200 OK
```
The response body contains an IPv4 network object.
**Update an IPv4 assignment**
```text
PATCH /net/{int_ip}
```
**Request body**
```json
{
"ip": "100.100.101.0",
"profile_id": 2,
"prefix_len": 24
}
```
**Success response**
```text
200 OK
```
The response body contains the updated IPv4 network object.
**Delete an IPv4 assignment**
```text
DELETE /net/{int_ip}
```
**Success response**
```text
204 No Content
```
There is no request body.
## IPv6 networks
Supported prefix lengths are `/16` through `/128`.
**Retrieve all IPv6 assignments**
```text
GET /net6/
```
**Success response**
```text
200 OK
```
```json
[
{
"ip": "2001:db8:100::",
"profile_id": 1,
"prefix_len": 64
}
]
```
**Create an IPv6 assignment**
```text
POST /net6/
```
**Request body**
```json
{
"ip": "2001:db8:100::",
"profile_id": 1,
"prefix_len": 64
}
```
**Success response**
```text
201 Created
```
The response body contains the created IPv6 network object.
**Retrieve an IPv6 assignment**
```text
GET /net6/{ipv6}
```
**Path parameters**
| Parameter | Type | Description |
|---|---|---|
| `ipv6` | IPv6 string | IPv6 address or network address identifying the record |
**Success response**
```text
200 OK
```
The response body contains an IPv6 network object.
**Update an IPv6 assignment**
```text
PATCH /net6/{ipv6}
```
**Request body**
```json
{
"ip": "2001:db8:100::",
"profile_id": 2,
"prefix_len": 64
}
```
**Success response**
```text
200 OK
```
The response body contains the updated IPv6 network object.
**Delete an IPv6 assignment**
```text
DELETE /net6/{ipv6}
```
**Success response**
```text
204 No Content
```
There is no request body.
## NAPT assignments
NAPT assignments map inclusive source-port ranges on a shared IPv4 address to filtering profiles.
Port constraints:
- Minimum: `0`
- Maximum: `65535`
- Default lower bound: `0`
- Default upper bound: `65535`
- Both boundaries are included in the assignment.
Individual resource paths use integer `int_ip`. Request and response bodies use dotted-decimal `ip` strings.
**Create a NAPT assignment**
```text
POST /napt/
```
**Request body**
```json
{
"ip": "203.0.113.10",
"lower_port_bound": 10000,
"upper_port_bound": 19999,
"profile_id": 1
}
```
**Success response**
```text
201 Created
```
The response body contains the created NAPT object.
**Create several NAPT assignments**
```text
POST /napt/batch
```
**Request body**
```json
[
{
"ip": "203.0.113.10",
"lower_port_bound": 10000,
"upper_port_bound": 19999,
"profile_id": 1
},
{
"ip": "203.0.113.10",
"lower_port_bound": 20000,
"upper_port_bound": 29999,
"profile_id": 2
}
]
```
**Success response**
```text
201 Created
```
The response is an array of created NAPT objects.
**Retrieve all NAPT assignments for an IPv4 address**
```text
GET /napt/{int_ip}
```
Example:
```text
GET /napt/3405803786
```
`3405803786` is the integer representation of `203.0.113.10`.
**Success response**
```text
200 OK
```
```json
[
{
"ip": "203.0.113.10",
"lower_port_bound": 10000,
"upper_port_bound": 19999,
"profile_id": 1
},
{
"ip": "203.0.113.10",
"lower_port_bound": 20000,
"upper_port_bound": 29999,
"profile_id": 2
}
]
```
**Retrieve one NAPT assignment**
```text
GET /napt/{int_ip}/{lower_port_bound}/{upper_port_bound}
```
Example:
```text
GET /napt/3405803786/10000/19999
```
**Success response**
```text
200 OK
```
The response body contains one NAPT object.
**Update a NAPT assignment**
```text
PATCH /napt/{int_ip}/{lower_port_bound}/{upper_port_bound}
```
The path identifies the current record. The body contains the desired resulting values.
**Request body**
```json
{
"ip": "203.0.113.10",
"lower_port_bound": 10000,
"upper_port_bound": 19999,
"profile_id": 2
}
```
**Success response**
```text
200 OK
```
The response body contains the updated NAPT object.
**Delete one NAPT assignment**
```text
DELETE /napt/{int_ip}/{lower_port_bound}/{upper_port_bound}
```
**Success response**
```text
204 No Content
```
There is no request body.
**Delete several NAPT assignments**
```text
DELETE /napt/batch
```
The batch-deletion request uses dotted-decimal `ip` strings, not integer `int_ip` values. It does not include `profile_id`.
**Request body**
```json
[
{
"ip": "203.0.113.10",
"lower_port_bound": 10000,
"upper_port_bound": 19999
},
{
"ip": "203.0.113.10",
"lower_port_bound": 20000,
"upper_port_bound": 29999
}
]
```
**Success response**
```text
204 No Content
```
## Profile schedules
A schedule switches the profile identified by `{profile_id}` to `target_profile_id` during configured periods.
The source profile and target profile must be different.
**Day and time values**
`day` accepts either:
- A lowercase weekday name: `monday` through `sunday`.
- An integer from `0` through `6`, where `0` is Monday and `6` is Sunday.
`time` uses `HH:MM` format. Valid times fall on 30-minute boundaries. `00:00` and `24:00` are supported.
**Retrieve a schedule**
```text
GET /profile/{profile_id}/schedule
```
**Success response**
```text
200 OK
```
```json
{
"target_profile_id": 2,
"periods": [
{
"start": {
"day": "monday",
"time": "18:00"
},
"end": {
"day": "tuesday",
"time": "08:00"
}
}
]
}
```
**Create a schedule**
```text
POST /profile/{profile_id}/schedule
```
**Request body**
```json
{
"target_profile_id": 2,
"periods": [
{
"start": {
"day": "monday",
"time": "18:00"
},
"end": {
"day": "tuesday",
"time": "08:00"
}
},
{
"start": {
"day": 5,
"time": "00:00"
},
"end": {
"day": 5,
"time": "24:00"
}
}
]
}
```
**Success response**
```text
201 Created
```
The response body contains the created schedule.
**Update a schedule**
```text
PATCH /profile/{profile_id}/schedule
```
The request may update the target profile, the periods, or both.
**Change the target profile**
```json
{
"target_profile_id": 3
}
```
When only `target_profile_id` is supplied, it is changed for all existing periods.
**Replace all periods**
```json
{
"periods": [
{
"start": {
"day": "friday",
"time": "18:00"
},
"end": {
"day": "monday",
"time": "08:00"
}
}
]
}
```
When `periods` is supplied, all previously configured periods are deleted and replaced by the submitted collection.
**Success response**
```text
200 OK
```
The response body contains the updated schedule.
**Delete a schedule**
```text
DELETE /profile/{profile_id}/schedule
```
**Success response**
```text
204 No Content
```
There is no request body.
## Complete curl examples
**Retrieve profiles**
```bash
curl \
--request GET \
--header "Authorization: Bearer " \
--header "Accept: application/json" \
"/profiles/"
```
**Create an IPv4 assignment**
```bash
curl \
--request POST \
--header "Authorization: Bearer " \
--header "Content-Type: application/json" \
--data '{
"ip": "100.100.100.101",
"profile_id": 1,
"prefix_len": 32
}' \
"/net/"
```
**Replace profile categories and application rules**
```bash
curl \
--request PATCH \
--header "Authorization: Bearer " \
--header "Content-Type: application/json" \
--data '{
"cat_ids": [3, 4, 12, 66],
"apps": [
{
"app_id": 12,
"status": "allow"
},
{
"app_id": 93,
"status": "deny"
}
]
}' \
"/profiles/1"
```