Skip to content

Enroll a managed server

Enrollment connects another Ubuntu or Debian host to the aseStack controller. The generated script installs the agent, writes a host-specific token and mTLS certificate bundle, starts the systemd service, and runs the agent's local doctor check.

This guide uses:

Controller:     https://control.example.com
Managed server: managed.example.net
Server ID:      managed-01

Before you enroll

The managed server needs:

  • Ubuntu or Debian with systemd;
  • amd64 architecture for the standard CDN artifact;
  • root or sudo access;
  • outbound HTTPS access to control.example.com and cdn.asestack.dev;
  • a working system clock; and
  • the base download tools required by the agent updater.

On a minimal Ubuntu or Debian image, install those tools before running the generated script:

sudo apt-get update
sudo apt-get install -y curl tar gzip coreutils ca-certificates

The agent polls outward to the controller. You do not need to expose a new inbound agent port on managed.example.net.

On the controller, open Settings → Controller Settings and confirm Controller URL is exactly:

https://control.example.com

Save the setting before generating the enrollment. A wrong controller URL is embedded in the install script and prevents the agent from checking in.

1. Create the enrollment

  1. Open Servers.
  2. In Enroll Managed Server, enter managed-01 as the Server ID.
  3. Select Create enrollment.
  4. Check the displayed expiry.
  5. Select Copy install script.

Choose a stable, unique server ID. It identifies the host in commands, jobs, audits, and enrollment history; do not reuse one ID for multiple machines.

The default token and client-certificate lifetime is 2160h (90 days). The controller displays the exact expiry and keeps a redacted history of active, expired, and revoked enrollments.

Treat the script as a secret

The generated script contains a bearer token, a client private key, and certificate material. Do not paste it into chat, tickets, shared shell history, or a world-readable file. Anyone holding an active bundle may be able to impersonate that server until it expires or is revoked.

2. Run the script on the managed server

Connect to the intended host and become root:

ssh managed.example.net
sudo -i

Paste the copied content into a temporary root-owned file, execute it, and remove the file immediately afterward. For example, create /root/asestack-enroll.sh with mode 0600, then run:

bash /root/asestack-enroll.sh
rm -f /root/asestack-enroll.sh

The generated script:

  • installs asestack-agent from the checksum-verified CDN updater when needed;
  • creates /etc/asestack/agent with restricted permissions;
  • writes the controller CA, client certificate, and client private key;
  • writes /etc/asestack/agent/agent.env with mode 0600;
  • installs and enables asestack-agent.service; and
  • finishes by running asestack-agent doctor.

All write-capable agent guards start as false.

3. Verify the agent locally

On managed.example.net, run:

sudo systemctl is-active asestack-agent
sudo systemctl status asestack-agent --no-pager
sudo journalctl -u asestack-agent -n 50 --no-pager
sudo asestack-agent doctor

The service should be active. The doctor command reports detected distribution information and local metrics without enabling guarded write actions.

4. Verify the controller heartbeat

Return to Servers on control.example.com and wait for the first heartbeat. Then confirm:

  • managed-01 appears in Server Inventory;
  • the hostname is managed.example.net or the host's configured system hostname;
  • status becomes online;
  • version and last-seen data are current; and
  • Agent Readiness lists the host's preflight results.

Select Preflight to queue a read-only host preflight. Wait for the latest command state to reach completed before enabling any host action.

5. Add optional host metadata

The generated agent environment leaves address and region blank. To label the host explicitly, edit /etc/asestack/agent/agent.env on the managed server:

ASESTACK_AGENT_ADDRESS=managed.example.net
ASESTACK_AGENT_REGION=primary

When the host should act as a private site origin behind an aseStack gateway, also provide its private Tailscale, WireGuard, or other routed address:

ASESTACK_AGENT_PRIVATE_ORIGIN_ADDRESS=10.88.0.20

Restart the agent after editing:

sudo systemctl restart asestack-agent

The private-origin value is used only when you deliberately configure gateway-based site deployment. See Sites.

Action guards

Enrollment establishes identity and read-only management; it does not automatically permit destructive operations. A remote action generally needs both:

  1. its controller-side command guard; and
  2. the matching managed-host action guard.

For example, selected-host Nginx changes require the Nginx command guard on the controller and the Nginx action guard in the agent environment. Keep both off until the relevant preflight is ready, a recovery path is tested, and you understand the generated plan. See the configuration reference.

Rotate or revoke an enrollment

Before a token and client certificate expire:

  1. Open Servers.
  2. Select Re-enroll for managed-01.
  3. Handle the new script as sensitive material.
  4. Run it on the same managed host.
  5. Confirm the new heartbeat and preflight.
  6. Revoke any older active enrollment for that server.

Use Current Enrollments → Revoke active if a generated script was exposed or a server is no longer trusted. Removing a managed server also revokes its active enrollments; an online server requires an explicit force-removal confirmation.

Troubleshooting

The updater cannot find an artifact

Confirm uname -m reports x86_64. The standard published release path currently uses Linux amd64 artifacts.

The agent cannot reach the controller

From the managed host, verify public health and certificate trust:

curl -fsS https://control.example.com/api/v1/health

If that fails, fix DNS, outbound firewall rules, TLS, or the reverse proxy before re-enrolling.

The service is active but the server is offline

Check /etc/asestack/agent/agent.env for the intended controller URL and server ID, then inspect the journal. Do not publish the enrollment token or private-key contents while troubleshooting.

The enrollment expired or was revoked

Create a new enrollment for the same server ID and run its generated script. Re-enrollment rotates both the token and mTLS certificate material.