Server: Difference between revisions

From Bondix Wiki
No edit summary
No edit summary
Line 1: Line 1:
The Bondix SANE Server is a universal Linux service for x86_64 architectures (other architectures available on request). Thanks to static compilation, there are no special host operating system requirements such as specific LibC versions - the only requirement is kernel support for virtual tun/tap network interfaces.
[[Category:Server]]
[[Category:Manual]]
[[Main_Page|Start]] > [[Main_Page#Marketing_Material|Marketing Material]] > [[Manuals|Manuals]] > [[Manuals/Sane-server-v01|S.A.NE Server v01]]


== Requirements ==
== Preparations ==
To install the Bondix S.A.NE Server, you will need a few minutes of stable Internet, a web browser, and possibly some coffee or tea.


=== Resources ===
=== Supported Browsers ===
The resource requirement is based on the peak total throughput of the installation and the number of simultaneous tunnel connections. This formula can be used as a rule of thumb for the required memory:
The following browsers have been tested to function properly with Bondix S.A.NE:
Memory requirement (megabytes) = Bandwidth(Mbit) / 2 + TunnelCount * 5
* Google Chrome
* MS Edge
* Mozilla Firefox


Example: An installation of 100 tunnels should guarantee 50 Mbit/sec for each instance at full load. The peak bandwidth would thus be 100 * 50 Mbit = 5000 Mbit/sec. Using the above formula, this results in a memory requirement of approx. 3 gigabytes.
=== Installing the Linux VM (Ubuntu 20.4) ===
In addition to memory, the number of CPU cores is also critical. Bondix SANE Server distributes incoming tunnels to different CPU cores for load balancing. While the maximum throughput per CPU core depends on the hardware used, 500 - 1000 Mbit can be taken as a conservative estimate.
⚠️ '''For the installation, you will need root rights.''' ⚠️


Note: These assumptions for storage do not take into account requirements for the host operating system, other services, and the like. Requirements for storage space are negligible.
Set your firewalls to the following settings:
<nowiki>S.A.NE server port shares
- TCP: 443, 80
- UDP: 44343
SSH (Optional): 22</nowiki>


=== Public Ports ===
Make sure your server has a public static IP and is reachable from the Internet.
Bondix SANE Server requires a publicly accessible TCP port (default 443, but freely selectable) and at least one UDP port - the number of UDP ports depends on the environments configured.


== Installation ==
Execute the following script in the terminal window of your server to download the latest version of the S.A.NE server:
...
<nowiki>wget https://releases.bondix.dev/endpoint/install-bondix-server.sh</nowiki>


== Configuration ==
<gallery widths="500" heights="300">
The default installation script comes with a default configuration that enables the webinterface, where environment and tunnel configuration can be done. However, configuration is very versatile and can be customized.  
File:1-linux-install.png
</gallery>


==== JSON Configuration ====
To start the installation, enter the following commands:
Configuration is done using JSON commands. These can either be sent via a raw TCP socket (localhost:5112), or written to a configuration file (in a json-array) that is parsed on start-up.
<nowiki>chmod a+x install-bondix-server.sh
sudo ./install-bondix-server.sh</nowiki>


By default, S.A.NE server checks for the existence of a configuration file in its installation directory (e.g. <code>/opt/bondix/server/saneserver.json</code>) and at <code>/etc/saneserver.json</code>. If you want SANE server to load a configuration from a different location, you can specify it using a command line parameter.
Confirm all the following prompts with the Enter key for a standard installation.


==== Configuration Commands ====
<gallery widths="500" heights="300">
For a complete reference list of available commands, see [[Server Configuration]].  
File:2-linux-install.png
</gallery>


== Environments ==
After completing the installation, you can reach S.A.NE server web interface at the IP address shown. Log in with the username “admin” and the password previously generated during installation.
Environments are a collection of tunnels that share certain resources, like packet buffers, thread, UDP port and virtual network interfaces.   
 
[[File:Server Environment Settings.png|center|frame]]
<gallery widths="300" heights="200">
File:3-login.png
</gallery>
 
=== Updating the Linux VM ===
If you want to update your Bondix S.A.NE server version, the easiest way to do so is to first delete the installation on your Linux VM. For that, you'll need this command:
 
<nowiki>rm install-bondix-server.sh*</nowiki>
 
After that, just repeat the installation process as described above.
 
== Bondix S.A.NE Server ==
=== Licensing ===
If your server is not already licensed, you first need to activate the S.A.NE Server Tunnel license under the menu item “Licensing”.
 
<gallery widths="500" heights="300" perrow="2">
File:4-nolicense.png
File:5-activate-license.png
</gallery>
 
Enter the S.A.NE license key here, as well as a valid email address to which the license key is bound. You can also enter a name for the server instance here. Then press “Submit”.
 
<gallery widths="300" heights="200">
File:6-license-key.png
</gallery>
 
After the successful activation, the Licensing overview will display the number of licensed tunnels as well as the expiry date of your active tunnel subscriptions with the respective expiry date and the maximum number of active server instances possible under this license number.
 
<gallery widths="500" heights="300">
File:7-successful-activation.png
</gallery>
 
You can add further additional tunnels/server instances at any time under the item “Activate License”.
 
=== Administration ===
==== Overview ====
This is the web interface of a licensed S.ANE server.
 
<gallery widths="500" heights="500">
File:8-overview.png
</gallery>
 
==== Bondix S.A.NE Tunnels ====
To connect a S.A.NE-compatible router to a S.A.NE server, you first need to create a tunnel for this respective router. Only then does the server know that there will be a new router to receive data from and send data to.
 
===== Create a new S.A.NE tunnel =====
Navigate to the menu item “Tunnel”. Select the tunnel environment for which you want to create the tunnel by clicking the corresponding tab; the default is set to “env0”. Then, assign a unique tunnel name and press “Create”.
 
⚠️ '''The tunnel name must not contain any spaces.''' ⚠️
 
<gallery widths="500" heights="300" perrow="2">
File:9-add-tunnel.png
File:10-add-tunnel-detail.png
</gallery>
 
You will then automatically be navigated to the settings window of the newly created tunnel. There, set a password for establishing the connection, make sure that “Enabled” is ticked, and then press “Save”.
 
<gallery widths="500" heights="300">
File:11-tunnel-added.png
</gallery>
 
Your tunnel is now displayed under the menu item “Overview”. You can access settings for each tunnel simply by clicking on the tunnel name.
 
<gallery widths="500" heights="300">
File:12-tunnel-overview.png
</gallery>
 
===== Connect a compatible router to a S.A.NE server. =====
Make sure that the latest Bondix S.A.NE client is installed on your router. Go to the settings menu of your router’s S.A.NE client and enter the server’s IP address and the tunnel name and password you created in chapter 3.2.2 in the corresponding fields. Save your entry and then restart the service (Restart Service).
 
<gallery widths="500" heights="500">
File:13-tunnel-credentials.png
</gallery>
 
The tunnel is now listed in the S.A.NE server’s menu “Overview” including the number of its active connections. Click on the tunnel name to access the tunnel settings and options.
 
<gallery widths="500" heights="300">
File:12-tunnel-overview.png
</gallery>
   
===== Tunnel details and settings =====
====== Functions ======
 
<gallery widths="500" heights="500">
File:14-functions.png
</gallery>


== Running ==
The software can be run in the shell using <code>/opt/bondix/server/saneserver</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"
{| class="wikitable"
! Function !! Effect
|-
| 1 Enabled || Activates (ticked) or deactivates (unticked) the tunnel.
|-
|-
| <code>--daemon</code> || Runs the software as a daemon.
| 2 Revert || Undoes any changes that have not yet been saved.
|-
|-
| <code>--nopid</code> || Does not attempt to create a pid-file at <code>/var/run/saneserver.pid</code>
| 3 Save || Saves changes.
|-
|-
| <code>--listflags</code> || Lists available feature flags
| 4 Channel || Provides an overview of channels currently connected.
|}
 
''' Function “Override Client Settings” '''
If you activate this on server side, local tunnel presets and WAN priority settings of the connected router are overwritten or reset by the server’s S.A.NE. You will need to restart the tunnel.
 
<gallery widths="500" heights="300">
File:15-override-client-settings.png
</gallery>
 
====== Actions ======
 
<gallery widths="500" heights="500">
File:16-actions.png
</gallery>
 
{| class="wikitable"
! Function !! Effect
|-
|-
| <code>--flags <FLAG1> <FLAG2>... </code> || Enables the specified flag(s). Multiple flags are separated using space.
| 1 Restart tunnel || Allows the tunnel connection to be disconnected briefly and then reconnected. This is needed for some changes to take effect.
|-
|-
| <code></path/to/filename.json></code> || JSON configuration file that should be used
| 2 Open Monitor || Displays a graphical overview of the connections of the router.
|-
| 3 Expert Settings || Opens the server-side Bondix S.A.NE web monitor for diagnostic purposes.
|-
| 4 Delete Tunnel || Deletes a tunnel permanently without the possibility to restore it.
|}
|}


== Feature Flags ==
===== Tunnel Environments =====
Feature flags are switches that enable certain features that are otherwise unavailable. These features are usually experimental and should be used with caution.
In Bondix S.A.NE, a tunnel environment is a pool of resources used by a group of tunnels. This includes packet cache, CPU core, a UDP listener, and a virtual network interface.
 
====== Add Environments ======
During the S.A.NE server installation, the software automatically creates a default environment with the name “env0”. You can create and add further environments via the menu item “Add Environment”.
 
<gallery widths="500" heights="300">
File:17-tunnel-environments.png
</gallery>
 
====== UDP Listener settings ======
For common scenarios, select “0.0.0.0 (Any Interface)” for the UDP Listener IP.
 
⚠️ '''Each environment must be assigned its own unique UDP Listener Port. This port must not be used elsewhere in the system, and it must not be blocked by a firewall.''' ⚠️
 
====== Virtual Interface settings ======
Leave the Virtual Interface Name blank to automatically generate a name for it.
 
⚠️ '''The Virtual Interface Name and the Virtual Network (CIDR) assigned to the Tunnel Environment must also be unique, not to be used in any other environment.''' ⚠️
 
====== Outgoing settings ======
The Outgoing Interface describes where you want to route your data traffic. Optionally, you can enter a specific Outgoing IP address.
 
====== Activate Tunnel-to-Tunnel Communication ======
The option “Disable traffic among routers” is activated by default due to Bondix S.A.NE providing multi-tenancy support. This feature prevents routers assigned to a Tunnel Environment from communicating with each other. If you deactivate “Disable traffic among routers”, routers in the same environment can interact. You can adjust this setting separately for each environment.
 
== Troubleshooting ==
Sometimes, your Bondix S.A.NE server will not work as expected. If that happens, you may find possible solutions in this section.
{| class="wikitable"
{| class="wikitable"
! Problem !! Solution
|-
|-
| <s>useMMSG</s>|| 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.
| ? || Re-install Server (Update)
|-
|-
| <s>bondingProxy</s>|| Enables the TCP [[Bonding Proxy]].
| ? || Remove Server
|-
| ? || Start Bondix Service
|-
| ? || Stop Bondix Service
|-
| ? || Server update notification in Web interface update via console
|}
|}


== SNMP ==
== Bondix Server Log ==
The server comes with a net-snmp extension that implements the provided MIB. In order to use it with netsnmp, add this to your <code>/etc/snmp/snmpd.conf</code>:
This is an exemplary overview of a server’s current log messages:
pass_persist .1.3.6.1.3.45265 /opt/bondix/server/bxsnmp
 
<gallery widths="500" heights="300">
File:18-server-log.png
</gallery>
 
== Download ==
Download this manual as a PDF file from here: [https://bondixintelligence.sharepoint.com/:b:/s/BondixIntelligenceCoreTeam/ETzIJiPTEnFNkHPDsR_Fa54BUefrowdEGuaKzl_QR2PH2w?e=iTGhiP bondix_server_manual_v1_202202.pdf]

Revision as of 14:11, 7 June 2023

Start > Marketing Material > Manuals > S.A.NE Server v01

Preparations

To install the Bondix S.A.NE Server, you will need a few minutes of stable Internet, a web browser, and possibly some coffee or tea.

Supported Browsers

The following browsers have been tested to function properly with Bondix S.A.NE:

  • Google Chrome
  • MS Edge
  • Mozilla Firefox

Installing the Linux VM (Ubuntu 20.4)

⚠️ For the installation, you will need root rights. ⚠️

Set your firewalls to the following settings: 

S.A.NE server port shares 
- TCP: 443, 80 
- UDP: 44343 
SSH (Optional): 22

Make sure your server has a public static IP and is reachable from the Internet.

Execute the following script in the terminal window of your server to download the latest version of the S.A.NE server: 

wget https://releases.bondix.dev/endpoint/install-bondix-server.sh
  • 1-linux-install.png

To start the installation, enter the following commands: 

chmod a+x install-bondix-server.sh 
sudo ./install-bondix-server.sh

Confirm all the following prompts with the Enter key for a standard installation.

  • 2-linux-install.png

After completing the installation, you can reach S.A.NE server web interface at the IP address shown. Log in with the username “admin” and the password previously generated during installation.

  • 3-login.png

Updating the Linux VM

If you want to update your Bondix S.A.NE server version, the easiest way to do so is to first delete the installation on your Linux VM. For that, you'll need this command: 

rm install-bondix-server.sh*

After that, just repeat the installation process as described above.

Bondix S.A.NE Server

Licensing

If your server is not already licensed, you first need to activate the S.A.NE Server Tunnel license under the menu item “Licensing”.

  • 4-nolicense.png
  • 5-activate-license.png

  Enter the S.A.NE license key here, as well as a valid email address to which the license key is bound. You can also enter a name for the server instance here. Then press “Submit”.

  • 6-license-key.png

After the successful activation, the Licensing overview will display the number of licensed tunnels as well as the expiry date of your active tunnel subscriptions with the respective expiry date and the maximum number of active server instances possible under this license number.

  • 7-successful-activation.png

You can add further additional tunnels/server instances at any time under the item “Activate License”.  

Administration

Overview

This is the web interface of a licensed S.ANE server.

  • 8-overview.png

 

Bondix S.A.NE Tunnels

To connect a S.A.NE-compatible router to a S.A.NE server, you first need to create a tunnel for this respective router. Only then does the server know that there will be a new router to receive data from and send data to.

Create a new S.A.NE tunnel

Navigate to the menu item “Tunnel”. Select the tunnel environment for which you want to create the tunnel by clicking the corresponding tab; the default is set to “env0”. Then, assign a unique tunnel name and press “Create”.

⚠️ The tunnel name must not contain any spaces. ⚠️

  • 9-add-tunnel.png
  • 10-add-tunnel-detail.png

You will then automatically be navigated to the settings window of the newly created tunnel. There, set a password for establishing the connection, make sure that “Enabled” is ticked, and then press “Save”.

  • 11-tunnel-added.png

Your tunnel is now displayed under the menu item “Overview”. You can access settings for each tunnel simply by clicking on the tunnel name.

  • 12-tunnel-overview.png

 

Connect a compatible router to a S.A.NE server.

Make sure that the latest Bondix S.A.NE client is installed on your router. Go to the settings menu of your router’s S.A.NE client and enter the server’s IP address and the tunnel name and password you created in chapter 3.2.2 in the corresponding fields. Save your entry and then restart the service (Restart Service).

  • 13-tunnel-credentials.png

  The tunnel is now listed in the S.A.NE server’s menu “Overview” including the number of its active connections. Click on the tunnel name to access the tunnel settings and options.

  • 12-tunnel-overview.png
Tunnel details and settings
Functions
  • 14-functions.png
Function Effect
1 Enabled Activates (ticked) or deactivates (unticked) the tunnel.
2 Revert Undoes any changes that have not yet been saved.
3 Save Saves changes.
4 Channel Provides an overview of channels currently connected.

  Function “Override Client Settings” If you activate this on server side, local tunnel presets and WAN priority settings of the connected router are overwritten or reset by the server’s S.A.NE. You will need to restart the tunnel.

  • 15-override-client-settings.png
Actions
  • 16-actions.png
Function Effect
1 Restart tunnel Allows the tunnel connection to be disconnected briefly and then reconnected. This is needed for some changes to take effect.
2 Open Monitor Displays a graphical overview of the connections of the router.
3 Expert Settings Opens the server-side Bondix S.A.NE web monitor for diagnostic purposes.
4 Delete Tunnel Deletes a tunnel permanently without the possibility to restore it.
Tunnel Environments

In Bondix S.A.NE, a tunnel environment is a pool of resources used by a group of tunnels. This includes packet cache, CPU core, a UDP listener, and a virtual network interface.

Add Environments

During the S.A.NE server installation, the software automatically creates a default environment with the name “env0”. You can create and add further environments via the menu item “Add Environment”.

  • 17-tunnel-environments.png
UDP Listener settings

For common scenarios, select “0.0.0.0 (Any Interface)” for the UDP Listener IP.

⚠️ Each environment must be assigned its own unique UDP Listener Port. This port must not be used elsewhere in the system, and it must not be blocked by a firewall. ⚠️

Virtual Interface settings

Leave the Virtual Interface Name blank to automatically generate a name for it.

⚠️ The Virtual Interface Name and the Virtual Network (CIDR) assigned to the Tunnel Environment must also be unique, not to be used in any other environment. ⚠️

Outgoing settings

The Outgoing Interface describes where you want to route your data traffic. Optionally, you can enter a specific Outgoing IP address.

Activate Tunnel-to-Tunnel Communication

The option “Disable traffic among routers” is activated by default due to Bondix S.A.NE providing multi-tenancy support. This feature prevents routers assigned to a Tunnel Environment from communicating with each other. If you deactivate “Disable traffic among routers”, routers in the same environment can interact. You can adjust this setting separately for each environment.

Troubleshooting

Sometimes, your Bondix S.A.NE server will not work as expected. If that happens, you may find possible solutions in this section.

Problem Solution
? Re-install Server (Update)
? Remove Server
? Start Bondix Service
? Stop Bondix Service
? Server update notification in Web interface update via console

Bondix Server Log

This is an exemplary overview of a server’s current log messages:

  • 18-server-log.png

Download

Download this manual as a PDF file from here: bondix_server_manual_v1_202202.pdf

Retrieved from "https://wiki.bondix.dev/index.php?title=Server&oldid=516"