Zum Hauptinhalt springen

What is a Connector?

A Connector is the lightweight agent installed inside your network (data centre, VPC, on a workstation) that lets VaultPAM broker sessions to targets that are not directly reachable from the internet.

Why you need one​

Your targets (Windows servers, Linux hosts, databases) typically live behind a firewall. You do not want to punch inbound holes for VaultPAM. A connector solves this by making an outbound reverse tunnel to the VaultPAM control plane: sessions flow through that tunnel, so no inbound firewall changes are needed.

Deployment shapes​

  • Docker (recommended for servers) — one container per connector.
  • Native installer — MSI (Windows), DMG (macOS), DEB/RPM (Linux).
  • VM appliance — pre-built OVA for environments that want an immutable, signed VM image.
  • Kubernetes — Helm chart (v2 roadmap) or the Kustomize manifests we ship today.

How pairing works​

  1. You click Add Connector in the dashboard. VaultPAM generates a single-use enrolment token.
  2. You launch the connector with the token (pasted into a docker run, into a native installer prompt, or — once AIC-1958 lands — via a browser auto-pair flow).
  3. The connector presents the token, solves a certificate challenge, and is issued an mTLS client cert bound to its identity.
  4. In autonomous restart mode, the issued identity is stored under PAM_AGENT_DATA_DIR and must survive restarts. Use a Docker named volume or bind mount, a durable VM/native host path, or a Kubernetes PVC.
  5. From then on the connector keeps an outbound TLS tunnel open to the control plane. Sessions are multiplexed over that tunnel.

Runtime Modes​

The connector has two support modes:

  • Autonomous restart mode: the connector has persistent /data or equivalent durable local state, so identity survives restart and the connector reconnects on its own.
  • Guided recovery mode: the connector runs without persistent /data, so identity may be lost on restart and the UI guides recovery. The internal runtime state is needs_recovery; the UI renders it as Needs recovery.

In both modes, connector configuration must remain available separately from runtime identity. Configuration is deployment-owned state and must not be lost simply because /data is not persistent. Configuration must not include bootstrap tokens, private keys, certificate private material, or decrypted secrets.

Reachability and routing​

A Resource says which Connector can reach it. If you have multiple Connectors in different networks, each Resource points at the right one. VaultPAM never tries to reach the target directly — only through a Connector.

Health​

A Connector reports a heartbeat every 10 s. If the heartbeat stops, the dashboard shows Offline and the Connector is removed from routing decisions until it recovers. Sessions in flight through an offline Connector drop gracefully.