1. Executive Summary

Objective

This guide takes an Ubuntu 22.04 or 24.04 LTS host from bare OS to a fully registered, policy-managed FortiClient endpoint, then documents every command the Linux agent exposes. The Linux build is the one most teams deploy blind: there is no tray icon on a server, no GUI to fall back on, and almost every feature stays dark until the endpoint completes a Telemetry connection to EMS. Knowing the CLI is not a convenience here, it is the entire management plane.

Target Audience

Network and security engineers rolling out endpoint protection to Linux fleets, Linux system administrators supporting Ubuntu servers and workstations, DevOps and platform teams that need agent installs baked into golden images or configuration management, and SOC analysts who need on-demand scan and posture data from hosts with no desktop session.

2. Prerequisites and Architecture

Assumed Knowledge

• Working command of apt, dpkg, systemd, and journalctl.
• Understanding that FortiClient EMS, not the endpoint, is the source of licensing and policy.
• Familiarity with FortiGate remote access configuration, IPsec IKEv2 in particular.
• Comfort adding GPG-signed third-party apt repositories using the signed-by keyring model.

Environment and Lab Requirements

• Operating system: Ubuntu 22.04 LTS or 24.04 LTS on x86_64. GNOME is required for the GUI build. The server build needs no desktop environment at all.
• Agent version: FortiClient (Linux) 7.4.x or 8.0.x. Both expose the same forticlient command tree.
• Management: FortiClient EMS 7.4.x or 8.0.x, or FortiClient Cloud, reachable on TCP 8013 by default.
• Minimum resources: 512 MB RAM and 600 MB free disk. Budget considerably more if you intend to run full-filesystem AV scans.
• Network: Outbound HTTPS to repo.fortinet.com for packages and to FortiGuard for engine and signature updates.
• Entitlement: A valid EMS license seat. Until Telemetry connects, the agent reports as unlicensed and the protection features do not arm.
• Lab platform: Anything that gives you a clean snapshot. Proxmox, VMware Workstation, KVM, or an EC2 instance all work. Snapshot before the first registration so you can replay the onboarding.

Component Table

3. Step-by-Step Implementation Workflow

Phase 1: Choose the Correct Package

The Goal: Pick one of three distinct Linux builds before you touch a package manager. Picking wrong is the most common way a Linux rollout stalls on day one.

The Action: Match the build to the host role.

Phase 2: Install from repo.fortinet.com (Recommended)

The Goal: Install from a GPG-signed apt repository so future upgrades ride the normal apt upgrade cycle instead of a manual .deb hunt.

The Action: Import the repository key into a dedicated keyring, add the source list entry with signed-by, refresh, install. The ubuntu22 path serves both 22.04 and 24.04.

Step 1: Import the repository signing key

wget -O - https://repo.fortinet.com/repo/forticlient/8.0/ubuntu22/DEB-GPG-KEY \
  | gpg --dearmor \
  | sudo tee /usr/share/keyrings/repo.fortinet.com.gpg > /dev/null

Step 2: Add the apt source

echo "deb [arch=amd64 signed-by=/usr/share/keyrings/repo.fortinet.com.gpg] https://repo.fortinet.com/repo/forticlient/8.0/ubuntu22/ stable non-free" \
  | sudo tee /etc/apt/sources.list.d/repo.fortinet.com.list

Step 3: Refresh and install

sudo apt-get update
sudo apt install forticlient

Phase 3: Install from a Downloaded .deb (Air-Gapped or Pinned Builds)

The Goal: Install a specific build number, typically because change control demands a pinned version or the host has no route to the internet.

The Action: Pull the .deb from the Fortinet support portal or from EMS, then install and resolve dependencies. The second command is not optional. dpkg does not fetch dependencies on its own.

# GUI build (Ubuntu Desktop, GNOME)
sudo dpkg -i forticlient_<version>_amd64.deb
sudo apt-get install -f

# Headless / server build
sudo dpkg -i forticlient_server_<version>_amd64.deb
sudo apt-get install -f

# Free VPN-only build
sudo dpkg -i forticlient_vpn_<version>_amd64.deb
sudo apt-get install -f

GUI Verification: On a desktop install, launch FortiClient from the Activities overview. The window opens on the Zero Trust Telemetry pane and will read as unregistered until you complete Phase 5.

Phase 4: Verify the Install Footprint

The Goal: Confirm the binaries, helper tools, and log directory landed where you expect before you spend time debugging a registration that was never going to work.

# Installation directory and helper binaries
ls -l /opt/forticlient

# Confirm the CLI wrapper is on PATH
which forticlient

# Agent, engine, and signature versions
forticlient version

# Log directory (root-owned)
sudo ls -l /var/log/forticlient

# Package state
dpkg -l | grep -i forticlient

Phase 5: Register the Endpoint to EMS

The Goal: Establish the Telemetry connection. This is the gate. FortiClient receives its license and its entire policy set from EMS, and the protection features do not arm until this succeeds.

The Action: Register by IP, FQDN, or invitation code. Port 8013 is assumed unless you override it.

# Default port 8013
forticlient epctrl register <ems_ip_or_fqdn>

# Non-default listener port
forticlient epctrl register <ems_ip_or_fqdn> -p 8444

# EMS multitenancy: register into a named site
forticlient epctrl register <ems_ip_or_fqdn> -s <site_name>

# FortiClient Cloud or on-prem EMS via invitation code
forticlient epctrl register <invitation_code>

Expected output on a successful default-port registration:

Registering to EMS 192.168.34.30:8013 at site "default".

Registering to a SAML-protected EMS

When EMS has SAML user authentication enabled, the register command returns a URL instead of completing. The flow is a two-step handoff:

1. Run the normal register command. The CLI prints a SAML URL: line.
2. Open that URL in a browser and authenticate against your IdP.
3. Use the browser inspector to locate the redirect line beginning fabricagent://ems/onboarding? and copy it verbatim.
4. Hand that URL back to the agent, wrapped in quotes.

forticlient epctrl auth --saml "fabricagent://ems/onboarding?username=<user>&auth_token=<token>"

Certificate trust and deregistration

# Accept or deny a pending invalid EMS certificate
forticlient epctrl trust

# Unregister from EMS (only succeeds if the EMS profile permits it)
forticlient epctrl disconnect

GUI Verification: In EMS, navigate to Endpoints > All Endpoints and filter on the hostname. The record should show the Ubuntu host with an online status, the assigned endpoint profile, and any Zero Trust tags the posture rules matched.

Phase 6: Configure gnome-keyring Before Any CLI VPN Attempt

The Goal: Give the VPN subsystem a working credential store. On Ubuntu, FortiClient uses gnome-keyring to hold VPN credentials. If the keyring is absent or locked, CLI VPN connections misbehave in ways that look like authentication failures but are not.

The Action: Install the daemon, then initialize and unlock the login keyring.

sudo apt install -y gnome-keyring

killall gnome-keyring-daemon
echo -n "<your_login_password>" | gnome-keyring-daemon --unlock

Phase 7: Build and Use VPN Profiles

The Goal: Create a named tunnel profile, then drive it entirely from the shell so it can be scripted into systemd units, Ansible plays, or a login hook.

The Action: The edit subcommand walks an interactive prompt for tunnel type, remote gateway, port, authentication method, client certificate, and invalid-certificate handling. Everything after that is non-interactive.

# Create or modify a profile (interactive)
forticlient vpn edit <vpn_name>

# Inventory existing profiles
forticlient vpn list

# Inspect one profile in detail
forticlient vpn view <vpn_name>

# Connect, prompting for the password
forticlient vpn connect <vpn_name> --user=<username>

# Connect and persist the password to the keyring
forticlient vpn connect <vpn_name> --user=<username> --password --save-password

# Keep the tunnel up and reconnect on drop
forticlient vpn connect <vpn_name> --user=<username> --always-up

# Bring the tunnel up automatically
forticlient vpn connect <vpn_name> --user=<username> --auto-connect

# Tunnel state
forticlient vpn status

# Tear down
forticlient vpn disconnect

# Delete the profile
forticlient vpn remove <vpn_name>

GUI Verification: On the desktop build, open FortiClient and select Remote Access. Profiles created from the CLI appear in the VPN Name dropdown, and profiles pushed from an EMS Remote Access profile appear locked from local edit.

Phase 8: On-Demand Scanning, Patching, and Signature Updates

The Goal: Run antivirus and vulnerability operations without a GUI, and pull fresh engines and signatures on demand. Every command in this phase requires root.

# Targeted AV scan of a directory
sudo forticlient fmon scan custom /home

# Full filesystem scan (pass / as the path)
sudo forticlient fmon scan custom /

# Release a file from quarantine
sudo /opt/forticlient/fchelper -r <quarantined_file>

# Vulnerability scan: reports Critical / High / Medium / Low counts
sudo forticlient vulscan scan

# Auto-remediate detected vulnerabilities, then rescan
sudo forticlient vulscan patch

# Force an engine and signature update from FortiGuard
sudo /opt/forticlient/update

# Same, with verbose logging
sudo /opt/forticlient/update -v

# Update task help
/opt/forticlient/update -h

# Current engine and signature inventory
forticlient version

A completed AV scan prints a summary block and the path to the full log. A detection looks like this:

Found virus : EICAR_TEST_FILE
In file : /var/eicar.com
Action : Quarantine success
Quarantine file : forticlient/quarantine/eicar.com.1

--------------- Scan summary ---------------------
Total scan files : 10947
Found virus : 1
Worker crash : 0
Worker timeout : 0
--------------------------------------------------

Phase 9: Complete FortiClient (Linux) CLI Reference

The Goal: One table you can bookmark. This is the full published command surface for FortiClient (Linux) 7.4.x and 8.0.x. Every subcommand supports -h for inline usage.

Endpoint Control: forticlient epctrl

VPN: forticlient vpn

Antivirus, Vulnerability, and Update Tasks

4. Verification and Validation

Check 1: Telemetry and Licensing

This single command is your primary health check. Run it first, every time.

forticlient epctrl detail

What success looks like. The EMS block populates, Status reads Connected, a real license expiry date appears rather than Unlicensed, and any Zero Trust tags your posture rules should have matched are listed:

=====================================
FortiClient License Details
=====================================
License Expiry:  Mon Oct 14 11:16:32 2024 PDT
VPN Expiry:      N/A (EMS Connected)

=====================================
FortiClient EMS Details
=====================================
IP:                192.168.34.30
Site:              default
Host:              ubuntu
SN:                FCTEMS123456
Status:            Connected
Last Access Time:  Thu Jun  6 11:56:35 2024 PDT

=====================================
Zero Trust Tags
=====================================
Ubuntu2204

What failure looks like. The EMS block reads No telemetry data available. and the license shows Unlicensed. Stop and fix registration before touching anything else. Nothing downstream works from this state.

When the endpoint is also visible to a FortiGate, detail adds a FortiGate block listing the gateway IP, hostname, serial, and connection status.

Check 2: Engines and Signatures Actually Loaded

forticlient version

What success looks like. A serial number and UID are present, and the AntiVirus and Vulnerability engine and signature versions are real numbers. Widespread Unavailable entries across every row means the agent never completed a FortiGuard update. Run sudo /opt/forticlient/update -v and read the output.

Check 3: Tunnel Established and Routing Correctly

# Agent view of the tunnel
forticlient vpn status

# Kernel view: the tunnel interface and its assigned address
ip -br addr show

# Confirm the expected subnets point at the tunnel
ip route show

# Prove the far side answers and that DNS resolves internally
ping -c 4 <internal_host_ip>
dig +short <internal_fqdn>

What success looks like. vpn status reports the tunnel connected, a tunnel interface appears in ip -br addr holding an address from the VPN address pool, and the protected subnets resolve through it rather than through the physical NIC. A connected tunnel with no route change means split tunneling is configured differently than you assumed, not that the tunnel failed.

Check 4: Corroborate from the Infrastructure Side

# On the FortiGate: confirm the endpoint record arrived
diagnose endpoint record list

# On the FortiGate: inspect the dialup IPsec tunnel
diagnose vpn tunnel list

# On the endpoint: tail every FortiClient subsystem log
sudo tail -f /var/log/forticlient/*.log

Success Criteria at a Glance

5. Troubleshooting and Gotchas

Gotcha 1: CLI VPN Fails on Ubuntu Because gnome-keyring Is Not Unlocked

Symptom: forticlient vpn connect hangs, silently fails, or repeatedly re-prompts for credentials that you know are correct. The same profile connects fine from the GUI on a desktop session. This is the single most common Linux VPN support case and it is not an authentication problem at all.

Why it happens: FortiClient stores VPN credentials in gnome-keyring. Over SSH or on a server build there is no desktop session to unlock the login keyring, so the credential store is unavailable and the connection attempt dies before it reaches the gateway.

Diagnose

# Is the package even installed?
dpkg -l | grep gnome-keyring

# Is the daemon running for this session?
ps -ef | grep [g]nome-keyring-daemon

# Are the keyring sockets exported into the environment?
env | grep -i keyring

# Watch the VPN subsystem as you retry the connection
sudo tail -f /var/log/forticlient/*.log

Resolve

sudo apt install -y gnome-keyring
killall gnome-keyring-daemon
echo -n "<your_login_password>" | gnome-keyring-daemon --unlock
forticlient vpn connect <vpn_name> --user=<username>

Gotcha 2: Every Feature Is Dark Because Telemetry Never Connected

Symptom: The install succeeded, the binaries are present, but AV scans refuse to run properly, no policy applies, and epctrl detail shows Unlicensed and no telemetry data.

Why it happens: FortiClient must establish Telemetry to EMS to receive licensing. Features are only enabled after that connection completes. The usual root causes are a blocked TCP 8013, an EMS listening on a custom port that was never passed with -p, a multitenancy site name that was omitted, or an untrusted EMS certificate sitting in a pending state.

Diagnose

# Current registration state
forticlient epctrl detail

# Can the endpoint even reach the EMS listener?
nc -vz <ems_ip> 8013

# Is anything local dropping it?
sudo iptables -L -n -v
sudo ufw status verbose

# Is a certificate decision pending?
forticlient epctrl trust

Resolve

# Clean slate, then re-register with the correct port and site
forticlient epctrl disconnect
forticlient epctrl register <ems_ip_or_fqdn> -p <port> -s <site_name>
forticlient epctrl detail

# Once connected, pull signatures so the engines arm
sudo /opt/forticlient/update -v
forticlient version

Gotcha 3: The Tunnel Design Assumes SSL VPN, but the FortiGate Removed It

Symptom: An SSL VPN profile that worked for years stops connecting after a FortiGate upgrade, or a new Linux rollout cannot establish an SSL VPN tunnel at all against a recently upgraded gateway.

Why it happens: FortiOS 7.6.3 and later versions do not support SSL VPN tunnel mode. This is a gateway-side removal, not a client bug, and no amount of FortiClient troubleshooting on the Ubuntu host will fix it. The migration target is IPsec VPN.

Layer a second constraint on top of it: FortiClient (Linux) does not support IPsec IKEv2 with SAML authentication. If your organization standardized on SSL VPN plus SAML, the Linux population lands in the gap between both limits, and the design needs to change rather than the endpoint.

Diagnose

# On the endpoint: confirm what the profile is actually set to
forticlient vpn view <vpn_name>

# On the FortiGate: what version is the gateway running?
get system status

# On the FortiGate: is SSL VPN even configured any more?
show vpn ssl settings

Resolve

Rebuild the Linux profile as IPsec against a dialup IKEv2 phase 1, and pick an authentication method the Linux client actually supports: certificate plus password, or RADIUS with a push-based or token-based second factor.

forticlient vpn remove <old_ssl_profile>
forticlient vpn edit <new_ipsec_profile>
forticlient vpn connect <new_ipsec_profile> --user=<username>
forticlient vpn status

Gotcha 4: dpkg Dependency Failures on Ubuntu 24.04

Symptom: sudo dpkg -i leaves the package in a half-configured state with unmet dependencies, typically indicator or appindicator libraries that 24.04 no longer ships under the names an older build expects.

Why it happens: Older 7.4 builds were validated against 22.04 and declare dependencies that shifted names on 24.04. Note that FortiClient (Linux) 7.4.3 and later formally list Ubuntu 22.04 and 24.04 as supported, so the correct fix is almost always to move up a build rather than to force the install.

Diagnose

# What state is the package in?
dpkg -l | grep -i forticlient

# What exactly is unmet?
sudo apt-get install -f

# What does the package actually require?
dpkg -I forticlient_<version>_amd64.deb | grep -i depends

# Confirm the OS release you are on
lsb_release -a

Resolve

# Preferred: back out the manual install and use the signed repo instead
sudo apt-get remove --purge forticlient
sudo apt-get autoremove
sudo apt-get update
sudo apt install forticlient

# On a headless host, sidestep desktop indicator dependencies entirely
sudo dpkg -i forticlient_server_<version>_amd64.deb
sudo apt-get install -f

Quick Reference Card

# ---- Install ----
sudo apt install forticlient

# ---- Register ----
forticlient epctrl register <ems> -p <port> -s <site>
forticlient epctrl detail

# ---- VPN ----
forticlient vpn edit <name>
forticlient vpn connect <name> --user=<user> --save-password
forticlient vpn status
forticlient vpn disconnect

# ---- Scan ----
sudo forticlient fmon scan custom /
sudo forticlient vulscan scan

# ---- Update ----
sudo /opt/forticlient/update -v
forticlient version

# ---- Paths ----
/opt/forticlient          # binaries and helpers