Skip to content

Administrator Guide

This is the operational playbook for deploying and running Backend.AI GO under enterprise management. It sequences the work in the other enterprise pages into a day-1 setup and a set of day-N operations. Start here, then follow the links for the detail of each step.

The pages this guide draws on:

Day 1: stand up enterprise management

The first day is about establishing trust and getting one device managed end to end.

1. Generate and secure the signing key

Generate the organization's Ed25519 signing key and store it in a secrets manager or an access-controlled file. This key is the root of trust for the whole fleet, so back it up and restrict access to the operators who manage policy.

aigo-policy-server --generate-signing-key > policy-signing.pk8.b64

2. Extract and record the trust anchor

Print the public trust anchor from the signing key and record its id. You distribute this anchor to every device; it is what they use to verify the policy and the license.

aigo-policy-server \
    --signing-key-file policy-signing.pk8.b64 \
    --anchor-id org-2026 \
    --print-anchor

3. Author and sign the baseline policy

Write the EnterprisePolicy that defines your managed baseline (the settings to override and lock, the tool governance, any deployment profile, and the egress posture). See the Policy Schema Reference. Validate it before serving:

aigo-policy-server \
    --signing-key-file policy-signing.pk8.b64 \
    --policy-file policy.json \
    --anchor-id org-2026 \
    --dry-run

4. Stand up the policy server

Run the server under a service supervisor with the signing key, the policy, and your enrollment tokens. Put a TLS terminator in front of it. See Policy Server Deployment and Operation for the systemd unit and the full command. Confirm the version route responds:

curl -fsS https://policy.acme.example/api/v1/policy/version \
    -H "Authorization: Bearer <operator-api-key>"

5. Mint enrollment tokens

Create one-time enrollment tokens, one per device or one per batch, optionally bound to an organization label. Deliver each token through one of the three provisioning entry points. Keep the token list operator-only readable.

6. Prepare the provisioning profile and installer

Build a provision.json from packaging/provisioning/provision.example.json with your managementServerUrl and trust anchor. Decide how it reaches devices: a deep link per user, a manual paste, or an MDM or installer drop at the OS managed path. See Device Enrollment and Trust Anchors.

7. Enroll the first device and verify

Provision one device, then open Settings, then Organization. Confirm it shows managed mode, the organization, the locked-setting count, the egress posture, and a device fingerprint. Verify the anchor fingerprint matches the one you recorded in step 2.

8. Install the offline license (if required)

If your deployment requires a signed entitlement, sign a license with the org signing key and deploy it to <app_data>/enterprise/license.json. Confirm the Organization tab shows the license as valid. See Offline Licensing.

Day N: operate the fleet

Day-to-day operation is policy updates, key and token rotation, device lifecycle, and recovery.

Update the policy

Edit the policy document, then restart the policy server (or replace the served document) so it signs and serves the new version. Devices notice the new policy id on their next poll and download it. Because polling is interval-based (default 900 seconds), allow up to one poll interval for a change to reach the fleet. Roll out a risky change to a pilot group first by serving them a separate policy or using a separate server, then widen it.

Rotate the signing key

Rotate the signing key without a flag day by overlapping anchors. The steps:

  1. Generate a new signing key and extract its anchor.
  2. Add the new anchor to the provisioning profile (and re-provision or re-enroll devices) so clients trust both the old and the new key.
  3. Switch the policy server to sign with the new key and the new --anchor-id.
  4. After every device trusts the new anchor and has fetched a policy signed by it, retire the old anchor (or let its notAfter expire).

The same anchors verify the offline license, so re-sign and redeploy any active licenses with the new key during the overlap window.

Rotate enrollment tokens

Enrollment tokens are single-use and consumed on first enrollment. Mint fresh tokens for each new device or re-enrollment, and remove spent or stale tokens from the server's token list. Never reuse a token across devices.

Enroll and un-enroll devices

To enroll a device, deliver a provisioning profile and a fresh token through any of the three entry points. To re-enroll (for example after a key rotation), use the "re-enroll device" action in the Organization tab with a new token; new anchors merge with the existing ones. To un-enroll, remove the managed provision.json and any machine policy from the OS path; the device returns to un-managed mode on the next launch. See Device Enrollment and Trust Anchors.

Renew the offline license

Plan license renewals ahead of expiresAt so a device never enters the expired state. Sign the next license, deploy it over the existing one, and confirm the Organization tab returns to valid. The change is picked up without a restart. See Offline Licensing.

Recover from a policy-server outage

A managed device does not lose its posture when the policy server is unreachable. The last verified central policy is cached at <app_data>/enterprise/central_policy.json and stays enforced, the egress firewall stays installed, and the locks hold. The device simply keeps polling and picks up the latest policy once the server returns. A non-valid license never unlocks anything, so an outage cannot become a downgrade.

To harden against an extended outage, pair the central policy with a machine policy that carries the same baseline. The machine policy applies from a trusted local path with no network, so the floor holds even on a fresh install that has never reached the server. See Deployment Models.

Recover from a lost or compromised signing key

If the signing key is lost or exposed, treat it as a security incident. Generate a new key, distribute its anchor to every device (through re-provisioning or re-enrollment), switch the server to the new key, and retire the old anchor as soon as the fleet has migrated. Until the old anchor is retired, a holder of the old key can still sign a policy that trusting devices accept, so complete the migration promptly and consider setting a near-term notAfter on the compromised anchor to bound the exposure.

Operational checklists

Day-1 checklist

  • Signing key generated, backed up, and access-restricted.
  • Trust anchor extracted and its id recorded.
  • Baseline policy authored, validated with --dry-run, and served.
  • Policy server running under a supervisor behind TLS, version route confirmed.
  • Enrollment tokens minted and delivered securely.
  • Provisioning profile built and a delivery method chosen.
  • First device enrolled, anchor fingerprint verified, managed status confirmed.
  • Offline license signed and installed, if required, showing valid.

Day-N checklist

  • Policy changes piloted, then rolled out, with up to one poll interval for propagation.
  • Signing-key rotations performed with overlapping anchors and re-signed licenses.
  • Enrollment tokens rotated and spent tokens removed.
  • Devices enrolled and un-enrolled through the documented paths.
  • Licenses renewed ahead of expiry.
  • Audit records collected and retained per your compliance window (see Audit and Compliance).
  • A machine-policy baseline in place where an extended server outage is a concern.