Install  /  Linux (systemd)

Install Veirox Connect on a systemd host

Target: Ubuntu 22.04+, Debian 12+, Rocky 9+, any modern systemd-based
Linux distribution running as root access with outbound HTTPS/WSS to
the Veirox backend.

Prerequisites

• root access on the host
• outbound TCP 443 to the Veirox backend URL
• curl, systemctl, sha256sum, and one of cosign or openssl
  (for manifest signature verification)
• A one-time enrollment token from the Veirox UI (Connectors →
  Mint enrollment token). Tokens burn on first use and expire in 5
  minutes.

Install

copycurl -fsSL https://veirox.customer.com/api/install.sh \
  | sudo env VEIROX_BACKEND_URL=https://veirox.customer.com \
         VEIROX_ENROLLMENT_TOKEN=veirox_enr_REPLACE_ME bash

What the installer does

1. Detects OS + architecture.
2. Fetches the sha256 manifest and its cosign signature, verifies
   the signature against a pinned public key baked into install.sh.
3. Downloads the veirox-connector binary and the hardened systemd
   unit, verifies each against the manifest digest.
4. Creates a dedicated veirox-connector system user (no shell, no
   home directory).
5. Installs the binary at /usr/local/bin/veirox-connector and the
   unit at /etc/systemd/system/veirox-connector.service.
6. Writes a drop-in at
   /etc/systemd/system/veirox-connector.service.d/backend.conf with
   the backend URL.
7. Runs veirox-connector enroll --token ... as the veirox-connector
   user — this redeems the one-time token and writes the mTLS cert
   triple (cert.pem + key.pem + ca.pem) to /etc/veirox-connector/
   at mode 0600.
8. Enables and starts veirox-connector.service.

Corporate TLS-inspecting proxy

If your egress passes through a proxy that re-signs outbound TLS
with a private CA, set the corporate CA bundle before installing:

copysudo install -m 0644 corp-ca.pem /etc/ssl/veirox-corp-ca.pem
curl -fsSL https://veirox.customer.com/api/install.sh \
  | sudo env VEIROX_BACKEND_URL=https://veirox.customer.com \
         VEIROX_ENROLLMENT_TOKEN=veirox_enr_xxx \
         VEIROX_CONNECTOR_EXTRA_CA_BUNDLE=/etc/ssl/veirox-corp-ca.pem bash

After install, persist the bundle path via a unit drop-in:

copysudo tee /etc/systemd/system/veirox-connector.service.d/corp-ca.conf <<EOF
[Service]
Environment="VEIROX_CONNECTOR_EXTRA_CA_BUNDLE=/etc/ssl/veirox-corp-ca.pem"
EOF
sudo systemctl daemon-reload
sudo systemctl restart veirox-connector

Verify

Run the verification checklist.

Upgrade

Re-run the installer. The installer is idempotent when an mTLS cert
is already on disk: the existing credential is preserved, the binary
and unit are replaced with the published versions, and the service
is restarted.

copycurl -fsSL https://veirox.customer.com/api/install.sh \
  | sudo env VEIROX_BACKEND_URL=https://veirox.customer.com \
         VEIROX_ENROLLMENT_TOKEN=$(veirox-cli mint-token --connector my-host) bash

See upgrade.md for the full upgrade workflow.

Uninstall

copysudo systemctl disable --now veirox-connector
sudo rm -f /etc/systemd/system/veirox-connector.service
sudo rm -rf /etc/systemd/system/veirox-connector.service.d
sudo rm -rf /etc/veirox-connector /var/lib/veirox-connector
sudo rm -f /usr/local/bin/veirox-connector
sudo userdel veirox-connector
sudo systemctl daemon-reload

Then delete the connector in the Veirox UI (this revokes the cert
and adds it to the CRL).

Troubleshooting