Connector lifecycle

A connector is not finished when it is installed. Its identity has a fixed lifetime, an admin can revoke that identity at any time, and a new build arrives only when somebody asks for it or the environment is set to take releases automatically. This page covers what happens to a working connector after day one.

The identity expires after 90 days

Enrollment issues the connector an mTLS client certificate valid for 90 days. Once the enrollment token has been spent, that certificate is the connector's only credential. The service runs tokenless from then on and presents it on every reconnect.

Nothing renews it. There is no automatic renewal, no reminder and no warning as the date approaches. The environment card shows the version the connector reports and when it was last seen. It does not show when the identity was issued or when it expires.

An expired identity looks like this:

• the environment moves to Offline in the console and stays there,
• the agent can no longer read that environment and reports the connector as offline,
• on the host, journalctl -u vesper-connector repeats a session-ended line with a reconnect delay that grows and then settles at one minute.

The connector retries forever and cannot recover on its own, because recovery needs a new certificate and a certificate is only issued against a fresh enrollment token.

The identity is the node

Each connector is one node of the environment, and its identity is what tells one node from another. A connector that stops reporting stays in the environment as unreachable, with the time it was last seen, until an admin removes it. Nothing prunes it automatically, because Vesper cannot know whether a silent node is gone for good or switched off for the weekend.

Running the installer again on a node keeps its identity. The binary and the configuration are updated and the service restarts, and the console keeps showing the same node. See re-running the installer.

Revoke

An admin can revoke a connector's identity from the environment page. It takes effect immediately: the current certificate is refused and the live session is dropped.

Revoking acts on Vesper's side only. The binary, the service and /etc/vesper/connector.yaml stay exactly as they are on the host, and the service goes on running and retrying with a credential that is no longer accepted. Taking the connector off the machine is a separate step, covered in Install the connector.

Recovering an expired or revoked connector

The console no longer issues enrollment tokens or install commands, so a hand-installed connector whose identity expired or was revoked cannot enroll again from the console. The environment comes back through Wazuh Fleet: allow Vesper on its hosts in Wazuh Fleet and add them from Add hosts on the environment's Wazuh Fleet card. Each host enrolls with a new identity and appears as a new node. The old node stays listed as Unreachable. Uninstall the hand-installed connector on each host, then choose Remove node on its old row.

Moving to a new build

The connector can replace its own binary, but never on its own initiative. Somebody has to ask, and the host has to agree. The environment card compares the version the connector reports against the published release and says whether one is available. When it cannot read the release manifest it says nothing about currency rather than claiming you are up to date. On the host, the binary reports its own version:

vesper-connector --version

Asking: the two controls in the console

Both live on the environment's page, both are admin-only, and both act on the environment rather than on one node.

Control	What it does
Upgrade now	Asks the connectors in this environment to move to the published release, once.
Upgrade automatically	Off by default. While on, a new release is taken without anybody pressing anything.

Off is the default because the connector runs as root on your Wazuh manager, so replacing it unasked is a change on your machine rather than on ours.

Agreeing: the host has a veto

upgrade.enabled: false in /etc/vesper/connector.yaml makes the connector log and ignore every directive, whatever the console says. See the upgrade section.

Two other things have to hold, and neither is a setting:

• The service has to have been started by systemd. Applying an upgrade ends in the process exiting so that something restarts it on the new binary. A connector run in the foreground has nothing behind it, so it logs that fact at startup and then logs every directive it declines.
• The artifact has to check out. The connector refuses a download that is not https on its configured upgrade.download_host, refuses one whose checksum does not match, and runs the candidate with --version to prove it starts on this machine before anything is swapped. The checksum arrives over the connector's own authenticated session, not from the site serving the binary. Nothing is replaced until every one of those has passed, and a failed attempt is reported back to the console.

An upgrade keeps the identity

Replacing the binary touches nothing else. The certificate, the configuration file and the connector's identity all survive, so the 90-day clock is not reset and there is nothing to re-enroll. This is the one way to move to a new build that does not need a token.

Rolling one back

The replaced binary is kept beside the new one as /usr/local/bin/vesper-connector.prev:

sudo vesper-connector --rollback            # restores .prev over the current binary
sudo systemctl restart vesper-connector

It works with a broken configuration file and no network, because it touches the filesystem and nothing else. A rollback also tells Vesper not to offer that same version to that node again through auto upgrade; Upgrade now overrides it, because a person asking for the same version twice is a decision rather than a loop.

Installing a build by hand

On a hand-installed connector, running the installer again is still a way to move builds, and it is the way when the veto is set or the connector cannot reach Vesper at all. The installer downloads the current binary for the host's architecture, verifies its published checksum where one is available, and replaces /usr/local/bin/vesper-connector. The configuration file is rewritten, with the previous one saved beside it. Add --keep-config to leave it alone.

Like a remote upgrade, this keeps the identity. A host with a valid identity is not enrolled again, so the 90-day clock is not reset and no token is needed. Passing --re-enroll with a token is what makes an install by hand a re-enrollment.