Installation
This page covers running the Connector on a workstation or server, either as a standalone binary or as a Linux system service. To deploy it as a self-contained VM instead, see Deploying the OVA appliance. 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 |
Before you start
- The machine needs outbound HTTPS (tcp/443) to Connect. If egress from your network is restricted, provision the firewall rules in Network Requirements first.
- It also needs outbound access to the on-prem systems you plan to integrate with (Panorama, NSX Manager, Firewall Management Center, FortiManager, Infoblox Grid Manager).
- On Linux, you need root (or see step 3 for running unprivileged).
- In Connect, you need access to Settings > Connectors to download builds and create registration codes.
1. Download the Connector
- In FireMon Connect, open Settings > Connectors. The Download the Connector app step lists the available builds for macOS, Linux, and Windows.
- 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.- The table also offers a Software Bill of Materials (CycloneDX) download.
- Extract it.
Verify the download
Each build in the download table has a Checksum (SHA256) column. Hover over the shield icon next to the checksum for a copy-paste command that verifies the file you downloaded and prints a clear pass/fail. Verify before you run the binary: the steps below bypass your OS's publisher checks, and the checksum confirms the file is the published release.
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:
- Run the binary once and let Gatekeeper block it.
- 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
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/. An ordinary user can't create either directory, so without sudo the first run stops with a permission error before it asks for a registration code. 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 can't find the credentials and prompts you to pair again.
On macOS:
./firemon-connector
On Windows (PowerShell):
.\firemon-connector.exe
On first run it prompts for:
- Connector name: defaults to your machine's hostname.
- 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:
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. It's never accepted as a command-line flag, since arguments are visible in the process list and 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
In Connect, Settings > Connectors > Connectors shows the Connector in the Registered Connectors table with a green status dot, an Accounts count (hover it for the list), a Last Seen time, and a Created timestamp. Green means the Connector's WebSocket connection to Connect is open. Jobs are fetched separately over HTTPS every 30 seconds, so a red Connector can still finish jobs if only WebSocket traffic is blocked; see Troubleshooting: Connectivity. The terminal itself shows only a startup banner and occasional status lines; the Connector's activity goes to its log files.
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 writing a unit file yourself.
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-connectorsystem 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
systemdunit, 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. Pairing as the firemon-connector user gives the credentials file the ownership the service needs to read it.
Check status with 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 starts on boot and restarts automatically if it exits. Self-updates are verified the same way as on the appliance, but only the appliance can roll one back; on a service install, an update that keeps crashing leaves the service stopped. See Updates. 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 manually if you no longer need the credentials and logs, or run --decommission first (see Security & Data Protection).
Run one Connector per identity
Every Connector reads the same local credentials file, so a second copy started from the same paired install would run under the same Connector ID. The Connector prevents this: a second start detects the running copy, prints Another connector instance is running, waits up to 45 seconds for it to exit, and then stops rather than run alongside it (as a systemd service, it keeps waiting instead). It can't detect a paired install's credentials copied to another machine, or a cloned appliance. Two Connectors sharing one identity compete for the same work, causing duplicate runs and jobs that stall or never finish.
On macOS, Windows, and a standalone Linux binary, a self-update relaunches the Connector as a new background process and the old process exits (see Updates), so your terminal prompt returns while the Connector keeps running. Ctrl-C at that prompt won't stop it.
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 while 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 restarts the Connector automatically, so a killed process comes 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 (for example, to reach two separate environments), pair a second install with its own registration code rather than copying a paired install's credentials.
Configuration file
On first run the Connector creates configuration.json in its config directory (the directory that holds credentials.json, listed under step 3), beside a configuration.schema.json and a configuration.example.json that document the keys. Every key has a default, so the file starts with just a schema reference. The keys, each with an environment variable that overrides it:
| Key | Environment variable | Default |
|---|---|---|
logDir | FIREMON_LOG_DIR | The per-OS log path below |
logLevel | FIREMON_LOG_LEVEL | INFO (DEBUG, INFO, WARN, ERROR, or FATAL) |
logMaxSize | FIREMON_LOG_MAX_SIZE | 10 MB per file |
logMaxFiles | FIREMON_LOG_MAX_FILES | 5 rotated files |
logConsole | FIREMON_LOG_CONSOLE | Off |
autoUpdate | FIREMON_AUTO_UPDATE | On. See Updates |
updateCheckIntervalMs | FIREMON_UPDATE_CHECK_INTERVAL | Ten minutes |
Restart the Connector after changing the file. The same directory also holds the Connector's working state; leave those files alone.
Where logs live
| OS | Path |
|---|---|
| Linux | /var/log/firemon-connector/ |
| macOS | ~/Library/Logs/firemon-connector/ |
| Windows | %LocalAppData%\firemon-connector\logs\ |
FIREMON_LOG_DIR overrides the default path; see step 3 for running unprivileged.
Logs are structured JSON, rotated automatically, and capped at about 60 MB. Entries at INFO level and above are also forwarded to Connect for support purposes. See Security & Data Protection: Log forwarding for what those entries contain.