Hybrid Appliances

Register an on-premise appliance, download the signed agent for it from Aegis, and enrol it with a single-use token.

A hybrid appliance (a small server inside your own network that runs the Aegis agent) lets connectors reach systems that are not reachable from the internet. The appliance connects out to Aegis; nothing in your network has to accept calls from outside. This screen, Settings → Integrations → Appliances at /settings/appliances, is where you register appliances, fetch the agent package and hand each appliance the settings it needs to enrol. Each appliance also has its own page, where you follow its health, send it jobs and adjust its agent settings.

Who uses it

What's on this screen

Under the breadcrumb Settings / Integrations / Appliances sit the title Appliances and a one-line description. Below them, up to two amber banners can appear. The licence banner described above shows when the Hybrid Appliance licence is missing. The banner "Appliance enrollment is not configured" shows when the deployment has no appliance certificate authority: it explains that a token could not be used to enrol anything and asks you to have your operator provision the appliance CA first. The captured screen shows this second banner, which is why its token buttons are greyed out.

Two cards then fill the page. Agent package offers the signed agent for the first installation on your appliance server. Hybrid Appliances carries Add Appliance at its right and lists every registered appliance, one per row:

Each row ends with Generate token (on an enrolled appliance, Regenerate token) and a bin icon. With nothing registered, the list reads "No appliances yet". The list shows up to 100 appliances on one page, with no paging controls.

  1. Open Administration in the sidebar and select Settings. On the Integrations tab, select the Hybrid Appliances card. The Appliances screen opens.
  2. To read this chapter while you work, select the book icon in the top bar. The User Guide opens at the page for the screen you are on.
  3. Read the Agent package card. When a signed release is available, it names the agent version and lists each package file with its .sha256 and .sig files beside it. The download comes from your own Aegis tenant, which checks the package's checksum and signature before serving it. Where no release has been published for your deployment yet, as on the captured screen, the card reads "No signed agent package is available for download on this deployment yet."
Settings → Appliances with the certificate-authority banner, the Agent package card and three registered appliances — /settings/appliances.
Settings → Appliances with the certificate-authority banner, the Agent package card and three registered appliances — /settings/appliances.

Registering an appliance

  1. Select Add Appliance. A dialog asks for a Name — lowercase letters, digits and hyphens, 3 to 63 characters, starting and ending with a letter or digit, for example dc1-appliance-01 — and an optional Display name. A name that breaks the rule is refused under the field before anything is sent.
  2. Select Create. The dialog closes, "Appliance created" confirms it, and the appliance joins the list as Pending.
  3. Select Generate token on the appliance's row to open the enrolment dialog, described below. When the licence or the appliance certificate authority is missing, the button stays greyed out, and hovering over it says which of the two is lacking.

Installing the agent

Download the package together with its .sha256 and .sig files. Before installing, run sha256sum -c on the .sha256 file and verify the .sig signature with the Euraika public key, as the customer guide that comes with the agent explains. You need this download only for the first installation: once enrolled, the appliance fetches later updates itself over its secured connection, and only versions published for your tenant are offered to it.

Enrolling an appliance

Generate token opens Enrollment token — followed by the appliance's name. No figure is shown here because the token on screen is a live secret.

  1. Copy the token straight away with Copy token. The amber note says why: it is shown only once and cannot be retrieved again. The line below it gives the expiry — a token is valid for 24 hours and can be used once.
  2. Check the two addresses the agent needs. Runtime endpoint is the appliance host the agent talks to after enrolment, using its certificate. Enrolment endpoint is the main Aegis address, used once for the token enrolment, because the agent has no certificate yet. The dialog also shows the Appliance ID and Tenant ID.
  3. Select Copy settings to copy the Agent settings block — the two endpoints, the token, both ids and the state directory — and paste it into the agent's environment file on the appliance server. Restart the agent, then select Close.

Once the agent has enrolled, its chip in the list changes from Pending, and the heartbeat, telemetry and agent version start to fill in.

Treat the token as a password

Anyone holding an unused token can enrol a machine as this appliance until it expires. Paste it only into the agent's settings file, never into a ticket or chat. If it may have leaked, generate a new token.

The appliance's own page

Select an appliance's name in the list to open its page. The header repeats the status chip, last heartbeat, last telemetry and agent version, and Back to appliances returns to the list. Six tabs sit below; each one can be linked to directly. No figure of this page was captured for this edition of the guide.

Revoking or removing an appliance

The bin icon at the end of a row acts according to the appliance's state. On a Pending appliance it is Delete: the registration was never used and is removed. On an enrolled appliance it is Revoke: its certificate is invalidated and it is disconnected, but the entry stays so you can enrol it again with a new token. Both ask for confirmation first and work without the licence, so a fleet can always be wound down.

Tips and limits

Where this connects