mesh-catalog/modules/forticlient/README.md

forticlient

The FortiClient VPN client on the workstations, as a module (novox/hq ADR 0208): its tray in the operator's session and the vendor's service behind it, and an adapter that hands the client's resolver file to the machine's own resolver (novox/hq ADR 0247). It requires x11-display and split-dns, so it is assigned only where a display server and the machine's own resolver (systemd-resolved) are held on the same machine.

This is the operator's work VPN. Nothing of its configuration is the mesh's: no profile, no credential, no gateway, no certificate is declared, read, printed or stored by the module or its tools. The tools report running and connected state only.

Owns

what	where
the vendor's scheduler service, which holds the tunnel	forticlient.service, running and enabled
the adapter to the machine's own resolver	forticlient-tools split-dns, a process as root

Nothing else. It holds no seat, makes no contribution and writes no file.

The client's names: the adapter (ADR 0247)

FortiClient's Linux client, connecting, moves /etc/resolv.conf aside and writes its own: its servers, reached through its tunnel, and the company's search domains. It never tells systemd-resolved or NetworkManager a link's DNS, and never writes the file again during a session. On its own that file either cuts the machine off from the mesh's names (while it stands) or is overwritten by the mesh and cuts the person off from the company's names (for the rest of the session). Research 033 measured both.

The quirk is the client's, so the adapter is this module's. The machine's resolver keeps the client's write and holds it for whoever handles it. The adapter, once a second:

1. asks the resolver, over its socket on the machine, for the write standing now;
2. if the file's header says FortiClient wrote it, reads its servers and its search and domain lines, and waits up to 15 s for the client's tunnel interface (fctvpn…) to be up;
3. calls the resolver's route with the tunnel, those domains and those servers, taking the write in the same call. The resolver puts its own file back at once, and from then on the company's domains go to the company's servers over the tunnel, and every other name to the mesh's resolvers;
4. when the tunnel goes, calls unroute;
5. every 10 s, checks the route is still in place (a resolver restarted forgets it) and gives it again.

A write that is not the client's, one with no tunnel within 15 s, one with nothing to route and one the resolver refuses are left to the resolver, which puts its own file back after 90 s. The node-engine then says it (ADR 0241's rewritten, naming the writer). So a failed handover is loud.

Search domains route, they do not expand. The client's domains become routing domains: a full name under one goes to the company's servers. A short name is not completed with them, because the machine's resolver file is the mesh's and lists no search domains.

All of it stays on the machine. The adapter runs as root and talks to the resolver over its root-only socket, never over the bus. Its journal names counts, never a server, a domain or the tunnel. The client's configuration is still never opened: what is read is the file the client wrote where every program reads it. A VPN whose client tells systemd-resolved its link's DNS itself needs no adapter.

• The client is kept as found. forticlient-vpn (7.4.3) is not in the official repositories: on both workstations it is a foreign (AUR) package that repackages the vendor's build, installed explicitly. The host installs from the official repositories only, so the module cannot declare it. ADR 0205's pinned archive does not fit: it is a vendor binary set with a root service, a firewall helper and an install script. It waits for the mesh's package repository (research 027 question 1, option P2). Until then a fresh workstation installs it by hand.
• The service is declared, and so depended on. forticlient.service is the package's unit, running and enabled on both workstations. Declared running and enabled, it is held in that state, and on a machine without the package the host refuses it by name (does not exist on this machine): loud, never a silent pass. The asus-zephyrus-g14 module does the same with its foreign daemons. The module never restarts it: a change to nothing of the module's would, and nothing of the module's changes.
• The configuration stays the operator's, and unread. /etc/forticlient/, the client's database under /opt/forticlient/, the account's FortiClient settings, the VPN profiles, saved credentials and certificates are set in the client's own window. They are found (ADR 0182), and unlike any other found file, the tools do not even read them.

How it starts: the vendor's autostart entry, and nothing else

The tray has two processes: fortitraylauncher, which starts and watches fortitray. The package's install script links /etc/xdg/autostart/Fortitray.desktop to the package's /opt/forticlient/Fortitray.desktop (Exec=/opt/forticlient/fortitraylauncher). The session runs it once at login through the i3 module's dex --autostart --environment i3. That entry is the tray's one start. The module adds no xinitrc slot and no node-display-session exec, because either would start it a second time. The link is the vendor's, made by its install script; the mesh does not make or remove it.

The tunnel is not the tray's: the service's processes hold it, as root. Ending the tray leaves a connected tunnel connected.

Tools

They are served by the node's runtime as the operator account (ADR 0175).

tool	does
forticlient_status (r)	the installed version, and that it is from outside the official repositories the service: active, enabled whether the launcher and the tray run: pid, since, and the scope or unit they run in what starts the tray at login connected or not, as the number of the client's tunnel interfaces that are up
forticlient_restart (a)	asks the tray and its launcher to end (SIGTERM), forces them after 5 s, and starts the launcher in the operator's session as a transient user unit mesh-forticlient-tray, so it outlives the tools runtime. The launcher starts the tray. The service and the tunnel are not touched. Refused plainly when nobody is logged in to the desktop
forticlient_check (r)	the package is installed the service is running and enabled exactly one start: the vendor's entry is present and not hidden by an entry of the account, and dex is installed no window-manager exec one launcher and one tray run in a desktop session Being connected is never a finding: that is the operator's to decide. Each finding says what to do

What the tools never touch, held by the tests (a fake machine carries a profile, a gateway, an address, a secret and a certificate where the client keeps them, and no answer may hold any of them):

• no file under /etc/forticlient or the account's FortiClient settings is opened, and under /opt/forticlient only the tray's autostart entry, through its link (it names the launcher and nothing else);
• the vendor's command-line client and fortivpn are never run, and its logs are never read;
• a process is named by its command name only, never by its arguments;
• connected is whether an interface named fctvpn… is up, from its flags. The interface's name (it carries an identifier) and its addresses are never answered. A tunnel of a kind that brings up no such interface (IPsec) is not seen, and the answer says not connected.

What changes when it is assigned

	laptop	desktop
package	none: forticlient-vpn 7.4.3.5411, explicit, foreign	the same
service	none: running and enabled	the same
tray	none: dex starts it from the vendor's entry, in the login session's scope	none on disk. No tray runs now: that session began before dex was installed, and the predecessor's window manager never started it. The next login is the first that starts it

Migration (ADR 0182)

Nothing is required on either machine. On the desktop, log out and in once, or run forticlient_restart, and the tray runs from its one start. forticlient_check then answers ok.

Leaves as found

Everything of the client's: its configuration and database, the VPN profiles and credentials, its logs, /etc/xdg/autostart/Fortitray.desktop (the vendor's link), the package itself.

Relies on

• The package, installed by hand. Without it the host refuses the service by name.
• i3's dex line for the start: XDG autostart has no seat. Assigned without i3, the tray does not start. forticlient_check says so.
• A display server on the same machine (x11-display, ADR 0208 §3).
• The machine's own resolver on the same machine (split-dns, ADR 0247): systemd-resolved, assigned before this module requires it, on every machine this module runs on.