Client Configuration: Difference between revisions

From Bondix Wiki
No edit summary
(layer2 description update)
 
(3 intermediate revisions by the same user not shown)
Line 84: Line 84:
|-
|-
| interfaces|| a JSON object where each key is a network interface name, with the corresponding value being a [[Client/Presets|preset]] name. Required.
| interfaces|| a JSON object where each key is a network interface name, with the corresponding value being a [[Client/Presets|preset]] name. Required.
Instead of a preset name, an object with various interface settings can be specified, as specified in [[#update-interfaces]]
|}
|}
||
||
Line 106: Line 107:
|
|
=== enable-layer2 ===
=== enable-layer2 ===
Adds a single interface to the tunnel.  
Instructs the client to establish a layer 2 tunnel. Layer 2 must also be enabled on the server, otherwise the tunnel will fall back to layer3. Combining layer2 with BondingProxy is currently not supported.
 
When enabled, the client will create a tap interface and call bridgeutils (brctl) to automatically add this interface to the specified bridge.  
{| class="wikitable"
{| class="wikitable"
|+ Parameters
|+ Parameters
Line 157: Line 160:
|
|
=== quicksetup ===
=== quicksetup ===
Sets up client using a base64 encoded JSON string containing connection info. JSON must be in this format:
Sets up client using a base64 encoded JSON string containing connection info.  
<nowiki>{"t":"TUNNELNAME", "p":"TUNNELPASSWORD", "s": "SERVER"}</nowiki>


{| class="wikitable"
{| class="wikitable"
|+ Parameters
|+Parameters
|-
|-
| data || base64 encoded JSON string.
|data||base64 encoded JSON string with the following layout:
{"t": "TUNNELNAME", "p": "TUNNELPASSWORD", "s": "SERVER", "sp": "SERVERPORT", "bs": "BACKUPSERVER", "bp": "BACKUPSERVERPORT"}
"t", "p" and "s" are required, "sp", "bs" and "bp" are optional. If no server port is provided, port 443 will be used.
 
Creating a quickconnect code in Linux:
$ echo "{\"t\":\"TUNNELNAME\",\"p\":\"TUNNELPASSWORD\",\"s\":\"SERVER\"}"|base64
eyJ0IjoiVFVOTkVMTkFNRSIsInAiOiJUVU5ORUxQQVNTV09SRCIsInMiOiJTRVJWRVIifQo=
|}
|}
||
||
  <nowiki>{"target": "tunnel",  
  <nowiki>{"target": "tunnel",  
  "action": "quicksetup",  
    "action": "quicksetup",  
  "data": "..."
    "data": "..."
  }  
    }  
}</nowiki>
  }</nowiki>
|-
|-


|
|
=== set ===
=== set===
Sets tunnel properties. See [[Tunnel Settings]].
Sets tunnel properties. See [[Tunnel Settings]].
{| class="wikitable"
{| class="wikitable"
|+ Parameters
|+Parameters
|-
|-
| values || JSON object with values to change. Required.
| values||JSON object with values to change. Required.
|}
|}
||
||
  <nowiki>{"target": "tunnel",  
  <nowiki>{"target": "tunnel",  
  "action": "set",  
    "action": "set",  
  "values": {"maxConcurrentChannel": 2}
    "values": {"maxConcurrentChannel": 2}
}</nowiki>
  }</nowiki>
|-
|-


|
|
=== set-meta ===
===set-meta===
Allows to add custom information that is shown on the server's tunnel status page. It has no further effect.
Allows to add custom information that is shown on the server's tunnel status page. It has no further effect.
{| class="wikitable"
{| class="wikitable"
|+ Parameters
|+Parameters
|-
|-
| data || Flat JSON object with custom info
|data||Flat JSON object with custom info
|}
|}
||
||
  <nowiki>{
  <nowiki>{
  "target": "tunnel",  
    "target": "tunnel",  
  "action": "set-meta",  
    "action": "set-meta",  
  "data": {"location": "Test Lab", "customer": "Evil Corp"}
    "data": {"location": "Test Lab", "customer": "Evil Corp"}
}</nowiki>
  }</nowiki>
|-
|-


|
|
=== set-remote ===
===set-remote===
Sets tunnel properties on the remote end. See [[Tunnel Settings]].
Sets tunnel properties on the remote end. See [[Tunnel Settings]].
{| class="wikitable"
{| class="wikitable"
|+ Parameters
|+Parameters
|-
|-
| values || JSON object with values to change. Required.
|values||JSON object with values to change. Required.  
|}
|}
||
||
  <nowiki>{"target": "tunnel",  
  <nowiki>{"target": "tunnel",  
  "action": "set-remote",  
    "action": "set-remote",  
  "values": {"maxConcurrentChannel": 2}
    "values": {"maxConcurrentChannel": 2}
}</nowiki>
  }</nowiki>
|-
|-


|
|
=== set-interface ===
===set-interface===
Sets tunnel interface properties. See [[Tunnel Settings]].
Sets tunnel interface properties. See [[Tunnel Settings]].
{| class="wikitable"
{| class="wikitable"
|+ Parameters
|+Parameters
|-
|-
| index || Index of the channel. 0 for first created channel, 1 for second, etc..
|index|| Index of the channel. 0 for first created channel, 1 for second, etc..  
|-
|-
| values || JSON object with values to change.
|values||JSON object with values to change.
|}
|}
||
||
  <nowiki>{"target": "tunnel",  
  <nowiki>{"target": "tunnel",  
  "action": "set-interface",
    "action": "set-interface",
  "index": 0,  
    "index": 0,  
  "values": {"enabled": false}
    "values": {"enabled": false}
}</nowiki>
  }</nowiki>
|-
|-


|
|
=== set-remote-interface ===
===set-remote-interface===
Sets interface properties on the remote end. See [[Tunnel Settings]].
Sets interface properties on the remote end. See [[Tunnel Settings]].
{| class="wikitable"
{| class="wikitable"
|+ Parameters
|+Parameters
|-
|-
| index || Index of the channel. 0 for first created channel, 1 for second, etc..
|index|| Index of the channel. 0 for first created channel, 1 for second, etc..
|-
|-
| values || JSON object with values to change.
|values ||JSON object with values to change.  
|}
|}
||
||
  <nowiki>{"target": "tunnel",  
  <nowiki>{"target": "tunnel",  
  "action": "set-remote-interface",
    "action": "set-remote-interface",
  "index": 0,  
    "index": 0,  
  "values": {"enabled": false}
    "values": {"enabled": false}
}</nowiki>
  }</nowiki>
|-
|-


|
|
=== set-preset ===
=== set-preset===
Applies a tunnel preset. See [[Client/Presets|Presets]] for more info.
Applies a tunnel preset. See [[Client/Presets|Presets]] for more info.
{| class="wikitable"
{| class="wikitable"
|+ Parameters
|+Parameters
|-
|-
| name || Name of the tunnel preset. Required.
|name|| Name of the tunnel preset. Required.
|}
|}
||
||
  <nowiki>{"target": "tunnel",  
  <nowiki>{"target": "tunnel",  
  "action": "set-preset",  
    "action": "set-preset",  
  "preset": "Bonding"
    "preset": "Bonding"
}</nowiki>
  }</nowiki>
|-
|-


|
|
=== set-ifname ===
===set-ifname===
Renames the virtual network tunnel interface.
Renames the virtual network tunnel interface.
{| class="wikitable"
{| class="wikitable"
|+ Parameters
|+Parameters
|-
|-
| name || The name that the interface should be renamed to. Required.
|name ||The name that the interface should be renamed to. Required.
|}
|}
||
||
  <nowiki>{"target": "tunnel",  
  <nowiki>{"target": "tunnel",  
  "action": "set-ifname",  
    "action": "set-ifname",  
  "name": "bondix0"
    "name": "bondix0"
  }  
    }  
}</nowiki>
  }</nowiki>
|-
|-


|
|
=== set-cert-check ===
===set-cert-check===
Enables or disables verification of the server's SSL certificate. ''TODO: Which root cert dir is used when no custom root certificate is provided?''
Enables or disables verification of the server's SSL certificate. ''TODO: Which root cert dir is used when no custom root certificate is provided?''
{| class="wikitable"
{| class="wikitable"
|+ Parameters
|+Parameters
|-
|-
| enabled || Enables or disables SSL certificate verification. Required.
|enabled||Enables or disables SSL certificate verification. Required.
|}
|}
||
||
  <nowiki>{"target": "tunnel",  
  <nowiki>{"target": "tunnel",  
  "action": "set-cert-check",  
    "action": "set-cert-check",  
  "enabled": true
    "enabled": true
  }  
    }  
}</nowiki>
  }</nowiki>
|-
|-


|
|
=== set-root-ca ===
===set-root-ca===
Specifies a root certificate that can be used to verify the authenticity of the remote server. When used, SSL server verification will be automatically enabled.
Specifies a root certificate that can be used to verify the authenticity of the remote server. When used, SSL server verification will be automatically enabled.
{| class="wikitable"
{| class="wikitable"
|+ Parameters
|+ Parameters
|-
|-
| file || location of the public root certificate file. Required.
|file ||location of the public root certificate file. Required.
|}
|}
||
||
  <nowiki>{"target": "tunnel",  
  <nowiki>{"target": "tunnel",  
  "action": "set-root-ca",  
    "action": "set-root-ca",  
  "file": "/etc/ssl/foobar.pub"
    "file": "/etc/ssl/foobar.pub"
  }  
    }  
}</nowiki>
  }</nowiki>
|-
|-


|
|
=== set-certificate ===
===set-certificate ===
Loads a tunnel client certificate. See [[Certificates]] for further information.
Loads a tunnel client certificate. See [[Certificates]] for further information.
{| class="wikitable"
{| class="wikitable"
|+ Parameters
|+Parameters
|-
|-
| cert || location of the public certificate file. Required.
|cert||location of the public certificate file. Required.
|-
|-
| key || location of the private certificate key file. Required.
|key||location of the private certificate key file. Required.
|}
|}
||
||
  <nowiki>{"target": "tunnel",  
  <nowiki>{"target": "tunnel",  
  "action": "set-certificate",  
    "action": "set-certificate",  
  "cert": "/etc/ssl/foobar.pem"
    "cert": "/etc/ssl/foobar.pem"
  "key": "/etc/ssl/foobar.key"
    "key": "/etc/ssl/foobar.key"
}</nowiki>
  }</nowiki>
|-
|-


|
|
=== embed-certs ===
===embed-certs===
A helper functions to embed tunnel & root certificate inside the configuration instead of an external file. Performs the same actions as set-certificate and set-root-ca combined.
A helper functions to embed tunnel & root certificate inside the configuration instead of an external file. Performs the same actions as set-certificate and set-root-ca combined.
{| class="wikitable"
{| class="wikitable"
|+ Parameters
|+Parameters
|-
|-
| cert || The tunnel public certificate as string. Required.
|cert ||The tunnel public certificate as string. Required.
|-
|-
| key || The tunnel private certificate key as string. Required.
|key || The tunnel private certificate key as string. Required.
|-
|-
| root || The public root certificate for server verification. Required.
|root||The public root certificate for server verification. Required.
|}
|}
||
||
  <nowiki>{"target": "tunnel",  
  <nowiki>{"target": "tunnel",  
  "action": "embed-certs",  
    "action": "embed-certs",  
  "cert": "...",
    "cert": "...",
  "key": "...",
    "key": "...",
  "root": "..."
    "root": "..."
}</nowiki>
  }</nowiki>
|-
|-


|
|
=== set-root-ca ===
===set-root-ca===
Specifies a root certificate that can be used to verify the authenticity of the remote server. When used, SSL server verification will be automatically enabled.
Specifies a root certificate that can be used to verify the authenticity of the remote server. When used, SSL server verification will be automatically enabled.
{| class="wikitable"
{| class="wikitable"
|+ Parameters
|+Parameters
|-
|-
| file || location of the public root certificate file. Required.
|file||location of the public root certificate file. Required.
|}
|}
||
||
  <nowiki>{"target": "tunnel",  
  <nowiki>{"target": "tunnel",  
  "action": "set-root-ca",  
    "action": "set-root-ca",  
  "file": "/etc/ssl/foobar.pub"
    "file": "/etc/ssl/foobar.pub"
  }  
    }  
}</nowiki>
  }</nowiki>
|-
|-


|
|
=== update-interfaces ===
===update-interfaces===
Updates interface information. If a provided interface already exists, it will be updated accordingly. If a provided interface is new, it will be created. Interfaces that have been previously defined but are not provided here will be removed.
Updates interface information. If a provided interface already exists, it will be updated accordingly. If a provided interface is new, it will be created. Interfaces that have been previously defined but are not provided here will be removed.
{| class="wikitable"
{| class="wikitable"
|+ Parameters
|+Parameters
|-
|-
| interfaces || JSON Object with interfaces. Property names specify the linux WAN interface to be used (e.g. "eth1")
|interfaces||JSON Object with interfaces. Key specifies the linux WAN interface to be used (e.g. "eth1"), with its value being an object with the following properties.
|}
|}
{| class="wikitable"
{| class="wikitable"
|+Object Parameters
|+Object Parameters
|name
|name
|string; Interface name that is shown in logs and in the endpoint webinterface.
|string; Interface name that is shown in logs and in the endpoint webinterface.  
|-
|-
|preset
|preset
Line 394: Line 401:
|object; {"min": 0, "max": 100}. "min" and "max" specfiy lower and upper bandwidth limits in MBit/sec for outgoing traffic (towards endpoint). A value of "0" means no limit. When a minimum value is specified, make sure that the value is below the maximum throughput of the interface to avoid congestion.
|object; {"min": 0, "max": 100}. "min" and "max" specfiy lower and upper bandwidth limits in MBit/sec for outgoing traffic (towards endpoint). A value of "0" means no limit. When a minimum value is specified, make sure that the value is below the maximum throughput of the interface to avoid congestion.
|-
|-
|downstream
|downstream  
|object; {"min": 0, "max": 100}. "min" and "max" specfiy lower and upper bandwidth limits in MBit/sec for incoming traffic (from endpoint). A value of "0" means no limit. When a minimum value is specified, make sure that the value is below the maximum throughput of the interface to avoid congestion.
|object; {"min": 0, "max": 100}. "min" and "max" specfiy lower and upper bandwidth limits in MBit/sec for incoming traffic (from endpoint). A value of "0" means no limit. When a minimum value is specified, make sure that the value is below the maximum throughput of the interface to avoid congestion.
|-
|-
|standby
| standby  
|boolean; When enabled, the interface will go into standby if other sufficient interfaces are available, as specified by the "minimum connected channel" value configured. When in standby, Bondix will make no traffic through this interface until reactivated (e.g. due to a different interface going down). You can change the minimum number of connected channel by adding this command in saneclient.json:
|boolean; When enabled, the interface will go into standby if other sufficient interfaces are available, as specified by the "minimum connected channel" value configured. When in standby, Bondix will make no traffic through this interface until reactivated (e.g. due to a different interface going down). You can change the minimum number of connected channel by adding this command in saneclient.json:
  <nowiki>{"target": "tunnel", "action": "set", "values": { "minConnectedChannel": 2 }}</nowiki>
  <nowiki>{"target": "tunnel", "action": "set", "values": { "minConnectedChannel": 2 }}</nowiki>
|-
|-
|maxLatency
|maxLatency  
|number; overrides the maximum latency setting in milliseconds. Any packet exceeding this latency limit will be considered as lost, and the interface will not be used until latency is below the specified maximum. We do not encourage exposing this setting as it can have a negative impact on performance/throughput. (Default value is 1000 ms;
| number; overrides the maximum latency setting in milliseconds. Any packet exceeding this latency limit will be considered as lost, and the interface will not be used until latency is below the specified maximum. We do not encourage exposing this setting as it can have a negative impact on performance/throughput. (Default value is 1000 ms;
|-
|-
|enabled
| enabled
|boolean; If disabled, the interface will not be used, but still shown in the webinterface.  
|boolean; If disabled, the interface will not be used, but still shown in the webinterface.
|}
|}
Note: Updating the preset will override upstream, downstream, maxLatency & standby settings to default values.  
Note: Updating the preset will override upstream, downstream, maxLatency & standby settings to default values.  
Line 432: Line 439:


|
|
=== update-packetSize ===
===update-packetSize===
Updates the maximum size that UDP packets may carry. Changing this value will cause a tunnel restart.
Updates the maximum size that UDP packets may carry. Changing this value will cause a tunnel restart.
{| class="wikitable"
{| class="wikitable"
|+ Parameters
|+Parameters
|-
|-
| value || Packet size value. Required. Valid range: 500 to 1400.
|value||Packet size value. Required. Valid range: 500 to 1400.  
|}
|}
||
||
  <nowiki>{
  <nowiki>{
  "target": "tunnel",  
    "target": "tunnel",  
  "action": "update-packetSize",
    "action": "update-packetSize",
  "value": 1400
    "value": 1400
}</nowiki>
  }</nowiki>
|-
|
===cloudlink===
Instructs the client to use Unwired® Cloudlink to retrieve its tunnel configuration. The client will use the provided API key and the mac address of the specified interface to authenticate itself.
A CA file must be provided in order to properly validate the SSL certificate of the CloudLink API endpoint.
 
''This command should not be used in combination with "create" to configure tunnel credentials or "add-server" to configure a target server.''
{| class="wikitable"
|+Parameters
|apiKey
|The CloudLink API key used for authentication. This key can be obtained by registering at https://admin.wifi.unwired.at
|-
|interface||The name of a linux interface whose mac address should be used for identification. Required.
|-
|caFile
|Location of a root certificate used for SSL validation of the CloudLink API endpoint.
|}
|
{
  "target": "tunnel",
  "action": "cloudlink",
  "apiKey": "CLOUDLINK-API-KEY",
  "interface": "eth0",
  "caFile": "/etc/ssl/certs/ca-certificates.crt"
}
|}
|}




== Interactive Commands ==
==Interactive Commands==
Interactive commands can be used to interact with the tunnel and retrieve various information via the CLI socket.
Interactive commands can be used to interact with the tunnel and retrieve various information via the CLI socket.
''TODO: Add JSON responses''
''TODO: Add JSON responses''
Line 455: Line 487:


|
|
=== get ===
===get===
Returns all [[Tunnel Settings|tunnel settings]].
Returns all [[Tunnel Settings|tunnel settings]].
| style="width: 40%"|
| style="width: 40%" |
  <nowiki>{"target": "tunnel",  
  <nowiki>{"target": "tunnel",  
  "action": "get"
    "action": "get"
}</nowiki>
  }</nowiki>
|-
|-


|
|
=== get-interface ===
===get-interface===
Returns [[Tunnel Settings|settings]] for a specific interface.
Returns [[Tunnel Settings|settings]] for a specific interface.
{| class="wikitable"
{| class="wikitable"
|+ Parameters
|+Parameters
|-
|-
| index || Index of the interface to fetch information from.
|index||Index of the interface to fetch information from.
|}
|}
||
||
  <nowiki>{"target": "tunnel",  
  <nowiki>{"target": "tunnel",  
  "action": "get-interface",  
    "action": "get-interface",  
  "index": 0
    "index": 0
}</nowiki>
  }</nowiki>
|-
|-


|
|
=== status ===
===status===
Returns current tunnel information.
Returns current tunnel information.
||
||
  <nowiki>{"target": "tunnel",  
  <nowiki>{"target": "tunnel",  
  "action": "status"
    "action": "status"
}</nowiki>
  }</nowiki>
|-
|-


|
|
=== reset===
===reset===
Performs a disconnect & reconnect.
Performs a disconnect & reconnect.
||
||
  <nowiki>{"target": "tunnel",  
  <nowiki>{"target": "tunnel",  
  "action": "reset"
    "action": "reset"
}</nowiki>
  }</nowiki>
|}
|}


== System Commands ==
==System Commands==
{| class="wikitable"
{| class="wikitable"
|-
|-


|
|
=== shutdown ===
===shutdown===
Shuts down the client and terminates.
Shuts down the client and terminates.
| style="width: 40%"|
| style="width: 40%" |
  <nowiki>{
  <nowiki>{
  "target": "system",  
    "target": "system",  
  "action": "shutdown"
    "action": "shutdown"
}</nowiki>
  }</nowiki>
|-
|-


|
|
=== set-log ===
===set-log ===
Enables logging to file or changes output file.
Enables logging to file or changes output file.
{| class="wikitable"
{| class="wikitable"
|+ Parameters
|+Parameters
|-
|-
| file || The filename that the log should be written to. Required.
|file||The filename that the log should be written to. Required.
|-
|-
| fileMode|| can be <code>append</code> or <code>overwrite</code>.  Required.
|fileMode||can be <code>append</code> or <code>overwrite</code>.  Required.
|}
|}
||
||
  <nowiki>{
  <nowiki>{
  "target": "system",  
    "target": "system",  
  "action": "set-log",  
    "action": "set-log",  
  "file": "/var/log/saneclient.log",  
    "file": "/var/log/saneclient.log",  
  "fileMode": "append"
    "fileMode": "append"
}</nowiki>
  }</nowiki>
|-
|-


|
|
=== set-script-path ===
===set-script-path===
Changes the directory that points towards the client scripts. (/opt/bondix/client/scripts by default)
Changes the directory that points towards the client scripts. (/opt/bondix/client/scripts by default)
{| class="wikitable"
{| class="wikitable"
|+ Parameters
|+Parameters
|-
|-
| path || Path to the new bondix script directory.
|path|| Path to the new bondix script directory.
|}
|}
||
||
  <nowiki>{
  <nowiki>{
  "target": "system",  
    "target": "system",  
  "action": "set-script-path",  
    "action": "set-script-path",  
  "path": "/etc/bondix/scripts"
    "path": "/etc/bondix/scripts"
}</nowiki>
  }</nowiki>
|-
|-


|
|
=== set-webinterface ===
===set-webinterface===
Enables the integrated webserver & debug webinterface.
Enables the integrated webserver & debug webinterface.
{| class="wikitable"
{| class="wikitable"
|+ Parameters
|+Parameters
|-
|-
| host || IP that the service should listen on. Required.
|host|| IP that the service should listen on. Required.
|-
|-
| port || TCP Port that the service should listen on. Required.  
|port||TCP Port that the service should listen on. Required.
|-
|-
| allowConfig || En- or disables web configuration. Not required, enabled by default.
|allowConfig||En- or disables web configuration. Not required, enabled by default.
|-
|-
| allowMonitor || En- or disables web monitor. Not required, enabled by default.
|allowMonitor||En- or disables web monitor. Not required, enabled by default.
|-
|-
| configApiKey|| The password required to access the realtime monitor monitor.
|configApiKey||The password required to access the realtime monitor monitor.
|-
|-
| webroot || Web root directory. Points to the "www" subdirectory in installation directory. Not required, changing not advised.
|webroot||Web root directory. Points to the "www" subdirectory in installation directory. Not required, changing not advised.
|}
|}
||
||
  <nowiki>{
  <nowiki>{
  "target": "system",  
    "target": "system",  
  "action": "set-webinterface",  
    "action": "set-webinterface",  
  "host": "0.0.0.0",  
    "host": "0.0.0.0",  
  "port": "80",
    "port": "80",
  "allowConfig": false,  
    "allowConfig": false,  
  "allowMonitor": true,  
    "allowMonitor": true,  
  "configApiKey": "123456",  
    "configApiKey": "123456",  
  "webroot": "/tmp/"
    "webroot": "/tmp/"
}</nowiki>
  }</nowiki>
|}
|}

Latest revision as of 11:28, 21 October 2024

Commands

A JSON command has the following structure: {"target": "<module>", "action": "<command>", [...additional values...]}, where <module> specifies the configuration submodule and <command> specifies what should be done.

Tunnel Commands

create

Sets up basic tunnel configuration.

Parameters
name Tunnel Name. Required.
password Password. Required.
server Endpoint target IP. Optional.
interfaceName Desired name of the virtual tunnel network interface. Optional.
values A JSON object containing configuration parameters for the tunnel. 
{"target": "tunnel", 
  "action": "create", 
  "name": "MyTunnel", 
  "password: "1234", 
  "server": "10.0.0.1", 
  "interfaceName": "bndx0", 
  "values": {...}
}

add-server

Adds a endpoint server. If multiple servers are added, the client will cycle through them until a connection has been established successfully.

Parameters
host IP or host of the destination server. Required.
port Port of the destination server. Optional (Default: "443"). 
{"target": "tunnel", 
  "action": "add-server", 
  "host": "10.0.0.1", 
  "port": "443"
}

add-interface

Adds a single interface to the tunnel.

Parameters
interface Name of the linux network interface. Required.
name Human-readable name for the interface. Optional.
preset Preset that should be applied to this interface. Optional.
values Configuration values for this interface. See Tunnel Settings. Optional. 
{"target": "tunnel", 
  "action": "add-interface", 
  "interface": "wlan0",
  "name": "WiFi",
  "preset": "mobile",
  "values": {"enabled": false} 
}

create-interfaces

Creates channels for the specified interfaces using presets.

Parameters
interfaces a JSON object where each key is a network interface name, with the corresponding value being a preset name. Required.

Instead of a preset name, an object with various interface settings can be specified, as specified in #update-interfaces 

{"target": "tunnel", 
  "action": "create-interfaces", 
  "interfaces": { 
    "wwan0": "mobile", 
    "eth1": "ethernet"
  } 
}

delete

Resets the complete tunnel configuration, including interfaces. 

{"target": "tunnel", 
  "action": "delete"
}

enable-layer2

Instructs the client to establish a layer 2 tunnel. Layer 2 must also be enabled on the server, otherwise the tunnel will fall back to layer3. Combining layer2 with BondingProxy is currently not supported.

When enabled, the client will create a tap interface and call bridgeutils (brctl) to automatically add this interface to the specified bridge.

Parameters
bridge The name of the network bridge that should be used. Required.
tapname Name of the virtual tap interface. Optional, a dynamic name will be used when no name is supplied. 
{
"target": "tunnel", 
  "action": "enable-layer2", 
  "bridge": "br-lan",
  "tapname": "bondixTap0"
}

enable-proxy

Enables Bonding Proxy.

Parameters
host Host where the bonding proxy server should listen on.
port Port to be used with the bonding proxy server.
interface Interface from which outgoing tcp connections should be proxied. 
{
"target": "tunnel", 
  "action": "enable-proxy", 
  "host": "0.0.0.0",
  "port": "18080"
}

disallow-swap

Explicitly tells the linux kernel to prevent memory swapping (mlockall). 

{
  "target": "tunnel", 
  "action": "disallow-swap"
}

quicksetup

Sets up client using a base64 encoded JSON string containing connection info.

Parameters
data base64 encoded JSON string with the following layout: 
{"t": "TUNNELNAME", "p": "TUNNELPASSWORD", "s": "SERVER", "sp": "SERVERPORT", "bs": "BACKUPSERVER", "bp": "BACKUPSERVERPORT"}

"t", "p" and "s" are required, "sp", "bs" and "bp" are optional. If no server port is provided, port 443 will be used.

Creating a quickconnect code in Linux: 

$ echo "{\"t\":\"TUNNELNAME\",\"p\":\"TUNNELPASSWORD\",\"s\":\"SERVER\"}"|base64
eyJ0IjoiVFVOTkVMTkFNRSIsInAiOiJUVU5ORUxQQVNTV09SRCIsInMiOiJTRVJWRVIifQo=

{"target": "tunnel", 
    "action": "quicksetup", 
    "data": "..."
    } 
  }

set

Sets tunnel properties. See Tunnel Settings.

Parameters
values JSON object with values to change. Required. 
{"target": "tunnel", 
    "action": "set", 
    "values": {"maxConcurrentChannel": 2}
  }

set-meta

Allows to add custom information that is shown on the server's tunnel status page. It has no further effect.

Parameters
data Flat JSON object with custom info 
{
    "target": "tunnel", 
    "action": "set-meta", 
    "data": {"location": "Test Lab", "customer": "Evil Corp"}
  }

set-remote

Sets tunnel properties on the remote end. See Tunnel Settings.

Parameters
values JSON object with values to change. Required. 
{"target": "tunnel", 
    "action": "set-remote", 
    "values": {"maxConcurrentChannel": 2}
  }

set-interface

Sets tunnel interface properties. See Tunnel Settings.

Parameters
index Index of the channel. 0 for first created channel, 1 for second, etc..
values JSON object with values to change. 
{"target": "tunnel", 
    "action": "set-interface",
    "index": 0, 
    "values": {"enabled": false}
  }

set-remote-interface

Sets interface properties on the remote end. See Tunnel Settings.

Parameters
index Index of the channel. 0 for first created channel, 1 for second, etc..
values JSON object with values to change. 
{"target": "tunnel", 
    "action": "set-remote-interface",
    "index": 0, 
    "values": {"enabled": false}
  }

set-preset

Applies a tunnel preset. See Presets for more info.

Parameters
name Name of the tunnel preset. Required. 
{"target": "tunnel", 
    "action": "set-preset", 
    "preset": "Bonding"
  }

set-ifname

Renames the virtual network tunnel interface.

Parameters
name The name that the interface should be renamed to. Required. 
{"target": "tunnel", 
    "action": "set-ifname", 
    "name": "bondix0"
    } 
  }

set-cert-check

Enables or disables verification of the server's SSL certificate. TODO: Which root cert dir is used when no custom root certificate is provided?

Parameters
enabled Enables or disables SSL certificate verification. Required. 
{"target": "tunnel", 
    "action": "set-cert-check", 
    "enabled": true
    } 
  }

set-root-ca

Specifies a root certificate that can be used to verify the authenticity of the remote server. When used, SSL server verification will be automatically enabled.

Parameters
file location of the public root certificate file. Required. 
{"target": "tunnel", 
    "action": "set-root-ca", 
    "file": "/etc/ssl/foobar.pub"
    } 
  }

set-certificate

Loads a tunnel client certificate. See Certificates for further information.

Parameters
cert location of the public certificate file. Required.
key location of the private certificate key file. Required. 
{"target": "tunnel", 
    "action": "set-certificate", 
    "cert": "/etc/ssl/foobar.pem"
    "key": "/etc/ssl/foobar.key"
  }

embed-certs

A helper functions to embed tunnel & root certificate inside the configuration instead of an external file. Performs the same actions as set-certificate and set-root-ca combined.

Parameters
cert The tunnel public certificate as string. Required.
key The tunnel private certificate key as string. Required.
root The public root certificate for server verification. Required. 
{"target": "tunnel", 
    "action": "embed-certs", 
    "cert": "...",
    "key": "...",
    "root": "..."
  }

set-root-ca

Specifies a root certificate that can be used to verify the authenticity of the remote server. When used, SSL server verification will be automatically enabled.

Parameters
file location of the public root certificate file. Required. 
{"target": "tunnel", 
    "action": "set-root-ca", 
    "file": "/etc/ssl/foobar.pub"
    } 
  }

update-interfaces

Updates interface information. If a provided interface already exists, it will be updated accordingly. If a provided interface is new, it will be created. Interfaces that have been previously defined but are not provided here will be removed.

Parameters
interfaces JSON Object with interfaces. Key specifies the linux WAN interface to be used (e.g. "eth1"), with its value being an object with the following properties.
Object Parameters
name string; Interface name that is shown in logs and in the endpoint webinterface.
preset string; Interface preset to be used (e.g. "mobileAggressive", "ethernet",...}
upstream object; {"min": 0, "max": 100}. "min" and "max" specfiy lower and upper bandwidth limits in MBit/sec for outgoing traffic (towards endpoint). A value of "0" means no limit. When a minimum value is specified, make sure that the value is below the maximum throughput of the interface to avoid congestion.
downstream object; {"min": 0, "max": 100}. "min" and "max" specfiy lower and upper bandwidth limits in MBit/sec for incoming traffic (from endpoint). A value of "0" means no limit. When a minimum value is specified, make sure that the value is below the maximum throughput of the interface to avoid congestion.
standby boolean; When enabled, the interface will go into standby if other sufficient interfaces are available, as specified by the "minimum connected channel" value configured. When in standby, Bondix will make no traffic through this interface until reactivated (e.g. due to a different interface going down). You can change the minimum number of connected channel by adding this command in saneclient.json: 
{"target": "tunnel", "action": "set", "values": { "minConnectedChannel": 2 }}
maxLatency number; overrides the maximum latency setting in milliseconds. Any packet exceeding this latency limit will be considered as lost, and the interface will not be used until latency is below the specified maximum. We do not encourage exposing this setting as it can have a negative impact on performance/throughput. (Default value is 1000 ms;
enabled boolean; If disabled, the interface will not be used, but still shown in the webinterface.

Note: Updating the preset will override upstream, downstream, maxLatency & standby settings to default values. 

{
  "target": "tunnel", 
  "action": "update-interfaces",
  "interfaces": {
    "eth1": {
      "name":"WAN1", 
      "preset": "mobileAggressive", 
      "upstream": {"min": 0, "max": 50},
      "downstream": {"min": 0, "max": 100},
      "standby": false,
      "maxLatency": 1000,
      "enabled": true
    },
    "eth2": {
      "name":"WAN2", 
      "preset": "mobileAggressive", 
      "upstream": {"min": 0, "max": 50},
      "downstream": {"min": 50, "max": 100}
  }
}

update-packetSize

Updates the maximum size that UDP packets may carry. Changing this value will cause a tunnel restart.

Parameters
value Packet size value. Required. Valid range: 500 to 1400. 
{
    "target": "tunnel", 
    "action": "update-packetSize",
    "value": 1400
  }

cloudlink

Instructs the client to use Unwired® Cloudlink to retrieve its tunnel configuration. The client will use the provided API key and the mac address of the specified interface to authenticate itself. A CA file must be provided in order to properly validate the SSL certificate of the CloudLink API endpoint.

This command should not be used in combination with "create" to configure tunnel credentials or "add-server" to configure a target server.

Parameters
apiKey The CloudLink API key used for authentication. This key can be obtained by registering at https://admin.wifi.unwired.at
interface The name of a linux interface whose mac address should be used for identification. Required.
caFile Location of a root certificate used for SSL validation of the CloudLink API endpoint. 
{
  "target": "tunnel", 
  "action": "cloudlink",
  "apiKey": "CLOUDLINK-API-KEY",
  "interface": "eth0",
  "caFile": "/etc/ssl/certs/ca-certificates.crt"
}


Interactive Commands

Interactive commands can be used to interact with the tunnel and retrieve various information via the CLI socket. TODO: Add JSON responses

get

Returns all tunnel settings. 

{"target": "tunnel", 
    "action": "get"
  }

get-interface

Returns settings for a specific interface.

Parameters
index Index of the interface to fetch information from. 
{"target": "tunnel", 
    "action": "get-interface", 
    "index": 0
  }

status

Returns current tunnel information. 

{"target": "tunnel", 
    "action": "status"
  }

reset

Performs a disconnect & reconnect. 

{"target": "tunnel", 
    "action": "reset"
  }

System Commands

shutdown

Shuts down the client and terminates. 

{
    "target": "system", 
    "action": "shutdown"
  }

set-log

Enables logging to file or changes output file.

Parameters
file The filename that the log should be written to. Required.
fileMode can be append or overwrite. Required. 
{
    "target": "system", 
    "action": "set-log", 
    "file": "/var/log/saneclient.log", 
    "fileMode": "append"
  }

set-script-path

Changes the directory that points towards the client scripts. (/opt/bondix/client/scripts by default)

Parameters
path Path to the new bondix script directory. 
{
    "target": "system", 
    "action": "set-script-path", 
    "path": "/etc/bondix/scripts"
  }

set-webinterface

Enables the integrated webserver & debug webinterface.

Parameters
host IP that the service should listen on. Required.
port TCP Port that the service should listen on. Required.
allowConfig En- or disables web configuration. Not required, enabled by default.
allowMonitor En- or disables web monitor. Not required, enabled by default.
configApiKey The password required to access the realtime monitor monitor.
webroot Web root directory. Points to the "www" subdirectory in installation directory. Not required, changing not advised. 
{
    "target": "system", 
    "action": "set-webinterface", 
    "host": "0.0.0.0", 
    "port": "80",
    "allowConfig": false, 
    "allowMonitor": true, 
    "configApiKey": "123456", 
    "webroot": "/tmp/"
  }
Retrieved from "https://wiki.bondix.dev/index.php?title=Client_Configuration&oldid=738"