Client Configuration: Difference between revisions

From Bondix Wiki
(initial page)
 
No edit summary
Line 68: Line 68:
   "host": "10.0.0.1",  
   "host": "10.0.0.1",  
   "port": "443"
   "port": "443"
}</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>
}</nowiki>
|-
|-
Line 90: Line 114:


|
|
=== add-interface ===
=== delete ===
Adds a single interface to the tunnel.  
Resets the complete tunnel configuration, including interfaces.
{| 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",  
  <nowiki>{"target": "tunnel",  
   "action": "add-interface",
   "action": "delete"
  "interface": "wlan0",
  "name": "WiFi",
  "preset": "mobile",
  "values": {"enabled": false}
}</nowiki>
}</nowiki>
|-
|-
Line 131: Line 140:
}</nowiki>
}</nowiki>
|-
|-


|
|
Line 152: Line 160:
   "host": "0.0.0.0",
   "host": "0.0.0.0",
   "port": "18080"
   "port": "18080"
}</nowiki>
|-
|
=== disallow-swap ===
Explicitly tells the linux kernel to prevent memory swapping (mlockall).
||
<nowiki>{
  "target": "tunnel",
  "action": "disallow-swap"
}</nowiki>
}</nowiki>
|-
|-
Line 372: Line 390:
   "file": "/etc/ssl/foobar.pub"
   "file": "/etc/ssl/foobar.pub"
   }  
   }  
}</nowiki>
|
=== 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 in use but are not provided here will be removed.
{| class="wikitable"
|+ Parameters
|-
| interfaces || JSON Object with interfaces.
|}
||
<nowiki>{
  "target": "tunnel",
  "action": "update-interfaces",
  "interfaces": {
    "eth1": {"name":"WAN1", "preset": "mobileAggressive", "upstream": 50, "downstream": 100},
    "eth2": {"name":"WAN2", "preset": "mobileAggressive", "upstream": 10, "downstream": 50},
  }
}</nowiki>
}</nowiki>
|-
|-


|
|
=== delete ===
=== update-packetSize ===
Resets the complete tunnel configuration, including interfaces.
Updates the maximum size that UDP packets may carry. Changing this value will cause a tunnel restart.
{| class="wikitable"
|+ Parameters
|-
| value || Packet size value. Required. Valid range: 500 to 1400.
|}
||
||
  <nowiki>{"target": "tunnel",  
  <nowiki>{
   "action": "delete"
  "target": "tunnel",  
   "action": "update-packetSize",
  "value": 1400
}</nowiki>
}</nowiki>
|}
|}


== Interactive Commands ==
== Interactive Commands ==

Revision as of 14:15, 13 October 2022

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 on start-up.

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"}
]

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. 
{"target": "tunnel", 
  "action": "create-interfaces", 
  "interfaces": { 
    "wwan0": "mobile", 
    "eth1": "ethernet"
  } 
}

delete

Resets the complete tunnel configuration, including interfaces. 

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

enable-layer2

Adds a single interface to the tunnel.

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. JSON must be in this format: {"t":"TUNNELNAME", "p":"TUNNELPASSWORD", "s": "SERVER"}

Parameters
data base64 encoded JSON string. 
{"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 in use but are not provided here will be removed.

Parameters
interfaces JSON Object with interfaces. 
{
  "target": "tunnel", 
  "action": "update-interfaces",
  "interfaces": {
    "eth1": {"name":"WAN1", "preset": "mobileAggressive", "upstream": 50, "downstream": 100},
    "eth2": {"name":"WAN2", "preset": "mobileAggressive", "upstream": 10, "downstream": 50},
  }
}

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
}


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 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/"
}
Retrieved from "https://wiki.bondix.dev/index.php?title=Client_Configuration&oldid=86"