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. Install the policy server

Install the version-matched bare Linux binary from the private release, or build the dedicated package from source. The policy server is not part of the desktop installer or aigo-server package, and no official container image is published. Verify aigo-policy-server --version before continuing. See Policy Server Deployment and Operation.

2. 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.

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

3. 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 \
    > trust-anchor.json

4. Author and validate 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). Give it a unique policyId and an RFC3339 issuedAt. 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

5. Prepare enrollment tokens and persistent state

Create one random, single-use enrollment token per device or enrollment batch and map each token to an optional organization label in the JSON token document. Install both the token document and the signing key as mode 0600, owned by the service account. Create a persistent owner-only data directory for users.db, encrypted access keys, device-registry.json, and consumed-token digests. Do not use /tmp.

6. Start locally and bootstrap operator access

Start the server on 127.0.0.1:8444 with an explicit --data-dir, keeping the TLS reverse proxy disabled. Create the first administrator through POST /api/v1/setup/register-admin, then use that session to create an operator key through POST /admin/keys. The deployment guide provides commands that keep the password out of process arguments and shell history. Store the API-key secret immediately because it is returned only once.

Check the first-run state before registration:

curl -fsS http://127.0.0.1:8444/api/v1/setup/status

7. Enable TLS and verify the policy server

Run the server under the corrected systemd unit, then enable the same-host TLS reverse proxy. Keep the upstream listener on loopback. Confirm the version route responds through the public HTTPS name with the narrow enterprise_read operator key:

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

8. Prepare the provisioning profile and installer

Build a provision.json from packaging/provisioning/provision.example.json with your managementServerUrl, the public anchor from trust-anchor.json, the poll interval, and, for unattended enrollment, one fresh token. 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.

9. 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 3.

10. 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 and assign both a new policyId and a new issuedAt. The client uses policyId as its version key and does not download the full document while that id is unchanged. Run the production command with --dry-run, install the validated file atomically, restart aigo-policy-server, and confirm /api/v1/policy/version reports the new id. The process does not watch the file and does not reload on SIGHUP.

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 it a separate policy id 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 document, which the server reads from a mode 0600 file, AIGO_POLICY_ENROLLMENT_TOKENS, or standard input. Restart the server after changing any token source; all three are read only at startup. Never reuse a token across devices. A consumed token stays consumed across a server restart, so removing it from the document is housekeeping rather than a security step.

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

  • Version-matched Linux policy-server binary installed and verified.
  • Signing key generated, backed up, and access-restricted.
  • Trust anchor extracted and its id recorded.
  • Baseline policy authored, validated with --dry-run, and served.
  • Persistent data directory created, backed up, and writable only by the service account.
  • Enrollment tokens minted, installed mode 0600, and delivered securely.
  • First administrator and narrow operator API key created before external exposure.
  • Policy server running under a supervisor behind TLS, version route confirmed with the operator key.
  • 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 updates assigned a new policyId, passed --dry-run, and were activated by a restart before rollout.
  • 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, spent tokens removed, and the service restarted after source changes.
  • 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.
  • Persistent policy-server state included in backup and recovery checks.