NETMapper configuration reference

Every environment variable in .env.example, what it does, and what it defaults to.

View raw Markdown

All NETMapper settings come from environment variables. With Docker Compose they live in a .env file next to docker-compose.yml; on bare metal they live in /etc/netmapper/.env. Values marked required have no default and docker compose refuses to start without them. Everything else can stay as it is.

Required: the release to run

These three come straight from the GitHub release notes of the version you want to run. The digest is what actually pins the image: a tag can be repointed upstream, a digest cannot. Upgrading means replacing all three.

Variable What it does Default
NETMAPPER_VERSION Image tag of the release to run, for example 0.1.0. none, required
NETMAPPER_BACKEND_DIGEST sha256:... digest of the backend image for that release. none, required
NETMAPPER_FRONTEND_DIGEST sha256:... digest of the frontend image for that release. none, required

Required: secrets

Variable What it does Default
POSTGRES_PASSWORD Password for the in-stack PostgreSQL role. Compose builds DATABASE_URL from it, so you never construct the URL by hand. none, required
NETMAPPER_JWT_SECRET HS256 signing key for issued access tokens. The production startup gate refuses to boot on a secret shorter than 32 bytes or left at the development placeholder. Rotating it invalidates every outstanding token and forces all users to log in again. none, required
NETMAPPER_ENCRYPTION_KEY urlsafe-base64 Fernet key that encrypts switch SSH passwords, notification-channel secrets and AI provider keys at rest. none, required

Generate them, for example:

python3 -c "import secrets; print(secrets.token_urlsafe(24))"   # POSTGRES_PASSWORD
python3 -c "import secrets; print(secrets.token_urlsafe(48))"   # NETMAPPER_JWT_SECRET
python3 -c "import base64, os; print(base64.urlsafe_b64encode(os.urandom(32)).decode())"

Losing NETMAPPER_ENCRYPTION_KEY makes every stored secret unrecoverable. There is no key escrow and no recovery code. Back it up separately from the database dump, in a password manager or a secret store, and never commit it to git. A database backup on its own does not restore your switch passwords.

Database

Variable What it does Default
DATABASE_URL SQLAlchemy URL, for example postgresql+psycopg://user:pass@host:5432/netmapper. Compose derives it from the POSTGRES_* values; set it by hand only on bare metal or against an external database. derived by Compose
POSTGRES_USER PostgreSQL role name. netmapper
POSTGRES_DB Database name. netmapper
NETMAPPER_ALLOW_SQLITE Permits a SQLite DATABASE_URL. Development only. false

Network

Variable What it does Default
NETMAPPER_HTTP_PORT Host port for the app over plain HTTP. With the HTTPS overlay this port is not published, because nginx takes 80 and 443 instead. 80
NETMAPPER_COOKIE_SECURE Marks the auth cookies Secure. Set it to false only when users reach the app over plain http:// with no TLS in front: browsers refuse Secure cookies on plain HTTP, so login would fail. true
DOMAIN_NAME Hostname used by docker-compose.https.yml for the Let’s Encrypt certificate and the nginx server name. Only for a host that must be reachable from outside; prefer a firewall and a zero-trust proxy in front of plain port 80. empty
VITE_API_URL Base URL the React app uses to reach the API. The release frontend proxies the API itself, so this matters mainly for a source build. unset

Optional tuning

Everything here has a working default. All of these ship commented out in .env.example.

Variable What it does Default
NETMAPPER_ENV Set to production to enable the startup secret gate, which refuses to boot on weak or placeholder secrets. development relaxes it for a source build. production in the release compose file
NETMAPPER_JWT_EXPIRE_MINUTES Lifetime of an issued access token, in minutes. 60
NETMAPPER_LOGIN_RATELIMIT Per-IP rate limit on the login endpoints, in slowapi syntax. Rejections carry a Retry-After header. 5/minute
NETMAPPER_SCHEDULER_ENABLED Enables the APScheduler jobs behind scheduled scans and the daily maintenance work. Manual scans do not need it. true in the release compose file
NETMAPPER_AUDIT_RETENTION_DAYS How long audit log rows are kept. A prune job runs daily at 03:30 local time, and admins can prune on demand from the audit log UI. 90
NETMAPPER_SCAN_COOLDOWN_SECONDS Minimum gap between scans of the same switch. 30
NETMAPPER_SCAN_USER_HOURLY_LIMIT Maximum scans one user may trigger per hour. 30
LOG_LEVEL Backend log verbosity. Raise it to DEBUG while reproducing a problem, then put it back. INFO

Email alerts (SMTP)

Set these to let alert rules deliver over email, then restart the backend and add a channel of type email under Settings, Alerting, Notification Channels. The “Send test” button verifies delivery before you attach the channel to a rule.

Variable What it does Default
SMTP_HOST SMTP server hostname. empty
SMTP_PORT SMTP port. 587
SMTP_USER SMTP username. empty
SMTP_PASSWORD SMTP password. Encrypted at rest when stored on a channel. empty
SMTP_FROM Envelope and header sender address. empty
SMTP_TLS Use STARTTLS. true

Telemetry and crash reporting

Variable What it does Default
NETMAPPER_TELEMETRY_ENABLED Anonymous daily usage ping. On by default. Set it to false to opt out; the environment variable always wins over the in-app switch, which then shows as locked. true
NETMAPPER_TELEMETRY_URL Where the daily ping goes. Point it at an endpoint you control to keep the aggregate for yourself. https://telemetry.nx1xlab.dev/v1/ping
NETMAPPER_SENTRY_DSN Crash reporting to a Sentry project you own. Unset means no crash reporting at all. Request and response bodies, environment variables, switch credentials, switch IPs, AI keys and notification secrets are scrubbed before anything is sent. unset, off

The ping carries a random install id, version numbers, OS family, bucketed counts, and the kinds of scanners and AI providers in use. Nothing about your network: no IPs, MACs, hostnames, switch names, credentials or scan output. The full field list and the opt-out in the UI are on the security and privacy page.