Install swXtchBridge

  • Updated on Jun 20, 2025
  • Published on Apr 10, 2024
  • 8 minute(s) read
Prev Next

WHAT TO EXPECT

In this article, users will learn how to install containerized SwXtchBridge via Docker 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 to installing swXtchbridge on your virtual machine.

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.

STEP TWO: Update Ubuntu 20.04 to Kernel 5.15 (Ubuntu ONLY)

If the SwXtchBridge VM is on Ubuntu 20.04, please update to Kernel 5.15. To do this:

  1. Use the following commands:

    sudo apt-get install linux-generic-hwe-20.04
sudo apt update && sudo apt full-upgrade

  2. Reboot your machine. If a user is running an Air-Gapped install, they will need to download and Install the package manually: https://vitux.com/how-to-install-latest-linux-kernel-5-15-on-ubuntu-20-04

  3. Use the following to verify the kernel version is at 5:15:

    uname -r

    The output will read:

    5.15.0-1023

STEP THREE: Gather Information from the swXtchBridge Data NIC (RHEL ONLY)

This step is only required for users running on a RHEL machine.

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

    ip a

  2. Make note of the PCI Address, IP Address, subnetMask, and mac for your swXtchBridge data NIC. This information is required for configuration after installation.

STEP FOUR: 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 swXtchBridge installation fails, for troubleshooting purposes.

Containerized Installation via Docker

By installing the containerized version of the swXtchBridge installer via Docker, users can forgo the traditional steps of downloading dependencies since they will be packaged together. 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.

Prerequisites

Users must install Docker on their RHEL or Ubuntu. Please use the following commands below to properly install Docker for swXtchBridge.

RHEL

  1. Ensure the operating system is RHEL9.

  2. Run the following command to prepare the repositories for the docker install: 

    sudo dnf config-manager --add-repo https://download.docker.com/linux/rhel/docker-ce.repo
cat /etc/yum.repos.d/docker-ce.repo
sudo sed -i 's/$releasever/9/g' /etc/yum.repos.d/docker-ce.repo
cat /etc/yum.repos.d/docker-ce.repo
sudo dnf -y install dnf-plugins-core

  3. Install Docker:

    sudo dnf install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

  4. Run the following commands to enable Docker on your machine: 

    sudo usermod -aG docker $USER
sudo systemctl enable docker
sudo systemctl start docker

Ubuntu

  1. Ensure the operating system is Ubuntu 20.04.

  2. Install Docker: 

    curl https://get.docker.com/ > dockerinstall && chmod 777 dockerinstall && sudo ./dockerinstall

  3. Run the following commands to enable Docker on your machine: 

    sudo usermod -aG docker $USER
sudo systemctl enable docker
sudo systemctl start docker

Running Containerized Install

To run a containerized install via Docker, do the following:

  1. Open a bash console on any machine that is on the same control plane network as the cloudSwXtch that you intend to use as the bridge host.

  2. 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, they use the IP address in place of the name in all future commands. This can happen if the default DNS settings are changed for the Virtual Network.

  3. Run the following command with the --docker argument, replacing <cloudSwXtch-IP> with the cloudSwXtch’s IP address, the <Data-NIC> with the Data Interface IP and the <User-NIC> with the Multicast Interface IP.   If high performance capability  if a user requires higher throughput for 10+ GB of traffic amend the command below with a  --high_perf_driver arguement.  For more information see Switching to High Performance Mode.

    sudo sh -c "curl -s http://<cloudSwXtch-IP>/services/install/swxtch-bridge-install.sh | bash -s -- -d <Data-NIC> -i <User-NIC> --docker"

    Example: 

    sudo sh -c "curl -s http://172.41.128.25/services/install/swxtch-bridge-install.sh | bash -s -- -d eth1 -i eth1 --docker"

    swXtchBridge Topologies

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

  4. Confirm that the selected control NIC is the one you would like to us.

  5. If not, click No to manually select one.

Installation is now complete. You can continue onto Verify swXtchBridge Installation in swXtch-top.

Viewing swXtchBridge Container Logs

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

Upgrading your swXtchBridge via Docker

Before You Start - Save Adaptors and Connections Information

  1. Go to wXcked Eye Topology Graph.

  2. Select the swXtchBridge component.

  3. Record the information under the Adaptors and Connections sections. These configurations will not save when updating and will need to be re-added after reinstall.  

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

  1. Get the swXtchBridge docker container ID for both the control and data.

  2. Stop the docker service.

  3. Remove both containers from the machine.

  4. Reinstall the cloudSwXtch using the command in Step 3 of Containerized Installation via Docker.

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

Additional Arguments for swXtchBridge Installer

$ sudo ./swxtch-bridge-install.sh --help
========== swXtch.io Bridge Installer ==========
2025-01-02 11:56:19.230 *** Logging to: 'bridge-install.log' ***
2025-01-02 11:56:19.265 Linux Distribution: almalinux (version: '9.5'; major version: '9').
2025-01-02 11:56:19.279 Arguments (1): --help
Usage: ./swxtch-bridge-install.sh [OPTIONS]
  -u                              just uninstall the swXtch.io bridge (default:no)
  -c <nic>                        manually select nic for control interface
  -d <nic>                        manually select nic for data interface
  -i <nic>                        manually select nic for user interface
  --airgap                        airgap mode: do not try to update nor install dependencies from the internet
                                  (update your system and install the required OS packages manually, before installing)
  --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
  --force_swx_ctrl_to_public_ip   use swxtch control interface public ip (if available) instead of default. (avoiding user interaction)
  --force_swx_data_to_public_ip   use swxtch data interface public ip (if available) instead of default. (avoiding user interaction)
  --docker                        Runs swXtch.io bridge in a docker container
  -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 for a user’s bare metal NICs, it is recommended that users first install the swXtchBridge following the Installation instructions above. Then, a user should re-install the swXtchBridge on their VM with the additional high-perf-driver argument. Verify swXtchBridge installation in swXtch-top

Verify swXtchBridge installation was a success by navigating to swXtch-top on your cloudSwXtch instance. There, you should see the new Bridge virtual machine listed under the Components view.

swxtch-bridge3-after_install_swxtch-top_validation

Accessing logs for swXtchBridge

Containerized Install

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

    ubuntu@ip-172-41-128-232:~$ docker ps
CONTAINER ID   IMAGE           COMMAND             CREATED          STATUS                          PORTS     NAMES
f8fb84bbaf53   swxtch-bridge   "./entrypoint.sh"   14 minutes ago   Restarting (2) 37 seconds ago             swxtch-bridge-control-1

  2. Record the docker name and id 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 swxtch-bridge-ctrl-1 -f -n 100

Configuring swXtchBridge

There may be some scenarios that require special configuration for the swXtchBridge. For more information, see swXtchBridge under Configuring cloudSwXtch.

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.

ubuntu@ip-172-41-128-232:~$ docker ps
CONTAINER ID   IMAGE           COMMAND             CREATED          STATUS                          PORTS     NAMES
f8fb84bbaf53   swxtch-bridge   "./entrypoint.sh"   14 minutes ago   Restarting (2) 37 seconds ago             swxtch-bridge-control-1

STOP


docker stop swxtch-bridge-control-1

START

docker start swxtch-bridge-control-1

RESTART

docker restart swxtch-bridge-control-1

Uninstalling swXtchBridge

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

  1. Get the swXtchBridge docker container ID for both the control and data. 

    ubuntu@ip-172-41-128-232:~$ docker ps
CONTAINER ID   IMAGE           COMMAND             CREATED          STATUS                          PORTS     NAMES
f8fb84bbaf53   swxtch-bridge   "./entrypoint.sh"   14 minutes ago   Restarting (2) 37 seconds ago             swxtch-bridge-control-1

  2. Stop the docker service.

  3. Remove both containers from the machine.

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