QuickConnect

Quick Connect Format

A quick connect code is BASE64 encoded JSON. It can either contain tunnel credentials to a server, or point to a 3rd party orchestration server, to which the client connects and receives its connection details.

With embedded credentials:

{"t":"<Tunnel>", "p":"<Password>", "s": "<Server>", "p": "<Server-Port>", "b": "<Backup-Server>", "bp": "<Backup-Server-Port>"}

Server port & backup server (+ port) are optional. If no port is provided, port "443" is assumed.

Tunnel Name, password & server are required.

With Orchestration server URL:

{"u": "Orchestration Server URL", "m": {"meta": "data"}}}

Orchestration Server Protocol

When the client is started with a quick connect code that points to an orchestration server, it sends a HTTP POST request to the provided URL.

Client Request

{"action":"request", "version":"1", "info": {"architecture": "X86_64/Common KVM processor", "build":"20221130-0939-8e0de0d"}, "meta": {"meta": "data"}}

Property	Description
action	The type of request. The following values are valid: request - initial request when the device is asking for credentials ping - ping request when the device is connected ping-down - ping request when the device has received credentials, but the tunnel is not connected
version	Protocol version. For now, this field is "1".
info	Various information gathered from the client device, such as architecture and build version. Available information might vary depending on platform and build. todo add fingerprint info
meta	Optional custom meta-data that is encoded in the connection string ("m").

Server Response

{"result": "ok", "version": 1, "tunnel":"test1", "password":"test", "server":"10.42.0.11", "keepAlive":360, "keepAliveDown":1}

Property	Description
result	Should contain "ok". Any other value will cause the client to disable the tunnel.
server	Target server. Should be an IP address
tunnel	Tunnel name
password	Tunnel password
keepAlive	Interval in minutes in which a keep alive request should be sent when the tunnel is connected. If the value is omitted or -1, no keep alive intervals will be sent while the tunnel is connected.
keepAliveDown	Interval in minutes in which a keep-alive request should be sent when the tunnel is not connected. If no value is supplied, 1 minute is assumed.

If the server is not reachable, responds with a non 200 HTTP return code, or if the response contains invalid JSON, the request is considered failed. In this case, the next request will be done either 5 seconds later, or after the time specified in keepAlive/keepAliveDown.

Ping Requests

The client can send periodical pings to an orchestration server, which can be used to update credentials or track activity.

When the client tunnel is connected, the interval provided by the "keepAlive" property is used - if the value is -1, no requests are sent as long as the tunnel is connected.

If the client is not able to connect the tunnel, the interval provided by the "keepAliveDown" property is used instead. Unlike regular ping, this type of request cannot be disabled.