Skip to content

Config Reference

Config Push Protocol

Users can customize the information sent from the controller to get different settings based on their department. The information should include fields like guid, hostname, version, ip_addresses, mac_address, os, and label.

watchdog_config

Matching Priority

Watchdog evaluates the controller's payload against the rules in mapping.conf in a strict left-to-right priority order. The first condition that produces a match assigns the department; remaining (lower-priority) conditions are not evaluated.

┌─────────┐   ┌──────────┐   ┌──────────────┐   ┌──────────────┐   ┌──────┐
│  label  │ → │ hostname │ → │ ip_address   │ → │ mac_address  │ → │  os  │
└─────────┘   └──────────┘   └──────────────┘   └──────────────┘   └──────┘
  highest                                                            lowest
  priority                                                           priority

For each step in priority order, Watchdog checks every department in mapping.conf for a rule on that field. As soon as one department matches, the search stops and that department is returned. If two departments have a rule on the same field that both could match, the one declared first in mapping.conf wins.

  1. Label — exact, case-insensitive equality between the controller's label field and the department's label rule. Highest priority.
  2. Hostname — pattern match between the controller's hostname and the department's host rule. A wildcard (*) is allowed in the rule (e.g. newyork-*).
  3. IP Address — the controller's ip_addresses list is checked against the department's address CIDR. A match means at least one of the controller's IPs falls inside the CIDR.
  4. MAC Address — pattern match between the controller's mac_address and the department's mac rule. A wildcard (*) is allowed in the rule.
  5. Operating System — the controller's os is compared against the department's os rule. Lowest priority.

All comparisons are case-insensitive. If no rule on any field matches, no department is assigned and an empty configuration is returned.

Example Workflow of Matching

Here’s a simple example to illustrate how the matching process works:

  • Controller Information:
  • Label: "hr"
  • Hostname: "newyork-hr1"
  • IP Addresses: ["123.11.219.5"]
  • MAC Address: "23:ab:123:45:67:89"

  • OS: "linux"

  • Matching Process:

  • Label Matching: The system checks the label "hr". It finds that the HR department has a matching label, so it immediately selects the HR department.
  • Hostname, IP, MAC, and OS: Since the label matched, the system does not proceed to check the other conditions (hostname, IP, MAC, or OS).

The HR department is selected based on the label match, even though other conditions might also match.

mapping.conf

This file contains mappings for different departments, specifying conditions like the hostname pattern, label, operating system, IP address range, and MAC address pattern.

# mapping.conf
# File to define groups for the browsermon controllers
# based on any criteria (guid, hostname, mac, version, ip, os, label)

[Staff]
host=austin-*
label=staff
os=windows

[HR]
host=newyork-*
os=linux
label=hr
address=123.11.219.0/24
mac=23:ab:123:*

[Accounts]
host=sunnyvale-*
os=linux

[CEO]
host=chicago-ceo*
label=ceo
os=windows

watchdog.conf

Watchdog relies on the watchdog.conf configuration file for essential settings. Here are the key configuration parameters: 

[default]
mode=local
bmkey= 
authcode=
blacklist=guid
logdir=logs
loglevel=INFO
maxBytes=5242880
backupCount=5
limit=True
rate=100/m
allowedhosts=['*']
[eti]
eti_index_ttl=90
eti_host=eti.eunomatix.com
eti_port=443
[ucs]
ucs_updates=false
ucs_host=ucs.eunomatix.com
ucs_port=443
[proxy]
proxy_mode=false
http_proxy=http://10.10.10.10:1234
https_proxy=https://10.10.10.10:1234
[GunicornConfig]
watchdog_port=8900
certfile=./cert/server.crt
keyfile=./cert/server.key
sslconfig=/etc/watchdog/ssl-config.ini

Configuration Explanation

  • mode: Set the mode to either ‘local’ or ‘cloud’ based on your deployment.
  • bmkey: Provide the Base64-encoded license key.
  • authcode: Add the Base64-encoded authorization code.
  • blacklist: Selects how watchdog-blacklist.conf is interpreted. Accepted values are guid (block controllers whose GUID matches an entry) or ip (block controllers whose source IP falls inside any listed IP/CIDR). An invalid or missing value causes Watchdog to fail at startup. See the watchdog-blacklist.conf section below.
  • logdir: Defines the path to the log dir
  • loglevel: Set the desired log level. Set it to DEBUG if the program doesn’t work the intended way.
  • maxbytes: Set the rotating size of logs in Bytes (default: 5242880)
  • backupCount: Set the rotating copies count of the logs (default: 5)
  • limit: Enable the rate limiting.
  • rate: Give the rate at which API is accessible.
  • allowedhosts: List of hosts that can access default to all if leave empty
  • eti_index_ttl: Time-to-live (TTL) in days for Elasticsearch threat index before deletion (default: 90)
  • eti_host: Hostname or IP where the ETI API is running
  • eti_port: Port number the ETI API listens on
  • ucs_updates: Enable or disable daily UCS (URL Classification Service) updates. Should be set to false on airgapped systems. When enabled, the watchdog service will perform a daily sync with the UCS API. (default: false)
  • ucs_host: Hostname or IP where the UCS API is running
  • ucs_port: Port number the UCS API listens on
  • proxy_mode: Enable or disable proxy mode.
  • http_proxy: URL for http proxy server
  • https_proxy: URL for https proxy server
  • watchdog_port: Port number where watchdog runs
  • certfile: Path to the TLS server certificate. Default ./cert/server.crt. In the standard install this file is generated by scripts/init-pki.sh and is part of the shared PKI used by Watchdog, Kafka, and Elasticsearch — see Certificate Management.
  • keyfile: Path to the TLS private key. Default ./cert/server.key. Generated alongside server.crt by init-pki.sh.
  • sslconfig: Path to ssl-config.ini. This file controls the subject fields (CN, Organization, etc.) and the additional Subject Alternative Names (san.dns, san.ip) baked into the auto-generated TLS certificate. Set the SAN entries here if your BrowserMon controllers connect with strict TLS verification — see Certificate Management for details.

browsermon-watchdog.conf

This file defines the settings for each department, including the browser type, mode, schedule window, log directory, log mode, rotation interval, kafka_mode, eti_mode, ucs_mode, cache_ttl, and cache_max_size.

[HR]
browser=firefox
mode=scheduled
schedule_window=1m
logdir=/opt/browsermon/logs
logmode=json
rotation=1h
kafka_mode=false
eti_mode=false
ucs_mode=false
extension_read_mode = false
extensions_scheduler = 24h
cache_ttl=30d
cache_max_size=1000

[Accounts]
browser=chrome
mode=scheduled
schedule_window=1m
logdir=/opt/browsermon/logs
logmode=csv
rotation=1h
kafka_mode=true
eti_mode=false
ucs_mode=false
extension_read_mode = false
extensions_scheduler = 24h
cache_ttl=30d
cache_max_size=1000

[CEO]
browser=firefox
mode=scheduled
schedule_window=1m
logdir=C:\\browsermon\\history
logmode=csv
rotation=1h
kafka_mode=true
eti_mode=false
ucs_mode=false
extension_read_mode = false
extensions_scheduler = 24h
cache_ttl=30d
cache_max_size=1000

watchdog-blacklist.conf

Lists controllers that Watchdog will refuse to license. Blacklisted controllers receive a 403 response from /api/check-license/.

The file is interpreted according to the blacklist= value in watchdog.conf:

  • blacklist=guid — each entry is a controller GUID (UUIDv4)
  • blacklist=ip — each entry is a single IP address or a CIDR block; Watchdog blocks any controller whose source IP falls inside one of these ranges

Lines beginning with # and blank lines are ignored. Invalid entries (malformed UUID in guid mode, malformed CIDR in ip mode) are logged at ERROR level and dropped from the blacklist set — the controller they refer to will not be blocked. Grep watchdog.log for Invalid <mode> entry in blacklist after editing the file.

GUID mode example

# /etc/watchdog/watchdog-blacklist.conf
00000000-0000-4000-8000-000000000000
11111111-1111-4111-8111-111111111111

IP mode example

# /etc/watchdog/watchdog-blacklist.conf
10.0.0.5
192.168.10.0/24
203.0.113.0/24

The file is loaded once at Watchdog startup. Edits to watchdog-blacklist.conf require restarting Watchdog before they take effect.

Exposed Ports

The host-published ports for a full install:

Port Required by
8900/tcp All deployments
8092/tcp Deployments with Kafka mode enabled
1514/tcp Deployments with Kafka mode enabled (Grafana UI)
9200/tcp Deployments with Elasticsearch / ETI / UCS enabled