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_tablesloaded. Theinet linguardtable 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
sudogroup for the host install.
Delivered files
| File | Purpose |
|---|---|
MaelGard-Linux-<arch>-preprod.flatpak | Session Flatpak, GTK UI, embedded host payload. |
gateway-root.pem | Gateway root PEM, to pin via --server-ca-file. |
SHA256SUMS.txt | Integrity 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.flatpakInstall the host payload
Two paths: interactive via the tray icon and polkit, or silent via the command line.
Interactive path
- Launch the app from the menu:
flatpak run com.maelgard.LinGuard. - From the tray icon menu, pick Install host protection.
- Enter the administrator password in the polkit prompt.
- Wait for the Protection installed notification. The icon switches to the protected state.
- 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
| Flag | Required | Purpose |
|---|---|---|
--install-from <path> | Yes | Flatpak source directory (binaries, services, policies). |
--server-url <url> | Yes | MaelGard gateway URL. |
--tenant <uuid> | Yes | Customer tenant identifier. |
--server-ca-file <path> | Yes | Gateway PEM root. Pins the certificate. |
--enroll-token <token> | Yes | Single-use enrollment token. |
--uninstall-token <token> | No | Token required to uninstall. |
--autostart-flatpak | No | Launches the Flatpak at every user session login. |
--browser-policies | No | Deploys the CA and Chrome/Firefox Snap policies. Strongly recommended. |
Files created on the endpoint
| Path | Purpose | Mode |
|---|---|---|
/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.service | systemd 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.crt | Local CA, pushed into the system store via update-ca-certificates. | 0644 |
/etc/opt/chrome/policies/managed/linguard.json | Chrome policy: disable QUIC, ECH, DoH, trust the CA. | 0644 |
/etc/firefox/policies/policies.json | Firefox 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.servicein stateactive (running). - Table
inet linguardloaded 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=trueandstatus.model_versionscontainspii-nerlite.- Journal
journalctl -u linguardfree of anypartial sandboxmessage.
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 60The 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 statusThe 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.LinGuardUninstall 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.