Skip to content

Documentation

Agent updates

This guide shows how to bring a new LEA agent version to your hosts: import it, try it on a few hosts first, then roll it out to everyone, and go back if something is wrong.

Before you start

  • You need the Agent updates permission (administrators have it). The page is Settings → Agent updates.
  • Every release of LEA Platform contains an agent pack, agents/lea-agent-<version>.tgz with its signature lea-agent-<version>.tgz.sig. The upgrade script imports it for you. Newer agent packs are also published on the LEA Portal.
  • Importing a version changes nothing on your hosts. Hosts only get a version you pin to them or make the fleet default.

How agent updates work

An agent update is the agent replacing its own runner program with the version assigned to its host, without reinstalling.

  1. Each host is assigned one version: its host pin, otherwise a group pin of one of its groups, otherwise the fleet default. A host with none of these keeps the version it runs.
  2. When the assigned version differs from the version the host runs, the server offers it on the next check-in (about every 30 seconds).
  3. The agent downloads the program for its own system and processor from your LEA server and checks its SHA-256 checksum. A file with a wrong checksum is thrown away.
  4. Agents from version 2.1.0 then restart themselves into the new version. Older agents only download it and switch at their next restart; see Agents older than 2.1.0.
  5. If the new version does not start, the agent goes back to the version it had and tries once more. After two failed starts it stays on its version and the host shows FAILED.

Nothing is uninstalled: enrollment, certificates and lea.conf stay as they are.

Versions

The Versions table lists every agent version this server knows.

ColumnWhat it means
PlatformsThe systems and processors this version has a program for, such as linux/amd64 or windows/arm64.
SignatureWhether the pack's signature was checked with the GSR key when it was imported; VERIFIED is expected.
HostsHow many hosts run this version now, and how many are assigned to it.
MandatoryMarks a version all hosts must reach; hosts still behind a mandatory version after a day raise a notification.

DEFAULT next to a version means it is the fleet default. A version that is the default or pinned somewhere cannot be deleted.

Hosts

The Hosts table shows, for every host, the version it runs and the version it should run.

ColumnWhat it means
AssignedThe agent version this host should run: its host pin, else a group pin, else the fleet default.
FromWhere the assigned version comes from: a host pin, a group, or the fleet default.
StatusWhere this host is in the update: CURRENT, UPDATING, RESTART PENDING, FAILED, NO BUILD or NOT ASSIGNED.
StatusMeaning
CURRENTThe host runs its assigned version.
UPDATINGThe host has not reported the new version yet. It downloads it on its next check-in.
RESTART PENDINGThe new version is downloaded and checked. The agent switches when it restarts.
FAILEDThe download, the checksum or the start of the new version failed. Hover the pill to see why. The host keeps working on its old version.
NO BUILDThe assigned version has no program for this host's system and processor, so nothing is offered. Import a pack that includes it, or pin another version.
NOT ASSIGNEDNo pin and no fleet default apply. The host keeps its version.

To find hosts in a large fleet:

  • Type in Search host, version, platform or group and press Enter. For example 2.1.0, linux/arm64 or a group name.
  • Click a status (for example Failed) above the table to show only hosts in that state. The number next to each status counts the hosts that match your search.
  • Click a column header to sort by it. Click it again to reverse the order.
  • Use the page controls under the table to move between pages and choose how many rows to show.

The search, the status and the sort are kept in the page address, so you can share or bookmark the view.

To pin many hosts at once:

  1. Search or choose a status so that the table shows the hosts you want.
  2. Click Select all N matching. You should see "N selected" next to the result count.
  3. Click Pin N selected and choose the version.

The checkbox in the table header selects the hosts on the current page only. Clear selection unselects all.

Import an agent version

  1. Open Settings → Agent updates.
  2. Under Import an agent version, click Choose pack (.tgz) and pick lea-agent-<version>.tgz.
  3. Click Choose signature (.sig) and pick lea-agent-<version>.tgz.sig.
  4. Click Import.

You should see: "Imported agent version 2.1.0 (signature valid) for darwin/amd64, …". The version appears in Versions with VERIFIED.

If your LEA server may reach the LEA Portal, paste the pack address into Or the pack address from the LEA Portal and click Import from address instead. The server downloads the pack and the .sig next to it.

From a shell on the LEA server:

./lea_packs.sh import agents/lea-agent-2.1.0.tgz

With the command line tool:

lea agents import lea-agent-2.1.0.tgz
lea agents import --url https://portal.example.com/agents/lea-agent-2.1.0.tgz

Note: A pack whose signature does not verify is refused. A version number that is already imported with different programs is refused too.

Try a version on a few hosts first

A segmented rollout gives a new version to a test group first and to everyone later.

  1. Create a group with a few test hosts, for example canary. See Groups.
  2. In Versions, click the pin icon on the new version.
  3. Pick the group under Groups and click Pin.

You should see the hosts of that group under Hosts with the new version under Assigned, From showing the group, and Status going from UPDATING to CURRENT within a few minutes.

To pin single hosts, tick them in Hosts and click Pin selected.

From the command line:

lea agents pin 2.1.0 --group canary
lea agents pin 2.1.0 --host web-01 --host web-02
lea agents hosts --version 2.1.0

A host pin wins over a group pin. When a host is in several pinned groups, the lowest pinned version wins.

Roll out to every host

  1. Check that the test hosts show CURRENT and still report results.
  2. Under Fleet default, choose the new version.

Every host without a pin now updates on its next check-in. Pinned hosts and groups keep their pinned version until you remove the pin.

lea agents default 2.1.0

Tip: Choose None (only pinned hosts and groups update) as the fleet default when you want every update to go through pins.

Go back to an earlier version

  1. Pin the earlier version to the affected group or hosts, or make it the fleet default.
  2. The agents download it and restart into it.

The newer program stays on the host under the name disabled-lea-agent-runner-…, so going forward again needs no new download.

Rolling back works for agents from 2.1.0. An agent older than 2.1.0 always starts the highest version it finds; to roll one back, use Update an agent by hand.

Remove a pin

  • A group pin: in Group pins, click Remove.
  • A host pin: in Hosts, click Unpin on the host.
  • From the command line: lea agents unpin --group canary or lea agents unpin --host web-01.

The hosts follow their group or the fleet default again.

Update an agent by hand

Updating an agent by hand installs the agent your LEA server ships over the installed one, without enrolling the host again.

Use it for an agent that cannot update itself, to roll back an agent older than 2.1.0, or to update the watchdog. The watchdog (lea-agent) starts the runner and is not replaced by automatic updates.

Copy the command from Update an agent by hand on Settings → Agent updates and run it on the host. It looks like this:

Linux and macOS, as root:

curl -fsSL https://lea.example.com/deploy/deploy.sh | sudo LEA_SERVER='lea.example.com' LEA_UPGRADE=1 bash

Windows, in an Administrator PowerShell:

$env:LEA_SERVER='lea.example.com'; $env:LEA_UPGRADE='1'; curl.exe -fsSL https://lea.example.com/deploy/deploy.ps1 | Out-String | Invoke-Expression

You should see: "LEA agent updated on linux/amd64; it reports its new version on the next check-in".

The command stops the agent, replaces both programs, removes every downloaded version and the update state, and starts the agent again. Enrollment, certificates and lea.conf are kept. Without LEA_UPGRADE=1, the install command refuses to touch an existing installation.

Agents older than 2.1.0

Agents before 2.1.0 download an assigned version and check it, but they do not restart themselves.

  • They show UPDATING until they run the new version, because they do not report their update state.
  • Restart them once to switch: Linux sudo systemctl restart lea, macOS sudo launchctl kickstart -k system/com.lea.agent, Windows Restart-Service LEAAgent. Or use Update an agent by hand.
  • From 2.1.0 on, every later update and rollback is automatic.

On Windows, downloaded versions are named lea-agent-runner-windows-amd64.exe-<version> so that every agent version finds them.

Air-gapped sites

Agents download new versions from your LEA server itself, so nothing on the hosts needs internet access. Carry the agent pack in with the release, or download it from the LEA Portal on a connected machine and import it with Choose pack (.tgz). See Air-gapped sites.

If something goes wrong

What you seeWhat to do
FAILED with "hash verification failed"The download was changed on the way, often by a proxy. The agent tries again every 15 minutes. Check proxies between the host and the LEA server.
FAILED with "did not start after 2 attempts"The new version crashed on this host. The agent went back to its old version and set the new one aside. Collect the agent log (see Troubleshooting), then pin the host to the old version. To try the same version again, delete agent-update.json in the agent folder (/var/lib/lea or C:\ProgramData\LEA) and restart the agent.
FAILED with "did not start after 2 attempts" and "no server signing key configured" in the agent logThe host has no signing key in lea.conf, and new agents do not run without one. Follow Turn on server checks on existing hosts.
FAILED with "download failed with status: 404"The version has no program for this system or processor. Check Platforms in Versions.
A host stays on UPDATINGThe host does not check in, or it runs an agent older than 2.1.0 and needs one restart. Look at Last seen on the host page.
RESTART PENDING does not go awayThe agent waits until it has run for at least 35 seconds. If it stays, restart the agent once.
"agent packs cannot be imported" or "bad signature"The pack is not signed with the GSR key, or it was changed. Download it again from the LEA Portal.

More detail: Agent auto-update reference and Agent versions reference.