This document describes the integration process of the ThreatSTOP DNS Defense with a BIND 9 DNS server running on TSCM.


This document describes the integration process of the ISC Bind 9 ThreatSTOP DNS Firewall server running on TSCM.

Setup proceedure summary:

  • Open a ThreatSTOP account if you have not already done so.
  • Using the Portal, configure a new device - Manufacturer: ISC and Model: BIND 9 (TSCM)
  • Run tsadmin add command to create the device. The device will automatically configure itself. (untouched Bind configuration files backed up to /opt/threatstop/etc/bind_stock_configs.tgz)
  • Configure the client machines to be protected to use the ThreatSTOP DNS Firewall for address resolution.


Current Version

# To check current module version(s) run
ts-client$ tsadmin version --all
ts-bind v1.10-01

Supported Systems

Operating System OS Provided Bind Version
Ubuntu 20.04 BIND 9.16

Device Settings

You will need the following two sets of settings to complete the installation. You can retrieve the RPZ Zone name, Policy TSIG Key name, Policy TSIG Key secret and Device ID via the settings of the device in the Admin Portal.



The ThreatSTOP TSCM Bind DNS Firewall requires a system that meets at least these specifications.

  • 2 GB of RAM
  • 10 GB of disk space
  • Time synchronized (NTP)


To retrieve its configuration and policy, and to upload log data, the machine needs the following connectivity:

  • DNS over UDP (Internal Clients -> DNS Firewall Device)
    • Inbound UDP port 53 [or whatever port you specify]
  • DNS over TCP
    • IP Range:
    • Outbound TCP port 53 or 5353
  • DNS over UDP (optional, but recommended for DNS notifications)
    • IP Range:
    • Inbound UDP port 53
    • Hostname:
    • IP range:
    • Outbound TCP port 443
  • NTP
    • Outbound UDP port 123

Setup instructions

The following steps will walk you through adding the ThreatSTOP TSCM Bind DNS Firewall device.

ThreatSTOP Portal setup

  • If you want to use a custom DNS Firewall policy, please read DNS Firewall Policies
  • Create a new Device Entry: Click on Devices and then on Add Device.
    • The Manufacturer is: ISC
    • The Model is: BIND 9 (TSCM)
    • TSCM Bind (This will create your policy and TSIG keys, you will continue the installation on the TSCM via command line wizard)
  • Select the DNS Firewall policy - either a pre-defined policy or a custom policy
  • Note: It can take up to 30 minutes for a new device to become available after it is created in the Portal. Once the device is available, its IP address will be recognized in the output of the following command:

The Admin Portal will display a form to enter the device settings described below and the links to retrieve the TSCM image.

  • Nickname: This is a mnemonic name used to identify the device. It can be set to any string (A-Z, 0-9, - and _). If you create multiple device entries, each entry must have a unique nickname. The Nickname will be used to identify the device on the TSCM and in the Reporting user interface.

  • Policy: Select a pre-defined policy or a customized policy. It must be an DNS Policy type.

  • IP Type: Access to the ThreatSTOP services is controlled in part using an ACL allowing the device IP to connect. If your device has a static public IP address (the most common case), select static. If your device has a dynamic public IP address, the ThreatSTOP services can lookup the IP address using a DNS fully-qualified name (FQDN).

  • Public IP address: In static mode, this is the public IP address of the TSCM. It is possible to configure multiple device entries with the same public IP address.

  • Note: An optional field to store a note of your choice about the device - location, identifiers, model…

Adding ISC Bind Device - TSCM CLI

You will be prompted for all required device settings listed below.

$ tsadmin add --type bind [device nickname]

TSCM CLI required settings

ThreatSTOP Portal Device Settings

Setting Value
Device ID Retrieved from device settings
DNS Server IP Address Zone masters retrieved from device settings
RPZ Zone Name Retrieved from device settings
Policy TSIG Key Name Retrieved from device settings
Policy TSIG Key Secret Retrieved from device settings

Bind specific settings

Setting Description
Trusted ACL Addresses allowed to query this DNS server. Space separated special Bind keywords (all, localhost, localnets), IP(s) or CIDR addresses i.e.
Bind Port The TCP port the TSCM should use for listening for DNS requests
Bind Mode Bind mode of operation (1 = Recursion only, 2 = Forwarder only)
Bind Forwarders (only if Bind mode set to forwarder only) Space separated DNS server IP addresses used to forward upstream queries i.e.

The TSCM device will produce Bind configuration files with the supplied settings after the setup wizard completes.

Testing / Troubleshooting

You can test the RPZ policy is working correctly by verifying a known blocked address like returns NXDOMAIN. Below is an example of running with the DNS Utility dig.

dig @[Bind Server IP or Hostname]
;; ->>HEADER<<- opcode: QUERY, status: NXDOMAIN, id: 5611
;; flags: qr rd ra; QUERY: 1, ANSWER: 0, AUTHORITY: 0, ADDITIONAL: 2

Below is an example using nslookup, found natively on Windows machines.

C:\Users> nslookup [Bind Server IP or Hostname]
Server:     [Bind Server Hostname]
Address:    [Bind Server IP]#53

** server can't find NXDOMAIN

Looking up a non-restricted website like should return its current IP. You can repeat this on any client using this device as a DNS server.

  • Check that a log entry was added to /var/log/threatstop/devices/[device name]/syslog
  • You can test connectivity to ThreatSTOP by running:
$ curl
Your IP address: <ip address>
Address is in the list of authorized hosts

You can verify the Bind configuration has no major syntax errors by running

sudo named-checkconf

Customizing your configuration

As of v1.05 we’ve added the ability for localized configuration. We’ve created three entry points where you can add configuration to extend the BIND configuration without directly modifying the configuration files we manage.

├── local.logging.conf
├── local.named.conf
└── local.options.conf
  • local.named.conf - This is where you would put any global settings, the root of the configuration such as view definitions.
  • local.logging.conf - This is where you would add any logging configuration. anything you would normally add into the logging { ... } section.
  • local.options.conf - This is where you add configuration options for named.conf.options, basically anything you need to add to the options { ... } section.

After making any change make sure you run named-check to verify your configuration file is read ok. In the example below we added a non-existent setting dnssec off; to the /etc/bind.local/local.options.conf and ran the named-checkconf application to see if it parses ok.

threatstop@tsclient:/etc$ named-checkconf /etc/bind/named.conf
/etc/bind.local/local.options.conf:1: unknown option 'dnssec'


  • Mon, 21 Dec 2020 09:09:00 (1.05-02) urgency=low
    • GS-2594 : Zone name update bugfix
  • Fri, 30 Oct 2020 09:56:00 (1.05-01) urgency=low
    • GS-2502 : setLock bugfix
  • Thu, 29 Oct 2020 11:56:00 (1.04-01) urgency=high
    • GS-2518 : mutex bugfix
  • Thu, 21 May 2020 14:06:00 (1.03-01) urgency=low
    • GS-2404 : Added localized bind configs, fixed auto-config bug
  • Fri, 17 Jan 2020 10:13:00 (1.02-01) urgency=low
    • GS-2187 : Reconfigure Support and update now forces zone xfer
    • GS-2088 : Package enhancements and logging adjustments for future OS support
  • Thu, 18 Jul 2019 16:46:00 (1.01-02) urgency=low
    • GS-1979 : updating telemetry
    • GS-2088 : updating syslog source
  • Fri, 05 Apr 2019 16:23:00 (1.01-01) urgency=low
    • GS-1958 : Maintenance release
  • Wed, 20 Feb 2019 09:51:00 (1.00-04) urgency=low
    • GS-1932 : bind options and validation all done in device module
  • Thu, 07 Feb 2019 09:34:00 (1.00-03) urgency=low
    • GS-1910 : disable listening on ipv6
  • Fri, 01 Feb 2019 16:44:00 (1.00-02) urgency=low
    • GS-1910 : fixed upstream dns port template issue. bind ctp updates not propogating. bind rndc reconfig on ctp update
  • Mon, 21 Jan 2019 16:03:00
    • GS-1881 : Updated writing ACL config

Additional Information