tools/Tunnels

Tunnels

Give SikkerKey a private connection to services inside your network, reaching only the targets you declare.

Updated today

A tunnel gives SikkerKey a private connection to services running inside your network. A small connector runs on one host, dials out to SikkerKey, and holds that connection open. SikkerKey can then reach the endpoints you name on that tunnel, without those services accepting connections from the internet.

One tunnel connects one host. The connector installed on that machine is the tunnel, so a second machine needs its own tunnel and its own install token.

#How a tunnel works

You create a tunnel in the dashboard and receive a single-use install command.

You run that command on a host inside your network. It installs the connector, generates an identity for the host, and registers the background service.

You approve the tunnel in the dashboard once the host reports in.

You declare the targets the tunnel may reach, each with a name, a host, and a port.

Features that support tunnels refer to a target by name. SikkerKey signs each request, and the connector verifies it before opening a connection.

The connector is always the side that dials out, so your firewall needs no inbound rule for SikkerKey. Your own applications continue to reach the service directly on your network.

#Before you begin

Tunnels are available on plans that include them. Your plan also sets how many tunnels a vault can hold.
Creating, approving, and deleting tunnels requires the tunnel management capability in your vault role. Viewing requires the tunnel view capability.
The connector runs on Linux and macOS, on x86-64 and arm64. Installing it needs administrative access on that host.
Choose a host that stays running and can reach the services you want to expose.

#Create a tunnel

Open Tunnels in the dashboard and select the plus button.

Enter a name that identifies the host, then create the tunnel.

Copy the install command. It is shown once.

The install token is valid for 24 hours and can be used once. Only its hash is stored, so it cannot be shown again or reissued. If the token expires or is lost before the host is installed, delete the tunnel and create another.

#Install the connector

Run the copied command on the host that should carry the tunnel. It downloads the connector, verifies it against the checksums published with the release, claims the tunnel for that host, and registers the background service.

bash

curl -fsSL https://sikkerkey.com/connector.sh | sh -s -- sk_tun_...

The service runs as a systemd unit on Linux and a launchd agent on macOS, so the tunnel comes back after a reboot. Check on it with:

bash

sudo systemctl status sikkerkey-connector
sudo journalctl -u sikkerkey-connector -f

The connector is open source under the MIT license. The source is available from SikkerKeyOfficial/sikkerkey-connector.

#Approve the tunnel

A newly installed tunnel connects but carries no traffic until you approve it. Open the row menu on the Tunnels page and select Approve once the host reports its name and connection state.

Status	Meaning
Awaiting install	The tunnel exists and its install command has not been run yet.
Token expired	The install command was not used within 24 hours. Delete the tunnel and create another.
Needs approval	A host has claimed the tunnel and is waiting for you to approve it.
Ready	The tunnel is approved and enabled, and can carry traffic to its targets.
Disabled	The tunnel is turned off. The connector stays installed and no target is reachable.

The Tunnels page also shows whether the connector is currently connected, the hostname it reported, and how many targets it holds.

#Declare the targets SikkerKey may reach

A target is a named endpoint on your network. Nothing is reachable through a tunnel until you declare it, so the target list is both the product interface and the boundary on what the tunnel can touch.

Open the tunnel’s row menu and select Configure.

Add a target with a name, a host, and a port.

Reference the target by its name wherever a feature asks for one.

Field	Notes
Name	Lowercase letters, numbers, and hyphens, up to 63 characters, unique on the tunnel. Consumers reference this name and never see the address.
Host	An address or hostname as it resolves on the machine running the connector. Internal DNS names, private addresses, and loopback are all valid.
Port	The port the service listens on.

Targets are protocol-agnostic. A target names a host and a port, which is what lets a tunnel serve more than one kind of service.

A target must point at an address inside your network. Public addresses are rejected, because a service that is already reachable from the internet does not need a tunnel.

Disabling or removing a target ends its reachability immediately. Anything configured to use that target stops resolving.

#How a tunnel is authenticated

Both directions are authenticated, and each side generates the key it signs with. Only public keys are ever transmitted.

Direction	How it is proven
The host proves itself to SikkerKey	An Ed25519 key pair generated during installation. The private key stays on the host and only the public half is sent.
SikkerKey proves itself to the host	A separate Ed25519 key pair held for this tunnel. The connector pins its public half at installation and checks every request against it.

Each request to open a connection is signed over the target, a timestamp, and a nonce. The connector refuses a signature that does not verify, a timestamp outside a five minute window, a nonce it has already seen, and any target that is not declared on the tunnel.

The connector keeps its configuration and private key under ~/.sikkerkey/connector/ on the host.

#Manage a tunnel

Rename a tunnel or edit its targets from Configure.
Disable a tunnel to stop all traffic while leaving the connector installed. Enable it again to resume.
Delete a tunnel to sever it permanently and release its slot in your plan allowance.

To remove the connector from the host itself, run:

bash

sudo sikkerkey-connector uninstall

Disabling or deleting a tunnel stops anything that depends on it. A leased secret routed over that tunnel can no longer issue credentials, and accounts it already issued can no longer be removed through it. Move those workloads to a replacement before severing a tunnel that is in use.

#Troubleshoot tunnels

Symptom	What to check
The install command reports that the token is invalid	An install token works once and expires after 24 hours. Delete the tunnel and create another to get a fresh command.
The tunnel shows as awaiting install after running the command	Check the connector log for the outcome of the claim, and confirm the host can reach SikkerKey over HTTPS.
The connector installs but the service does not start	Run the install command again on the same host. It sets up the service for the identity already enrolled, without needing a new token.
The tunnel keeps reconnecting	Reconnection after a network interruption or a SikkerKey deployment is expected. The connector retries with an increasing delay and reports each attempt in its log.
A target cannot be added	Confirm the name uses lowercase letters, numbers, and hyphens, is unique on the tunnel, and that the address is inside your network.
A tunnel cannot be selected when creating a leased secret	Only tunnels that are installed, approved, and enabled can be selected. Confirm the tunnel is ready and holds at least one enabled target.
Test connection fails for a tunnel-routed leased secret	Confirm the connector is connected, the target address and port are correct from that host, and the service accepts connections from it.
A new tunnel cannot be created	Confirm your plan includes tunnels and that the vault is below its tunnel allowance. Delete an unused tunnel to free a slot.