Managing Bridges¶

This page covers the day-to-day management of Bridge deployments, including monitoring status, handling updates, and managing instances.

Viewing Bridge Status¶

All registered Bridges are listed under Admin → Bridges in the web portal.

Status	Meaning
Active	At least one Bridge instance is actively heartbeating.
Inactive	One or more instances are registered but none are currently heartbeating. The Bridge may still be starting, or all instances have stopped sending heartbeats.
Pending Registration	The Bridge has been created in the portal but no instances have completed their initial registration handshake.

The Last Seen timestamp on the Bridge indicates when any instance last sent a successful heartbeat. A Bridge whose Last Seen timestamp is significantly older than expected is likely offline or unreachable.

Monitoring and Alerts¶

The platform generates alerts for the following Bridge conditions:

Bridge disconnected — the Bridge has not polled within the expected interval.
Update available — a new Bridge binary version is available.
Job execution failure — a job dispatched to the Bridge failed during execution.

Alerts are visible in the web portal under Admin → Alerts and can be integrated with external monitoring via SIEM export.

Viewing Logs¶

Linux — follow live output:

sudo journalctl -u bridge -f

Linux — last 50 lines:

sudo journalctl -u bridge -n 50

Windows: Open Event Viewer and filter by source zaita-bridge under Windows Logs → Application.

Look for repeated heartbeat lines (approximately every 30 seconds) as a sign of normal operation. Increase log verbosity by setting ZAITA_LOG_LEVEL=debug in the env file and restarting — reset to info once the issue is resolved.

Updates¶

Bridges installed as a Linux SystemD service or Windows service can be updated directly from the SaaS web portal:

Navigate to Admin → Bridges in the web portal.
Select the Bridge to update.
Select Update Bridge.
Confirm the action.

The Bridge will download and apply the update, then restart the service automatically. The trust relationship and state files are preserved — no re-registration is required.

Alternatively, you can upgrade by installing a new package directly on the host:

Debian / Ubuntu:

sudo dpkg -i zaita-bridge_<new-version>_amd64.deb

RHEL / Rocky / AlmaLinux:

sudo rpm -U zaita-bridge-<new-version>.x86_64.rpm

Configuration in /etc/bridge/env and state files in /var/lib/bridge/ are preserved across package upgrades.

Connection Testing¶

The platform supports on-demand connectivity tests that the Bridge executes on-premises and reports back to the portal. This is useful for verifying that the Bridge can reach a target system or certificate authority before issuing deployment orders.

To run a connection test:

Navigate to the target system or certificate authority in the portal.
Select Test via Bridge.
The result — success, or failure with error detail — is displayed in the portal and recorded in the audit log. A failed test generates an alert.

Two entity types are supported:

Target systems — SSH handshake for SSH-based targets; TCP reachability probe for WinRM-based targets.
ADCS certificate authorities — TCP probe to the configured connector host.

TLS Certificates¶

The Bridge automatically obtains a TLS certificate from the Zaita platform during initial registration. This certificate is used to secure Courier connections on port 443. The Bridge manages all certificate renewals itself — renewals are performed automatically before expiry without any disruption to Courier connectivity. No manual configuration or intervention is required at any point in the certificate lifecycle.

State Files¶

The Bridge stores its persistent identity and state in /var/lib/bridge/ on Linux and C:\ProgramData\Zaita\Bridge\data\ on Windows. All files in this directory are accessible only to the Bridge service account.

Warning: Deleting the state directory permanently destroys the Bridge instance's identity. The Bridge will be unable to reconnect to the platform. Decommission the instance in the portal and create a new one if the state directory is lost.

Do not include the state directory in system backups. If a backup is restored, the instance will fail to authenticate because the Bridge frequently rotates it's credentials.

Managing Instances¶

A Bridge can run as a cluster of multiple independent instances to provide high availability. A maximum of 10 instances can be registered per Bridge.

Instance Statuses¶

Each instance has its own status independent of the parent Bridge:

Status	Meaning
`pending`	Registration token has not yet been used. The instance is waiting for the Bridge binary to call in.
`registered`	Token was consumed and the public key was stored, but no heartbeat has been received yet.
`active`	The instance is sending heartbeats and operating normally.
`inactive`	The instance has previously been active but is no longer heartbeating.
`error`	The instance has entered an error state.

Primary Instance¶

One instance in each Bridge cluster is designated the primary. Only the primary instance receives job assignments (certificate deployment orders, discovery jobs). All other instances continue to send heartbeats as standbys.

If the primary instance stops heartbeating for more than 5 minutes, any other instance that sends a heartbeat will automatically promote itself to primary and demote the stale instance. This means HA clusters self-recover without manual intervention.

The primary designation is visible on the Bridge detail page alongside each instance's status.

Adding Instances¶

Instances can be added to an existing Bridge at any time:

Navigate to Admin → Bridges and select the Bridge.
Select Add Instances and specify how many to add.
A new registration token is generated for each new instance.
Deploy each instance using its token. See Setting Up a Bridge for deployment instructions.

Each new instance begins in pending status and transitions to active once it completes registration and sends its first heartbeat.

Regenerating a Registration Token¶

If a registration token is lost before the instance has registered, a new token can be generated:

Navigate to Admin → Bridges and select the Bridge.
Locate the instance with pending status.
Select Regenerate Token.

Token regeneration is only available for instances that have not yet completed registration (token_used = false). Once an instance has registered, its token cannot be regenerated.

Removing an Instance¶

Individual instances can be removed without affecting the rest of the cluster:

Navigate to Admin → Bridges and select the Bridge.
Locate the instance to remove.
Select Delete and confirm.

The deleted instance will receive an authentication failure on its next heartbeat and cease operation. All other instances continue operating normally. If the deleted instance was the primary, the oldest remaining instance is automatically promoted.

To add a replacement instance, follow the steps in Adding Instances above.

Authentication and Trust¶

After registration, each Bridge instance authenticates its heartbeats by signing the current timestamp with its private key. The control plane verifies the signature against the registered public key. No trust tokens rotate during normal operation — each heartbeat is independently authenticated using the key pair established at registration time.

If you suspect a Bridge instance has been compromised, delete the instance from the portal immediately. The next heartbeat from that instance will fail authentication, and the instance will stop operating.

Console Commands¶

When running as a standalone binary (not under SystemD or as a Windows service), the Bridge accepts commands typed on stdin. These are useful for manual testing and troubleshooting.

Command	Description
`heartbeat`	Send an immediate heartbeat to the platform.
`rotate_keys`	Rotate the Bridge's signing key pair.
`list_discoveries`	List discovery jobs assigned to this Bridge instance.
`run_discover <n>`	Manually run discovery job number `n` from the `list_discoveries` output.
`check_host <host>`	Scan a single IP address or hostname for TLS certificates on common ports.
`refresh_tls_cert`	Force immediate renewal of the Bridge's proxy TLS certificate without restarting.
`help`	Show available commands.
`quit` / `exit`	Gracefully shut down the Bridge.

These commands are not available when the Bridge is running as a managed service.

Deleting All Instances¶

To immediately halt all activity for a Bridge without deleting the Bridge record itself, delete each instance individually. All instances will fail authentication on their next heartbeat and cease operation. You can then add new instances and re-deploy to restore connectivity.

Deleting a Bridge¶

Deleting a Bridge removes it permanently from the platform and invalidates all associated trust tokens.

Navigate to Admin → Bridges.
Select the Bridge to delete.
Select Delete and confirm.

Ensure no active jobs or Courier connections depend on the Bridge before deleting it.

Local Courier Proxy¶

Each Bridge has a Local Courier Proxy setting that controls whether the Bridge's local HTTPS proxy listener is enabled for Couriers operating within your network.

To change this setting:

Navigate to Admin → Bridges and select the Bridge.
Toggle the Run Local Proxy setting.
Save the changes.

When enabled, Couriers in the same network segment can be configured to route their requests through the Bridge rather than connecting directly to the SaaS. See Couriers — Introduction for Courier-side configuration.

Uninstalling¶

Before removing a Bridge from a host, decommission it in the portal to keep your inventory clean.

Linux — remove the package (preserves config and state)¶

# Debian / Ubuntu
sudo apt-get remove zaita-bridge

# RHEL / Rocky / AlmaLinux
sudo dnf remove zaita-bridge

This stops and disables the service and removes the binary, but leaves /etc/bridge/ and /var/lib/bridge/ intact.

Linux — purge everything¶

# Debian / Ubuntu (removes binary, config, state, and service account)
sudo apt-get purge zaita-bridge

On RHEL-family systems, dnf remove does not purge config or state. Clean up manually if required:

sudo dnf remove zaita-bridge
sudo rm -rf /etc/bridge /var/lib/bridge
sudo userdel bridge

Note: After purging, the Bridge instance's identity is permanently gone and cannot be restored. Ensure the instance has been deleted from the portal before purging.