Client

The Bondix SANE client is the software that you install on your supported router, which establishes a connection to the server using multiple WAN links.

For OpenWRT based routers, please check this page.

Installation

Log into your router via SSH and do the following:

Create installation directory	mkdir -p /opt/bondix cd /opt/bondix
Download installation package	curl -o sane.tar.gz <DOWNLOAD-URL>
Extract package	tar -xvzf sane.tar.gz

You can verify that the correct version has been installed with the command /opt/bondix/client/saneclient --version

If successful, it should print its version string.

Configuration

Configuration is done using JSON commands. These can either be sent via a raw TCP socket (localhost:5113), or written to a configuration file (in a json-array) that is parsed at start-up. This allows both a fixed configuration as well as adjustments during runtime without the need to restart the service. By default, SANE checks for the existence of a configuration file in its installation directory (e.g. /opt/bondix/client/saneclient.json) and at /etc/saneclient.json. If you want SANE to load a configuration from a different location, you can specify it using a command line parameter.

Quick Start

This example provides the minimal necessities to get a tunnel up and running:

[
  {"action": "create", "target": "tunnel", "name": "TUNNELNAME", "password": "TUNNELPASSWORD"},
  {"action": "add-server", "target": "tunnel", "host": "ENDPOINTSERVER", "port": "443"},
  {"action": "create-interfaces", "target": "tunnel", "interfaces": {
    "eth1": "mobileAggressive",
    "wwan0": "mobileAggressive",
    "wwan1": "mobileAggressive"
  }},
  {"target": "tunnel", "action": "set-preset", "preset": "bonding"}
]

For an example using SSL certificate authentication, go to Certificates

Command Structure

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.

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-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 configuration & monitor. Not required, "123456" by default. 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/" }

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" }
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.	{"target": "tunnel", "action": "create-interfaces", "interfaces": { "wwan0": "mobile", "eth1": "ethernet" } }
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} }
set Sets tunnel properties. See Tunnel Settings. Parameters values JSON object with values to change. Required.	{"target": "tunnel", "action": "set", "values": {"maxConcurrentChannel": 2} }
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" } }
delete Resets the complete tunnel configuration, including interfaces.	{"target": "tunnel", "action": "delete" }

Interactive Commands

Interactive commands can be used to 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 various tunnel information.	{"target": "tunnel", "action": "status" }
reset Performs a disconnect & reconnect.	{"target": "tunnel", "action": "reset" }

Running

The software can be run in the shell using /opt/bondix/client/saneclient, where it will run in the foreground. However, it is recommended to start the service automatically on startup, which can be different depending on the platform.

Parameters

--daemon	Runs the software as a daemon.
--nopid	Does not attempt to create a pid-file at /var/run/saneclient.pid
--listflags	Lists available feature flags
--flags <FLAG1> <FLAG2>...	Enables the specified flag(s). Multiple flags are separated using space.
</path/to/filename.json>	JSON configuration file that should be used

Feature Flags

Feature flags are switches that enable certain features that are otherwise unavailable. These features are usually experimental and should be used with caution.

useBlake	Switches from SHA256 to the "blake" hashing algorithm. Depending on architecture, this can slightly improve performance.
useBlake3	Switches to the "blake3" hashing algorithm. Depending on architecture, this can slightly improve performance.
disableHash	Disables hashing completely, allowing potential MitM, with a vast speed improvement.
useMMSG	uses useMMSG linux socket API to send & receive multiple UDP packets at once. This improves performance under load, while stable there are some corner cases which can trigger error messages in the log.
channelRoutes	Makes the client create specific routes for each channel. Experimental, do not use.
bondingProxy	Enables the TCP Bonding Proxy.

bndutil

bndutil is a command line utility that allows to query and modify SANE during runtime.

root@Teltonika-RUTX12:/opt/bondix/client# ./bndutil
Usage:
   bndutil [--json] <command>
            --json  switch to JSON output

Available commands:
  * bndutil status
  * bndutil get
  * bndutil set <propertyName1> <propertyValue1> [propertyName2] [propertyValue2] ...
  * bndutil get-interface <index>
  * bndutil set-interface <index> <propertyName1> <propertyValue1> [propertyName2] [propertyValue2] ...
  * bndutil shutdown
  * bndutil restart 
    (tunnel reset & reconnect)

speedtest

Speedtest is a small utility that downloads (and discards) data via HTTP(s) using one or more WAN interfaces. It is useful to compare performance of each individual interface and the combined bandwidth over SANE's virtual tunnel interface.

root@Teltonika-RUTX12:/opt/bondix/client# ./speedtest
Usage: speedtest [--json] <download-url> <intf1> [intf2] ...

E.G. to test performance of each WAN interface directly:

./speedtest http://speed.hetzner.de/100MB.bin wwan0 wwan1 wwan2

Testing performance of the tunnel:

./speedtest http://speed.hetzner.de/100MB.bin tun0