11. Install agents on Linux (and macOS)

This chapter installs, upgrades and removes the agent on Linux hosts, and at the end on macOS. For what the agent does, read chapter 10 first. To install from the console without logging in to each host, see chapter 13.

11.1 Before you start#

You also need, from the server administrator:

• the server address the hosts reach (a name or an IP address, never localhost);
• for a self-signed server certificate, the certificate file lawliet-server.pem.

Make the certificate file on the server:

sudo ./lawliet tls --export          # writes ./lawliet-server.pem

Copy it to each host, for example to /root/lawliet-server.pem.

11.2 Procedure: install with the copy-paste command#

Use this when the host can reach the server.

Required permission (console): Manage agents (to see the filled-in command). On the server, sudo ./lawliet token prints the same command. Four-eyes: no.

Risk: installs a root service on the host. Rollback: uninstall it (11.6).

1. Get the command. Either:
   • Console: Environment > Hosts > Install agent > Install command > Linux, then the copy button. If the server's certificate is self-signed, keep Self-signed certificate ticked.
   • Server: sudo ./lawliet token, section "Linux".
2. If the server certificate is self-signed, copy lawliet-server.pem to the host as /path/to/lawliet-server.pem, or edit that path in the command (it appears twice).
3. Open a terminal on the host and paste the command. It is one line. Its shape is:

   d="$(mktemp -d)" && curl -fsSL --cacert /path/to/lawliet-server.pem -o "$d/install.sh" https://<server>/api/v1/agents/download/linux && head -c 2 "$d/install.sh" | grep -q '^#!' && sudo bash "$d/install.sh" --server https://<server> --token <enrolment-secret> --ca-cert /path/to/lawliet-server.pem; rc=$?; rm -rf "$d"; [ "$rc" -eq 0 ]

   Do not type it by hand: copy it, it carries the enrolment secret.

4. Wait for the installer to finish (normally under a minute).

What you see on the host: the installer checks the server, downloads the compiled agent, checks its SHA-256, installs it as /opt/lawliet-agent/lawliet-agent, starts the lawliet-agent and lawliet-watchdog services and waits up to 60 seconds for enrolment.

What you see in the console: the host appears on Environment > Hosts within about a minute, status online.

If it fails: the installer prints one plain verdict and its fix (see chapter 10.9). A download that fails installs nothing. Exit status 3 means the server refused the enrolment; the message gives the reason (401: wrong secret; 409: an older record of this host exists - remove it in the console and the agent enrols by itself).

Note: the console's step text says the script "installs Python dependencies". The compiled agent needs none; Python is used only by the fallback.

11.3 Procedure: install from an offline package#

Use this when the host cannot download anything from the server.

Required permission: Deploy agents remotely (it also makes offline packages). Four-eyes: yes in the console (critical action "Deploy agents remotely"). The server CLI needs root and no second signature.

Risk: a package holds an enrolment code that lets hosts join until it expires. Treat it like a password. Rollback: revoke the code (11.3.3); uninstall the agents (11.6).

11.3.1 Make the package in the console#

1. Open Environment > Hosts > Install agent > Offline package.

2. Fill in the form:

   Field	What to enter
   Target	Linux x86-64 or Linux ARM64. A target the server does not carry shows "(not on this server)"
   Label	A name you will recognise, for example "Plant floor"
   Valid for (days, at most 30)	Default 7
   Hosts it may enrol (at most 1000)	Default 50. Each host that enrols uses one
   Server address the hosts reach	Filled in; change it if the hosts reach the server by another address
   Server certificate (PEM)	Shown for a self-signed server. The certificate the server serves is packed automatically; paste one only to pack a different file

3. Click Request package. What you see: "Sent for approval (request #N). Once a second person approves it, create the package here."

4. A second administrator approves it under Approvals > Waiting for me (the request shows the target, hosts, days, address and certificate).

5. Back in Install agent > Offline package, click Check again, then Create package. (You can also run it from Approvals > My requests > Execute now.)

6. What you see: "Package ready", the enrolment code (shown once), the Package SHA-256 - note it down, and a Download link. Download the file now: the link works once, for you, for 15 minutes. A package nobody downloads is deleted after an hour.

11.3.2 Or make the package on the server#

sudo ./lawliet agent-package --os linux --arch amd64 --hosts 50 --days 7 --label "Plant floor"

What you see: the file name, the enrolment code number, the expiry, the agent SHA-256 and the Package SHA-256. Note the package SHA-256 and copy the file to the host by your approved channel. The code is audited as made through the CLI, and is revoked like any other (16.6).

11.3.3 Install the package on the host#

1. On a trusted machine, compare the package's SHA-256 with the value the console or the CLI showed:

   sha256sum lawliet-agent-linux-amd64-offline-12.tar.gz

   Do not install it if they differ.

2. Copy the archive to the host (USB stick, a share, scp).
3. On the host, as root:

   tar xzf lawliet-agent-linux-amd64-offline-12.tar.gz
   sudo bash lawliet-agent-linux-amd64/install_linux.sh --offline-package lawliet-agent-linux-amd64

   You can also give the archive itself: --offline-package <file>.tar.gz.

What you see: "Package contents match its checksum list", then the install. Nothing is downloaded. If the host can reach the server, it enrols at once. If it cannot yet, the installer says "Installed; it will enrol automatically once this host can reach <server>" and exits 0; the agent keeps trying while the code is valid.

If it fails:

Afterwards, the code is removed from /opt/lawliet-agent/config.env once the agent has enrolled. To check (prints 0 when it is gone):

grep -c '^LAWLIET_REGISTRATION_SECRET=.' /opt/lawliet-agent/config.env

Revoke the code when you are done: Install agent > Offline package > Enrolment codes > Revoke. Revoking needs only the permission (it takes risk away). Hosts already enrolled are not affected. The list shows each code's label, target, uses (for example 12/50), expiry, status (active, expired, exhausted, revoked) and the last host that used it.

11.4 Installer options#

To use an option:

1. Start from the command in 11.2 (or 11.3.3) and add the options you need, for example --name web-01 or --sha256 <hash>.
2. Run it as root on the host.
3. What you see: the installer prints each step and ends with the agent running; the options it was given are reflected in the result (for example the console name).

Take a hash for --sha256 from a source that did not travel with the file (the release notes, or the server). Never from a .sha256 file next to the binary.

11.5 Managing the agent on the host#

Run these as root. What you see: active (running) from systemctl status, recent heartbeat and command lines in the log, and the host online in the console within a minute of a restart.

systemctl status lawliet-agent              # is it running
journalctl -u lawliet-agent -n 50 --no-pager  # recent log
journalctl -u lawliet-agent -f              # live log
sudo systemctl restart lawliet-agent        # restart

With self-protection on, the services restart themselves if stopped, and the watchdog restores the program file. Use the console to turn protection off first (chapter 16).

Re-running the installer upgrades the agent in place and keeps the host's identity. The new program is checked and started once before the old one stops. If anything fails, the previous program, services and settings are put back.

11.6 Procedure: uninstall the agent#

Risk: the host stops being monitored. Rollback: install it again (11.2); with the console record kept and its token revoked, it enrols as the same agent.

1. If the agent is protected, get an uninstall code first: Environment > Hosts > the host > Self-protection > Issue uninstall code (four-eyes; valid 1 hour, this host only). Or turn protection off for the host and wait until the console shows Off. See chapter 16.

2. On the host, as root, run the installer the server serves (from the bundle: agents/install_linux.sh):

   sudo bash install_linux.sh --uninstall                 # unprotected agent
   sudo bash install_linux.sh --uninstall --code <code>   # protected agent

3. Remove the record in the console (chapter 10.7), or it stays listed as offline.

What you see: the services, /opt/lawliet-agent, /etc/lawliet and the agent log are removed.

If it fails: "a valid host authorization code is required" means the agent is protected and the code is missing, wrong, expired or for another host. Issue a new one.

Note: a command line is visible to other users of the host and to process auditing while it runs. Issue the code just before use; it expires after one hour.

11.7 macOS#

The macOS installer works like the Linux one: take the command from Install agent > Install command > macOS (or ./lawliet token), run it with sudo in Terminal, and the host appears in Environment > Hosts (11.2). Uninstall, status and log commands are in the table. What you see for a running agent: state = running from the status command.

Differences from Linux:

• Options available: --server, --token, --name, --sha256, --ca-cert, --insecure, --python, --local-binary, --uninstall, --code, --recovery-key. There is no --reset-token, --refresh-ca or --offline-package, and no macOS offline package.
• To give a macOS agent a new server certificate: copy the new file over /etc/lawliet/server-ca.pem, then run sudo launchctl kickstart -k system/com.lawliet.agent.
• The binary is ad-hoc signed, not notarized. Downloaded by the installer it runs normally. A copy downloaded with a browser is quarantined; clear it with xattr -d com.apple.quarantine <file> before running it by hand.

More detail: Linux agent reference and offline packages.