Skip to main content

Install from Wazuh Fleet

Wazuh Fleet installs the read-only sidecar on a host as a Fleet plugin and binds it to Pharos, and nobody opens a shell on the machine. The result is one manager per host on the Managers page, reporting over an outbound connection.

Onboarding a deployment starts here, and it is the only way a manager is added. Fleet installs the plugin binary described below. Nobody runs an install command.

Before starting​

  • Adding a manager requires an admin of the Pharos workspace, and Fleet checks the same thing on its side.
  • The workspace belongs to a Wazuh organisation, the one Fleet knows. Fleet looks a workspace up by its organisation and by nothing else.
  • The environment's hosts already run Fleet's connector and have checked in. A host that has never reported cannot be given a plugin. See Install the connector.
  • The hosts are Linux on amd64 or arm64.

Add a manager​

  1. Open the Managers page and press Add a manager. A window opens over the list, Add a manager from Wazuh Fleet, with one row per Fleet host in the workspace's organisation. Each row names the host, its environment, whether it runs On-prem or on Wazuh Cloud, and whether Fleet has heard from it recently.
  2. Press Add beside a host. A row without Add says why instead: Already a Pharos manager, No Pharos plugin release in Fleet, or Only an admin can add a manager. A host whose manager was removed from Pharos is offered again, and adding it makes a new manager.
  3. What happens next depends on where the host runs.
    • On-prem. The host is added at once and nothing is typed. The row reads Adding while Pharos mints one registration token for that host and hands it to Fleet. The window then turns to Wazuh login for the host and follows the install. Fleet's installer may have found the Wazuh login the host already uses, and the plugin tries it before anything is asked. See The test, in the same window.
    • Wazuh Cloud. The window turns to Wazuh login for the host and asks for the login first. Nothing is added until Add manager is pressed, and Back returns to the list.
  4. When the login form shows, it takes two logins, the indexer and the Wazuh API, and the button that sends them stays disabled until both are filled in. The indexer serves indicator sightings, and the agent census and the package inventory that Pharos matches against the corpus are read through the Wazuh API. A CA certificate is optional and verifies the certificate both endpoints present. An address typed without https:// or without a port is completed with the default port, 9200 for the indexer and 55000 for the Wazuh API, and the form shows the address it will send under the field. A port that was typed is kept. An address with a path, a query or a user name is refused until it is corrected.
  5. Send the login. On Wazuh Cloud the button is Add manager, and Pharos mints one registration token for that host and hands it to Fleet with the login. Fleet refuses the add when the Wazuh Cloud environment cannot run plugins. On an on-prem host already added, the button is Use this login. Either way the login goes to that host alone. The button reads Testing and the form locks while the plugin signs in with it.

A token registers exactly one manager and is spent when used. The manager is named after the environment and the host, production / indexer-01 for instance. An environment grows the same way: add a node in Fleet, then add that host here.

The test, in the same window​

Nothing is installed when the host is added. The host learns about the plugin on its next heartbeat, which the connector sends every 30 seconds, then downloads the plugin from Pharos's own download site, installs it and registers with its token. This usually takes a few minutes, and a host that is offline right now joins when it comes back. A card at the top of the window follows the host through Waiting for the host to check in with Wazuh Fleet, Wazuh Fleet is installing the Pharos plugin and The plugin is enrolling with Pharos, and reads The plugin did not come up on the host when it failed. Under each step, a sentence says whether anything needs doing and what to check in Wazuh Fleet if the step does not move on.

Pharos never reaches the deployment's Wazuh, so whether a login works is answered by the plugin. On every heartbeat the plugin signs in to the Wazuh indexer and the Wazuh API with the login it holds, on every Wazuh version, and reports each answer.

The login found on the host​

An on-prem host added with nothing typed moves on to Trying the Wazuh login this host already has once it enrols. The window waits up to two minutes for the plugin to report on the login Fleet's installer found there. Type the login instead opens the form during the wait. The window ends this step in one of three ways:

  • The Wazuh login works. Pharos uses the login Fleet found on the host. Press Done to close the window.
  • The indexer login works. No Wazuh API login was found on this host. On a host that does not run Wazuh 5, the installer can find the indexer login without the Wazuh API one. The card is amber, because Pharos cannot count the manager's agents without it. Done keeps the manager as it is, and Set Wazuh credentials opens the form to type both logins.
  • The form opens. The card says why, and shows what the plugin reported when it reported something.
The card readsWhat to type
No Wazuh login was found on this hostThe login Pharos should use to read this manager
Wazuh rejected the login found on this hostA login that works
The plugin could not reach Wazuh with the login found on this hostThe login and the address Pharos should use
The plugin has not reported yetThe login, now. The answer can still arrive
This host's plugin is too old to use a login found on the hostThe login Pharos should use
The plugin did not come up on the hostA login. Sending it asks Wazuh Fleet to install the plugin again

A host whose plugin cannot yet use a login found on the host waits the same two minutes and then asks, until Wazuh Fleet upgrades the plugin. A login typed here is tested as described next.

A typed login​

Once a typed login has been sent, the card reads Testing the Wazuh login and, when the plugin reports, shows two rows, Wazuh indexer and Wazuh API, each with a state. Hovering a state shows what the plugin reported.

StateMeaning
ReachableThe target answered with this login
Login rejectedWazuh refused the user name or the password
Certificate errorThe certificate did not verify
UnreachableNothing answered at the address, which is what a wrong port looks like
Read refusedThe login signed in and was refused a read it needs
Not testedNo answer about this target yet
Not usedAn older plugin does not test this target on this Wazuh version

The window ends in one of three ways:

  • Done. Both targets answered. Press it to close the window.
  • Try again. A target failed or the plugin did not come up. The card leads with what failed and shows what the plugin reported. The form unlocks with the typed values kept, so they can be corrected and sent again to the same host.
  • Close. The plugin is running but has not reported a login test within 90 seconds. The answer can still arrive, and the manager's Status tab shows it. An older plugin cannot test a login at all, so the window ends the same way and says that Pharos confirms the login once Wazuh Fleet upgrades the plugin.

Closing the window early​

The window can be closed at any point, the wait and the test included. The manager stays added, and its Status tab shows the same two rows and offers Change Wazuh credentials, or Set Wazuh credentials when it has no login yet, to fix the login later. That window tests the new login with the same card and ends the same way.

Fleet holds each token for at most one hour. A host that stays away longer misses its token, and the plugin on it says so in Fleet rather than trying a token that can no longer work. The other hosts are unaffected.

Pharos knows whether a manager has registered. Fleet knows what each host did with the plugin. The two are kept in different places on purpose:

To find outLook in
Whether a host has registered and is reportingPharos: the manager's row and its sync reading on the Managers page
Whether the plugin has installed on a host, or why it could notFleet: the environment's Services panel, one row per host
Whether the plugin process is aliveFleet: the Hosts table, reading a plugin's health
What the manager read from the clusterPharos: the manager's own page

When the list is empty​

  • "Wazuh Fleet could not be reached." Pharos could not ask. Try again in a moment.
  • "No Wazuh Fleet hosts yet. Enrol one in Fleet and it appears here." Fleet answered, and no connector has checked in. See Install the connector.

If adding fails​

Nothing is left behind. Pharos mints the token first and then asks Fleet, so if Fleet refuses or cannot be reached, the token just minted is revoked before the window reports the failure, and no manager is created. The message is the specific refusal, never a generic one. Fix it and add the host again.

Disconnecting, and what stays​

Disconnecting an environment is an admin's act. Pharos asks Fleet to take the plugin off, and each host removes it on its next check-in. It can also be done from Fleet's side: disabling Pharos in the environment's Services panel is a disconnect, and Fleet tells Pharos.

Disconnecting is not revoking

Disconnecting stops the reporting and nothing else. The managers stay on the Managers page with their inventory, their history and this month's usage. Revoking a manager is a separate, terminal act on the manager's own page, and it is never done on the deployment's behalf. See The managers and their lifecycle.

What the plugin reads, and where updates come from​

The plugin reads the deployment with one Wazuh login. It is either the login Fleet's installer found on the host, which never leaves the host and never reaches Pharos, or a login typed in Pharos, which reaches the plugin over the encrypted channel Fleet already uses to manage that host. Everything the plugin reads with it is read-only.

The login typed at Add a manager reaches that host alone, so two managers of one Fleet environment can hold different logins. Changing it is different. An admin opens a Fleet-managed manager's Status tab and presses Change Wazuh credentials, or Set Wazuh credentials when it has none yet, on its Connection card. The new login is shared by every Pharos manager of that Fleet environment: it reaches each host on the next delivery, and each plugin applies it without a reinstall and without anything being run on the machine. The window stays open after Save and waits for the first manager to report with the new login. It then says the login works, or shows what the plugin was told and keeps the typed values so they can be corrected and saved again. A manager whose plugin is too old to test a login says so instead of saying the login works. When no manager reports within 90 seconds, it says the login was sent and will be read when one does. Every live manager shows its Wazuh indexer and Wazuh API rows on that same card.

A login found on the host can sign in and still be refused the CTI status. The manager's Connection card then shows The login found on this host cannot read the CTI status. Everything else reads. Change Wazuh credentials with a login that can read .wazuh-cti-consumers clears it, and like any change it replaces the login on every Pharos manager of that Fleet environment, the found logins of the other hosts included.

The registration token is the only value that reaches Pharos. The plugin registers over https only and refuses a plain address rather than send the token in the clear, and it deletes the token from the host only once Pharos has accepted it. A refusal keeps it for another attempt, because a discarded token is a credential nothing can re-issue.

Disconnecting and removing a Fleet-installed manager work from its own page. A Fleet-installed manager takes its registration credential from Fleet, so no install command is ever shown for it. Its Connection card offers Change Wazuh credentials instead. Updates to the plugin come from Fleet, on Fleet's rollout schedule, and the machine owner can hold them or roll one back: see Connector lifecycle and updates.