Installation

This page covers running the Connector on a workstation or server, either as a standalone binary you launch yourself or — on Linux — as a system service using the installer we ship. If you'd rather deploy it as a self-contained VM, see Deploying the OVA appliance instead; pairing works the same way on every path.

You want	Use	Covered in
To try the Connector, or run it on demand	The .zip standalone executable	Steps 1–4 below
An always-on Connector on an existing Linux host	The .tar.gz with the service installer	Install as a Linux service
An always-on Connector with nothing to manage	The .ova appliance	Deploying the OVA appliance

1. Download the Connector

1. In FireMon Connect, open Settings > Connectors. The Download the Connector app step lists the available builds for macOS, Linux, and Windows.
2. Download the file for your platform:
   • .zip — the standalone executable. Run it yourself; nothing is installed.
   • .tar.gz (Linux only) — the same executable plus a service installer. See Install as a Linux service.
3. Extract it.

Verify the download

Each build in the download table has a Checksum (SHA256) column. Click the shield icon next to the checksum for a copy-paste command that verifies the file you downloaded and prints a clear pass/fail. Do this before you run the binary — the steps below ask you to override your OS's own trust prompts, and the published checksum is what confirms you're overriding them for the file FireMon actually built.

Allowing the download on macOS

macOS builds are not currently notarized, so Gatekeeper blocks the first launch as "from an unidentified developer." To allow it:

1. Run the binary once and let Gatekeeper block it.
2. Open System Settings > Privacy & Security, scroll to the Security section, and click Open Anyway for firemon-connector.

For scripted or headless installs, clear the quarantine attribute instead:

chmod +x ./firemon-connector
xattr -dr com.apple.quarantine ./firemon-connector

Allowing the download on Windows

The Windows build is not currently code-signed, so SmartScreen may warn that it's an unrecognized app. Choose More info > Run anyway to allow it.

2. Create a registration code

1. On the same Settings > Connectors page, click Create registration code. An 8-character code appears — click Copy registration code.

The code is single-use and expires after 24 hours. If it expires before you use it, generate a new one.

3. Run and pair

Open a terminal in the directory where you extracted the binary and run it.

On Linux:

sudo ./firemon-connector

Linux needs elevated privileges by default. The Connector writes its credentials to /etc/firemon-connector/ and its logs to /var/log/firemon-connector/, neither of which an ordinary user can create — without sudo, the first run fails with a permission error. To run it unprivileged instead, point both directories somewhere you can write:

FIREMON_CONFIG_DIR="$HOME/.firemon-connector" \
FIREMON_LOG_DIR="$HOME/.firemon-connector/logs" \
  ./firemon-connector

Set the same two variables on every subsequent run — the Connector reads its saved credentials from FIREMON_CONFIG_DIR, so a run without them looks unpaired and prompts you again.

On macOS:

./firemon-connector

On Windows (PowerShell):

.\firemon-connector.exe

On first run it prompts for:

1. Connector name — defaults to your machine's hostname.
2. Registration code — paste the code from step 2.

On success you'll see Registration successful! Connector ID: .... Credentials are saved locally so you won't be prompted again on subsequent runs:

OS	Credentials location
Linux	/etc/firemon-connector/credentials.json
macOS	~/Library/Application Support/firemon-connector/credentials.json
Windows	%LocalAppData%\firemon-connector\credentials.json

Pairing without the prompts

For a scripted or headless install, pair in a separate step with --pair, which registers and then exits — no Ctrl-C needed:

printf %s 'YOUR-CODE' | ./firemon-connector --pair --name=connector-01

The registration code is read from stdin, or from the FIREMON_REGISTRATION_CODE environment variable if you'd rather set it there. It is deliberately never accepted as a command-line flag: arguments are visible to every user on the host via the process list and persist in shell history. --name sets the display name in Connect and defaults to the hostname.

The same privilege rule applies here — on Linux, run --pair with sudo (or with FIREMON_CONFIG_DIR pointed somewhere writable), because this is the step that writes the credentials file.

Once --pair succeeds, start the Connector normally (or start the service, if you used the Linux installer).

4. Confirm it's online

The terminal logs Connector ready and Cloud connection established, and polls for work every 30 seconds. In Connect, Settings > Connectors > Connectors shows it in the Registered Connectors table with a green status dot, a Last Seen time, and a Created timestamp.

Leave it running — closing the terminal (or Ctrl-C) stops the Connector. For a deployment that survives reboots, use Install as a Linux service below or Deploying the OVA appliance.

Install as a Linux service

The Linux .tar.gz build bundles the executable with a systemd unit and an install.sh that wires it up, so you get an always-on Connector on an existing Linux host without hand-writing a unit file.

Extract the tarball and run the installer as root:

tar -xzf connector-<version>-linux-x86_64.tar.gz
cd firemon-connector-<version>-linux-x86_64
sudo ./install.sh

The installer:

• creates a firemon-connector system user (no login shell, no home directory) to run the service,
• installs the executable to /usr/local/bin/firemon-connector,
• creates /etc/firemon-connector/ for configuration and /var/log/firemon-connector/ for logs, owned by that user,
• installs and enables the systemd unit — but does not start it, because the Connector has to be paired first.

Pair it as the service user, then start the service:

printf %s 'YOUR-CODE' | sudo -u firemon-connector /usr/local/bin/firemon-connector --pair
sudo systemctl start firemon-connector

Use a registration code from step 2. Running --pair as firemon-connector matters: it writes the credentials file with the ownership the service needs to read it later.

Check on it with either the service log or the Connector's own log files:

sudo systemctl status firemon-connector
sudo journalctl -u firemon-connector -f
ls /var/log/firemon-connector/

The service restarts automatically if it exits and starts on boot. To remove it:

sudo ./install.sh --uninstall

Uninstall stops and removes the service, the executable, and the service user. It deliberately leaves /etc/firemon-connector/ and /var/log/firemon-connector/ in place — delete them yourself if you want the credentials and logs gone, or use --decommission first (see Security & Data Protection).

Run one Connector per identity

Every Connector reads the same local credentials file, so starting a second copy on the same machine (or from the same paired install) runs it under the same Connector ID. Two processes sharing one identity fight over the same work — duplicate discovery runs, syncs that time each other out, jobs that never finish because each instance keeps reclaiming it from the other.

This is easy to get wrong because the Connector updates itself automatically (see Updates): it downloads a new build, relaunches, and the old process exits — but on macOS/Windows your terminal prompt returns while the new process keeps running in the background. A returned prompt doesn't mean the Connector stopped.

Before starting the Connector again, confirm no copy is already running (macOS/Linux):

pgrep -fl firemon-connector   # empty output means nothing is running

To stop a running Connector, stop it by name rather than relying on Ctrl-C (which only works if it's still your terminal's foreground process).

If you installed it as a service (the Linux tarball or the OVA appliance), stop the service — the unit is configured to restart the Connector automatically, so killing the process just brings it back about ten seconds later:

sudo systemctl stop firemon-connector

Otherwise, on macOS/Linux:

pkill -f firemon-connector
pgrep -fl firemon-connector   # confirm — no output means it stopped

On Windows (PowerShell):

Get-Process firemon-connector -ErrorAction SilentlyContinue | Stop-Process

If you need to run more than one Connector (e.g. to reach two separate environments), pair a second install with its own registration code rather than copying a paired install's credentials.

Where logs live

OS	Path
Linux	/var/log/firemon-connector/
macOS	~/Library/Logs/firemon-connector/
Windows	%LocalAppData%\firemon-connector\logs\

On Linux, FIREMON_LOG_DIR overrides the default path — see step 3 for running unprivileged.

Logs are structured JSON, rotated automatically (up to five 10 MB files). The terminal running the Connector also prints the key lines as they happen.

Log entries at INFO level and above are also forwarded to FireMon for support purposes. See Security & Data Protection — Log forwarding for what those entries contain.