DocumentationInstall the Linux agent

Install the Linux agent

Install the Linux agent

Deploy the MaelGard agent on desktop Linux: session Flatpak, systemd host payload, nftables redirection, enrollment and license import.

Download the matching Flatpak and host archive from /en/account/downloads, extract the archive, and use the included French step-by-step guide. Remove any previous version with its original uninstall token before acceptance testing. The Linux agent is a session Flatpak (GTK UI, session agent) plus a host payload installed via the command line or via polkit. The host payload carries the service, the worker, the admin tool and the nftables redirection.

Prerequisites

  • Distribution: Ubuntu 24.04 LTS or newer, Fedora 40 or newer. Other systemd distributions with kernel 5.2 or newer.
  • Architecture: x86_64 (amd64) and aarch64 (ARM64), LinGuard 0.1.3 preproduction.
  • Init system: systemd required for supervision and NoNewPrivs, Landlock constraints.
  • Firewall: nftables, module nf_tables loaded. The inet linguard table is created by the service.
  • Flatpak: 1.14 or newer, Flathub remote added at user scope.
  • polkit: active polkit agent in the session (default under GNOME, KDE).
  • Session bus: working user D-Bus.
  • Account: member of the sudo group for the host install.

Delivered files

Install package contents
FilePurpose
MaelGard-Linux-<arch>-preprod.flatpakSession Flatpak, GTK UI, embedded host payload.
gateway-root.pemGateway root PEM, to pin via --server-ca-file.
SHA256SUMS.txtIntegrity checksums of delivered files.

Install the Flatpak

The Flatpak installs at user scope. It downloads the GNOME 50 runtime from Flathub on first deployment.

flatpak remote-add --user --if-not-exists flathub https://dl.flathub.org/repo/flathub.flatpakrepo
flatpak install --user -y flathub org.gnome.Platform//50
flatpak install --user -y ./MaelGard-Linux-$(uname -m)-preprod.flatpak

Install the host payload

Two paths: interactive via the tray icon and polkit, or silent via the command line.

Interactive path

  1. Launch the app from the menu: flatpak run com.maelgard.LinGuard.
  2. From the tray icon menu, pick Install host protection.
  3. Enter the administrator password in the polkit prompt.
  4. Wait for the Protection installed notification. The icon switches to the protected state.
  5. Configure the gateway and enroll the endpoint (see below).

Silent path

Equivalent to msiexec /qn on Windows: no user interaction, properties on the command line.

P=$(flatpak info --user --show-location com.maelgard.LinGuard)/files/libexec/linguard/host
sudo "$P/bin/linguard-svc" --install-from "$P" \
  --autostart-flatpak --browser-policies \
  --server-url https://gateway.example.local:28443 \
  --tenant <TENANT_ID> \
  --server-ca-file ./support/gateway-root.pem \
  --enroll-token <TOKEN> \
  --uninstall-token <UNINSTALL-TOKEN>

The JSON output must contain "ok":true and, under enrollment, a device_id.

linguard-svc install-from options

Flags accepted by the host payload
FlagRequiredPurpose
--install-from <path>YesFlatpak source directory (binaries, services, policies).
--server-url <url>YesMaelGard gateway URL.
--tenant <uuid>YesCustomer tenant identifier.
--server-ca-file <path>YesGateway PEM root. Pins the certificate.
--enroll-token <token>YesSingle-use enrollment token.
--uninstall-token <token>NoToken required to uninstall.
--autostart-flatpakNoLaunches the Flatpak at every user session login.
--browser-policiesNoDeploys the CA and Chrome/Firefox Snap policies. Strongly recommended.

Files created on the endpoint

Host payload layout
PathPurposeMode
/opt/linguard/Static binaries linguard-svc, linguard-admin, linguard-worker.0755
/var/lib/linguard/Event database, downloaded models, state.0700
/etc/linguard/Local configuration and signed policies.0755
/run/linguard/Service IPC sockets.0755
/etc/systemd/system/linguard.servicesystemd unit (Type=notify, watchdog).0644
/usr/share/polkit-1/actions/polkit action for the admin view (com.maelgard.linguard.admin.policy).0644
/usr/local/share/ca-certificates/linguard-local-ca.crtLocal CA, pushed into the system store via update-ca-certificates.0644
/etc/opt/chrome/policies/managed/linguard.jsonChrome policy: disable QUIC, ECH, DoH, trust the CA.0644
/etc/firefox/policies/policies.jsonFirefox Snap policy: install the local CA.0644

Verify the install

admin=/opt/linguard/linguard-admin
systemctl status linguard --no-pager
sudo nft list table inet linguard | grep redirect
sudo $admin status | python3 -m json.tool
  • Unit linguard.service in state active (running).
  • Table inet linguard loaded in nftables with the redirect rules.
  • In linguard-admin status: driver.loaded=true, service_alive=true, two listeners (127.0.0.1:…, [::1]:…).
  • status.protection_active=true and status.model_versions contains pii-nerlite.
  • Journal journalctl -u linguard free of any partial sandbox message.

Enrollment

If enrollment was not done via --enroll-token, run it by hand after install.

sudo /opt/linguard/linguard-admin enroll --token <FRESH-TOKEN> --wait 60

The command waits up to 60 seconds for server confirmation. It then prints device_id and not_after. The token is single-use.

License import

sudo /opt/linguard/linguard-admin license status
sudo /opt/linguard/linguard-admin license import ~/dist/client.lic
sudo /opt/linguard/linguard-admin license status

The license must be issued for the configured tenant. State must switch to state=valid, mode=licensed. A service restart preserves this state.

Configuration via policies

The GPO equivalent on Linux is a signed JSON file at /etc/linguard/policies.json. It is read every 5 minutes and locks the parameters it carries.

{
  "settings": {
    "sync.server_url": "https://gateway.example.local:28443",
    "sync.tenant_id": "<TENANT_ID>",
    "ui.decision_timeout_ms": 20000,
    "policy.global_bypass": "disabled"
  }
}

Uninstall

sudo /opt/linguard/linguard-svc --uninstall \
  --uninstall-token <UNINSTALL-TOKEN> --purge
flatpak uninstall --user -y com.maelgard.LinGuard

Uninstall removes the binaries, systemd unit, sockets, nftables table, local CA and browser policies. The --purge flag also removes data under /var/lib/linguard/.

Known limits

  • Flatpak browsers: Firefox and Chrome from Flathub are not covered. Their trust stores stay isolated from the system store.
  • OCR: scanned PDF and image analysis is unavailable in this release. The OCR engine is not wired on Linux.
  • ARM64: not shipped. Only x86_64 is built.
  • Root self-protection: a root administrator can stop the agent. Shutdown is detected by the server (missing heartbeat) and logged.