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:
|
| 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.
