Setting Up a Bridge¶

This guide walks through registering a Bridge in the Zaita web portal and deploying it in your environment. For an overview of what a Bridge is and how it works, see Bridges — Introduction.

Prerequisites¶

Before you begin, ensure the following:

You are signed in to the Zaita web portal with the Deployment Administrator or Super Administrator role.
You have determined where the Bridge will be deployed and which deployment method you will use.
The deployment host has outbound HTTPS access (port 443) to the Zaita SaaS endpoint for your region.
The deployment host has network access to any target systems the Bridge will need to reach for certificate deployment or discovery.

Step 1 — Register the Bridge in the Web Portal¶

Before deploying the Bridge, you must register it in the platform. Registration generates the initial trust token used to establish the Bridge's identity.

Navigate to Admin → Bridges in the web portal.
Select Create Bridge.
Configure the Bridge:
- Name — a descriptive name identifying this Bridge (for example, Production Network — Sydney).
- Description — optional notes on this Bridge's role or location.
- Instance Count — the number of instances to create (1–10). Each instance is independently deployed and receives its own registration token. For production environments, set this to 2 or more for high availability.
Select Create. The portal will display a registration token for each instance.

Important: Copy each registration token before navigating away. Tokens are shown immediately after creation. If a token is lost before the instance has registered, it can be regenerated from the Bridge detail page — locate the pending instance and select Regenerate Token. Once an instance has completed registration its token cannot be regenerated.

Additional instances can be added to an existing Bridge at any time from the Bridge detail page. See Managing Bridges for details.

Step 2 — Deploy the Bridge¶

Option A: Windows Installer¶

Download the Windows installer (.exe) from the Zaita web portal under Admin → Bridges → Download.

Run the installer on the target Windows server. The installer will:

Install the Bridge binary to the configured installation directory.
Register a Windows service (ZaitaBridge) set to start automatically on boot.

After installation, configure the registration token before starting the service. Open C:\ProgramData\Zaita\Bridge\bridge.env in a text editor (run as Administrator) and set:

ZAITA_REGISTRATION_TOKEN=<your-registration-token>
ZAITA_API_URL=https://au.zaita.com

Then start the service:

Start-Service zaita-bridge

Or start it from Services (services.msc). The Bridge completes the initial trust handshake on first start and connects automatically on subsequent reboots.

Logs are written to the Windows Event Log under the source zaita-bridge and can be viewed in Event Viewer.

Option B: Linux Package (.deb / .rpm)¶

Download the appropriate package for your distribution from the Zaita web portal under Admin → Bridges → Download.

Debian / Ubuntu:

sudo dpkg -i zaita-bridge.deb

RHEL / CentOS / Fedora:

sudo rpm -i zaita-bridge.rpm

After installation, edit the environment file to supply the registration token:

sudo nano /etc/bridge/env

Uncomment and set ZAITA_REGISTRATION_TOKEN, and confirm ZAITA_API_URL matches the correct endpoint for your region:

ZAITA_REGISTRATION_TOKEN=<your-registration-token>
ZAITA_API_URL=https://au.zaita.com

Region	URL
Australia (default)	`https://au.zaita.com`
United States	`https://us.zaita.com`
Europe	`https://eu.zaita.com`

Save the file, then enable and start the service:

sudo systemctl enable bridge
sudo systemctl start bridge

SystemD Service¶

When installed via the Linux package, the Bridge runs as a dedicated low-privilege bridge system account created during installation. State files — including the registration state and cryptographic keys — are stored in /var/lib/bridge, which is owned exclusively by the service account. The Bridge automatically detects it is running under SystemD and adjusts its storage paths accordingly.

The service applies security hardening at the operating-system level: restricted filesystem visibility, no access to other users' home directories, and core dumps disabled to prevent key material from being written to disk in the event of an unexpected exit.

Configuration is loaded from /etc/bridge/env each time the service starts. After editing the file, apply changes with:

sudo systemctl restart bridge

Optional Configuration¶

The following variables in /etc/bridge/env can be uncommented and set as needed:

Variable	Default	Purpose
`ZAITA_LISTEN_ADDR`	`0.0.0.0:443`	Address and port for the local Courier proxy listener
`ZAITA_LOG_LEVEL`	`info`	Log verbosity — `trace`, `debug`, `info`, `warn`, or `error`
`ZAITA_DOMAIN`	(unset)	Domain name to use for the Bridge's TLS certificate
`ZAITA_DNS_SERVERS`	(system default)	Comma-separated DNS servers, e.g. `192.168.1.1,8.8.8.8`

Option C: Standalone Binary¶

Download the Bridge binary for your platform from the Zaita web portal under Admin → Bridges → Download.

Place the binary in a directory with restricted access. The Bridge will create its trust token and key files in the same directory — ensure only the Bridge process user has read/write access to this location.

Run the Bridge, passing the registration token and API URL:

./zaita-bridge \
  --token <your-registration-token> \
  --api-url https://au.zaita.com

If the host is running inside a container or SystemD environment that would otherwise be auto-detected, pass --standalone to force standalone mode:

./zaita-bridge --standalone \
  --token <your-registration-token> \
  --api-url https://au.zaita.com

Step 3 — Verify the Connection¶

Once the Bridge starts, it uses the registration token to complete the initial trust handshake with the SaaS control plane. After a successful handshake, the token is replaced with a rotating session token managed automatically by the Bridge.

To confirm the Bridge is connected:

Navigate to Admin → Bridges in the web portal.
Locate your Bridge and confirm the status shows Connected.
The Last Seen timestamp should update within a few minutes of deployment.

If the Bridge does not appear as connected within 5 minutes, see the Troubleshooting section below.

Post-Registration Cleanup¶

After the Bridge connects successfully, remove the registration token from the environment file. The token is one-time use and has already been consumed — leaving it in the file serves no purpose and adds noise to future diagnostics.

Linux:

sudo nano /etc/bridge/env
# Comment out or remove the ZAITA_REGISTRATION_TOKEN line
sudo systemctl restart bridge

Windows: Open C:\ProgramData\Zaita\Bridge\bridge.env as Administrator and remove or comment out the ZAITA_REGISTRATION_TOKEN line, then restart the service via services.msc or:

Restart-Service zaita-bridge

TLS Certificate¶

During the initial trust handshake, the Bridge automatically requests a TLS certificate from the Zaita platform. This certificate is used to secure Courier connections on port 443. No manual certificate configuration is required. The Bridge manages all subsequent renewals automatically. See Managing Bridges — TLS Certificates for more information.

Configuring Couriers to Use a Bridge¶

To route Courier traffic through a Bridge rather than directly to the SaaS, update the Courier's YAML configuration to point to the Bridge's address:

api:
  base_url: https://<bridge-host-or-ip>
  version: v1
  verify_tls: true

The Bridge does not need to be internet-accessible — it only needs to be reachable by Couriers within your internal network. See Couriers — Introduction for full configuration details.

Troubleshooting¶

Issue	Resolution
Bridge shows Disconnected in portal	Verify outbound HTTPS access to the Zaita SaaS endpoint. Confirm the registration token was entered correctly and has not been used previously.
Bridge shows Connected but jobs are not executing	Confirm the Bridge has network access to the relevant target systems. Check the Bridge logs for errors.
Trust token invalid or expired	Tokens expire after 24 hours. Generate a new token from the portal, update the env file, and restart the service.
Courier cannot reach the Bridge	Verify the Courier's `base_url` points to the Bridge's address. Confirm port 443 is accessible between the Courier host and the Bridge host.
Registration token lost	If the instance has not yet registered, open the Bridge detail page, locate the pending instance, and select Regenerate Token. If the instance has already registered, the token cannot be recovered — delete the instance and add a new one.
Linux service not starting	Check `journalctl -u bridge -f` for errors. Verify `/etc/bridge/env` contains a valid `ZAITA_REGISTRATION_TOKEN` and correct `ZAITA_API_URL`.
Linux env file permission error	Fix with: `sudo chown root:bridge /etc/bridge/env && sudo chmod 640 /etc/bridge/env`
Heartbeat failing — timestamp out of range	The Bridge signs requests with a timestamp; the platform rejects payloads more than ±5 minutes from server time. Check clock sync with `timedatectl status` and enable NTP with `sudo timedatectl set-ntp true`.
Port 443 already in use (Linux)	Another process is using port 443. Identify it with `sudo ss -tlnp \\| grep :443`, stop the conflicting service, or set `ZAITA_LISTEN_ADDR` in `/etc/bridge/env` to an alternate address and restart.
DNS resolution failing	Set `ZAITA_DNS_SERVERS=8.8.8.8` (or a known-working server) in the env file and restart. Multiple servers can be comma-separated.
Need more diagnostic output	Set `ZAITA_LOG_LEVEL=debug` in the env file and restart. Reset to `info` once the issue is resolved to avoid filling the log.