Nameserver Groups
Nameserver groups are ordered failover lists of DNS servers that resolvers query for reverse-DNS (PTR) lookups. A scan template in "Nameserver group" mode — or the global default in Admin › Settings — names one of these groups; the resolver group assigned to the template performs the lookups against these servers in order. Groups referenced by a template or by the global default cannot be deleted.
Inputs
| Name | Description | Allowed values | Default |
|---|---|---|---|
Name | Unique label for this group | Non-empty string, must be unique across nameserver groups | — |
Description | Optional free-text note about this group | Any text, max 10,000 characters | Empty |
Nameservers | The DNS servers to query, in failover order | One to eight entries; each an IP address or hostname plus a port | Port 53 per entry |
Query timeout (ms) | The most a resolver spends on one nameserver before trying the next — an upper bound: the resolver host's own resolv.conf retry options (attempts, per-try timeout) can end it sooner | 100–10,000 milliseconds | 2000 |
Fields & columns
| Name | Description |
|---|---|
Name | Editable inline — the group label. Links to the edit form. |
Description | Editable inline — optional note |
Nameservers | How many servers are in the list |
Timeout | The most a resolver spends on one nameserver, in milliseconds |
In use | Whether a scan template or the global default references this group |
How to
Give a scan template its own nameservers
- Create a nameserver group listing the servers that can answer PTR queries for the scanned networks.
- Create or open a resolver group whose resolvers can reach those servers.
- On the scan template, set Reverse DNS to "Nameserver group", pick this group and the resolver group.
Gotchas
- Each execution snapshots its group at start, and the dispatcher queues its lookups for the assigned resolver group; any online resolver in that group performs them against these servers.
- The list is a failover ORDER, not a pool: a resolver asks the first server and moves down only on timeout or error. A known limitation: the resolver's standard-library DNS client checks the host's own /etc/hosts before it ever dials a group member, so a static hosts-file entry for a scanned IP answers instead.
- Editing a group changes only FUTURE executions. Every execution snapshots the group it used, so its report stays historically true.
- A group used by a template or by the global default cannot be deleted — clear those references first.
- The word is always "nameserver" in this product; there is no "NS group".
API calls (6)
| Method | Path | Description |
|---|---|---|
| GET | /api/config/nameserver-groups | List all nameserver groups |
| POST | /api/config/nameserver-groups | Create a nameserver group |
| GET | /api/config/nameserver-groups/:id | Get one nameserver group with its ordered list |
| PUT | /api/config/nameserver-groups/:id | Update a nameserver group |
| DELETE | /api/config/nameserver-groups/:id | Delete a nameserver group (if unreferenced) |
| GET | /api/config/nameserver-groups/filter-values | Get available filter values for the table |
Related
- Resolvers — The workers that query these servers
- Resolver Groups — The resolvers that query these nameservers
- Scan Templates — Where a template chooses its reverse-DNS mode and nameserver group
- Settings — The global reverse-DNS default a template can inherit