Install swXtchBridge

  • Updated on Oct 21, 2025
  • Published on Apr 10, 2024
  • 11 minute(s) read
Prev Next

WHAT TO EXPECT

In this article, users will learn how to install SwXtchBridge and how to switch it to high performance capability if a user requires higher throughput for 10+ GB of traffic.

Before You Start

Review the SwXtchBridge System Requirements to understand the prerequisites for installing swXtchBridge on your virtual machine.

NOTE

There are different cloudSwXtch topologies users can deploy depending on the number of NICs they have. For more information on single-NIC, 2-NIC, 3-NIC configurations, see swXtchBridge Topologies.

Pre-Installation

The following steps must be done prior to installing the swXtchBridge.

STEP ONE: Update Currently Installed OS Packages

  1. Please update all of your currently installed OS packages

    1. RHEL

      dnf upgrade

    2. Ubuntu

      apt update && apt upgrade

  2. Reboot VM.

  3. Install Docker.  For swXtchBridge, users should install the latest version of Docker Engine for their VM. For quick installation guides, see our How to Install Docker on RHEL/Ubuntu.

STEP TWO: Gather Information from the swXtchBridge NICs

You will be asked what interfaces you want to use for control, data, and user, so you can see the names executing:

  1. Run the following command on the VM or the on-premises machine of your Data NIC:

    ip a

  2. Look for the names and the subnets to be sure you select the proper NIC when asked. You can also put the arguments to install in a non-interactive way.  Review swXtchBridge Topologies to ensure you understand what NIC’s should be used for each option given during the installation process.  

STEP THREE: Review Firewall Exceptions for RHEL [Optional]

The swXtchBridge installer script will automatically open the following ports:

sudo firewall-cmd --add-port=80/tcp --permanent
sudo firewall-cmd --add-port=9999/udp --permanent
sudo firewall-cmd --add-protocol=igmp --permanent

To open up additional ports for producing/consuming multicast traffic, use the following command:

sudo firewall-cmd --add-port=<port>/udp --permanent
sudo systemctl restart firewalld

NOTE

In some rare cases, it might be helpful to disable the firewall if the swXtchBridge installation fails, for troubleshooting purposes.

swXtchBridge Installation

Since swXtchBridge installs via Docker, users can forgo the traditional steps of downloading dependencies. Containers allow users to support any system that meets the basic system requirements. It will only work if the cloudSwXtch instance is up and running and the bridge host has network connectivity to the cloudSwXtch instance.

Reminder

Before you start, review the swXtchBridge System Requirements for Docker-specific RHEL and Ubuntu system requirements.

Install steps

Follow the next steps:

  1. Open a shell console on the machine that you intend to use as the bridge host. Make sure it has connectivity to the control plane network of the cloudSwXtch.

    1. Ping the cloudSwXtch using your instance name or IP.

      ping <cloudSwXtch-instance-IP or instance-name>

      1. If the ping fails to find the cloudSwXtch instance by name, try pinging the IP address of the cloudSwXtch instance. If the IP works, then use the IP address in place of the name in all future commands. This can happen if the default DNS settings are not configured for the Virtual Network.

  2. Run the following command, replacing <cloudSwXtch-IP> with the cloudSwXtch’s IP address.  Note that if this is a upgrade and you have configuration you want saved use the persist argument (--persist).  

    curl http://<swxtch-ip>/swx/services/install/swx-bridge-install.sh -o swx-bridge-install.sh; chmod +x swx-bridge-install.sh; ./swx-bridge-install.sh --auto_deps

Note:  The installer will attempt to pick the correct interfaces, to ensure selection of interfaces to be used in the install use the arguments below.  To better understand them refer to swXtchBridge Topologies.

--ctrl_interface

--data_interface

--user_interface

  1. Confirm that the selected control NIC is the one you would like to use. Select Y to use the currently displayed, or N to change to your desired NIC.  

  2. Next, the installer will ask you to choose your data NIC.  For more information on understanding which NIC to select, see swXtchBridge Topologies.

  3. Next, the installer will ask you to choose your user NIC.  For more information on understanding which NIC to select, see swXtchBridge Topologies.

Optionally, you can use the following arguments to make the installation unattended:

-c, --ctrl_interface <interface name>   manually select control interface
-d, --data_interface <interface name>   manually select data interface
-i, --user_interface <interface name>   manually select user interface
--swxtch_ctrl_ip <ip address>           manually select ctrl ip of the swXtch
--swxtch_data_ip <ip address>           manually select data ip of the swXtch

The installation should be complete. You can continue onto Verify swXtchBridge Installation in swx-top.

Viewing swXtchBridge Container Logs

To view swXtchBridge Container logs, users will need to run the docker logs command. For a complete list of Docker commands, see Helpful Docker Service Commands.

Upgrading your swXtchBridge via Docker

To upgrade the swXtchBridge, you can install the new version and use the following argument:

--persist                               keep persistence folder

Additional arguments for swXtchBridge Installer

$ ./swx-bridge-install.sh -h
2025-08-26 17:05:02.044 ========== swXtch.io Bridge Installer ==========
Usage: ./swx-bridge-install.sh [OPTIONS]
  -u                                      just uninstall swXtch.io bridge (default: no)
  -c, --ctrl_interface <interface name>   manually select control interface
  -d, --data_interface <interface name>   manually select data interface
  -i, --user_interface <interface name>   manually select user interface
  --auto_deps                             automatically install dependencies and setup environment. IT WILL TRIGGER A REBOOT FOR RH/CENTOS/ALMA
  --route_control_to_data                 tunnel control data through the data interface (default: false)
  --override_src_ip                       override the source IP of incoming packets (default: false)
  --high_perf_driver                      high-performance drivers will be installed (if required) as part of the swXtch.io bridge installation
  --persist                               keep persistence folder (default: do not keep it)
  -h | --help                             shows this help

Switching to High Performance Mode

Certain NICs can handle a high-performance version of the swXtchBridge. This should only be used if a user requires higher throughput for 10+ GB of traffic. For a complete list of recommended NICs, see NIC Requirements under swXtchBridge System Requirements.

To install the high-performance drivers, you need to provide the —high_perf_driver argument in the installation line.

curl http://<swxtch-ip>/swx/services/install/swx-bridge-install.sh -o swx-bridge-install.sh; chmod +x swx-bridge-install.sh; ./swx-bridge-install.sh --auto_deps --high_perf_driver

Accessing logs for swXtchBridge

  1. Use the docker ps command to list all the Docker containers currently running on your machine.

    $ docker ps
CONTAINER ID   IMAGE               COMMAND             CREATED      STATUS          PORTS     NAMES
27f64deaac2e   swx-bridge:latest   "./entrypoint.sh"   4 days ago   Up 42 minutes             swx-bridge

  2. Record the Docker name of the swXtchBridge service you would like to see logs for.

  3. Use the docker logs command with the container service name.  Note that at times you may need to use the container id instead of the name.

    1. control

       docker logs swx-bridge -f -n 100

Configuring swXtchBridge Interfaces 

By default, swXtchBridge installation will attempt to resolve the interface that is routable to the cloudSwXtch. However, if a user would like to do this manually, the swXtchBridge can be configured in one of two ways: 

  • For hairpin forwarding on a single interface

  • For bridge in the middle redirection between two interfaces

This section will go into the changes a user would have to make to the swXtchBridge JSON configuration file to apply the above methods.

Where to Find swXtchBridge Configuration Files

The location of the swXtchBridge JSON file is /var/opt/swxtch/swxtch-bridge-cfg.json.

swXtchBridge Configuration JSON Example

{
    "bridgeConfig": {
        "ctrlInterfaceName": "eth0",
        "dataInterfaceName": "e636:00:02.0",
        "userInterfaceName": "e636:00:02.0",
        "nicsConfig": null,
        "swxtchCtrlIp": "10.2.128.10",
        "swxtchCtrlPort": 80,
        "swxtchDataIp": "10.2.192.116",
        "swxtchDataPort": 9999,
        "overwriteSenderIp": null,
        "dataGatewayIp": null,
        "groundToCloudSubscriptions": null,
        "cloudToGroundSubscriptions": [],
        "pollingIntervalMilliseconds": 1000,
        "subscriptionsPollingIntervalMilliseconds": 100,
        "mtuSize": 1500,
        "adaptorsConfig": {},
        "overrideSrcIp": false,
        },
        "xdpModeData": null,
        "xdpModeUser": null,
        "cloudTunIp": null,
        "rpcPort": 10002
    },
    "ha": {
        "producer": false,
        "consumer": false,
        "bufferSizeInPackets": 131072,
        "maxTimeToBufferPacketsMs": 50,
        "protocol": "swxtch"
    },
    "streamSpecs": null
}

Fields in Common Explained

Below are deeper explanations for certain fields in the cloudSwXtch config file: 

  • "ctrlInterfaceName": NIC used for control-plane communication with cloudSwXtch 

  • "dataInterfaceName": NIC used for the data-plane communication with cloudSwXtch. For Bridge 2, the config file uses the ethernet name. For Bridge 3, the config file uses the PCI address.

  • "userInterfaceName": NIC used for multicast ground traffic. For Bridge 2, the config file uses the ethernet name. For Bridge 3, the config file uses the PCI address.

  • "pathId": Please set this to zero. 

  • "groundToCloudSubscriptions": Please leave blank as it is no longer necessary since ground to cloud is done dynamically via IGMP joins from the cloud client.

  • "cloudToGroundSubscriptions": Traffic coming into the cloudSwXtch with these addresses will be forwarded to bridge and then to the userInterface. 

  • "pollingIntervalMilliseconds:" Polling consists on a sync with the cloudSwXtch to exchange MC groups information. 

Using the status API call to get swxtch-bridge JSON file

Alternatively, users can use a /status API call to get the swxtch-bridge.json file. To do this, use the following command replacing the <bridge-ctrl-IP> with the IP address of the bridge:

curl -x GET http://<bridge-ctrl-ip>/status

For a single interface 

bridge-type2_singleinterface(1)

To accomplish a single interface configuration for your swXtchBridge, users will need to specify the same InterfaceName for Ctrl, Data and User in the swxtch-bridge.json file. In the example, each are assigned to eth0. 

        "ctrlInterfaceName": "eth0",
        "dataInterfaceName": "eth0",
        "userInterfaceName": "eth0",

For bridge in the middle of two interfaces

bridge-type2_twointerfaces(1)

Alternatively to the single interface approach, a user can decide to place the swXtchBridge between two interfaces in order to redirect traffic from the user interface to the data interface. In the example below, the ctrlInterfaceName and the dataInterfaceName are the same (eth1) while the userInterfaceName differs (eth0). 

        "ctrlInterfaceName": "eth1",
        "dataInterfaceName": "eth1",
        "userInterfaceName": "eth0",

Using swXtchBridge cloud to ground API to Join/Leave 

swXtchBridge has the capability to do join and leaves from ground to cloud via an HTTP endpoint on the bridge. This will enable the forwarding of multicast traffic from cloud to ground. 

To Join:

curl -X POST http://<BRIDGE_CTRL_IP>/addCloudToGround -d '{"MulticastGroups":["239.239.239.99:9000"],"UpdateConfigFile":false}'

To Leave: 

curl -X POST http://<BRIDGE_CTRL_IP>/removeCloudToGround -d '{"MulticastGroups":["239.239.239.99:9000"],"UpdateConfigFile":false}'

Note: A user can set the UpdateConfigFile to "true" in order to make their configuration permanent. This means that the changes to swXtchBridge will persist between restarts. 

Configuring swXtchBridge Static Subscriptions 

The cloud to ground and ground to cloud flows are static based on entry into a json file. In order to do this, modify the bridge JSON configuration file and add the static multicast groups for either groundToCloudSubscriptions or cloudToGroundSubscriptions.  This can also be accomplished using .  See wXcked Topology Graph Component Panel.
Modify the JSON array attribute for "cloudToGroundSubscriptions" or "groundToCloudSubscriptions" and add the appropriate multicast groups from either option.

{
    "bridgeConfig": {
        "ctrlInterfaceName": "eth0",
        "dataInterfaceName": "eth1",
        "userInterfaceName": "eth0",
        "swxtchCtrlIp": "10.0.0.1",
        "swxtchCtrlPort": 80,
        "swxtchDataIp": "10.0.1.1",
        "swxtchDataPort": 9999,
        "pathId": 0,
        "groundToCloudSubscriptions": [    
        "226.0.23.182:13000",
        "226.0.23.183:13000",
        "226.0.23.184:13000",
        "226.0.23.185:13000"],
        "cloudToGroundSubscriptions": [
        "225.0.23.182:12000",
        "225.0.23.183:12000",
        "225.0.23.184:12000",
        "225.0.23.185:12000"],
        "pollingIntervalMilliseconds": 1000
    }
}

After modifying the configuration file, restart the swXtchBridge service see swXtchBridge Commands.

Using a specific gateway address for swXtchBridge

By default, swXtchBridge will resolve the data gateway MAC address by arping the first IP address of the subnet for the data interface. However, if the gateway IP address is not there, then the dataGatewayIP field can be added into the configuration file. This will force the Bridge to resolve the gateway MAC address by using the IP address specified. In the example below, the user inserted their own data gateway IP address. 

"dataGatewayIp": "192.168.1.2",


swXtchBridge Commands

After deploying your swXtchBridge, a user can execute commands to stop, start, and restart their instance. They can execute these commands in the command window of their swXtchBridge.

First, you must find the Docker name or ID.

$ docker ps
CONTAINER ID   IMAGE               COMMAND             CREATED       STATUS       PORTS     NAMES
e4dfedcc27d8   swx-bridge:latest   "./entrypoint.sh"   2 hours ago   Up 2 hours             swx-bridge

STOP

docker stop swx-bridge

START

docker start swx-bridge

RESTART

docker restart swx-bridge

Uninstalling swXtchBridge

Using Docker

To uninstall the swXtchBridge via Docker, users will need to follow these steps:

  1. Get the swXtchBridge docker container ID.

    $ docker ps
CONTAINER ID   IMAGE           COMMAND             CREATED          STATUS                          PORTS     NAMES
f8fb84bbaf53   swxtch-bridge   "./entrypoint.sh"   14 minutes ago   Restarting (2) 37 seconds ago             swx-bridge

  2. Stop the Docker service.

  3. Remove the container from the machine.

For a complete list, see Helpful Docker Service Commands under cloudSwXtch How To’s.

Using the installer

Simply run the installation script with the argument -u. If you already have the installation script, execute it like:

./swx-bridge-install.sh -u

If you don’t have the script, download it and execute it:

curl http://<swxtch-ip>/swx/services/install/swx-bridge-install.sh -o swx-bridge-install.sh; chmod +x swx-bridge-install.sh; ./swx-bridge-install.sh -u