Environment Variables
Use mac env to inspect values and their source. Secret values are masked.
mac env
mac env
mac env set KEY=VALUE
mac env unset KEY
sudo mac env set --global KEY=VALUE
sudo mac env unset --global KEY
File Priority
Highest priority first:
~/.mac/env: per-user overrides, mode0600./etc/mango/mac/env: node-wide overrides, mode0640, owned byroot:docker./usr/share/mango-ai-center/env.defaults: package defaults, replaced on upgrade.
Managed files override shell values except MAC_CONFIG_DIR and MAC_IMAGE_SOURCE.
MAC_IGNORE_USER_ENV=1 skips user settings; package scripts use it for node-wide operation:
sudo env MAC_IGNORE_USER_ENV=1 mac env
sudo env MAC_IGNORE_USER_ENV=1 mac restart master --wait
Place the flag after sudo env. It skips, not deletes, the user file for this invocation.
Ordinary sudo mac reads user overrides. MAC_CONFIG_DIR and image-source flags still apply.
Keep master address, node name, token, and deployment settings node-wide. Shared-home user overrides can still win under sudo. Unset conflicting values in their source file and restart the role.
Image Source
MAC_IMAGE_SOURCE=registry pulls; local builds. Its precedence is:
- Process environment.
- Node-wide value (including the package default when declared).
- User file.
--local / --registry on pull, start, or restart override this for one invocation.
Variable Reference
env.defaults lists tuning variables. Registry/SDK pins are release-specific; inspect
resolved tags with mac images.
Common
| Variable | Purpose |
|---|---|
MASTER_IP | Required master address for agent mode |
MAC_CONFIG_DIR | Compose/config directory; default /etc/mango/mac |
MAC_REGISTRY | MAC image registry prefix; public packages use repo.mangoboost.io/public-docker/mac |
MAC_VERSION | Override MAC image tags; unset uses the installed CLI version |
SDK_AGENT_IMAGE | Override the release-pinned SDK agent image; not a moving latest tag |
MAC_IMAGE_SOURCE | registry or local |
MAC_OFFLINE | Default false; offline installer sets true, disabling registry fallback |
NODE_NAME | Node name; defaults to hostname |
MAC_NODE_IP_PREFIX | Literal prefix selecting a host address; include a trailing dot for an IPv4 subnet |
TZ | IANA timezone; CLI detects the host, raw Compose falls back to UTC |
MAC_LOG_LEVEL | debug, info (default), warn, or error; restart to apply |
MAC_AUTH_ENABLED | User JWT authentication; default true |
MAC_ADMIN_PASSWORD | Seeds admin only when no users exist; default admin |
MAC_ALLOWED_ORIGINS | Allowed credentialed CORS origins; unset sends no CORS headers |
MAC_TRUSTED_PROXIES | Trusted proxy IPs/CIDRs for forwarded client addresses; unset trusts the web UI container |
Stale MAC_VERSION pins can run old images. Compare mac version with mac info
and remove unwanted pins from both env files.
Node Authentication
| Variable | Purpose |
|---|---|
MAC_NODE_TOKEN | Shared master/agent token; recommended 32–128 characters from A-Z, a-z, 0-9, _, - |
MAC_NODE_TOKEN_FILE | Read token from a file; inline token takes precedence |
MAC_NODE_AUTH_MODE | sys-manager policy for emergency/missing-token cases; see installed defaults |
MAC_NODE_ALLOW_IPS | Optional source IP/CIDR filter for sys-manager; include master, loopback, and required bridge addresses |
MAC_REGISTRY_ALLOWLIST | Additional registries permitted for node updates |
Privileged master start generates /etc/mango/mac/node_token if unset; an unwritable
directory falls back to a user token. Root-only files require sudo for start/restart.
Check user overrides. Securely copy the token into every agent’s node-wide MAC_NODE_TOKEN;
it is not distributed, and mismatches prevent enrollment. This token protects node control,
SDK gateway, and log relay separately from user JWTs. Keep it identical across nodes and
restart master before agents when enabling/rotating it. Agent token files must be readable
inside each consuming container; a host-only MAC_NODE_TOKEN_FILE can enroll but fail
control authentication. Prefer the inline node-wide token.
Service Ports
| Variable | Purpose |
|---|---|
MASTER_API_PORT | Master HTTP API; default 28080 |
MASTER_WEB_PORT | Dashboard; default 23000 |
PROMETHEUS_PORT | Master Prometheus host port; default 29090 |
LOKI_PORT | Master Loki port; default 29210 |
PROMETHEUS_BIND_ADDR, LOKI_BIND_ADDR | Default 127.0.0.1; these services have no built-in authentication |
PROMETHEUS_RETENTION_SIZE | Metrics storage cap; default 20GB, with 30-day retention |
SDK_AGENT_INTERNAL_PORT | SDK agent loopback REST port; default 28100, reached through authenticated sdk-gate on 28000 |
SNMP_PORT | Switch SNMP destination port; default 161 |
ALERT_RULES_PATH | API-server alert rules JSON location |
Exporter port settings on the master change target addresses, not agent listeners. See Installation for the ports to permit between hosts.
Logs and Agent Health
| Variable | Purpose |
|---|---|
LOKI_PUSH_URL | Agent log destination; defaults to the master's authenticated /api/v1/logs/push relay |
LOKI_PUSH_MAX_LINES | Maximum log lines per push; default 2000 |
MAC_HEALTH_CHECK_INTERVAL | Agent health poll interval in seconds; default 30 |
MAC_HEALTH_CHECK_TIMEOUT | Probe timeout in seconds; default 5 |
MAC_TARGET_GRACE_SEC | Retain offline agent scrape targets for this many seconds; default 600 |
SMARTCTL_TIMEOUT_SEC | Per-device SMART deadline; default 30 seconds |
SMART_INTERVAL_SEC | SMART refresh interval; default 300 seconds |
Agent log positions persist in /var/lib/mango-ai-center/sys-exporter. All-in-one uses
the relay container name on mac-network.
TLS (HTTPS)
| Variable | Purpose |
|---|---|
MAC_TLS_ENABLED | Enable API/dashboard HTTPS; default false |
MAC_TLS_CERT_DIR | Host directory with server.crt and server.key, mounted into containers |
MAC_TLS_PORT | API HTTPS port; default 28443 |
MAC_WEB_TLS_PORT | Dashboard HTTPS port; default 23443 |
MAC_TLS_CERT_FILE | Container cert path; default /etc/mac/certs/server.crt |
MAC_TLS_KEY_FILE | Container key path; default /etc/mac/certs/server.key |
Switch Access
| Variable | Purpose |
|---|---|
SWITCH_USER | SSH user; default admin |
SWITCH_PASSWD_LIST | Comma-separated SSH password candidates |
SWITCH_PASSWD | Legacy single password when the list is unset |
SNMP_COMMUNITY | SNMP community; default public |
SWITCH_MGMT_CIDRS | Allowed switch management CIDRs/IPs receiving SNMP/gNMI credentials; empty allows all discovered addresses |
MAC_SSH_KNOWN_HOSTS | Strict OpenSSH known_hosts path inside api-server; mount/copy the file into the container |
Without explicit known_hosts, API data stores first-use keys and rejects changes.
Restrict SWITCH_MGMT_CIDRS to your management network.
gNMI Streaming Telemetry
Capable SONiC switches use gNMI; other switches fall back to SNMP. LLDP discovery uses SNMP.
| Variable | Purpose |
|---|---|
GNMI_ENABLED | Default true; false forces SNMP |
GNMI_PORT | Default 8080 |
GNMI_USERNAME, GNMI_PASSWORD | gNMI credentials, empty by default |
GNMI_TLS_MODE | none (default), skip-verify, or ca |
GNMI_TLS_CA_FILE | CA path inside switch-exporter for ca mode |
GNMI_SAMPLE_INTERVAL_SEC | Counter subscription interval; default 5 |
GNMI_PATH_MODE | auto (default), sonic-db, or openconfig |
GNMI_MAX_FAILURES | Failures before SNMP fallback; default 5 |
GNMI_RETRY_COOLDOWN_SEC | Delay before retrying gNMI; default 600 |
LLMBoost
| Variable | Purpose |
|---|---|
LLMBOOST_HOST_PORTS | Explicit ports to probe on online agents for /v1/models; unset disables probing |
LLMBOOST_ENGINE_ENDPOINTS | Additional reachable OpenAI-compatible engine URLs |
LLMBOOST_ENABLED | Unset follows configured discovery paths; false disables federation |
LLMBOOST_DASHBOARD_URL | Link to the deployment's Grafana |
LLMBOOST_SERVING_NAMESPACES, LLMBOOST_PLATFORM_NAMESPACES | Override Kubernetes namespace discovery |
K8S_API_ENDPOINT, K8S_API_TOKEN | Kubernetes API URL and ServiceAccount token |
K8S_API_CA_CERT | CA path inside api-server |
K8S_KUBECONFIG | Kubeconfig path inside api-server; exec/auth-provider credentials are unsupported |
K8S_NAMESPACES | Optional namespace scope |
K8S_INSECURE_SKIP_VERIFY | Skip Kubernetes TLS verification; avoid in production |
Host/Kubernetes discovery can coexist. Apply /etc/mango/mac/k8s/mac-llmboost-rbac.yaml
to the target cluster. Paths are inside api-server; host env paths do not mount files.
See LLMBoost.
MASS and BMC
| Variable | Purpose |
|---|---|
MASS_API_ENDPOINT | MASS Manager API URL; unset disables integration |
MASS_DASHBOARD_URL | MASS dashboard link |
MASS_USERNAME, MASS_PASSWORD | MASS service identity |
MAC_BMC_USER, MAC_BMC_PASSWORD | BMC fallback for nodes without individual configuration |
MAC_BMC_ENCRYPT_KEY | Optional BMC credential encryption key, at least 32 bytes |
MAC_BMC_KEY_FILE | Generated key location; default /app/data/.bmc_key |
The default BMC key is generated in API data; preserve it with mac.db. Persist MASS
credentials node-wide; runtime credentials are lost on restart.
Inspecting Current State
mac env labels default, global, and user sources. Restart after changes and check
mac info. Do not share unmasked environments or credential-bearing files.