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.

Updates¶

How a Bridge update is applied depends on the deployment method.

Linux SystemD and Windows Service¶

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.

Docker¶

Docker-based Bridges cannot be updated via the SaaS web portal. To update, pull the latest image and restart the container:

docker pull registry.zaita.com/bridge:latest
docker stop zaita-bridge && docker rm zaita-bridge
docker run -d \
  --name zaita-bridge \
  --restart unless-stopped \
  -e ZAITA_API_URL=https://au.zaita.com \
  -v zaita-bridge-data:/app/data \
  registry.zaita.com/bridge:latest

The persistent volume (zaita-bridge-data) preserves the trust token and key files across the restart. No re-registration is required provided the volume is retained.

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.

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.

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.