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.

Agent Fleet Management — Agent Installation

Overview​

The Agent Installation tab guides you through deploying a new copy agent onto a target host.

Agents run as standalone Java processes. They connect back to the console over HTTPS and register themselves on first contact. Once registered, the agent appears on the Live Agents tab and can receive copy jobs immediately.

Prerequisites​

  • Network access. The target host must reach the console at the address you use to open the console in your browser. The install command downloads the script from that address.
  • Console DNS Name. If a Console DNS Name is set on this tab, the host must also reach the console at that name on the same port. The agent uses that name from then on.
  • Storage. The host must have enough storage throughput for the expected copy load.
  • SELinux disabled. The agent service cannot start while SELinux is Enforcing. See the steps below.
  • Java 25.0.5. See the Java requirement below.
  • Hostname. The host's hostname must resolve to its interface IP address, not to a loopback address such as 127.0.1.1.
  • Time. The host syncs to NTP and runs in UTC.

Disable SELinux​

The install script checks with getenforce. If SELinux is Enforcing, the script exits with these instructions.

  1. Edit the SELinux config file to make the change permanent. It takes effect after the next reboot.

    vi /etc/selinux/config

  2. Set the line SELINUX=disabled, then save and exit (:wq).

  3. Disable SELinux immediately, without a reboot. This is required before you re-run the installer.

    setenforce 0

Java requirement​

The agent requires Java 25, and Java 25.0.5 should be pre-installed 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 pre-installing is the default path. The install script uses a Java 25 or newer that is already installed, even if it is not the default java. It installs Amazon Corretto 25 automatically only if there is none.

Auto-install requires outbound HTTPS to corretto.aws. If the host has no internet access, pre-install Java before you run the script.

See Which Java the agent runs.

Installation steps​

  1. Generate an agent key. Click Generate Key. The console creates a one-time registration token. Copy the key, because it is shown only once.
  2. Run the install command. As root on the target host, run the one-liner shown in the UI or in the key dialog.
  3. Verify registration. Switch to the Live Agents tab. The new agent should appear within 30 seconds with status ONLINE.

The install script performs these actions:

  • Finds a Java 25 or newer. It uses the default java first, then the one with the highest major version under /usr/lib/jvm.
  • Downloads and installs Amazon Corretto 25 only if no suitable Java exists. It uses RPM on RHEL, Rocky, and SUSE, DEB on Debian and Ubuntu, and tar.gz on other Linux distributions.
  • Prints progress and clear error messages if the internet is unreachable or the install fails.
  • Creates the argus-agent service user and the /opt/argus-agent/ directory.
  • Downloads copy-engine.jar from the console using the agent key.
  • Writes a default jvm.args file and pins the chosen Java in java.pin.
  • Writes the start script and registers a systemd service that runs it.
  • Enables and starts the service.

Which Java the agent runs​

The agent needs Java 25 or newer. The install script chooses a Java and pins it. The agent keeps starting even if the host's default java changes later, for example after an OS update.

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 does it download Amazon Corretto 25.

The script 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-copy-engine-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 not, the script picks another Java 25 or newer the same way the installer does, and pins that one.
  • If the host has no Java 25 or newer, the script starts the default java anyway. That start fails, and the script writes the reason to the service journal.

Check which Java is used​

  • cat /opt/argus-agent/java.pin shows the pinned Java.
  • journalctl -u argus-copy-engine shows the start script's messages, such as argus-agent: pinned Java … and 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 installed with an older install script​

The systemd unit of these agents still runs /usr/bin/java, the host's default Java. They 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-copy-engine.service
systemctl daemon-reload && systemctl restart argus-copy-engine

This pins that Java path directly in the unit. Re-running the install command also installs the start script.

Agent key​

The registration key is a one-time token. After the agent registers successfully, the key is consumed and cannot be reused. The console then issues the agent its own ongoing key. The agent sends it in the X-Agent-Key header on every heartbeat and call. You can rotate that key from the Dashboard.

If registration fails, regenerate the key and try again.

JVM configuration​

After the agent registers, you can give it a custom JVM profile with heap size, GC tuning, and thread counts.

  1. Define profiles in Setup & Settings > Diagnostics > JVM Profiles.
  2. Assign one with the agent's JVM Profile picker on the Live Agents tab.

The agent restarts with the new JVM flags at a heartbeat when no copy job is running on it. While a job runs, the change waits and is retried on every heartbeat. The agent's log notes once that the change is deferred. The restart therefore never cuts off a running copy.

To apply the change sooner, drain the agent and let its running jobs finish.

JVM profiles and host sizing guide​

The JVM Profiles & Host Sizing Guide table on this tab is populated from the JVM profiles configured in Setup & Settings > Diagnostics > JVM Profiles.

For each profile, these columns are computed from the profile's heap arguments (-Xms and -Xmx) by a sizing formula:

  • Host RAM
  • Required vm.max_map_count
  • CPU cores
  • Disk
  • OS thread count
  • Concurrent-job capacity

If you add, edit, or delete a profile on the Diagnostics tab, this table updates on the next page load. The Default profile is built in and cannot be edited.

To support a new host class, create a profile on Diagnostics > JVM Profiles. The matching sizing row then appears here with no further configuration.

Assigning one of these profiles to an agent restarts the agent only when no copy job is running on it. See JVM configuration.

Required vm.max_map_count​

Every built-in profile uses the ZGC garbage collector. ZGC needs a Linux kernel memory-mapping limit of at least floor(heap MB × 1.8).

Many hosts ship with the historical default of 65,530. That is enough for the smaller profiles but too low for 48 GB Host and 64 GB Host. Those two rows are shown in red with a warning icon.

Before you assign a flagged profile, raise the limit on the agent host:

  1. Run sysctl -w vm.max_map_count=<value>.
  2. Persist the value in /etc/sysctl.d/.

The Live Agents tab applies the same check to each agent's last-reported value:

  • In the profile picker, options below the agent's current limit are shown in red with a warning prefix.
  • If you assign one anyway, a confirmation dialog shows the exact numbers and remediation commands.
  • The bulk Set JVM Profile action runs the same check. It shows one combined confirmation that lists which selected agents are short and by how much. Confirming applies the profile to all of them.

The requirement is specific to ZGC. A custom profile that does not enable ZGC (-XX:+UseZGC) has no such requirement. An example is a profile that uses G1, the JVM's default collector. Its column shows "—" and it never triggers a warning.

The heap is taken from the profile's last -Xmx argument. That is the one the JVM applies if a profile lists more than one.

DNS cache flags​

Every built-in profile passes -Dsun.net.inetaddr.ttl=0. The agent's JVM keeps no DNS answers, so every new connection resolves the source and target names again. Connections spread across the nodes behind a round-robin DNS name.

When a lookup fails, for example because the DNS server is down, the copy waits and retries for up to 15 minutes instead of failing the object. It keeps its multipart upload.

The DNS Cache TTL setting in Setup & Settings > Advanced Settings does not change copy agents.

Vault agent​

Vault agents run on their own Linux VM inside the vault network and manage vault-side operations.

You do not install vault agents here. Go to Vault Operations > Vault Agents > Install to generate a vault-scoped registration key and download the matching install command. This tab generates copy-engine keys only.

Tips​

  • Run the agent as a systemd service or equivalent, so that it restarts automatically after a host reboot.
  • Multiple agents on the same host need a different port each. Set the port with the ENGINE_PORT environment variable. The default is 9091.
  • After a console upgrade, an agent that runs an older version shows an Upgrade button on the Live Agents tab. After you click it, the agent pulls the new JAR from the console at its next heartbeat. It waits while copy jobs run on it.
  • Cancel Upgrade withdraws the request while it is still pending.