|
|
| (12 intermediate revisions by 2 users not shown) |
| Line 1: |
Line 1: |
| The Bondix SANE client is the software that you install on your [[Client/Supported Devices|supported]] router, which establishes a connection to the [[Server|server]] using multiple WAN links.
| |
|
| |
|
| For '''OpenWRT''' based routers, please check [[Client/OpenWRT|this page]].
| | __NOINDEX__ |
| | | __NONEWSECTIONLINK__ |
| = Installation =
| |
| Log into your router via SSH and do the following:
| |
| {| class="wikitable"
| |
| |-
| |
| | Create installation directory || <code>mkdir -p /opt/bondix
| |
| cd /opt/bondix</code>
| |
| |-
| |
| | Download installation package || <code>curl -o sane.tar.gz <DOWNLOAD-URL></code>
| |
| |-
| |
| | Extract package || <code>tar -xvzf sane.tar.gz</code>
| |
| |}
| |
| | |
| You can verify that the correct version has been installed with the command
| |
| <code>/opt/bondix/client/saneclient --version</code>
| |
| | |
| If successful, it should print its version string.
| |
| | |
| = Configuration =
| |
| Configuration is done using [https://www.json.org/ 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. <code>/opt/bondix/client/saneclient.json</code>) and at <code>/etc/saneclient.json</code>. 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:
| |
| <nowiki>[
| |
| {"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"}
| |
| ]
| |
| </nowiki>
| |
| | |
| For an example using SSL certificate authentication, go to [[Certificates]]
| |
| | |
| == Command Structure ==
| |
| A JSON command has the following structure:
| |
| <code>{"target": "<module>", "action": "<command>", [...additional values...]}</code>, where <module> specifies the configuration submodule and <command> specifies what should be done.
| |
| | |
| == System Commands ==
| |
| {| class="wikitable"
| |
| |-
| |
| | |
| |
| |
| === shutdown ===
| |
| Shuts down the client and terminates.
| |
| | style="width: 40%"|
| |
| <nowiki>{"target": "system",
| |
| "action": "shutdown"
| |
| }</nowiki>
| |
| |-
| |
| | |
| |
| |
| === set-log ===
| |
| Enables logging to file or changes output file.
| |
| {| class="wikitable"
| |
| |+ Parameters
| |
| |-
| |
| | file || The filename that the log should be written to. Required.
| |
| |-
| |
| | fileMode|| can be <code>append</code> or <code>overwrite</code>. Required.
| |
| |}
| |
| ||
| |
| <nowiki>{"target": "system",
| |
| "action": "set-log",
| |
| "file": "/var/log/saneclient.log",
| |
| "fileMode": "append"
| |
| }</nowiki>
| |
| |-
| |
| | |
| |
| |
| === set-webinterface ===
| |
| Enables the integrated webserver & debug webinterface.
| |
| {| class="wikitable"
| |
| |+ 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.
| |
| |}
| |
| ||
| |
| <nowiki>{"target": "system",
| |
| "action": "set-webinterface",
| |
| "host": "0.0.0.0",
| |
| "port": "80",
| |
| "allowConfig": false,
| |
| "allowMonitor": true,
| |
| "configApiKey": "123456",
| |
| "webroot": "/tmp/"
| |
| }</nowiki>
| |
| |}
| |
| | |
| == Tunnel Commands ==
| |
| {| class="wikitable"
| |
| |-
| |
| | |
| |
| |
| === create ===
| |
| Sets up basic tunnel configuration.
| |
| {| class="wikitable"
| |
| |+ 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.
| |
| |}
| |
| | style="width: 40%"|
| |
| <nowiki>{"target": "tunnel",
| |
| "action": "create",
| |
| "name": "MyTunnel",
| |
| "password: "1234",
| |
| "server": "10.0.0.1",
| |
| "interfaceName": "bndx0",
| |
| "values": {...}
| |
| }</nowiki>
| |
| |-
| |
| | |
| |
| |
| === add-server ===
| |
| Adds a endpoint server. If multiple servers are added, the client will cycle through
| |
| them until a connection has been established successfully.
| |
| {| class="wikitable"
| |
| |+ Parameters
| |
| |-
| |
| | host|| IP or host of the destination server. Required.
| |
| |-
| |
| | port || Port of the destination server. Optional (Default: "443").
| |
| |}
| |
| ||
| |
| <nowiki>{"target": "tunnel",
| |
| "action": "add-server",
| |
| "host": "10.0.0.1",
| |
| "port": "443"
| |
| }</nowiki>
| |
| |-
| |
| | |
| |
| |
| === create-interfaces ===
| |
| Creates channels for the specified interfaces using [[Client/Presets|presets]].
| |
| {| class="wikitable"
| |
| |+ Parameters
| |
| |-
| |
| | interfaces|| a JSON object where each key is a network interface name, with the corresponding value being a [[Client/Presets|preset]] name. Required.
| |
| |}
| |
| ||
| |
| <nowiki>{"target": "tunnel",
| |
| "action": "create-interfaces",
| |
| "interfaces": {
| |
| "wwan0": "mobile",
| |
| "eth1": "ethernet"
| |
| }
| |
| }</nowiki>
| |
| |-
| |
| | |
| |
| |
| === add-interface ===
| |
| Adds a single interface to the tunnel.
| |
| {| class="wikitable"
| |
| |+ Parameters
| |
| |-
| |
| | interface || Name of the linux network interface. Required.
| |
| |-
| |
| | name || Human-readable name for the interface. Optional.
| |
| |-
| |
| | preset || [[Client/Presets|Preset]] that should be applied to this interface. Optional.
| |
| |-
| |
| | values || Configuration values for this interface. See [[Tunnel Settings]]. Optional.
| |
| |}
| |
| ||
| |
| <nowiki>{"target": "tunnel",
| |
| "action": "add-interface",
| |
| "interface": "wlan0",
| |
| "name": "WiFi",
| |
| "preset": "mobile",
| |
| "values": {"enabled": false}
| |
| }</nowiki>
| |
| |-
| |
| | |
| |
| |
| === set ===
| |
| Sets tunnel properties. See [[Tunnel Settings]].
| |
| {| class="wikitable"
| |
| |+ Parameters
| |
| |-
| |
| | values || JSON object with values to change. Required.
| |
| |}
| |
| ||
| |
| <nowiki>{"target": "tunnel",
| |
| "action": "set",
| |
| "values": {"maxConcurrentChannel": 2}
| |
| }</nowiki>
| |
| |-
| |
| | |
| |
| |
| === set-remote ===
| |
| Sets tunnel properties on the remote end. See [[Tunnel Settings]].
| |
| {| class="wikitable"
| |
| |+ Parameters
| |
| |-
| |
| | values || JSON object with values to change. Required.
| |
| |}
| |
| ||
| |
| <nowiki>{"target": "tunnel",
| |
| "action": "set-remote",
| |
| "values": {"maxConcurrentChannel": 2}
| |
| }</nowiki>
| |
| |-
| |
| | |
| |
| |
| === set-interface ===
| |
| Sets tunnel interface properties. See [[Tunnel Settings]].
| |
| {| class="wikitable"
| |
| |+ Parameters
| |
| |-
| |
| | index || Index of the channel. 0 for first created channel, 1 for second, etc..
| |
| |-
| |
| | values || JSON object with values to change.
| |
| |}
| |
| ||
| |
| <nowiki>{"target": "tunnel",
| |
| "action": "set-interface",
| |
| "index": 0,
| |
| "values": {"enabled": false}
| |
| }</nowiki>
| |
| |-
| |
| | |
| |
| |
| === set-remote-interface ===
| |
| Sets interface properties on the remote end. See [[Tunnel Settings]].
| |
| {| class="wikitable"
| |
| |+ Parameters
| |
| |-
| |
| | index || Index of the channel. 0 for first created channel, 1 for second, etc..
| |
| |-
| |
| | values || JSON object with values to change.
| |
| |}
| |
| ||
| |
| <nowiki>{"target": "tunnel",
| |
| "action": "set-remote-interface",
| |
| "index": 0,
| |
| "values": {"enabled": false}
| |
| }</nowiki>
| |
| |-
| |
| | |
| | |
| | |
| |
| |
| === set-preset ===
| |
| Applies a tunnel preset. See [[Client/Presets|Presets]] for more info.
| |
| {| class="wikitable"
| |
| |+ Parameters
| |
| |-
| |
| | name || Name of the tunnel preset. Required.
| |
| |}
| |
| ||
| |
| <nowiki>{"target": "tunnel",
| |
| "action": "set-preset",
| |
| "preset": "Bonding"
| |
| }</nowiki>
| |
| |-
| |
| | |
| |
| |
| === set-ifname ===
| |
| Renames the virtual network tunnel interface.
| |
| {| class="wikitable"
| |
| |+ Parameters
| |
| |-
| |
| | name || The name that the interface should be renamed to. Required.
| |
| |}
| |
| ||
| |
| <nowiki>{"target": "tunnel",
| |
| "action": "set-ifname",
| |
| "name": "bondix0"
| |
| }
| |
| }</nowiki>
| |
| |-
| |
| | |
| |
| |
| === 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?''
| |
| {| class="wikitable"
| |
| |+ Parameters
| |
| |-
| |
| | enabled || Enables or disables SSL certificate verification. Required.
| |
| |}
| |
| ||
| |
| <nowiki>{"target": "tunnel",
| |
| "action": "set-cert-check",
| |
| "enabled": true
| |
| }
| |
| }</nowiki>
| |
| |-
| |
| | |
| |
| |
| === 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.
| |
| {| class="wikitable"
| |
| |+ Parameters
| |
| |-
| |
| | file || location of the public root certificate file. Required.
| |
| |}
| |
| ||
| |
| <nowiki>{"target": "tunnel",
| |
| "action": "set-root-ca",
| |
| "file": "/etc/ssl/foobar.pub"
| |
| }
| |
| }</nowiki>
| |
| |-
| |
| | |
| |
| |
| === set-certificate ===
| |
| Loads a tunnel client certificate. See [[Certificates]] for further information.
| |
| {| class="wikitable"
| |
| |+ Parameters
| |
| |-
| |
| | cert || location of the public certificate file. Required.
| |
| |-
| |
| | key || location of the private certificate key file. Required.
| |
| |}
| |
| ||
| |
| <nowiki>{"target": "tunnel",
| |
| "action": "set-certificate",
| |
| "cert": "/etc/ssl/foobar.pem"
| |
| "key": "/etc/ssl/foobar.key"
| |
| }</nowiki>
| |
| |-
| |
| | |
| |
| |
| === 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.
| |
| {| class="wikitable"
| |
| |+ 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.
| |
| |}
| |
| ||
| |
| <nowiki>{"target": "tunnel",
| |
| "action": "embed-certs",
| |
| "cert": "...",
| |
| "key": "...",
| |
| "root": "..."
| |
| }</nowiki>
| |
| |-
| |
| | |
| |
| |
| === 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.
| |
| {| class="wikitable"
| |
| |+ Parameters
| |
| |-
| |
| | file || location of the public root certificate file. Required.
| |
| |}
| |
| ||
| |
| <nowiki>{"target": "tunnel",
| |
| "action": "set-root-ca",
| |
| "file": "/etc/ssl/foobar.pub"
| |
| }
| |
| }</nowiki>
| |
| |-
| |
| | |
| |
| |
| === delete ===
| |
| Resets the complete tunnel configuration, including interfaces.
| |
| ||
| |
| <nowiki>{"target": "tunnel",
| |
| "action": "delete"
| |
| }</nowiki>
| |
| |}
| |
| | |
| == Interactive Commands ==
| |
| Interactive commands can be used to retrieve various information via the CLI socket.
| |
| ''TODO: Add JSON responses''
| |
| {| class="wikitable" style="width: 100%"
| |
| |-
| |
| | |
| |
| |
| === get ===
| |
| Returns all [[Tunnel Settings|tunnel settings]].
| |
| | style="width: 40%"|
| |
| <nowiki>{"target": "tunnel",
| |
| "action": "get"
| |
| }</nowiki>
| |
| |-
| |
| | |
| |
| |
| === get-interface ===
| |
| Returns [[Tunnel Settings|settings]] for a specific interface.
| |
| {| class="wikitable"
| |
| |+ Parameters
| |
| |-
| |
| | index || Index of the interface to fetch information from.
| |
| |}
| |
| ||
| |
| <nowiki>{"target": "tunnel",
| |
| "action": "get-interface",
| |
| "index": 0
| |
| }</nowiki>
| |
| |-
| |
| | |
| |
| |
| === status ===
| |
| Returns various tunnel information.
| |
| ||
| |
| <nowiki>{"target": "tunnel",
| |
| "action": "status"
| |
| }</nowiki>
| |
| |-
| |
| | |
| |
| |
| === reset===
| |
| Performs a disconnect & reconnect.
| |
| ||
| |
| <nowiki>{"target": "tunnel",
| |
| "action": "reset"
| |
| }</nowiki>
| |
| |}
| |
| | |
| = Running =
| |
| The software can be run in the shell using <code>/opt/bondix/client/saneclient</code>, 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 ==
| |
| {| class="wikitable"
| |
| |-
| |
| | <code>--daemon</code> || Runs the software as a daemon.
| |
| |-
| |
| | <code>--nopid</code> || Does not attempt to create a pid-file at <code>/var/run/saneclient.pid</code>
| |
| |-
| |
| | <code>--listflags</code> || Lists available feature flags
| |
| |-
| |
| | <code>--flags <FLAG1> <FLAG2>... </code> || Enables the specified flag(s). Multiple flags are separated using space.
| |
| |-
| |
| | <code></path/to/filename.json></code> || 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.
| |
| {| class="wikitable"
| |
| |-
| |
| | 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.
| |
| <nowiki>root@Teltonika-RUTX12:/opt/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)
| |
| </nowiki>
| |
