Manage servers

Modify server information and control servers remotely.

Edit server information#

Change basic information#

1. Click Update on the server’s detail page
2. You can modify:
   • Name: Server identifier
   • Authorized groups: User groups with access
   • Owner: Server owner
3. Click Save

Note: Metric alerts are managed in the Metrics app—see Configure metric alerts.

Tunnel and code editor#

Two checkboxes in the Update panel decide whether a server can be used for port forwarding and for the browser code editor:

• Tunnel: allows port forwarding with alpacon tunnel
• Code editor: allows the code editor

In a work session, port forwarding and the code editor work only on servers where the box is checked. If no server in a session has it on, the feature in the session shows a warning that no server has it enabled.

Who can change them: owners and managers of a group assigned to the server, maintainers of the server, and users with the Staff or Superuser role. Other users don’t see the Update button.

Requirements:

If the server doesn’t meet them, the feature can’t be turned on: saving fails with an error that names the requirement. Upgrading the agent fixes the version requirement; it doesn’t add memory, so a server with less than 2 GB can’t run the code editor. If the agent later reports a version that doesn’t meet the requirement, Alpacon turns the feature off, and it stays off until you turn it on again.

On Windows servers, port forwarding works with Alpamon 2.5.1 or later, but the code editor can’t run: the box can be checked, but opening the editor ends with a startup timeout. See Windows servers.

Turning a feature off stops new port forwarding or editor connections to the server. An open editor can’t be reconnected while the feature is off.

Defaults for new servers: a Superuser sets whether each feature starts on for newly registered servers in Server defaults. The default applies once, when a server is registered, and only if it meets the requirements. Changing it doesn’t change servers that are already registered.

Server details#

View detailed information in the server detail page:

Overview tab:

• Agent information (version, status)
• OS information (distribution, version)
• System information (CPU, memory, disk)
• Operating information (uptime, boot time)
• Network interfaces
• Offline alert history

Next to the last-synced time, click Refresh now to pull current system information immediately instead of waiting for the next scheduled sync.

Under Network interfaces, Offline alert history lists this server’s resolved offline alerts, newest first, five per page: when each was raised (Raised), when it resolved (Resolved), how long it stood (Stood for), why it closed (Cause), and which channels delivered the resolution (Delivered—the same chips as Alert history). Cause shows a short label with a tooltip carrying the full sentence: Reconnected, Stable again (a flap phase settled), Decommissioned, Disabled, Alert turned off, Deleted, Instance off, No longer applies, or Not recorded for an alert resolved before causes were tracked. Unlike charts and metric alerts, this table isn’t gated by the Metrics extension—it’s available on every plan.

Activity tab:

• Command execution history
• Server comments and mentions
• User activity logs
• Direct logins that reached the server without Alpacon, in the same timeline as work sessions—see On a server’s page

Access tab:

• Direct-login coverage: whether direct logins to this server are captured, and for a server that isn’t covered, the reason, what to change and how to check—see Check a server
• System users, each with its last direct login, its open findings, and a flag when it is bound to a removed member
• System groups

Charts and metric alerts live in the Metrics app, not on server detail—see Monitor server status.

Logs tab:

• Recent logs from Alpamon agent
• Backhaul history (data transmission logs)
• Transmission status and data size

Server control#

Requirements:

• Server status: Connected
• Permission: owner or manager of an assigned group, a maintainer of the server, or a user with the Staff or Superuser role

Agent card#

The Agent card on a server’s detail page covers the Alpamon agent itself. Next to the agent’s version, Update policy shows the workspace’s agent update policy: Latest, One release behind, or Manual.

• Restart agent: restarts the agent process. Useful for resolving connection issues—the server briefly shows offline and reconnects on its own.
• Upgrade agent: updates the agent to the latest release and restarts it. Shown only when the update policy is Manual; under an automatic policy, the agent is upgraded inside the workspace’s maintenance window and no button is shown. On Windows the agent needs Alpamon 2.4.0 or later; for an older agent, see upgrading the agent.
• Install or upgrade alpamon-pam: installs the alpamon-pam package on the host as root through its package manager, or upgrades an older version, for a server registered with alpamon alone or one that was offline when sudo with MFA was turned on. Shown for a host that uses apt, yum, or zypper while its agent is connected. When the server’s sudo policy row shows that alpamon-pam isn’t set up, the same action appears as an install link on that row. While Sudo through Alpacon is off in Access rules, the button is disabled and shows sudo with MFA is off in Server access policies. A host already on the current version is left as it is, and a second request is refused while an install is still pending. The same action is available from the CLI as alpacon agent install-pam.

Click the button, confirm in the dialog, and watch the result in a toast message.

An upgrade never moves an agent to an older version. Under Manual, when the agent already runs the latest release, Upgrade agent stays visible but disabled, with the note Agent is up to date. While an upgrade is already in progress on the server, a second request is refused with “An agent upgrade is already in progress on this server. Try again after it finishes.”

Upgrade history#

On the server’s Overview tab, after network interfaces and offline alerts, Upgrade history lists automatic and manual agent upgrades for this server, newest first, five per page. Page controls appear below the list when there are more than five. Upgrade status and Started by (Automatic or Manual) narrow the list. Repeated failures of the same kind appear as one row, such as “Failed 3 times in a row”; while a filter is on, each attempt has its own row. Select a failed, timed-out, or rolled-back row with a log to open its agent log. All upgrade history opens upgrades for every server you can see. Anyone who can see the server can see its history.

Each row shows:

• Outcome: In progress, Succeeded, Rolled back (the new version didn’t come up cleanly, so the agent went back to the previous one), Failed, Timed out (the agent didn’t confirm the upgrade in time), or Refused (the upgrade was withdrawn before it reached the agent).
• Versions: the version the agent moved from and the version it moved to, for example 1.4.2 → 1.5.0. Until the agent reports back, the version it’s being upgraded to is marked (target).
• When and who: when the upgrade was requested, and who started it—a member’s username, an API token’s name, or Alpacon automatic policy (latest) for an automatic upgrade.
• Reason: for a failed or rolled-back upgrade, why it didn’t land, and for a refused or failed one, a short explanation from Alpacon.

The reason labels are:

A Refused row usually means the maintenance window closed before the upgrade reached the agent, the policy was switched to Manual, a manual upgrade replaced a pending automatic one, or Alpacon paused automatic upgrades platform-wide. Nothing was installed, and the agent keeps running the version it had.

Records begin when upgrade history was introduced. Earlier upgrades aren’t shown, and a server with no upgrades since then shows “Upgrade records are kept from the time this history was introduced. Earlier upgrades are not shown.” Each upgrade is also recorded in the activity log, both when it’s sent and when it ends, so it’s included when you search or export workspace activity.

To see upgrades across every server you can see, open Servers and choose More → Agent upgrades. It lists the latest agent upgrades on those servers, newest first, and any role that can see servers can open it. Filter it by Outcome or by Started by (Automatic or Manual), and select a server name to open that server. Each row reads the same way as the list above. The same history is also available through the agent upgrades API.

Upgrade failure alert#

When an agent upgrade fails or is rolled back, Alpacon raises a warning alert on that server, titled for example Agent upgrade to 1.5.0 failed. It appears in the bell and the alert list only: no email or Slack message goes out for it, and it isn’t part of the hourly open alert digest. A server has at most one of these alerts open at a time, however many upgrades fail in a row, and the next successful upgrade resolves it. A successful upgrade sends no notification, and an upgrade that fails because of Alpacon configuration issue; no action needed raises no alert.

Host operations#

Rebooting a server, shutting it down, or upgrading its operating system packages isn’t a button on the server page. Run it inside a work session instead: open Websh in the session, or attach alpacon exec to it with --work-session, then run the command with sudo, the same way as any other privileged command (sudo reboot, sudo shutdown -h now, sudo apt upgrade -y or your platform’s package manager). For example, alpacon exec --work-session SESSION_ID my-server -- sudo reboot reboots my-server inside the session SESSION_ID. That keeps the operation under your workspace’s sudo policy, MFA, and approval rules, and Alpacon records the session like any other. If you’re planning one, mute the server’s alerts first—Alpacon doesn’t hold the offline alert automatically for a command run this way.

Server list actions#

Select one or more servers on the server list to:

• Request a work session covering the selected servers (Connect).
• Mute alerts on the selected servers—see Mute a server.
• Unregister the selected servers—see Bulk deletion.

Agent restart and agent upgrade aren’t available from the list; use the Agent card on each server’s detail page. Refreshing system information isn’t available from the list either; use Refresh now next to the last-synced time on the detail page.

Filtering:

• Group filter: Show servers from specific groups
• Status filter: Separate Connected/Disconnected servers
• Search: Quick search by server name

Server comments#

Share server-related information with team members.

Add comment:

1. Server detail > Activity tab
2. Write content in comment input
3. Mention specific users with @username
4. Click Add

Pin comments:

• Pin important comments to top (max 3)
• Click pin icon to pin/unpin

Upgrade a Windows agent that cannot self-update#

Automatic and manual agent upgrades are listed in upgrade history. Linux upgrades use the host package manager; macOS and Windows download a release. The server needs outbound HTTPS to api.github.com to check versions. During an upgrade the agent restarts, so the server may briefly appear offline. If the upgrade fails, the previous version continues to run.

On Windows, an agent running Alpamon 2.4.0 or later self-updates the same way as macOS. An agent older than 2.4.0 can’t update itself: its upgrade fails with Unsupported platform in the upgrade history, and Alpacon doesn’t schedule another one until the agent reports a different version. Re-running the installer doesn’t help on a registered host, because alpamon.exe register stops at config file already exists. Replace the binary by hand once instead, and later upgrades run on their own. Do the same if the self-update path is blocked.

Run these from an elevated PowerShell on the server itself (local console, RDP, or cloud serial console), not over Websh. Stopping the service ends every open Websh and WebFTP session and tunnel on the server, not only yours, so pick a time when no one is using it:

1. From GitHub Releases, download the latest alpamon-X.Y.Z-windows-amd64.zip and alpamon-X.Y.Z-checksums.sha256 into the same folder. Check that the archive’s hash matches the hash listed for that archive in the checksums file, and don’t use the archive if they differ:

   powershell

   (Get-FileHash .\alpamon-X.Y.Z-windows-amd64.zip -Algorithm SHA256).Hash.ToLower()
   Select-String 'alpamon-X.Y.Z-windows-amd64.zip' .\alpamon-X.Y.Z-checksums.sha256

2. Unblock and extract the archive as in Method 1.

3. In the extracted folder, stop the service and swap the binary. An older agent can leave an alpamon.exe process running after the service stops, which keeps the file locked, so end any that remain and move the old file aside instead of overwriting it:

   powershell

   Stop-Service alpamon -Force
   Get-Process alpamon -ErrorAction SilentlyContinue | Stop-Process -Force
   Move-Item -Force "$env:ProgramFiles\alpamon\alpamon.exe" "$env:ProgramFiles\alpamon\alpamon.exe.old"
   Copy-Item .\alpamon.exe "$env:ProgramFiles\alpamon\alpamon.exe"
   Start-Service alpamon

   The new agent deletes alpamon.exe.old when it starts.

4. Check that the agent version on the server’s Agent card shows the new release.

If an upgrade doesn’t take effect, see agent upgrade issues.

Related docs#

• Monitor servers
• Control server access
• Remove a server