Install the connector

The connector is a single static Go binary that runs inside your network and reports the host to Fleet and runs the services you allow on it. It dials out to connect.fleet.wazuh.com over mTLS and holds that session open. Nothing connects in, no port is opened, and Fleet reads nothing from the host beyond its name, its platform and the connector on it. On a Wazuh node the installer also looks, once, for the Wazuh login the host keeps, and that login never leaves the host. The connector explains the shape. This page is the install itself.

Requirements

• Linux with systemd. The installer stops with systemd is required if systemctl is not on the host.
• x86_64/amd64 or aarch64/arm64. Any other machine type stops the install with unsupported architecture: <what uname -m reported>.
• root, both to install and to run. Without it: must run as root (use sudo).
• A Wazuh node is the convenient host, not a requirement. The connector reads nothing from Wazuh, so any Linux host that reaches the gateway will do. A manager, indexer or dashboard node is the usual place because a service allowed on the host later is what reaches a Wazuh API. On such a node the installer finds the login that service can start with, as described in The Wazuh login the installer finds.
• curl or wget. Every download the installer makes falls back from one to the other. With neither it stops with need curl or wget.
• sha256sum or shasum. The binary is refused unless its published checksum matches. A published checksum that is missing, and a host that can compute neither digest, are refusals too rather than a pass; those two are what --allow-unverified overrides. A digest that was computed and disagrees is refused with checksum mismatch for the downloaded binary, and no flag gets past that.
• Outbound HTTPS on :443. The install itself reaches two hosts: dl.fleet.wazuh.com for the artifacts and connect.fleet.wazuh.com for enrolment and the session. No inbound rule is needed. A host that is later asked to run a plugin also downloads that plugin from its own service's site; see Connector services.

openssl is optional and is the only thing that notices an expired certificate: a host without it accepts a stored identity as valid on the strength of the three files being there. useradd is optional too: without it the three plugin accounts are not created and the installer logs a warning, rather than failing.

Behind an egress proxy the connector honours HTTP_PROXY, HTTPS_PROXY and NO_PROXY for enrolment, certificate renewal and the long-lived session.

Get the install command

Add the host first, in the console. Adding one mints a single-use enrollment token, valid for one hour, and shows the command that carries it. Copy it there and run it on the machine:

curl -fsSL https://dl.fleet.wazuh.com/install.sh | sudo bash -s -- --token=<ENROLLMENT_TOKEN>

That is the whole shipped command. It passes no other flag, so the binary's compiled-in defaults are the install: the gateway is wss://connect.fleet.wazuh.com and the data directory is /var/lib/fleet-connector.

The command is shown once

The console shows the install command in the panel that adds the host. Copy it before leaving that panel. If you lose it, the host's own page mints a fresh token: Get the install command before its first connector, Re-enroll this host after. See Your own hosts.

What the installer does, in order

1. Parses its arguments, refuses an unrecognised one, and checks root, architecture and systemd.
2. Creates /etc/fleet-connector (0755), /var/lib/fleet-connector (0711) and /var/lib/fleet-connector/plugins (0711). The data directory is traversable rather than private because a plugin runs as its own unprivileged user and has to reach its own state directory below it; everything secret in there is 0600 and owned by root. Later on it also creates /etc/fleet-connector/plugins, which is the machine owner's own directory for per-plugin overrides and is only ever read.
3. Adopts an identity or a config left behind by an older build, under /var/lib/mobius-connector and /etc/mobius/connector.yaml. The identity is copied across and the old directory is then removed; the config is copied and the original left where it is. Both steps are skipped entirely when a Mobius connector is installed on the host, because those two paths are then that product's.
4. Decides whether this run enrols, before anything is downloaded. A valid identity is kept; no identity and no token is refused here, with no network call made.
5. Downloads fleet-connector-linux-<arch> and its .sha256, refuses to install it unless they match (a missing .sha256 is a refusal too), and writes /usr/local/bin/fleet-connector (0755).
6. Fetches the gateway CA to /var/lib/fleet-connector/ca.pem. That file, not the system trust store, is what the connector trusts the gateway by.
7. Writes /etc/fleet-connector/connector.yaml (0600) with the gateway address when --connect was given, the data directory and the two cadences. It detects nothing, asks for nothing and takes no credentials, and it never creates a user or changes anything on the Wazuh side. See Connector configuration.
8. Enrols once with the token, when step 4 said so. The keypair is generated on the host and the private key never leaves it.
9. Looks for the Wazuh login this host keeps, reading files only, and writes what it found to /var/lib/fleet-connector/discovered-login.json. This step runs on every installer run, with or without a token, and never fails the install. --no-discover skips it. See The Wazuh login the installer finds.
10. Installs the systemd unit, then the self-update units and the confirm script, then creates the fleet-plugin-mobius, fleet-plugin-pharos and fleet-plugin-vesper system accounts, and last installs the plugin unit template. The accounts are created before the template and whether or not it downloads, because the core writes files a plugin reads and their owner has to exist first. The template is installed and never enabled here: an instance is enabled later, when Fleet asks for that plugin.
11. Reloads systemd, enables fleet-connector, enables the two reconciler units (fleet-connector-reconcile.path and .timer), and restarts fleet-connector. A restart rather than enable --now, so a re-install always replaces the running process.

Only the connector unit is required: if the self-update units, the confirm script or the plugin template are not published at the download site, the installer logs a warning for each and carries on. A host missing the self-update assets is installed and working with self-update off, and the reconciler units are not enabled on it.

It finishes with done: 'systemctl status fleet-connector' to check, journalctl -u fleet-connector for logs.

The Wazuh login the installer finds

A Wazuh node already stores the login its own components use. Step 9 reads it, once, as root, so a service installed on the host through Fleet can start working without anybody typing that login into the service's console. The step reads files only. It opens no connection and runs no other program.

Wazuh	Indexer login	Wazuh server API login
4.x	The manager's filebeat keystore, /var/lib/filebeat/filebeat.keystore. On a stock all-in-one node that is the indexer admin.	The dashboard's /usr/share/wazuh-dashboard/data/wazuh/config/wazuh.yml.
5.x	The dashboard's own keystore, /etc/wazuh-dashboard/opensearch_dashboards.keystore, read only when /usr/share/wazuh-dashboard/VERSION.json names a 5.x dashboard. That is the dashboard's own service account. It reads every Wazuh data index but not the CTI status.	wazuh_core.hosts in /etc/wazuh-dashboard/opensearch_dashboards.yml.

The indexer address comes from the indexer's own opensearch.yml, then from the dashboard's opensearch.hosts, then from the manager's filebeat.yml. A file that is not on the host is skipped silently, and one that is there and cannot be read is named in the output.

The installer writes /var/lib/fleet-connector/discovered-login.json, owned by root at 0600, only when it has a full indexer login, which is an address, a username and a password. A Wazuh server API login alone is not written, because no service can use one without the other. The installer copies no CA certificate, so a service that starts with this login verifies neither the indexer's certificate nor the Wazuh server API's. The installer prints what it found and where, and never a username or a password:

discover: indexer login found in /var/lib/filebeat/filebeat.keystore (https://127.0.0.1:9200)
discover: Wazuh API login found in /usr/share/wazuh-dashboard/data/wazuh/config/wazuh.yml (https://127.0.0.1:55000)
discover: wrote /var/lib/fleet-connector/discovered-login.json; every service Fleet allows on this host starts with this login, and a login set from a service replaces it

A host with no Wazuh login prints discover: no Wazuh login found on this host; each service asks for it from its own console and writes nothing.

The connector hands that login to every service installed on the host through Fleet, in the service's own files on the host, and to nothing else. It never travels in the heartbeat, never reaches Fleet and never appears in a log line. Every such service on the host receives the same login. A service keeps what it received under its own account, so a service disallowed later keeps it while it is stopped, and Disconnect or Remove takes it away. A login set from the service's own console replaces the one the installer found, and no later installer run overwrites it. Whether a service starts with the login at all is that service's own decision, and one that does not asks for its login from its own console.

The step runs again on every installer run, so a rotated password reaches the host by re-running the installer without --token. A host whose installer never looked, because it has only updated itself since it was installed, gets the login the same way. --no-discover reads nothing and deletes the file an earlier run wrote. Deleting it stops delivery and revokes nothing: a service that already took the login keeps it until a login is set from that service or the service is removed. An installer run that finds nothing deletes an older file too, and says so. A Wazuh Cloud environment never runs the installer, so none of this applies there.

Flags

Flag	What it does
--token=<TOKEN>	The enrollment token. Required for a first install and for --re-enroll. On a host that already has a connector, a token without --re-enroll stops the install.
--re-enroll	Replaces the identity this machine already has, which is also how it moves to another host entry in Fleet. Needs --token.
--force	Rewrites /etc/fleet-connector/connector.yaml even though one exists, keeping its upgrade block.
--connect=<wss URL>	Overrides the gateway. The default is wss://connect.fleet.wazuh.com.
--allow-unverified	Installs the binary when no checksum is published for it, or when the host has neither sha256sum nor shasum. Logged as a warning, never as a verification. It does not override a checksum that was computed and did not match: that stops the install either way.
--no-discover	Skips the search for the Wazuh login the host keeps and deletes /var/lib/fleet-connector/discovered-login.json when an earlier run wrote it. That stops delivery and revokes nothing: a service that already took the login keeps it until a login is set from that service or the service is removed.

Those six are the whole accepted set. --token and --connect are usable as --flag value or --flag=value. Anything else stops the install with unknown argument: <what you passed>. MOBIUS_DOWNLOAD_BASE in the shell environment points the downloads at a mirror.

The installer takes no typed Wazuh credentials. Passing --indexer-url, --indexer-user, --indexer-password, --manager-url, --manager-user or --manager-password, or setting the matching environment variables, stops the install with Fleet no longer takes Wazuh credentials: each service asks for what it needs from its own console. The only Wazuh login the installer handles is the one it finds on the host, and a login set from a service's own console replaces it.

Active Response is configured from Mobius, not from Fleet. Passing --active-response or --no-active-response stops the install with Active Response is configured from Mobius, not from Fleet.

Re-running the installer

Re-running the installer without --token is how a host is updated. A host whose identity is still valid keeps it, gets the current binary, unit and config, and is restarted. The installer says which way it went: identity <id> is valid: updating the binary and config, no enrolment needed.

An existing config is kept unless --force is passed: keeping existing /etc/fleet-connector/connector.yaml (pass --force to re-provision).

An enrolled host also updates itself without anyone re-running anything. See Connector lifecycle.

Re-installing on a host that already has a connector

A --token handed to a host that already has a connector stops the install before anything is downloaded, and the error names the two flags:

a Fleet connector is already installed on this host (identity <connector_id>, config /etc/fleet-connector/connector.yaml). Nothing was changed.
To move this host to the environment whose command you copied, re-run with --re-enroll.
To rewrite the configuration from what the host looks like now, remove --token and add --force.

--re-enroll replaces the identity. To rewrite the configuration instead, remove --token from the command first and then add --force: --force with the token still in place stops with the same error. The Re-enroll this host command on a host's page in Fleet already carries --re-enroll.

Verify

systemctl status fleet-connector
journalctl -u fleet-connector -f

Connector logs lists the other units that log on the host. The connector sends a heartbeat every 30 seconds. Until the first one arrives the host's page reads Waiting for the connector to enroll. Run the installer on the machine; once it dials the gateway, this host goes Connected. After it, the host reads Connected and its Host details card fills in with what the connector reported. A host stays Connected while a heartbeat has arrived in the last 90 seconds.

When enrolment fails

enrolment failed (token expired or already used? mint a new one). The token is single use and lives one hour. An existing config and identity are left untouched, so nothing is lost by getting a fresh command and running it again.

no valid connector identity in /var/lib/fleet-connector and no --token (mint one from the host's page in the console). Either a first install with no token, or the identity is incomplete, or the stored certificate has expired and the host has openssl to notice. Expiry is the one case renewal cannot repair, because renewing authenticates with the current certificate, so the way back is a fresh token. Running --re-enroll without one gives the matching message: --re-enroll needs --token (copy the install command from the host's page in the console).

Uninstall

curl -fsSL https://dl.fleet.wazuh.com/uninstall.sh | sudo bash             # binary and units
curl -fsSL https://dl.fleet.wazuh.com/uninstall.sh | sudo bash -s -- --purge   # and identity, config, plugins

Both modes stop and disable the plugins first, so no plugin is left running with a credential on a host whose owner believes they have uninstalled everything. The plugins are enumerated from what systemd knows, what is installed under /usr/local/lib/fleet-connector/plugins and what has state under /var/lib/fleet-connector/plugins. The default keeps /var/lib/fleet-connector, /etc/fleet-connector and the installed versions under /usr/local/lib/fleet-connector, and --purge removes those and the plugin accounts. Both modes delete /var/lib/fleet-connector/discovered-login.json, because a reinstall looks for the login again. The copies already in each service's files, and a login a service took, stay under /var/lib/fleet-connector/plugins until --purge or a removal.

Uninstalling is local. It does not remove the host from Fleet, which is a separate act described in Remove a host.