Skip to main content

VPN Settings

This guide explains how to manage VPN profiles in KIOPS and securely access remote infrastructure.

VPN Management

Why Do You Need VPN?​

VPN (Virtual Private Network) is a technology for securely accessing your internal network from remote locations.

VPN Benefits Comparison
  • Remote work: Without VPN, you cannot access internal systems. With VPN, you can access the internal network from anywhere.
  • Data transfer: Without VPN, data is transmitted in plain text with risk of interception. With VPN, data is securely transmitted through an encrypted tunnel.
  • IP whitelisting: Without VPN, you must add firewall rules for each IP. With VPN, you just allow the VPN IP.
  • Cluster access: Without VPN, you must expose the API to the public internet. With VPN, you access only through the internal network.
What is a VPN Tunnel?

A VPN tunnel creates an encrypted "virtual private line" over the internet. All traffic is encrypted in transit, so even if intercepted, the contents cannot be read.

Supported VPN Types​

KIOPS currently provides full support for WireGuard. OpenVPN and IPSec appear in the UI as placeholders for future support but cannot be selected at this time.

  • WireGuard (fully supported): A lightweight protocol with fast speed and simple setup. Keypair-based authentication, .conf import/export, and mobile compatibility are all available out of the box.
  • OpenVPN (coming soon): Planned for future addition to support compatibility with existing OpenVPN infrastructure. The option is currently disabled in the profile creation form.
  • IPSec (coming soon): An enterprise standard protocol; planned to be added together with OpenVPN support.
Which VPN Should You Choose?

At this stage, simply use WireGuard — there is no other option to weigh up. WireGuard is a proven protocol in terms of security, performance, and operational simplicity, and works well on mobile networks.

Creating a VPN Profile​

How to set up a VPN for accessing remote infrastructure.

Permission Notice: If you cannot access this feature, please request permission from your organization manager.

Step 1: Navigate to the VPN Management Page​

Click [VPN Management] in the left menu.

Step 2: Add a New VPN Profile​

Click the Add Profile button. The VPN profile settings modal opens.

Step 3: Select the VPN Type​

In the VPN type dropdown, select WireGuard. OpenVPN and IPSec are shown with a "coming soon" label and cannot be selected.

Step 4: Enter Basic Information​

Enter the basic information for the VPN profile:

  • Profile name: A name to identify the profile. (e.g., datacenter-vpn)
  • Description: A description of the profile. (e.g., VPN for data center access)
  • Server address: IP or domain of the VPN server. (e.g., vpn.company.com)
  • Port: VPN port. (e.g., WireGuard default is 51820)
If you already have a .conf file

If you already have a WireGuard configuration file (.conf), use the Import from .conf button located below the guidance text in the key information section to fill out the form in one step. Uploading the file automatically populates the server address, port, keys, internal IP, allowed IPs, and keepalive value.

Step 5: Configure Authentication Credentials​

Enter the keys required for WireGuard authentication.

  • Private Key (client private key): Click the Generate Client Keypair button next to the field, and KIOPS will immediately generate a secure Curve25519 keypair. The private key is filled into the input automatically, while the matching public key is shown in a separate notice. You must share the displayed public key with the VPN server administrator so it can be registered as a peer. If you already have a key issued externally, you can paste it directly instead.
  • Public Key (server public key): The public key of the VPN server you want to connect to. Enter the value provided by the server administrator. (This is different from the client public key generated by KIOPS in the previous step.)
  • Preshared Key: A pre-shared key. Enter only if the server uses PSK. (Optional, for additional security.)
Keypair retention policy

KIOPS encrypts the private key with AES-256-GCM at rest. Once saved, the private key is masked and cannot be retrieved again, so back it up from the screen shown immediately after clicking Generate Client Keypair if you need a copy.

Step 6: Configure Network Settings​

Enter the VPN network settings:

  • Internal IP: The IP to be assigned within the VPN. (e.g., 10.0.0.2/24)
  • Allowed IPs: Networks to route through the VPN. (e.g., 10.0.0.0/8, 192.168.0.0/16)
  • DNS: DNS server to use in the VPN. (e.g., 10.0.0.1)
  • PersistentKeepalive: Keepalive interval used to keep the connection alive behind NAT. (Default 25 seconds, recommended.)

Step 7: Save and Test​

Click the Save button. From the profile list, click the Test Connection button on the row to verify that the handshake succeeds. The result is shown in the modal as a step-by-step diagnostic (server reachability, handshake success, routing check).

Activating a VPN Connection​

How to connect using a configured VPN profile.

Step 1: Select a VPN Profile​

Select the VPN profile to connect to from the profile list on the [VPN Management] page.

Step 2: Start Connection​

Click the Connect button.

Step 3: Check Connection Status​

Check the connection status:

  • Connected: VPN is active and available.
  • Connecting: Attempting to connect.
  • Disconnected: VPN is inactive.
  • Error: Connection failed. Check the settings.

Step 4: View Connection Information​

When the connection is established, you can view the following information:

  • Assigned internal IP
  • Data transfer volume
  • Connection time
  • Handshake status

Connection Mode (Auto / VPN / Direct SSH)​

For every operation that requires SSH (devices, runtimes, builds, deployments, and so on), KIOPS shows a connection mode selection modal so the user can decide how the request is routed. Three modes are available:

  • Auto: If a VPN profile matches the target infrastructure and an active session exists, traffic is routed through the VPN tunnel; otherwise it falls back to direct SSH. This is the recommended default for most cases.
  • VPN: Always force the VPN tunnel. If no active session exists, a quick-connect modal opens immediately and prompts you to connect; if the target IP is outside AllowedIPs, an explicit error is shown.
  • Direct SSH: Bypass VPN entirely and use the registered multi-hop chain (jump server → target) as-is. Any associated VPN profile is ignored.
With VPN, you don't need jump-server credentials

In Auto/VPN modes, when an active session exists and the target IP is within the VPN's AllowedIPs, KIOPS automatically skips any registered jump-server (parent device) hops and connects using only the target server's SSH information. In other words, the VPN itself replaces the role of a jump server, so jump-server passwords/keys do not need to be managed separately.

In Direct SSH mode, the registered multi-hop chain is used in full, so you need credentials for both the jump server and the target server.

The VPN endpoint must match an infrastructure gateway hop for auto-stripping

For automatic hop stripping to work in multi-hop infrastructures (e.g. jump → internal target), the active VPN's endpoint must match one of the registered gateway hops. If it does not, KIOPS skips stripping to avoid colliding with the same private IP range from a different site — Auto falls back to direct SSH, while VPN mode is rejected with a clear error.

Configuring Infrastructure Access via VPN​

How to register a cluster that is only accessible through VPN.

Prerequisite: A VPN profile must be configured and an active session must exist.

Step 1: Activate VPN Connection​

Connect first to the VPN that provides access to the target network. Confirm that the VPN status indicator in the header shows the connection as active.

Step 2: Navigate to the Runtime Environment Page​

Click [Runtime Environment] in the left menu.

Step 3: Import External Runtime​

Click the Import External Runtime button. When the connection mode selection modal appears, the matching active VPN profile is selected automatically and Auto mode is chosen by default. You can force VPN mode if needed, or pick a different profile from the dropdown when multiple matches exist.

Step 4: Enter Cluster Connection Information​

Enter the cluster connection information using the internal network address within the VPN (e.g. 192.168.1.100:6443). You don't need to enter jump-server information separately — the VPN tunnel takes the gateway role.

Step 5: Test Connection and Save​

Test the cluster connection through the VPN, then save when it succeeds. If the test fails, suspect one of the following:

  • The target IP is not covered by the VPN's AllowedIPs → extend the AllowedIPs in the VPN profile.
  • The active VPN's endpoint does not match the registered gateway hop → pick a different VPN profile or use Direct SSH mode.

Importing/Exporting WireGuard .conf​

How to register a profile quickly via a configuration file, or export a registered profile so it can be used with other clients.

Importing a .conf File​

On the [VPN Management] page, open the Add Profile modal, then click Import from .conf located below the guidance text in the key information section and upload a WireGuard configuration file. The following fields are filled in automatically:

  • Server endpoint and port
  • Client private key
  • Server public key, preshared key
  • Client internal Address, AllowedIPs, PersistentKeepalive

You only need to enter the remaining fields (profile name, description, and so on) and save.

.conf export / OpenVPN Config / QR codes

The KIOPS UI does not currently expose a .conf download button. Exporting a registered profile for use with another client is only available via the CLI tooling, and OpenVPN configuration export and QR code download will be reviewed when OpenVPN is officially supported.

Quick Connect​

When you start an action that requires VPN access on the Device Management, Runtime Environment, or Service Management page and no VPN session is active yet, KIOPS shows a Quick Connect modal so you can activate VPN without leaving the page.

  • The modal appears automatically when a VPN-required action is attempted.
  • Pick an available VPN profile and click Connect — the handshake starts immediately.
  • The VPN status indicator in the top-right of the header shows current session count and connection state with color and icon, so you can see VPN status at a glance from anywhere.
Sessions are kept alive until you end the work

KIOPS's VPN sessions have no idle timeout. They stay active until the user explicitly disconnects or logs out, so you don't need to shorten keepalive values to avoid losing the session during long-running tasks.

Per-Device VPN Verification​

A feature that checks, in one go, whether a VPN profile can actually reach its target devices.

Step 1: Open the Per-Device Verification Modal​

On the [VPN Management] page, click the Verify Devices button on the profile row you want to verify.

Step 2: Select Target Devices​

A list of registered devices accessed through this VPN is displayed. Multiple devices can be selected at once.

Step 3: Run Verification​

Click Start Verification. KIOPS runs the following checks against each device sequentially:

  • Whether the WireGuard handshake succeeds
  • Reachability of the device IP/port (TCP connectivity)
  • Whether SSH login with the registered credentials succeeds

Each check is shown as pass/fail with a colored indicator, and on failure the cause (e.g. Connection refused, Permission denied) is shown alongside.

VPN Connection Monitoring​

How to monitor VPN connection status. The [VPN Monitoring] page is a PlatformAdmin-only menu; there is no separate vpn:monitor permission code granted to regular users.

Step 1: Navigate to the VPN Monitoring Page​

Open the [VPN Monitoring] page from the left menu. The page has two tabs at the top:

  • Active Sessions
  • Event Timeline

Step 2: Inspect Active Sessions​

The Active Sessions tab shows currently connected VPN sessions:

  • User: The user who owns the session.
  • Profile: The VPN profile in use.
  • Assigned IP: The internal IP assigned to the session.
  • Last Handshake: When the most recent handshake occurred.
  • Traffic: Cumulative bytes sent and received by the session.

You can use the Terminate Session button on a row to forcibly disconnect a specific session if needed.

Step 3: Review the Event Timeline​

The Event Timeline tab shows connection, disconnection, re-handshake, and error events in chronological order.

  • Event type filter: Filter by connect, disconnect, handshake failure, etc.
  • User filter: View only the events of a specific user.
  • Time range filter: Last 1 hour / 24 hours / 7 days, and so on.

Deleting a VPN Profile​

How to delete a VPN profile that is no longer in use.

Step 1: Select the Profile to Delete​

Click the VPN profile to delete on the [VPN Management] page.

Step 2: Confirm Disconnection​

If the profile is connected, disconnect it first.

Step 3: Delete the Profile​

Click the Delete button. Click Delete in the confirmation dialog.

Check if any runtime environments are using this VPN. The connection of related runtimes may fail.

Frequently Asked Questions​

VPN connection is failing​

Causes and solutions:

  • Server address error: Verify the IP or domain is correct.
  • Port blocked: Allow the WireGuard port (default 51820/UDP) in the firewall.
  • Authentication error: Verify the private key and the server public key are correct, and confirm that your public key has been registered as a peer on the server side.
  • Server down: Check if the VPN server is running.
Use the diagnostic modals

The Test Connection and Verify Devices buttons on the [VPN Management] page run KIOPS's backend diagnostics, checking handshake, routing, and SSH reachability step by step. The failed step and its cause are shown together, making it much faster to find the root cause than with a generic VPN client.

VPN connection keeps dropping​

  • Keep-alive setting: For WireGuard, set PersistentKeepalive = 25
  • Network changes: Reconnection needed when switching between WiFi and mobile.
  • NAT timeout: Check router NAT session timeout

Cannot access the cluster through VPN​

Things to Check
  1. Allowed IP range: Is the cluster network (e.g., 10.0.0.0/8) included in Allowed IPs?
  2. Routing settings: Is routing to the cluster network configured on the VPN server?
  3. DNS resolution: Are internal cluster domains resolving? (Check VPN DNS settings)

Speed is slow​

  • Adjust MTU: Try a lower MTU (1280-1400) than the default.
  • Server location: Use a VPN server in a nearby region.
  • AllowedIPs scope: Setting too broad a range (such as 0.0.0.0/0) routes all traffic through the VPN and can be slow. Specify only the internal network ranges you actually need.
Recommended Next Steps