Installing groundSwXtch

Pre-Installation Step: Create the environment

What is needed:

• For prerequisites, see groundSwXtch System Requirements

• A VM or physical machine running Ubuntu 24.04 (the version swXtch.io tests on).

• The VM needs an internet connection.

• The user must be able to log into the VM or physical machine (each groundSwXtch).

Prerequisites

If Docker is not installed, the installer installs it automatically from get.docker.com. To install Docker manually first, see How to Install Docker on RHEL and Ubuntu.

NOTES

• The installation script also installs all dependencies.

• The groundSwXtches at each site must use IP addresses that are different from those at every other site.

• Multicast addresses must be unique across sites: reusing the same multicast address at more than one site is not currently supported.

STEP ONE: Prepare the installation by updating the OS

1. Update all of the currently installed OS packages

   sudo apt update && sudo apt upgrade -y

2. Reboot VM

   sudo reboot now

STEP TWO: Install groundSwXtch

In this step, users will execute commands in their VMs or hardware devices to manually install a groundSwXtch.

1. Connect to the VM instance or hardware device that will be used as a groundSwXtch.

2. Enter the following commands to download and install the groundSwXtch installer script:

   curl -fL "https://swxrkdistribution.blob.core.windows.net/swxcontainer01/install-groundswxtch.sh?sp=rl&st=2026-05-21T21:40:09Z&se=2027-05-23T05:55:09Z&spr=https&sv=2026-02-06&sr=c&sig=HA9RA9sUQwLBKfePWwB3UhLKGlvtJgoT6z2bCU1Kb6k%3D" -o install-groundswxtch.sh && chmod +x install-groundswxtch.sh

3. Run the installer. Replace <version> with the version to install (for example v1.1.1), or use latest-prod to install the newest production release:

   sudo ./install-groundswxtch.sh install --image-tag groundswxtch:<version>

   1. Optional: choose the WAN and LAN interfaces with --wan-iface <WAN_interface> --lan-iface <LAN_interface>. When omitted, groundSwXtch detects the WAN interface and uses a virtual LAN. These values only apply to the first install; after that, change them in the groundSwXtch User Interface.

Example (same NIC for WAN and LAN):

sudo ./install-groundswxtch.sh install --image-tag groundswxtch:v1.1.1 --lan-iface enp2s0 --wan-iface enp2s0

Configuration and Log files for a groundSwXtch:

• Configuration files can be found in /var/lib/groundswxtch.

• Logs can be viewed using docker logs -f gswx

4. After the installation, run the following command to see if the container is running:

   docker ps

   There should be a line with the name gswx. For example:

   ubuntu@gs-host:~$ docker ps
   CONTAINER ID   IMAGE                       COMMAND            CREATED       STATUS        PORTS     NAMES
   d50428d6b201   groundswxtch:v1.1.1          "groundswxtchd"    5 hours ago   Up 5 hours              gswx
   95d07c68d75e   swx-tools:1.0.0             "sleep infinity"   5 days ago    Up 29 hours             swx-tools
   ubuntu@gs-host:~$
   

Help Arguments

To list all the installer options, run:

sudo ./install-groundswxtch.sh -h

The options most installations use:

swx-tools can be installed using the following commands after installing groundSwXtch:

sudo ./install-groundswxtch.sh swx-tools

swx-tools are used to test the system. Refer to Tools and Testing for more information on the tools provided.

The swx tools run in docker, therefore to access them and run swx commands:

sudo docker exec -it swx-tools bash

STEP THREE: License the groundSwXtch

For more information, see How to license the groundSwXtch.