Skip to main content

Examples

Replace placeholders with deployment values. Keep settings node-wide for package restarts.

Onboard a New Agent​

sudo mac env set --global MASTER_IP=<master-ip> MAC_NODE_TOKEN=<master-token>
mac pull agent
mac start agent --wait
mac test sanity --expect agent

Securely transfer the master’s token; it is not distributed. For conflicting shared user settings, inspect node-wide values and use sudo env MAC_IGNORE_USER_ENV=1 mac start agent --wait. This skips user overrides without modifying the shared file.

Check the Whole Cluster's Health​

mac test sanity --master <master-ip>
echo $?     # 0 all passed; 1 failure; 2 unreachable; 3 only remote nodes failed

On a running stack, --expect all|master|agent checks local services without login. Also verify UI metrics and logs.

Run a Local Development Build​

export MAC_CONFIG_DIR="$PWD/deploy"
mac pull master --local
mac start master --local --wait

Use the matching checkout and inspect user overrides before selecting a token. See Without the Package.

Switch to a Private Mirror​

sudo mac env set --global MAC_REGISTRY=<registry-host>/<mac-path>
sudo mac env set --global SDK_AGENT_IMAGE=<registry-host>/<sdk-image>:<tag>
mac pull all
sudo mac restart all --wait

Mirror MAC and SDK images. These overrides do not relocate external Prometheus, Loki, or vendor exporter images. Without registry access, use a complete offline bundle. Check mac images all --check; Docker login must use the pulling user.

Configure Switch SSH Credentials (Mixed Fleet)​

sudo mac env set --global SWITCH_USER=<switch-user> SWITCH_PASSWD_LIST=<password1>,<password2>
sudo mac env set --global SWITCH_MGMT_CIDRS=192.0.2.0/24
sudo mac restart master --wait

Use your actual management CIDRs and credentials.

Back Up Prometheus Before mac clean​

Stop the master for a consistent metrics backup:

mac stop master
docker run --rm -v mac-prometheus-data:/data:ro -v "$PWD":/backup \
  alpine tar czf /backup/prometheus-backup.tgz -C /data .
tar tzf prometheus-backup.tgz

Validate before deletion. This backs up only metrics. A full backup also needs mac-api-data (including the BMC key), mac-loki-data, configuration, and token files. mac clean deletes all three stores.

Restore Prometheus​

With master services stopped:

docker volume create mac-prometheus-data
docker run --rm -v mac-prometheus-data:/data -v "$PWD":/backup:ro \
  alpine tar xzf /backup/prometheus-backup.tgz -C /data
sudo mac start master --wait

Restore into an empty volume using the archive format above.

Pre-Set the Initial Admin Password​

sudo mac env set --global MAC_ADMIN_PASSWORD=<strong-password>
sudo mac start master --wait

Only deployments without users are seeded. Change existing passwords while signed in or through another admin in Users.

Reset the Admin Password Later​

Use another enabled admin in Settings → Users; otherwise request support recovery. Deleting mac-api-data also destroys enrollment, alerts, BMC settings, and encryption keys.

Reload Agent After a Driver Upgrade​

After upgrading the vendor driver according to its supported procedure:

mac restart agent --wait
mac test sanity --expect agent

Enrollment resumes automatically. Verify actual GPU metrics; running exporters do not prove driver access.