Skip to content

Servers Auto-register

SiteCenter exposes a small public surface that powers the Auto-Register Linux Servers flow inside the workspace Servers area. The UI retrieves a workspace-specific secret, renders the install command, and the Linux script in turn calls the backend to create the server, assign it to the workspace, and wire up the host-stats monitor.

API surface

GET /api/v1/acc/{accountCode}/ws/{wsId}/servers/getSecret

  • Purpose: fetch the workspace secret used by the auto-registration script.
  • Authentication: the request uses the usual account/workspace session contextualized by the logged-in browser. Frontend code calls this endpoint via apiServerGetAutoregisterSecret/...Regen.
  • Parameters:
  • accountCode (path) – alphanumeric identifier for the account.
  • wsId (path) – workspace UUID.
  • regen (query, optional, default false) – rerun generation logic and replace the stored secret.
  • Response (200 OK): { accountCode, workspaceId, secret }.
  • Error responses: 400 when the workspace does not exist or regen request is invalid, 500 on unexpected failures.

POST /api/pub/v1/a/{accountCode}/ws/{wsId}/servers/autoRegisterNew

  • Purpose: called by the install script to register a new Linux server and create its host-stats monitor.
  • Security: the controller validates the secret in the payload against the workspace property server-autoregister-secret and checks IP formats.
  • Payload (JSON):
  • secret (required) – value pulled from the /servers/getSecret call.
  • hostname (required) – Linux host name the script detected.
  • externalIp (required) – public IP detected by the script.
  • localIp (optional) – private IP if the script can resolve it.
  • Response (200 OK): { accountcode, MonitorCode, secret } containing the monitor reference data (used for future reporting).
  • Idempotency/limits: the controller reuses existing servers/monitors if they match hostname + IP and enforces per-account server/monitor quotas.

Auto-register command

The Svelte widget (/servers/autoregister/+page.svelte + ServerAutoRegisterInstructionsLinux.svelte) renders the command shown below once the workspace secret arrives:

bash <(curl -sL https://raw.githubusercontent.com/sitecenter-org/linux/main/scripts/monitoring/server/sitecenter-autoregister-host.sh) {accountCode} {workspaceId} {secret}

This script: - verifies prerequisites (Linux with curl, bash, root or sudo access, and cron). - detects server metadata (hostname, external IP, local IP, and sysinfo). - calls POST /api/pub/v1/a/.../servers/autoRegisterNew with the gathered data + secret. - downloads the monitoring bundle, installs the host stats agent in /usr/local/bin, and sets up a cron job that runs every minute. - stores the newly created monitor's aliveCode as the secret field in the API response so the agent can authenticate.

If a workspace secret must be rotated (all existing scripts become invalid), users click Regenerate in the same panel, which calls /servers/getSecret?regen=true and replaces the value stored in workspace properties.

Manual fallback

If workspaces lack the auto-register secret or permissions, users can still add a server manually through /app/account/{accountCode}/ws/{wsId}/servers/ and create host-stats monitors in the UI. The auto-register flow is simply a convenience wrapper around the same underlying server/monitor services.

Notes

  • The secret is stored on the workspace level property named server-autoregister-secret and is never exposed outside HTTPS requests.
  • The documentation page does not rely on CSR data but still sets csr = true for hot module reload.