Skip to main content
Migration Notice
We're migrating documentation from the old portal into this one. Some things may look a little different or out of place in the meantime — we know, and we're working to get it right. If something's unclear or doesn't look right, let us know.

Vault Agents — Install

Overview​

The Install tab walks you through the two steps needed to deploy a vault agent on a remote vault host:

  1. Generate a vault-scoped authentication key.
  2. Run the one-liner install command as root on the target machine.

Console DNS Name​

If your console is behind a load balancer or its IP may change, enter a DNS hostname here and save it. All install commands generated after saving use this hostname for CONSOLE_URL instead of the current IP address.

Vault agents installed with a DNS name survive console IP changes without being registered again. They keep connecting to the same hostname.

Leave this field blank to use the current browser origin (IP-based URL) in install commands.

Step 1: Generate a vault agent key​

Click Generate Vault Key to create a new vault-scoped authentication token. In the dialog:

  1. Enter a descriptive Key Name, for example vault-agent-site-a. This name identifies the agent in the token list and in the Dashboard.
  2. Click Generate Key.
warning

The key is shown exactly once. Copy it immediately. It cannot be retrieved after you close the dialog.

Vault scope​

Vault agent keys use the vault scope. They can authenticate only vault agent registration and vault sync endpoints. They cannot access copy-engine jobs, the settings API, or any other console functionality.

This is a deliberate security boundary. A compromised vault key cannot be used to exfiltrate data or change console configuration.

Step 2: Run the install command​

After you generate a key, run the install command as root on the vault agent host. Replace <VAULT_KEY> with the key value from Step 1.

curl -fsSL "<CONSOLE_URL>/api/agents/install.sh?type=vault-agent&key=<VAULT_KEY>" | bash

Replace the console's 443 and 8443 certificates with CA-issued certificates (TLS 1.2 or higher) before you install. Add -k to the command only while the console still uses its default certificate, because -k turns the TLS check off.

The install command is also shown pre-filled in the key display dialog right after key generation. You can copy it from there.

Remote host prerequisites​

The vault agent host must meet these requirements before you run the install command.

RequirementDetail
Java 25.0.5Pre-install Java 25.0.5 in the VM template. The installer checks only for Java 25 or newer, not for 25.0.5. Run java -version and confirm 25.0.5 before you install. The vault has no internet access, so this is the default path. If Java is missing, the script installs Amazon Corretto 25, which requires HTTPS to corretto.aws. See Which Java the agent runs.
SELinux disabledThe agent service cannot start while SELinux is Enforcing. See below.
Linux (x86_64 or aarch64)RHEL 8+, Rocky Linux 8+, Ubuntu 20.04+, SUSE/OpenSUSE, or any systemd-based Linux.
Root or sudo accessThe install script creates a systemd service.
Outbound HTTPS to consolePort 443 to the console only. The vault agent needs no S3 access.
Vault management APIOutbound 4443 to the vault ObjectScale management API.
Air-gap switchOutbound 22 (SSH) or 443 (RESTCONF) to the switch.
8 vCPU and 32 GB RAMMinimum host size for the vault agent.
HostnameThe hostname must resolve to the interface IP address, not to a loopback address such as 127.0.1.1.
TimeThe host syncs to NTP and runs in UTC.
Persistent storageThe agent writes config and state to /opt/argus-agent/. The config is in /opt/argus-agent/.argus-vault/.

Disable SELinux before installation​

SELinux in Enforcing mode blocks the systemd service from starting. Disable it before you run the install script.

  1. Make the change permanent. It takes effect after the next reboot.

    vi /etc/selinux/config

  2. Find the SELINUX= line and change it to:

    SELINUX=disabled

  3. Save and exit (:wq).

  4. Disable SELinux immediately without rebooting. This is required before you re-run the installer.

    setenforce 0

The install script checks SELinux status with getenforce. If it detects Enforcing, it exits and prints these instructions. After you run setenforce 0, re-run the install command.

What the install script does​

The script runs fully automated, with no prompts. It does the following:

  1. Checks for Java 25 or newer, and installs it if needed.
    • It uses the default java, or else the one with the highest major version under /usr/lib/jvm.
    • Only if there is none, it downloads and installs Amazon Corretto 25. It uses RPM on RHEL, Rocky, and SUSE, DEB on Debian and Ubuntu, and tar.gz on other Linux.
    • It prints each step and exits with a clear error if the internet is unreachable or the install fails.
  2. Downloads the vault agent JAR from this console (/api/agents/download/vault-agent).
  3. Creates /opt/argus-agent/ and writes the agent config (/opt/argus-agent/.argus-vault/config.json) with the provided key and console URL.
  4. Pins the chosen Java in /opt/argus-agent/java.pin, writes the start script, and creates a systemd service (argus-vault-agent) that runs it. The service is configured to start on boot.
  5. Starts the service. The agent connects, registers itself, and appears in the Dashboard tab.

Once registered, the agent discovers its assigned protection groups on its own. It then manages the incremental sync schedule and airgap lifecycle.

Which Java the agent runs​

The agent needs Java 25 or newer, and the vault agent host should have Java 25.0.5 pre-installed in the VM template. The install script decides which Java to use and pins it. The agent then keeps starting even if the host's default java changes later, for example when an OS update or another package makes Java 21 the default.

At install​

  1. The script uses the default java if it is Java 25 or newer.
  2. If not, it looks for an installed Java 25 or newer under /usr/lib/jvm and /usr/lib64/jvm. It uses the one with the highest major version.
  3. Only if there is none, it downloads Amazon Corretto 25.

It writes the real path of the chosen Java to /opt/argus-agent/java.pin, for example /usr/lib/jvm/java-25-amazon-corretto/bin/java.

At every start​

The systemd unit runs a start script, /usr/local/lib/argus-agent/argus-vault-agent-start.sh, instead of running java directly. The script is owned by root.

  • The script uses the pinned Java as long as it still exists and is Java 25 or newer.
  • If it does not, the script picks another Java 25 or newer the same way as the installer and pins that one.
  • If the host has no Java 25 or newer at all, the script starts the default java anyway. This fails, and the script writes the reason to the service journal.

Check which Java is pinned​

Use these commands:

cat /opt/argus-agent/java.pin
journalctl -u argus-vault-agent

The first command shows the pinned Java. The second shows the start script's messages:

argus-agent: pinned Java …
argus-agent: ERROR: Java 25 required …

The agent's own log shows nothing when Java is the problem, because the JVM stops before the agent starts logging. If the install fails, the script also prints the last lines of the journal.

Agents whose service unit runs /usr/bin/java​

On some agents the systemd unit still runs /usr/bin/java, the host's default Java. These agents stop starting after the default changes to an older Java. This happens on the next upgrade, JVM profile change, crash, or reboot. systemd then retries forever with UnsupportedClassVersionError.

To fix one without reinstalling, run the following as root. Use the host's Java 25 path.

JAVA=/usr/lib/jvm/java-25-amazon-corretto/bin/java
sed -i "s#^ExecStart=[^ ]*java #ExecStart=${JAVA} #" /etc/systemd/system/argus-vault-agent.service
systemctl daemon-reload && systemctl restart argus-vault-agent

This pins that Java path directly in the unit.

info

Re-running the install command also installs the start script. However, it rewrites /opt/argus-agent/.argus-vault/config.json, so the vault agent registers again.

Quantum Trust Signed Delivery​

A Quantum Trust Software Delivery card appears above the standard JAR upload. It lets you install a vault agent update as a Superna-authenticated .qtspkg package instead of a plain JAR file.

Superna signs QTS packages using ML-DSA-87 (NIST FIPS 204). The console verifies the signature before it allows installation. A green Quantum Trust Signed badge confirms the package is genuine.

If the signature check fails or the package is for a different component, installation is blocked with a clear error.

To install a package:

  1. Drag and drop a .qtspkg file onto the card, or click to browse.
  2. Review the validation result.
  3. Click Install Build N to confirm.
  4. Restart the service to apply the update.

The standard JAR upload below remains available alongside QTS. You can use either path.

Vault Agent JAR​

The Vault Agent JAR panel shows the version of the JAR hosted on this console. Vault agents download this JAR during fresh installs.

After an upload, registered agents compare their running version against the hosted version on every heartbeat. When the versions differ, a Version Mismatch badge appears on the Dashboard sub-tab and alarm VA-004 fires.

Which JAR the console hosts​

Every console image includes the vault agent built with it, stamped with the console's build, for example X.Y.Z-1510. When the console starts with a different agent than the one hosted, its own agent becomes the hosted JAR. A console upgrade or rollback therefore also makes the matching vault agent available.

A JAR you uploaded is kept across console restarts while its build number is higher than the console's own agent. When a console upgrade brings a newer agent, that agent replaces the upload. The console log says which JAR it kept or installed.

info

Self-upgrade is operator-initiated, not automatic. To upgrade an agent, click the up-arrow button on its Dashboard card and confirm. See the Dashboard help for the full upgrade lifecycle (UPGRADE_MANIFEST exchange, SHA-256 verification, and restart).

Upload a new JAR​

  1. Select the .jar file using the file picker.
  2. Enter the version string, ending in its build number, for example X.Y.Z-1520. It is displayed in the Dashboard and used for upgrade comparisons.
  3. Click Upload.

An upload whose version does not end in a build number, or is not higher than the console's own agent, is replaced by the console's agent on the next console start.

If no JAR is uploaded, fresh installs fail at the download step.