Settings¶
All settings live in danbyte/settings.py. Most are driven by env vars with
sensible dev defaults.
Database (Postgres-only)¶
DATABASES["default"] = {
"ENGINE": "django.db.backends.postgresql",
"NAME": os.getenv("DB_NAME", "danbyte"),
"USER": os.getenv("DB_USER", "danbyte"),
"PASSWORD": os.getenv("DB_PASSWORD", "danbyte"),
"HOST": os.getenv("DB_HOST", "127.0.0.1"),
"PORT": os.getenv("DB_PORT", "5432"),
"OPTIONS": {"connect_timeout": 10, "options": "-c jit=off"},
}
SQLite is no longer supported. Postgres 15+ is required for the
nulls_distinct=False unique constraint that makes the VRF model work.
JIT¶
Danbyte turns PostgreSQL's JIT compiler off for its own connections
(-c jit=off in the connection options). Its queries are short OLTP queries,
and JIT only costs time there: the full Devices list crossed jit_above_cost
and Postgres spent about 4 seconds compiling it on every request, against
0.15 s running it. The distro packages and the official postgres image both
ship with JIT on, so this applies to bundled, Docker and external databases
alike. Only Danbyte's sessions change; nothing is set on the server.
A connection pooler such as PgBouncer can refuse the options startup
parameter. Set DB_JIT=on in .env to leave it out (and the server's JIT
setting in force), or turn JIT off on the server instead:
Persistent connections¶
The gunicorn web app keeps each worker's database connection open for
DB_CONN_MAX_AGE seconds (default 60) instead of opening and
authenticating a new one per request; on a small API call that was most of
the cost (p50 20 ms → 7 ms on a local database). CONN_HEALTH_CHECKS is on,
so a connection the server dropped is replaced before a request uses it.
DB_CONN_MAX_AGE=0 restores a connection per request.
Only the WSGI app does this: danbyte/wsgi.py marks the process before
settings load. daphne (WebSockets), runserver, the RQ workers and
management commands keep 0.
Size max_connections (Postgres default 100) for every process that holds
one at a time:
gunicorn workers (WEB_CONCURRENCY, default ≤ 8)
+ RQ workers (danbyte-workers and danbyte-fastlane, one per worker process)
+ daphne (one per open request it serves)
+ timers and management commands running at the same moment
+ headroom for psql, backups and upgrades (10 or so)
A connection that stays open is idle between requests, so persistent connections do not raise the peak: each gunicorn worker held one while it served a request before too. With a pooler (PgBouncer in transaction mode) in front, the pooler's own limits apply instead.
Tuning PostgreSQL¶
The installer leaves the distribution's PostgreSQL defaults in place:
shared_buffers = 128MB and work_mem = 4MB, sized for a small shared
host. Danbyte runs on whatever the server is configured with, but a large
tenant (thousands of devices, tens of thousands of interfaces and addresses)
reads its lists and roll-ups faster with more memory. Nothing in Danbyte sets
these; they belong to the host, so set them in postgresql.conf (or a file in
conf.d/) and restart PostgreSQL.
A starting point for a host that runs Danbyte and its database together:
| Setting | Starting value | Why |
|---|---|---|
shared_buffers |
25 % of RAM (e.g. 2GB on 8 GB) |
Keeps the hot tables and indexes in PostgreSQL's own cache |
effective_cache_size |
50-75 % of RAM | Tells the planner how much the OS caches too; indexes are chosen more readily |
work_mem |
16MB-32MB |
Per sort or hash per query; the natural-sort lists and facet counts sort in memory instead of on disk. Multiplied by concurrent queries, so stay modest |
maintenance_work_mem |
256MB |
Faster VACUUM, index builds and upgrade migrations |
random_page_cost |
1.1 on SSD/NVMe |
The default 4 assumes spinning disks and steers the planner away from indexes |
max_connections |
see Persistent connections | Every web worker, RQ worker and daphne holds one |
Check what a running server uses with SHOW shared_buffers; (and so on) in
psql. On a container install, pass the settings as command: arguments to
the postgres service (postgres -c shared_buffers=2GB -c work_mem=16MB).
Finding slow queries with pg_stat_statements¶
pg_stat_statements records every statement's call count and time, which is
the quickest way to see what a slow page costs the database. It ships with
PostgreSQL (the postgresql-contrib package on older distributions) and needs
a restart to load:
Then create the extension as a superuser in the postgres database, not
in Danbyte's: it records statements from every database either way, and kept
out of Danbyte's database it never ends up in a Danbyte backup. A restore runs
as the danbyte role, which may not create the extension, so a backup that
carries it would fail to restore.
CREATE EXTENSION IF NOT EXISTS pg_stat_statements;
-- The ten Danbyte statements that took the most time in total.
SELECT round(total_exec_time) AS ms, calls, round(mean_exec_time, 1) AS mean_ms,
left(query, 120) AS query
FROM pg_stat_statements
WHERE dbid = (SELECT oid FROM pg_database WHERE datname = 'danbyte')
ORDER BY total_exec_time DESC
LIMIT 10;
-- Start a fresh measurement.
SELECT pg_stat_statements_reset();
The extension is optional: no migration creates or needs it. Its cost is
small (a few percent of CPU on a busy server); turn it off again by removing
it from shared_preload_libraries.
Redis (REDIS_URL, REDIS_PASSWORD, REDIS_SOCKET)¶
Redis holds the cache, the job queues and the WebSocket layer. All three -
and every queue, discovery included - are built from one connection, read
from these variables (danbyte/redis_conf.py):
| Variable | Default | Purpose |
|---|---|---|
REDIS_URL |
- | The server: redis://host:port/db, rediss://… for TLS, or unix:///path/to/redis.sock?db=0. May carry user:password@. |
REDIS_SOCKET |
- | A unix socket path, instead of REDIS_URL. |
REDIS_HOST / REDIS_PORT |
localhost / 6379 |
The server when neither of the above is set. |
REDIS_USERNAME |
- | An ACL user (Redis 6+). Without it the password is the default user's (requirepass). |
REDIS_PASSWORD |
- | The password. Unset: no AUTH, as before. |
RQ_REDIS_DB |
0 |
The database the job queues use; a second install on the same Redis picks a spare one. |
Which wins. The server comes from REDIS_URL, else REDIS_SOCKET, else
REDIS_HOST/REDIS_PORT. The credentials come from the URL or from
REDIS_USERNAME/REDIS_PASSWORD; setting both is fine when they agree. The
cache uses the URL's database, the queues RQ_REDIS_DB, the WebSocket layer
database 0.
Refused at startup, with a message that names no password: REDIS_URL
together with REDIS_SOCKET; REDIS_URL and a REDIS_HOST/REDIS_PORT
that name another server (localhost, 127.0.0.1 and ::1 count as one);
REDIS_SOCKET with REDIS_HOST/REDIS_PORT; a URL password or user that
differs from REDIS_PASSWORD/REDIS_USERNAME; an unknown scheme or URL
option. Before 0.20 the cache read REDIS_URL while the queues and the
WebSocket layer read REDIS_HOST/REDIS_PORT, so a split like that sent
them to different servers.
TLS. A rediss:// URL verifies the server's certificate against the
system CAs. Options in the URL: ssl_ca_certs=/path/ca.pem (a private CA),
ssl_certfile / ssl_keyfile (a client certificate), ssl_ca_path,
ssl_check_hostname, and ssl_cert_reqs=none to turn verification off.
Secrets. The password never goes into a URL Danbyte builds: each
consumer gets it as a separate setting, which Django's error reports mask,
and messages name the server as redis://user:***@host. Percent-encode a
password inside REDIS_URL (@ → %40); REDIS_PASSWORD takes it as it
is. Turning a password on: Hardening → Redis
authentication.
# a password (requirepass)
REDIS_PASSWORD=…
# an ACL user over the local socket
REDIS_URL=unix:///run/redis/redis-server.sock?db=0
REDIS_USERNAME=danbyte
REDIS_PASSWORD=…
CORS¶
CORS_ALLOWED_ORIGINS = os.getenv(
"CORS_ALLOWED_ORIGINS", "http://localhost:3000"
).split(",")
CORS_EXPOSE_HEADERS = ["X-Danbyte-Unknown-Params", "Warning"]
A cross-origin client can read the two headers a list sets for query parameters it ignored (REST API).
DRF¶
The API is default-closed: a view with no explicit permission_classes
requires authentication, so the next forgotten viewset isn't world-open.
Intentionally-public endpoints (the share-link resolve) opt in with AllowAny
explicitly. Authentication is session cookie (SPA) or a scoped API token; there
is no JWT (it was dead surface with weak defaults).
JSON responses go through api.renderers.FastJSONRenderer. It renders with
orjson when that package is installed and with DRF's own JSONRenderer
otherwise, and both write the same bytes (dates, decimals, UUIDs and IP
objects through DRF's encoder; ?indent= and anything orjson refuses fall
back to the standard renderer). orjson is not a requirement yet, so a
normal install renders exactly as before.
REST_FRAMEWORK = {
"DEFAULT_AUTHENTICATION_CLASSES": [
"auth_api.token_auth.ApiTokenAuthentication",
"rest_framework.authentication.SessionAuthentication",
],
"DEFAULT_PERMISSION_CLASSES": ["rest_framework.permissions.IsAuthenticated"],
"DEFAULT_PAGINATION_CLASS": "api.pagination.StandardResultsSetPagination",
"PAGE_SIZE": API_PAGE_SIZE, # 100
}
A list request without ?page_size= answers one page of API_PAGE_SIZE
rows with a next link. A caller that wants more names it with
?page_size=, up to API_MAX_PAGE_SIZE; a larger value is cut to the cap,
so ?page_size= can't force an amplified, memory-heavy response. The
default is small because serializing 10,000 rows held a gunicorn worker for
seconds, and the cap is 2,000 because a handful of 10,000-row pages still
held every worker (see Pagination).
A request whose page_size is above API_LARGE_PAGE_THRESHOLD (1,000, the
most the web app asks for in one request) is a large page. One user may have
API_LARGE_PAGE_CONCURRENCY of them in flight, counted across the session
and every API token they own, so more tokens buy no more large pages; the
next answers 429 with Retry-After until one finishes. Each
large page holds a slot in Redis (the cache) with a two-minute expiry and
gives it back when the response is built, so a worker killed mid-request
frees its slot anyway. If Redis can't be reached the guard lets requests
through rather than refusing them.
| Setting | Env var | Default | Purpose |
|---|---|---|---|
API_PAGE_SIZE |
API_PAGE_SIZE |
100 |
Rows a list answers when the request names no page_size. A positive whole number. |
API_MAX_PAGE_SIZE |
API_MAX_PAGE_SIZE |
2000 |
The most rows ?page_size= can ask for in one response. A positive whole number, at least API_PAGE_SIZE; unset, it is 2,000 or API_PAGE_SIZE if that is larger. |
API_LARGE_PAGE_THRESHOLD |
API_LARGE_PAGE_THRESHOLD |
1000 |
A request whose page_size is above this is a large page. A positive whole number between API_PAGE_SIZE and API_MAX_PAGE_SIZE; unset, it is 1,000 kept within those two. |
API_LARGE_PAGE_CONCURRENCY |
API_LARGE_PAGE_CONCURRENCY |
2 |
Large pages one user, all of their tokens together, may have in flight at once. A positive whole number. |
API_MAX_TOKENS_PER_USER |
API_MAX_TOKENS_PER_USER |
25 |
Unexpired API tokens one user may hold. Creating one more answers 400 until one is revoked or expires; tokens a script run mints don't count. A positive whole number. |
API_STRICT_QUERY_PARAMS |
API_STRICT_QUERY_PARAMS |
on | A query parameter a list does not understand answers 400, naming it and the parameters the list takes. 0/false/no/off turns it off for the install: the list then answers as if the parameter were absent and names it in an X-Danbyte-Unknown-Params header. A request can still send ?strict=0 (or ?strict=1 when it is off). On since 0.20, off in 0.19 (REST API). |
A value that is not a positive whole number, a cap below the default page,
or a threshold outside the default page and the cap stops the service at start with an error naming the setting, rather than
serving something other than what was configured. Set them in the service
environment (.env, or the unit's Environment=) and restart the web
service.
The web app asks for what it needs: a table, picker or map that filters
in the browser walks the pages, 1,000 rows a request up to 10,000, so it
never asks for a large page (a read that is answered 429 is retried after
its Retry-After), and a
list page whose tenant holds more says so rather than looking complete (see
Very long lists).
Application flow requirements¶
An application flow requirement
can mean thousands of generated flows. The requirement dialog's preview
warns above FLOW_REQUIREMENT_WARN_PAIRS flows, and a requirement that
resolves to more than FLOW_REQUIREMENT_MAX_PAIRS is refused: it reads
Unresolved and writes nothing until it is narrowed with pairing or
address, or this is raised.
| Setting | Env var | Default | Purpose |
|---|---|---|---|
FLOW_REQUIREMENT_WARN_PAIRS |
FLOW_REQUIREMENT_WARN_PAIRS |
500 |
The preview warns above this many generated flows for one requirement. A positive whole number. |
FLOW_REQUIREMENT_MAX_PAIRS |
FLOW_REQUIREMENT_MAX_PAIRS |
5000 |
A requirement resolving to more flows is refused. A positive whole number, at least the warning. |
A value that is not a positive whole number, or a cap below the warning,
stops the service at start with an error naming the setting. Set them in
the service environment (.env, or the unit's Environment=) and restart
the web service and the workers.
DEBUG (default-closed)¶
DEBUG defaults to False - production must not accidentally run in debug
(tracebacks leak source/settings and ALLOWED_HOSTS is bypassed). Development
sets DEBUG=True explicitly in .env. With DEBUG off the app also refuses to
start on the shared dev DJANGO_SECRET_KEY or a missing MONITORING_SECRET_KEY
(see Secrets).
DEBUG controls only debug behaviour (tracebacks, ALLOWED_HOSTS). It does
not decide whether cookies are TLS-only - that's DANBYTE_HTTPS below.
TLS / transport hardening (DANBYTE_HTTPS)¶
Set this when the deployment really is served over TLS. It turns on the
app-level backstop: Secure session + CSRF cookies, HSTS, and an http→https
redirect. Defaults to False.
Don't enable it without TLS
A Secure cookie set over a plain-http:// origin is discarded by the
browser. The login POST succeeds, the session cookie is dropped, the next
request is anonymous - so the app bounces straight back to the login form
with no error message. If login silently loops, check this setting first.
This is deliberately independent of DEBUG: tying transport requirements to the
debug flag means changing the DEBUG default silently locks every plain-http
install out of login. scripts/install.sh configures nginx + TLS and writes
DANBYTE_HTTPS=True into .env (and backfills it on upgrade), so
installer-managed hosts stay hardened. Behind the shipped nginx, nginx sends
HSTS for every upstream and drops Django's copy (see
Security headers).
Static¶
STATICFILES_DIRS includes design/, so the mockup theme.js and
tokens.css are served at /static/theme.js and /static/tokens.css - used
by _shell.html.
Hosts¶
ALLOWED_HOSTS and CSRF_TRUSTED_ORIGINS are set in .env (see
.env.example), never in a unit file in the repo. The dev unit
services/danbyte-backend.service carries no hosts or credentials and
listens on 127.0.0.1:8000; Vite on :3000 proxies to it.
One path is answered for any host: /.well-known/acme-challenge/<token>,
so a CA can validate a name for the site certificate before that name is
added here. Everything else under an unlisted host is a 400. See
HTTP-01 and host names.
Backups (DANBYTE_BACKUP_DIR, DANBYTE_SKIP_BACKUP)¶
DANBYTE_BACKUP_DIR is where the default local backup target and the
restore work directory live. Default: <install>/../danbyte-backups on
systemd installs, /app/backups in the container stack. The directory is
created on the first backup, mode 0700.
DANBYTE_SKIP_BACKUP=1 lets the upgrade scripts continue without the
Before upgrade backup (they stop otherwise when the backup fails or
pg_dump is missing). See Backup and restore.
Scripts (DANBYTE_SCRIPT_SANDBOX)¶
DANBYTE_SCRIPT_SANDBOX sets how sandboxed scripts
are confined:
auto, the default: bubblewrap namespaces around Landlock wherebwrapworks, Landlock alone where it does not. The run log says which.bwrap: bubblewrap around Landlock, and a run is refused whenbwrapcannot run.landlock: Landlock alone, as in 0.17. Scripts keep the host network, so they can reach devices directly.none: unconfined, and each run log says so. Use it only on a host without Landlock, knowing a script author can then read what the service account can, including.env.
Every value except none refuses a run the host cannot Landlock. An
unknown value means auto. Under bubblewrap a script has no network but
the API. What each level blocks is in
Scripts.
Trusted scripts are never confined.
DANBYTE_INTERNAL_URL is where a script's SDK reaches the API. Default:
http://127.0.0.1:8000. When set, its host is added to ALLOWED_HOSTS so the
backend answers to it; WebSocket origins and the site's public name keep to
the ALLOWED_HOSTS you set. The Docker stack sets it to http://backend:8000.
Device 3D models (DEVICE_MODEL_MAX_BYTES)¶
DEVICE_MODEL_MAX_BYTES is the largest
3D model a device type or device
takes, in bytes. The default is 26214400 (25 MB); a larger upload is
refused with the limit in the message. Keep it under the web server's
client_max_body_size (512 MB in the shipped nginx templates).
Vulnerability data uploads (DANBYTE_VULN_IMPORT_MAX_BYTES)¶
DANBYTE_VULN_IMPORT_MAX_BYTES is the largest file a deployment admin may
upload as vulnerability data
(NVD feeds, OSV archives, Microsoft's monthly CVRF documents, KEV, EPSS), in bytes. The default is 536870912
(512 MB), which is also the shipped nginx client_max_body_size; raise both
together. The unpacked-content, record and archive limits are fixed and listed
on the feature page. Uploads wait in MEDIA_ROOT/vuln-imports/ until their
job has parsed them, then are deleted; the folder is not served under
/media/.
Microsoft data window (DANBYTE_VULN_MSRC_MONTHS)¶
DANBYTE_VULN_MSRC_MONTHS is how many months of Microsoft's monthly
security update documents the server fetch
reads, counting the current month. The default is 12; values are held to
1-36, and a value that is not a number stops the server at start. Each
month is 4 to 30 MB and Microsoft revises old months often, so most of the
window is read again on a weekly refresh: a longer window costs bandwidth
and time on every run. Windows builds are cumulative, so twelve months find
every fix a host that is patched at least once a year is missing.
PDF reports (DANBYTE_REPORT_JOB_TIMEOUT)¶
A PDF report too large to render within a request
renders in the background, as a job on the low queue.
DANBYTE_REPORT_JOB_TIMEOUT is that render's deadline in seconds (default
300); a report estimated past about 70% of it is refused.
DANBYTE_REPORT_JOB_KEEP is how long the finished PDF is kept for the user
who asked for it, in seconds (default 3600).
CAD drawings (DANBYTE_CAD_CONVERTER)¶
DANBYTE_CAD_CONVERTER is the absolute path of the program that turns a DWG
into DXF for floor-plan CAD drawings.
DXF needs nothing.
Default (unset or empty): vendor/cad/bin/dwg2dxf in the app directory, the
static LibreDWG build the release bundle installs (or make cad-tools
builds), when it is there and executable. Without it, DWG uploads are refused
with the steps to save the drawing as DXF instead. An explicit path always
wins; off refuses DWG even with the bundled converter present. The value is
resolved when the services start, so restart them after adding a converter.
Two programs are accepted, by file name:
dwg2dxffrom LibreDWG (GPLv3; Debian and Ubuntu do not package it). The release bundle ships it, see Installation; the Docker image builds the same and setsDANBYTE_CAD_CONVERTER=/usr/local/bin/dwg2dxf.ODAFileConverter, the ODA File Converter (free download from the Open Design Alliance; not redistributable, so never bundled). It runs withQT_QPA_PLATFORM=offscreen.
Anything else, a relative path, a missing or non-executable file, or one writable by everyone is refused. The converter runs on the worker host only, in the sandbox below, without a shell, with a scrubbed environment, a 5-minute timeout and memory and output-size limits; its DXF may be at most 256 MB. The setting is read from the environment only, never from the UI, and is kept in a configuration backup.
Converter sandbox (DANBYTE_CAD_SANDBOX)¶
The converter parses files anyone with change rights on a floor plan can upload, so it runs in a bubblewrap sandbox, the same one scripts use:
- its own user (
nobodyinside), pid, ipc, uts and network namespaces: no network at all, not even loopback to the database or Redis, and no other process to see or signal; - a read-only root that holds only the converter, the uploaded DWG
(read-only) and one output directory, the only place it can write. No
Danbyte directory,
.env, media, home directories,/procor/sys; - no capabilities,
no_new_privs, and Danbyte's seccomp filter that refuses unix sockets.
The bundled dwg2dxf is static, so that is all it sees. A dynamically linked
converter also sees the system directories (/usr, /lib, name and font
configuration) and its own install directory, read-only; a converter whose
directory contains the Danbyte directory is refused. The ODA File Converter
additionally gets a /proc of its own sandbox and an empty private /tmp,
which Qt needs; Danbyte does not test ODA in the sandbox.
DANBYTE_CAD_SANDBOX takes two values:
bwrap, the default: the converter always runs in the sandbox. A host wherebwrapis missing or cannot create user namespaces (kernel, AppArmor, or a container's seccomp profile) refuses DWG uploads, and the upload form andGET /api/floor-plans/drawing-support/say why. DXF is unaffected.off: the converter runs without the sandbox, under the limits alone, with the service account's files and network. A hostile DWG that exploits a converter bug then runs with the rights of the worker that holds the database credentials and the secret keys. Set it only if you accept that, for example to run an operator-chosen converter that fails in the sandbox.
Any other value means bwrap. The ezdxf reader that renders the DXF is pure
Python and runs in its own process under the same limits, outside the
sandbox.
Outbound requests (SSRF guard)¶
User-configured outbound URLs - webhooks, notification channels, automation
targets, device-type import URLs, virtualization sources (Proxmox, vCenter,
Cloud Director), Windows server connections, a public assistant provider, the
end-of-life data source, the
vulnerability data services and
mirrors (NVD, OSV, Microsoft's MSRC CVRF API, CISA KEV, FIRST EPSS), and
per-tenant SMTP/LDAP hosts - are
validated before each request: the host is resolved and rejected if it points at
a loopback / RFC1918 / link-local / 169.254.0.0/16 (cloud metadata) / ULA /
reserved address. This stops a tenant admin pointing a webhook (or a tenant SMTP
relay) at internal services and reading the response back - critical for the
cloud-hosted, multi-tenant deployments.
The guard is DNS-rebinding safe: the resolved public IP is pinned for the
actual connection (with SNI/Host preserved for TLS), so a hostname that
resolves public on the first lookup can't be swapped to 169.254.169.254 on the
connect. Redirects are never followed: a 3xx answer is an error, so a host
that passes the check cannot bounce the request to an internal address. When an
outbound proxy is set, NO_PROXY is matched against the configured hostname,
not the pinned IP. WinRM and the vCenter SOAP connection (host hardware) are
pinned the same way, with TLS verified against the configured hostname.
Operator-configured deployment-wide SMTP/LDAP hosts are trusted and
not guarded (an operator may legitimately point them at an internal relay); only
tenant-supplied hosts are checked. The SSO identity provider (OIDC issuer and
the endpoints its discovery document names, SAML metadata URL) is set by a
deployment admin and stays allowed on a private address, but each discovery
that resolves to one logs a warning on danbyte.sso; allow-listed addresses do
not warn.
If you need an internal target (e.g. an on-prem automation runner like the IaC runner), allow-list its address(es):
Comma-separated CIDRs/IPs whose resolved addresses are permitted. Empty by default (all internal addresses blocked).
ACME issuers are not behind this guard: an internal CA on a private address
is what an issuer is for, and only a user with the issuer add/change
grant can set its directory URL
(see Certificates).
CA trust for ACME issuers (REQUESTS_CA_BUNDLE)¶
An ACME issuer with Verify TLS on trusts, in this order, the bundle in
REQUESTS_CA_BUNDLE (or CURL_CA_BUNDLE) when the service environment
sets it to a file, else the operating system's trust store
(/etc/ssl/certs/ca-certificates.crt and the other distribution paths
OpenSSL reports), else Python's certifi roots - plus the issuer's own
CA certificate field. Before 0.20 only certifi was used, so a private
root added with update-ca-certificates was ignored and
REQUESTS_CA_BUNDLE=/etc/ssl/certs/ca-certificates.crt in .env was the
workaround. That line still works - it replaces the system store as the
base, and an issuer's CA certificate is still added on top - but it is no
longer needed. Details:
Private CAs and trust.
REQUESTS_CA_BUNDLE is read by every requests call in the process, not
just ACME; set it only when you want that.
Check-engine targets (central-runner SSRF)¶
The monitoring check engine runs both on remote outpost agents (deployed
inside a network to monitor internal hosts - reaching loopback/RFC1918 is the
point) and in the central server (where a tenant-defined check target of
127.0.0.1 or an RFC1918 neighbour is an SSRF oracle onto internal services).
The cloud-metadata endpoint (169.254.0.0/16) and the unspecified address are
refused everywhere. To also refuse loopback / RFC1918 / reserved targets on the
central runner - the posture for a cloud, multi-tenant deployment - set:
Default False, so a self-hosted deployment that monitors its own LAN from the
central box is unaffected. DANBYTE_SSRF_ALLOWLIST (above) also exempts its
CIDRs from this block. Outpost agents keep the permissive default regardless.
Discovery¶
Discovery - package inventory and service scans - is off unless the deployment allows it and a tenant admin turns it on. Every variable that changes it, with defaults, accepted values and effect, is on Discovery: settings:
| Variable | Default |
|---|---|
DANBYTE_DISCOVERY_ENABLED |
unset (the stored deployment switch decides) |
DANBYTE_DISCOVERY_WINRM_ALLOWED |
True |
DANBYTE_DISCOVERY_WINRM_CA_BUNDLE |
the system CA bundle |
DANBYTE_DISCOVERY_ALLOW_FIRST_USE_KEYS |
True |
DANBYTE_DISCOVERY_SCAN_MAX_RATE |
200 (held to 1-2000) |
DANBYTE_DISCOVERY_NMAP_ALLOWED |
True |
NMAP_BINARY |
unset (nmap on the service user's PATH) |
Runs go to the RQ queue discovery; the danbyte-inventory timer queues
scheduled ones (queue and timer).
The check-engine target policy above applies to every address Discovery
contacts from the server.
Security headers¶
Response hardening is applied at the nginx edge (see
deploy/nginx/danbyte.prod.conf.template), so it covers the SPA, API, and docs
uniformly and survives an app restart:
server_tokens off- no nginx version banner.- HSTS -
max-age=31536000; includeSubDomains. X-Content-Type-Options: nosniff,X-Frame-Options: SAMEORIGIN(also enforced by Django'sSECURE_CONTENT_TYPE_NOSNIFF/X_FRAME_OPTIONS), andframe-ancestors 'self'in the CSP. Other sites can't frame Danbyte; the topology report draws each saved view in a hidden frame of the map page, which needs the same origin to be allowed. A site you manage yourself withDENYorframe-ancestors 'none'leaves that report at Drawing….Referrer-Policy: same-origin, a restrictivePermissions-Policy, andCross-Origin-Opener-Policy/Cross-Origin-Resource-Policy: same-origin.- An enforced Content-Security-Policy with
report-uri /api/csp-report/.connect-srcallowsraw.githubusercontent.comandapi.github.comso the device-type import's Fetch with my browser option works, andvector.openstreetmap.orgfor the Site map's default vector tiles (a different vector source in Settings → Site map → Basemap needs its host added here by hand).worker-src 'self' blob:lets MapLibre run its bundled tile worker. Everything else stays same-origin. The SPA loads only same-origin bundled assets (no external scripts/styles/ fonts, noeval, bundled web workers; the presence WebSocket is same-origin), so the policy doesn't block anything it serves. Itsscript-src 'self' 'unsafe-inline' 'wasm-unsafe-eval'is the floor ('wasm-unsafe-eval'lets the bundled WebAssembly for 3D models and STEP/IGES compile, and allows noeval): every page also carries the frontend server's own policy with a fresh nonce and'strict-dynamic', which the browser enforces as well, so an injected script does not run (DANBYTE_CSP_MODE).style-src 'unsafe-inline'stays for the charts'<style>blocks. Any real-browser violation is POSTed to/api/csp-report/and logged to thedanbyte.csplogger, so tightening the policy later is observable rather than a silent breakage. The report endpoint is unauthenticated + CSRF-exempt (the browser sends no cookie/token) and only logs.
Django-side, SECURE_REFERRER_POLICY, SECURE_CONTENT_TYPE_NOSNIFF, and
X_FRAME_OPTIONS are set unconditionally (not gated on DEBUG) as defence in
depth for any path served without nginx in front, and DANBYTE_HTTPS=True adds
the same HSTS value for installs that terminate TLS somewhere else.
One owner per header. Behind the shipped nginx configs, nginx owns HSTS,
X-Frame-Options, X-Content-Type-Options, Referrer-Policy and
Cross-Origin-Opener-Policy: each location drops Django's copy with
proxy_hide_header and sends its own, so a browser gets one header with one
value. Without nginx, Django's copy is the only one. The Docker image's nginx
does the same for the headers it sets, and leaves HSTS to the backend
(DANBYTE_HTTPS), since it only has a self-signed certificate.
HSTS has no preload at either layer. Being on the browsers' preload list is
a decision for whoever owns the domain, and it is hard to undo; add it in your
own proxy if you want it.
API responses aren't cached. Every /api/ response to a signed-in caller
(session or API token) carries Cache-Control: private, no-store, so a browser
keeps no copy on disk after sign-out and a shared proxy keeps none at all
(core.middleware.ApiNoStoreMiddleware). A view that sets its own
Cache-Control keeps it - file downloads, 3D models and thumbnails choose
their own. Anonymous API responses, /media/, /static/ and the hashed
/assets/ are left to their own headers.
Your own nginx
A hand-written site that adds these headers needs the same
proxy_hide_header lines in each proxied location (or once at the server
level, repeated in any location that has its own proxy_hide_header).
Otherwise every Django response carries two copies.
Page script policy (DANBYTE_CSP_MODE)¶
The frontend server sends each HTML page a Content-Security-Policy of its
own, with a script nonce drawn for that page:
script-src 'nonce-…' 'strict-dynamic' 'self' 'unsafe-inline'; worker-src 'self' blob:; object-src 'none'; base-uri 'self'; report-uri /api/csp-report/.
| Variable | Default | Values |
|---|---|---|
DANBYTE_CSP_MODE |
enforce |
enforce, report (sent as Content-Security-Policy-Report-Only), off |
Read from the environment, else from .env, when the frontend starts;
restart danbyte-frontend-prod after changing it. Anything else enforces.
The Vite dev server defaults to off. Details and how to report a
violation: Hardening → Content-Security-Policy.
Logging¶
Console logging is on by default (django at INFO, rq.worker at INFO).
Suitable for journalctl --user -fu danbyte-backend.
Password reset (PASSWORD_RESET_ENABLED)¶
PASSWORD_RESET_ENABLED=true turns on self-service
Forgot password?
by email. Default: off. Even when on, it is offered only while deployment
email is enabled, the deployment has a mail server of its own (an SMTP host,
or a delivering EMAIL_BACKEND) and the public base URL is set: the link is
built from that URL, never from the request's Host header.
PASSWORD_RESET_LINK_TIMEOUT is how long a reset link works, in seconds
(default 3600). Invite and administrator-sent links keep Django's
PASSWORD_RESET_TIMEOUT (three days); the two kinds of link are not
interchangeable.
The mail is sent by the RQ default queue, so it needs danbyte-workers
running. Changing your own password (Preferences → Password) needs no
setting.
Secrets¶
| Setting | Where it lives | Dev default | Prod |
|---|---|---|---|
DJANGO_SECRET_KEY |
env | dev-key-change-in-prod |
env var, rotated |
DB_PASSWORD |
env | danbyte |
env var, rotated |
| Email creds | DB (UI) or env | console backend | Settings → Email (encrypted) |
The EMAIL_* env vars remain the fallback, but the SMTP server, credentials,
and outbound-delivery options are normally configured at runtime under
Settings → Email (users.manage). They live in the
deployment-wide singleton core.DeploymentSettings; the SMTP password is
Fernet-encrypted at rest. See
Notifications.
The secret store¶
Settings → Security → Secret store (secrets_provider on
DeploymentSettings) picks where Danbyte files the secrets it manages -
credentials, PSKs and keys, CSR and ACME keys - see
The secret store.
Blank disables every feature that needs one. The Key Vault URL and sign-in
endpoint must be https://; a Vault address may be http:// (with a
warning). Switching stores moves nothing: each secret is read from the store
it was written to while that stays configured, and the card asks before a
switch that leaves secrets behind. manage.py migrate_secret_store --from X
--to Y [--apply] moves them (details);
manage.py cleanup_secret_store lists and removes secrets whose record is
gone (details).
What the monitoring key protects¶
MONITORING_SECRET_KEY encrypts every EncryptedJSONField column - every
credential Danbyte keeps in its own database:
- monitoring: check-template and SNMP-profile secrets, Redfish endpoint credentials, monitoring-engine tokens and SSH credentials, the Outpost repository token, notification-channel secrets, certificate-issuer secrets, and the local secret store (device credentials, CSR/ACME private keys, FHRP auth keys);
- integrations: webhook signing secrets, automation-target tokens, NetBox import tokens, Windows Server and virtualization-source credentials;
- Zabbix, PRTG and Oxidized connection credentials, and PRTG credentials;
- backup-target credentials;
- the NVD API key for vulnerability data;
- SSO and LDAP secrets (identity providers, user profiles), and the SMTP and LDAP passwords in deployment, tenant and site settings.
It is also the secret backup archives
are encrypted under. DJANGO_SECRET_KEY (sessions, signed tokens) is separate.
Rotating the monitoring key¶
MONITORING_SECRET_KEY takes a comma-separated list, newest first. New values
are always encrypted under the first key; every key in the list is tried on
read. To replace a key without losing a stored secret:
- Add the new key first on every process that reads the database - the
web service, the WebSocket service and every worker
(
MONITORING_SECRET_KEY=<new>,<old>in.envor the unit'sEnvironment=) - and restart them all. A process without the new key cannot read values written under it, so do all of them before step 2. -
Re-encrypt the stored values under the new key:
.venv/bin/python manage.py rotate_monitoring_key --dry-run # counts only .venv/bin/python manage.py rotate_monitoring_key--dry-runprints, per model and field, how many values would be re-encrypted and how many are already current. The real run works in batches (--batch-size, default 500), one transaction per batch, and skips values already under the new key, so it can be stopped and run again. It writes one change-log entry for the run (who, when, counts) rather than one per row, and never prints a value. A value no configured key can open is left as it is and named by model and primary key; the command then exits non-zero. 3. Verify nothing is left under an older key:It exits non-zero while any value still needs an older key. 4. Remove the old key from the list on every process and restart them again.
Backups made before the rotation are encrypted under the old key: keep a copy
of it for as long as you keep those archives, and put it back in the list
(after the current key) to restore one. Settings → Security shows how many
keys are configured, never the keys themselves. A custom
MONITORING_SECRETS_BACKEND without rotate support is refused by the command.
Monitoring¶
Settings for the Monitoring / check engine. All have working defaults, so the feature runs with none of them set.
| Setting | Default | Purpose |
|---|---|---|
MONITORING_SECRET_KEY |
derived from SECRET_KEY in DEBUG; required when DEBUG=False |
Encryption key for stored credentials at rest (Fernet) - see What the monitoring key protects. A dedicated key gives credential encryption an independent lifecycle: rotating SECRET_KEY doesn't void stored secrets, and a SECRET_KEY leak can't decrypt them. The app refuses to start in production without it. scripts/install.sh generates one (and backfills older installs from the existing SECRET_KEY so already-stored secrets stay decryptable). May be a comma-separated list, newest first: the first key encrypts, every key decrypts. An empty entry (a stray comma) or a key listed twice stops the service at start. Never just replace it once secrets are stored - old ciphertext becomes unreadable; rotate it instead. |
MONITORING_SECRETS_BACKEND |
empty (Fernet) | Dotted path to a factory returning a SecretsBackend. Swap in an external store (OpenBao/Vault) without touching models. |
MONITORING_CONCURRENCY |
100 |
Max concurrent check attempts in one worker job's asyncio loop. Raising it needs a matching LimitNOFILE bump on the worker unit. |
MONITORING_GLOBAL_INTERVAL_SECONDS |
300 |
Default schedule (seconds) for assignments in follow_global mode. |
MONITORING_GLOBAL_ENABLED |
True |
Global on/off switch that follow_global assignments obey. |
MONITORING_SHARD_SIZE |
2000 |
Targets per ICMP multiping shard (one RQ job each). |
MONITORING_GENERIC_SHARD_SIZE |
200 |
Targets per TCP/HTTP/… shard. |
MONITORING_INFLIGHT_DEADLINE_SECONDS |
600 |
A check claimed (in_flight) longer than this is treated as orphaned by a dead/restarted worker and reclaimed by the dispatcher's reaper, so it re-runs instead of being stuck unknown. A healthy run clears in_flight within seconds. |
MONITORING_EXEC_ENABLED |
False |
Master switch for exec (script/plugin) checks. Off by default - running local commands from the UI is privileged. Set True and MONITORING_PLUGIN_DIR to use them. See Script / exec checks. |
MONITORING_PLUGIN_DIR |
empty | Directory of trusted Nagios-style plugins. An exec check may only run a plugin (by bare name, no path traversal) inside this dir; args are passed without a shell. |
MONITORING_WEBHOOK_TIMEOUT |
5 |
Per-channel webhook POST timeout (seconds). |
MONITORING_RESULT_RETENTION_DAYS |
30 |
Delete CheckResult rows older than this (daily prune). Raw results run ~600k rows/day on a busy install (~2.4 GB heap at 17 days) - raise only with the disk to match; the rolled-up state + transitions carry the long-term story. |
MONITORING_TRANSITION_RETENTION_DAYS |
365 |
Delete StateTransition rows older than this. Each check's newest change before the cutoff is kept, so a check that has not changed for longer still has its status. |
MONITORING_SNMP_SAMPLE_RETENTION_DAYS |
3 |
Delete SNMP interface counter samples (the utilisation sparklines) older than this; the sparklines read only this window. |
MONITORING_ROLLUP_HOURLY_RETENTION_DAYS |
30 |
Delete hourly check rollups older than this. Daily rollups are never pruned. See Rollups. |