.env.example

# ============================================================================
# MNM — Environment Configuration
# ============================================================================
#
# Copy this file to .env and edit before first deployment:
#
#     cp .env.example .env
#     $EDITOR .env
#     docker compose up -d
#
# Values here are read by docker-compose at container creation. Note that
# Compose bakes env values in at container CREATE time, NOT at start —
# changing .env and running `docker compose restart` does NOT pick up
# changes. After editing, recreate affected containers:
#
#     docker compose up -d --force-recreate <service>
#
# ## Markings used in this file
#
#   [REQUIRED]  Must be set before first deploy. Bootstrap will refuse
#               to run without these.
#   [OPTIONAL]  Has a sensible default; only set if you need to override.
#   [SECRET]    Treat as sensitive. Never commit to git, never paste in
#               chat, never log. .env is in .gitignore for this reason.
#               Use distinct values per field — reusing one password
#               across postgres / redis / admin widens blast radius if
#               any one is compromised.
#   [CONNECTOR] Optional integration with an external system. Leave
#               blank to disable; the relevant connector won't load.
#   [DEFERRED]  Wired in compose but the feature isn't shipping in
#               v1.0. Safe to leave blank.
#
# ## Generating strong values
#
# Strong random for passwords / secret keys:
#     python3 -c "import secrets; print(secrets.token_urlsafe(48))"
#
# ============================================================================


# ----------------------------------------------------------------------------
# Core deployment settings
# ----------------------------------------------------------------------------

# [REQUIRED] IANA timezone name — controls timestamp display across
# every container. Examples: America/New_York, Europe/London,
# Asia/Tokyo. See `timedatectl list-timezones` for the full list.
MNM_TIMEZONE=America/Boise

# [OPTIONAL] Reachable hostname or external IP of this MNM host.
# Drives Grafana's `GF_SERVER_ROOT_URL`, which Grafana stamps into
# generated URLs (share links, snapshot URLs, alert callback links).
# Default `localhost` works for lab deployments where operators hit
# the host directly; for any other deployment, set this to the
# hostname or IP operators actually use to reach this box, otherwise
# share links will point at "localhost" and not work for anyone but
# the local operator. Future external-URL features will read this
# variable too.
MNM_DOMAIN=localhost


# ----------------------------------------------------------------------------
# Nautobot superuser (used by bootstrap.sh and login)
# ----------------------------------------------------------------------------

# [REQUIRED] Username for the Nautobot admin account that bootstrap
# creates. Also the login for the controller dashboard.
MNM_ADMIN_USER=mnm-admin

# [REQUIRED] [SECRET] Password for the Nautobot admin and controller
# dashboard. Bootstrap refuses to run without this set. Use a strong
# value — this account has full Nautobot superuser privileges.
MNM_ADMIN_PASSWORD=

# [REQUIRED] Email address attached to the admin account. Any
# valid-format address is fine; not used for sending mail today.
MNM_ADMIN_EMAIL=admin@example.com


# ----------------------------------------------------------------------------
# Nautobot server
# ----------------------------------------------------------------------------

# [REQUIRED] [SECRET] Django cryptographic secret. Used for session
# cookies, password reset tokens, and other security-sensitive
# Django operations. Generate with:
#     python3 -c "import secrets; print(secrets.token_urlsafe(48))"
# Changing this value invalidates all existing sessions and
# password-reset tokens.
NAUTOBOT_SECRET_KEY=

# [OPTIONAL] Comma-separated list of hostnames Nautobot will accept
# in the Host: header. Default `*` accepts any host (convenient for
# lab; restrictive deployments should pin to your real hostname).
NAUTOBOT_ALLOWED_HOSTS=*


# ----------------------------------------------------------------------------
# PostgreSQL
# ----------------------------------------------------------------------------
# Single PostgreSQL 15 instance hosts BOTH the `nautobot` database
# (inventory, IPAM) AND the `mnm_controller` database (sweep history,
# polling state, endpoint correlation). bootstrap.sh creates the
# second database after the container is healthy.

# [OPTIONAL] PostgreSQL role name. Owns both databases. Default
# value works for fresh installs; only change if integrating with
# external tooling that expects a different role.
POSTGRES_USER=nautobot

# [REQUIRED] [SECRET] PostgreSQL password for the role above. Used
# by Nautobot, the controller, and bootstrap.sh.
POSTGRES_PASSWORD=

# [OPTIONAL] Initial database name (Nautobot's). Default value
# works for fresh installs.
POSTGRES_DB=nautobot

# [OPTIONAL] Name of the controller's database. Created by bootstrap.sh
# inside the postgres container. Default works for fresh installs.
# MNM_CONTROLLER_DB=mnm_controller


# ----------------------------------------------------------------------------
# Redis
# ----------------------------------------------------------------------------
# Single Redis 7 instance shared across Nautobot (cache + Celery
# broker) and the controller (Celery result backend reads as fallback
# for the upstream nautobot-device-onboarding PENDING-forever bug).
# Logical-database split:
#   db 0 — Nautobot cache
#   db 1 — Nautobot Celery broker + result backend (controller reads)

# [REQUIRED] [SECRET] Redis password. Without this, anything on
# mnm-network could read/write Redis (and steal Celery results).
REDIS_PASSWORD=


# ----------------------------------------------------------------------------
# NAPALM — read-only credentials for network device polling
# ----------------------------------------------------------------------------
# NAPALM is the multi-vendor abstraction MNM uses for routes / BGP
# polling (and as a fallback for vendors without a Tier 1 connector).
# These credentials are used by both the Nautobot core (for the
# legacy onboarding plugin) AND by the Nornir plugin under bare
# NAPALM_* names — docker-compose copies values to both name forms
# automatically.
#
# Recommended setup: a dedicated read-only service account on each
# device with view-config-level access (Junos: needs `view configuration`
# permission; Cisco: privilege 5 or above). MNM never writes config —
# Rule 1 — but most NAPALM getters need view privileges.

# [OPTIONAL until first onboarding] Username. If unset, bootstrap
# skips creating a default Nautobot SecretsGroup; you'll need to
# add credentials manually before onboarding any devices.
# NAUTOBOT_NAPALM_USERNAME=

# [OPTIONAL until first onboarding] [SECRET] Password matching the
# username above.
# NAUTOBOT_NAPALM_PASSWORD=

# [OPTIONAL] NAPALM connection timeout in seconds. Default 30 is
# fine for most lab/SMB environments. Bump for high-latency WAN
# paths or slow devices (Junos SRX series tends to need 60+).
# NAUTOBOT_NAPALM_TIMEOUT=30


# ----------------------------------------------------------------------------
# SNMP — Tier 0 universal collection
# ----------------------------------------------------------------------------
# v1.0 ships SNMPv2c support only (SNMPv3 deferred to v1.1). Per-
# device community strings are configured at onboarding time on the
# Discover page or via /api/onboarding/direct-rest, NOT in this file.

# SNMP collection tuning. Applies to polling (ARP / MAC / LLDP /
# routes / BGP) — the slow-but-alive case. Default 10s timeout
# and 1 retry suit most networks. Raise the timeout for slow SNMP
# agents (some FortiOS releases, older Juniper EX, devices under
# load). Raise retries if you see UDP packet loss on the path.
#
# Does NOT apply to the initial discovery sweep, which uses a
# tighter built-in 3s timeout optimized for fast dead-IP iteration
# (most IPs in a sweep are unresponsive; the dead-IP path
# dominates wall-clock time).
#
# Per-device polling overrides are planned for v1.1.
# MNM_SNMP_TIMEOUT_SEC=10.0
# MNM_SNMP_RETRIES=1


# ----------------------------------------------------------------------------
# gNMI — streaming telemetry
# ----------------------------------------------------------------------------
# gnmic subscribes to gNMI feeds on devices that have it enabled.
# Most networks won't have gNMI configured; safe to leave blank.
# When set, the values are referenced from ./config/gnmic/gnmic.yml
# via ${} expansion.

# [CONNECTOR] gNMI username for devices with gNMI enabled.
# GNMI_USERNAME=

# [CONNECTOR] [SECRET] gNMI password.
# GNMI_PASSWORD=


# ----------------------------------------------------------------------------
# Grafana
# ----------------------------------------------------------------------------

# [REQUIRED] [SECRET] Grafana admin login password. The Grafana
# container will refuse to start without this set (compose uses the
# `${VAR:?error}` syntax to fail loudly rather than silently default
# to a known weak value). Set a strong random value:
#     python3 -c "import secrets; print(secrets.token_urlsafe(48))"
GRAFANA_ADMIN_PASSWORD=


# ----------------------------------------------------------------------------
# Prometheus
# ----------------------------------------------------------------------------

# [OPTIONAL] How long Prometheus retains metrics. Default 365 days.
# Whichever of (retention.time, retention.size 10GB hard cap) hits
# first wins. Bump cautiously — metric volume scales with both
# device count and per-device scrape richness.
# PROMETHEUS_RETENTION_DAYS=365


# ----------------------------------------------------------------------------
# Performance tuning
# ----------------------------------------------------------------------------

# [OPTIONAL] Concurrency caps for the controller's worker pools.
# Defaults are conservative; raise for fast hosts with many devices.
# MNM_SWEEP_CONCURRENCY=50          # Max parallel TCP probes per sweep
# MNM_COLLECTION_CONCURRENCY=20     # Max parallel SNMP walks per cycle


# ----------------------------------------------------------------------------
# Anomaly detection
# ----------------------------------------------------------------------------

# [OPTIONAL] Endpoints not seen in this many days are flagged as
# stale on the Events page. Per-deployment override available via
# POST /api/config (writes to kv_config table).
# ANOMALY_STALE_DAYS=7


# ----------------------------------------------------------------------------
# Database maintenance — controller's daily prune background job
# ----------------------------------------------------------------------------
# Evicts old endpoint_events, IP observations, orphaned watches, and
# stale sentinel rows from the mnm_controller database. Set
# MNM_RETENTION_DAYS to MATCH (or exceed) PROMETHEUS_RETENTION_DAYS
# so cross-referencing time ranges between Prometheus and the
# endpoint store always works.

# [OPTIONAL] Retention window. Default 365 days.
# MNM_RETENTION_DAYS=365

# [OPTIONAL] How often the prune job runs. Default daily.
# MNM_PRUNE_INTERVAL_HOURS=24


# ----------------------------------------------------------------------------
# Modular polling — per-device, per-job-type collection intervals (sec)
# ----------------------------------------------------------------------------
# These are defaults applied to NEW devices at onboarding. Per-device
# overrides live in the device_polls table and can be changed via
# PUT /api/polling/config/{device}/{job_type}.

# [OPTIONAL] ARP table polling interval. Default 5 minutes.
# MNM_POLL_ARP_INTERVAL=300

# [OPTIONAL] MAC / FDB table polling interval. Default 5 minutes.
# MNM_POLL_MAC_INTERVAL=300

# [OPTIONAL] DHCP-server-binding polling interval (Junos PyEZ today).
# Default 10 minutes.
# MNM_POLL_DHCP_INTERVAL=600

# [OPTIONAL] LLDP neighbor polling interval. Default 1 hour — LLDP
# topology changes infrequently.
# MNM_POLL_LLDP_INTERVAL=3600

# [OPTIONAL] How often the polling loop wakes up to check for due
# jobs. Default 30 seconds. Lower = faster reaction to schedule
# changes; higher = lower idle CPU.
# MNM_POLL_CHECK_INTERVAL=30


# ----------------------------------------------------------------------------
# Proxmox VE connector (optional read-only enrichment)
# ----------------------------------------------------------------------------
# When PROXMOX_HOST is set the controller starts a background loop
# that polls the Proxmox API for nodes / VMs / containers / ZFS pools
# and exposes Prometheus metrics at /api/proxmox/metrics. VMs and
# containers also surface as endpoints joined by MAC to ARP-table
# data from switches.
#
# Setup on the Proxmox side:
#   Datacenter → Permissions → API Tokens → Add
#     User: mnm-monitor@pve  (create the user first if needed)
#     Token ID: mnm-token
#     Privilege Separation: leave checked
#   Datacenter → Permissions → Add → API Token Permission
#     Path: /
#     Token: mnm-monitor@pve!mnm-token
#     Role: PVEAuditor   (built-in read-only role)
#   Then copy the token's UUID secret into PROXMOX_TOKEN_SECRET below.
#
# See docs/CONNECTORS.md for full setup walkthrough.

# [CONNECTOR] Proxmox API URL — leave blank to disable the connector.
# PROXMOX_HOST=https://192.0.2.10:8006

# [CONNECTOR] API token identifier in Proxmox's <user>!<token-id> form.
# PROXMOX_TOKEN_ID=mnm-monitor@pve!mnm-token

# [CONNECTOR] [SECRET] API token secret (UUID format).
# PROXMOX_TOKEN_SECRET=00000000-0000-0000-0000-000000000000

# [CONNECTOR] Verify Proxmox's TLS certificate. Default false because
# many Proxmox installs use self-signed certs. Flip to true if you've
# replaced the cluster cert with a real one.
# PROXMOX_VERIFY_SSL=false

# [CONNECTOR] How often to poll Proxmox in seconds. Default 5 minutes.
# PROXMOX_INTERVAL_SECONDS=300


# ----------------------------------------------------------------------------
# Embedded AI assistant (DEFERRED — Phase 3)
# ----------------------------------------------------------------------------
# Wired in compose but not yet built. v1.0 ships with these
# variables documented for forward compatibility; safe to leave blank.

# [DEFERRED] Local Ollama model name (Phase 3).
# OLLAMA_MODEL=llama3.1:8b

# [DEFERRED] [SECRET] External API key for higher-quality cloud LLM
# (Phase 3 — operator-opt-in alternative to local Ollama).
# ANTHROPIC_API_KEY=


# ----------------------------------------------------------------------------
# Cloud connectors (DEFERRED — Phase 4)
# ----------------------------------------------------------------------------
# Wired in compose but not yet built. Mist is the planned first cloud
# connector; included here for forward compatibility.

# [DEFERRED] [SECRET] Juniper Mist API token.
# MIST_API_TOKEN=

# [DEFERRED] Juniper Mist regional API endpoint.
# MIST_BASE_URL=https://api.mist.com

# [DEFERRED] Juniper Mist organization UUID.
# MIST_ORG_ID=