Install a connector

A connector is a small agent that runs on a Linux machine inside your network. It opens a connection out to Zaysa, so you never open a port to the internet, and it is how your team reaches private databases and servers through Zaysa. One connector serves everything in its network: you add databases and servers to it later, without running anything again.

This page installs a connector on a Linux machine. To read a Kubernetes cluster, install the connector inside the cluster instead: see Connect a Kubernetes cluster.

Before you start

• Any plan. Free includes one connector, Pro five and Business as many as you need.
• A Linux machine inside the network you want to reach, with curl and root or sudo. It can be small: the connector is one container. Docker is installed for you if it is missing.
• The machine can open outbound HTTPS (port 443) to zaysa.io. No inbound port is needed.

Add the connector

1. Open Connectors

   In the left sidebar, open Beam → Connectors and click Add connector (1).

   

2. Choose what it will reach and name it

   (1) Pick what the connector will reach first: Database, VM (SSH), Kubernetes or OpenShift. (2) Name it after where it runs, for example prod-vpc or office-network. (3) Click Create.

   

3. Copy the install command

   Zaysa shows the one-line command for this connector. Click Copy (1).

   

   It has this shape. Yours already contains your connector’s values, so there is nothing to fill in:

   Install command Copy

   curl -fsSL https://zaysa.io/api/beam/install | BEAM_TOKEN=bme_<one-time-code> BEAM_CONNECTOR_ID=<connector-id> BEAM_ENROLLMENT=SIGNED-ENROLLMENT-DOCUMENT BEAM_COMMAND_PUBKEY=<command-key> sh

   Treat the command like a password

   The BEAM_TOKEN in it is a one-time code: it works once, for one hour, and lets one machine register as this connector. Paste it only on the machine you chose, and do not share it in chat or tickets. If it leaks before you use it, delete the connector and add a new one.

4. Run it on your machine

   Open a terminal on the Linux machine, paste the command and press Enter. Keep the Zaysa window open: it says Waiting for “office-network” to dial in… until the connector connects. The installer ends like this:

   Linux machine

     preflight
     ✓ reaches Zaysa  https://zaysa.io
     ✓ policy  /etc/beam/policy.env  may reach private,loopback · may do db,cloud-api,ssh
   
     starting connector
     ✓ image up to date  zaysahq/beam-connector:<version>@sha256:<digest>
     ✓ supervised by systemd  /etc/systemd/system/beam-connector.service
     ✓ container running  beam-connector
     connecting... online
   
     🎉  Done — your connector is live.
     Back in Zaysa it shows online. This one connector is a gateway for its whole
     network: add as many databases as you want (managed or self-hosted) — no re-run.

Check it worked

Back in Zaysa, the connector’s card shows Online (1), when it was last seen and its version. From the same card you add what it should reach: Add database, Add SSH or Add K8s.

What the installer does

Reach servers over SSH

The same connector gives your team just-in-time SSH to servers in its network. The connector stays sandboxed: on each server you run one line that creates a login called beam, and that login may run only Zaysa’s small host helper as root, nothing else.

1. Turn on SSH for the connector

   On the connector’s card, click Add SSH. In the window that opens, choose Authorize a scoped key instead. The connector makes its SSH key on its own machine; the private half never leaves it.

   The other choice in that window

   Let the connector manage SSH itself re-runs the connector with full rights on the machine it runs on. Use it only when that machine is the one server people need to reach. For every other case the scoped key is safer.

2. Run the authorize line on each server

   Click Copy and run the line once on every server the connector should reach. It ends with BEAM_SSH_AUTHORIZED_OK.

   

   On the server	Details
   Login beam	Signs in with the connector’s key only. It is kept out of the group that Zaysa’s SSH certificates are trusted for, so no certificate can sign in as it.
   Host helper	/usr/local/sbin/zaysa-host-op. The only program beam may run as root. It creates and removes Zaysa’s own short-lived users, installs Zaysa’s SSH CA and reads the health snapshot for the VM page. It refuses every other account and command.
   Keys	A person’s keys are written as that person, never by root, so nothing in their home folder can point root at a system file.

3. Add the server

   Click I’ve authorized it, Add SSH host. Give the server a name and enter its address as the connector sees it (127.0.0.1 when the connector runs on that server). The admin login is already beam. Click Next, then Create.

   

   From now on, a teammate with access gets their own short-lived user on the server, removed again when the access ends.

After a connector update

A new connector version can bring a newer host helper. Open the connector’s ⋯ menu, choose SSH authorize line and run the line again on each server. Running it again is always safe.

Update the connector

Automatic updates are off. To update, run the same command again, or the same command without the token: the installer reuses the token already on the machine, so the connector keeps its identity and everything attached to it. If it reaches servers over SSH, run the SSH authorize line on them again afterwards (see After a connector update).

If something goes wrong

“installed, but it has NOT connected yet”

The container is running but cannot reach Zaysa. Check its log, then check that the machine can open outbound HTTPS to zaysa.io:

sudo docker logs beam-connector
curl -sSI https://zaysa.io | head -1

“the control plane rejected this token (401)”

The token is no longer valid. Delete the connector in Zaysa, add a new one and run its new command.

“This connector was installed for databases only”

Connectors installed before SSH was allowed by default keep their policy file. On the connector’s machine, add ssh to the capabilities and restart it:

sudo sed -i 's/^BEAM_CAPABILITIES=db,cloud-api$/BEAM_CAPABILITIES=db,cloud-api,ssh/' /etc/beam/policy.env
sudo systemctl restart beam-connector

“couldn't auto-install Docker”

Install Docker with your system’s package manager, for example sudo dnf install -y docker, then run the command again.

Remove a connector

• In Zaysa, click the bin icon on the connector’s card. Zaysa stops accepting it at once.
• On the machine, stop it and remove its files:

sudo systemctl disable --now beam-connector
sudo rm -f /etc/systemd/system/beam-connector.service
sudo docker rm -f beam-connector
sudo rm -rf /etc/beam

Next steps