Skip to content
Sencai.docs

VPN profiles

A server that only has a private address cannot be reached from the internet, and that includes the browser terminal. A VPN profile tells Sencai how to get into your private network: through an OpenVPN or WireGuard gateway, an SSH jump host (bastion), or a SOCKS5 or HTTP proxy that you already operate. You attach a profile to a cloud instance, and its terminal then opens a tunnel through the profile first and connects to the server from inside your network.

Open Settings → VPN Profiles (/gravity/settings/vpn-profiles). The page lists the profiles of the organization you have selected.

What you can connect through

Section titled “What you can connect through”
Type Use it when Carries
OpenVPN You run an OpenVPN gateway Everything the tunnel routes
WireGuard You run a WireGuard peer Everything the tunnel routes
SSH bastion You already operate an SSH jump host TCP connections only
SOCKS5 proxy You run a SOCKS5 proxy, with or without a username and password TCP connections only
HTTP proxy You run an HTTP proxy that allows CONNECT, optionally over TLS TCP connections only
IPsec / IKEv2 You run an IPsec gateway See the note below

The browser terminal only opens TCP connections, so every type that works is enough for it.

The type of a profile is chosen when you create it and cannot be changed afterwards. To switch to another type, create a new profile and delete the old one.

Who can do what

Section titled “Who can do what”
Action Lowest role
See profiles (endpoint, status, which credentials are stored) Member
Attach a profile to an instance and open a terminal through it Member
Create, edit, turn on or off, delete, or test a profile Admin

Sencai’s own platform administrators have no shortcut here. They can use VPN profiles only through a membership in your organization that you granted. The permission keys are vpn:read, vpn:use, vpn:create, vpn:update, vpn:delete and vpn:test; see Permissions in depth. An organization can keep up to 100 profiles, and each profile needs a name that is unique within the organization.

Create a profile

Section titled “Create a profile”

Choose New profile. The dialog has five steps: Type, Sign-in method, Connection, Credentials and Review.

  1. Type. Pick the kind of connection from the six cards.

  2. Sign-in method. Answer how your gateway, bastion or proxy signs Sencai in. The choices depend on the type:

    Type Sign-in methods
    OpenVPN Certificate only; Username and password; Username, password and one-time code; Certificate, username and password; Certificate, username, password and one-time code
    WireGuard Key pair
    SSH bastion Private key; Password
    SOCKS5 proxy No sign-in; Username and password
    HTTP proxy No sign-in; Username and password
    IPsec / IKEv2 Pre-shared key; Certificate; EAP (username and password)

  3. Connection. The name, the address of your gateway, the port, the networks Sencai may reach (below) and the type’s own settings (below).

  4. Credentials. The secrets for the method you chose. They are write-only.

  5. Review, then save. The success message offers Test connection.

The connection step

Section titled “The connection step”
  • Gateway, peer, bastion or proxy host. A public host name (for example vpn.example.com) or a public IP address. Private, loopback and other internal addresses are refused: Sencai reaches your gateway over the internet, and the gateway then leads into your private network.
  • Port and protocol. Each type has a default (OpenVPN 1194, WireGuard 51820, IPsec 500, SSH bastion 22, SOCKS5 1080, HTTP proxy 3128). WireGuard and IPsec use UDP, and the SSH bastion and both proxies use TCP.
  • Allowed destinations. One IPv4 network per line, for example 10.9.1.2/32 for a single server or 10.20.0.0/16 for a whole network. Between /8 and /32, at most 32 networks, and 0.0.0.0/0 is not accepted. Sencai connects only to addresses inside these networks, however a session is configured. Anything else is refused before a connection is attempted.
  • Close an idle tunnel after. 60 to 3600 seconds, 600 by default. A tunnel that nobody uses is closed and opened again on the next session.
  • Turned on. A turned-off profile cannot open tunnels.

Settings that belong to the type

Section titled “Settings that belong to the type”
Type Settings
WireGuard Interface address (the Address line of your [Interface] section, for example 10.77.0.2/32), peer public key (the PublicKey of the [Peer] section), keepalive in seconds (0 to 120, 25 if empty), MTU (1200 to 1420, 1380 if empty)
SSH bastion Host key fingerprint in the form SHA256:... (required), keepalive in seconds (0 to 120, 30 if empty)
HTTP proxy TLS to the proxy itself. When it is on, the proxy’s certificate is checked against a CA certificate you add on the Credentials step, or against the usual public authorities if you add none
SOCKS5 proxy None. Sencai asks the proxy for connections by IP address
IPsec / IKEv2 Remote ID, local ID, IKE and ESP proposals, and whether to ask for a virtual IP address. Leave the proposals empty to use the defaults

The SSH bastion fingerprint is how Sencai makes sure it is talking to your bastion. It is pinned: if the bastion presents a different key, the connection fails with “host key changed” and Sencai never asks whether to trust the new one. You can read the fingerprint of a host key with ssh-keygen -lf /etc/ssh/ssh_host_ed25519_key.pub on the bastion. The fingerprint of any one of the bastion’s host keys (ed25519, ECDSA or RSA) is accepted.

Credentials

Section titled “Credentials”
Credential Where it applies Notes
Client certificate, private key, CA certificate OpenVPN, IPsec certificate PEM text, pasted or chosen from a file
TLS key (tls-crypt or tls-auth) OpenVPN, when the gateway uses one
Username and password OpenVPN, SSH bastion, SOCKS5, HTTP proxy, IPsec EAP
One-time code secret (TOTP seed) OpenVPN with a one-time code Base32 text or the otpauth:// link of the QR code
Private key, key passphrase WireGuard; SSH bastion A WireGuard key is 44 characters of base64. An SSH key is ed25519, ECDSA or RSA of at least 2048 bits, at most 16 KB, and a passphrase is needed only if the key is encrypted
Preshared key WireGuard (optional); IPsec pre-shared key

Credentials are stored encrypted on the server and are write-only: they are never sent back to your browser, shown, or written to logs. The list shows which ones are stored (Stored: username, password, private key and so on) and nothing else. To replace a credential, enter a new value when you edit the profile; leave the field empty to keep the stored one. The protection is encryption at rest on Sencai’s side, not end-to-end encryption, and Sencai can use the stored values to open tunnels on your behalf.

One-time codes

Section titled “One-time codes”

An OpenVPN profile that uses a one-time code can work in two ways:

  • With the TOTP seed stored, Sencai computes the current code itself every time it opens a tunnel, so the browser terminal works with no one typing anything.
  • Without it, the profile is marked Asks for a code and needs a person to type the current code for every test and every connection. The browser terminal cannot do that, so it refuses to open a session through such a profile. Either store the seed, or use Test connection to check the profile.

Test a profile

Section titled “Test a profile”

Choose Test connection on a profile. Sencai opens a real tunnel with the stored credentials and tells you whether it opened, how long it took, and why it failed if it did.

You can fill in Also try one server: an IPv4 address inside the allowed destinations and a port, for example the SSH port of a server you want to reach. Once the tunnel is open Sencai attempts a TCP connection to it, which tells you whether the route and the server really work.

If an SSH bastion test fails with “host key changed”, the result shows the fingerprint the bastion actually presented next to the one you pinned. If you trust the new key, edit the profile and pin it; otherwise do not connect.

Status and lockout

Section titled “Status and lockout”

Each profile row shows its status as Sencai last recorded it:

Status Meaning
Not tested No tunnel has been opened yet
Connecting A tunnel is being opened
Connected OK The last tunnel opened
Failed The last attempt failed. The row shows the error code and the reason
Locked Too many refused sign-ins. The row shows how long the lock lasts

A failed profile is never tidied away: the last error stays visible with its time.

After three refused sign-ins in a row, a profile is locked for 15 minutes. Wait for the lock to end and fix the credentials; every further failed attempt only makes the problem worse. This protects your gateway from being hammered with a wrong password, and it applies to every type. A WireGuard peer simply does not answer a wrong key, so that failure shows up as a timeout rather than a refusal.

Use a profile with an instance

Section titled “Use a profile with an instance”
  1. Open the instance and go to its connection setup (Finish import for an imported instance, Connection setup otherwise).
  2. In the VPN profile section choose the profile. None: connect directly is the default.
  3. Choose Save VPN profile.

You need the Owner or Admin role to change an instance, and permission to use VPN profiles. The selector shows the profile’s status next to its name, and warns you in these cases:

  • The profile is failed, locked or turned off.
  • The instance’s SSH host is outside the networks the profile may reach. Saving is then refused. If the SSH host is a name instead of an address, it is looked up when the tunnel is used, and the connection fails if it resolves outside the allowed networks.
  • The host is an IPv6 address. VPN profiles reach IPv4 networks only.

From then on the instance’s browser terminal shows via VPN and the profile’s name. If the instance is pinned to AWS Systems Manager or to a direct SSH connection, its profile is not used, and the terminal says VPN bypassed.

Troubleshooting

Section titled “Troubleshooting”
Error What it means and what to do
tunnel_auth_failed The gateway refused the credentials or the one-time code. Fix them before testing again
tunnel_timeout The gateway did not answer in time. Check the address, the port and the firewall in front of the gateway. For WireGuard, also check the key pair and the peer public key
tunnel_failed The tunnel could not be established. The detail line says more, for instance “host key changed” for an SSH bastion
tunnel_locked The profile is locked after repeated refused sign-ins. Wait for the lock to end
target_not_allowed The server is outside the profile’s allowed destinations
target_unreachable The tunnel is up but the server did not answer. Check the server and your routing
otp_required The profile needs a one-time code typed by a person. Store the TOTP seed, or use Test connection
vpn_profile_disabled The profile is turned off
vpn_profile_in_use The profile is still attached to instances. Detach it from them first
vpn_profile_limit The organization already has 100 profiles

A terminal session that fails because of its VPN profile is closed with a message that says so and points you back to VPN Profiles.

Delete a profile

Section titled “Delete a profile”

Choose Delete and type the profile’s name to confirm. A profile that is still attached to instances cannot be deleted; the dialog lists them, and you detach the profile from each first. Deleting destroys the stored credentials.

What is recorded

Section titled “What is recorded”

Creating, changing, testing, deleting, attaching and detaching a profile, issuing a terminal connection for it and a lockout are all recorded in the audit log. Credentials never appear in it.

What’s next

Section titled “What’s next”