Cloud agnostic cloudSwXtch Install

Pre-Installation Step: Create the environment

What is needed:

• For Pre-requisites see cloudSwXtch System Requirements.

• VM must be Ubuntu 24.04

• The VM needs an internet connection

• The user must be able to log into the VM using SSH

All the prerequisites are described in more detail in the cloudSwXtch System Requirements page.

Cloud Specifics for OCI

When creating the VM you MUST select “Hardware-assisted (SR-IOV) networking” in the “Advanced” section in the “Networking” tab.  Note that sometimes when this is selected it still sets it ot Paravirtualized networking.  If this happens then stop the Instance in OCI, select Edit, go to Advanced Options and select “Hardware-assisted (SR-IOV) networking.  Save and restart Instance and validate it set properly.

For the datanic the netplan needs to be added to set the IP and MAC adderss, refer to steps in Install cloudSwXtch via OCI Marketplace.

For multicast to work iptables/rules.v4 needs to be altered, refer to steps in Install cloudSwXtch via OCI Marketplace.

Cloud Specifics for GCP

A cloudSwXtch instance can’t have both NICs on the same VPC due to  a GCP limitation. Two subnets, each on different VPC network is needed. The subnets can be peered (single-subnet operation; 1 NIC on each agent) or not (higher performance; 2 NICs on each agent)

Prerequisites

Users must install and enable Docker on their Ubuntu VM. Please see  "How to Install Docker on RHEL and Ubuntu".

NOTE

The installation script can also install all dependencies, including Docker, if the argument  --auto_deps is used in the swx-install.sh line. See the STEP TWO.

STEP ONE: Prepare the installation by updating the OS

1. Update all of the currently installed OS packages

   apt update && apt upgrade -y

2. Reboot VM

   sudo reboot now

STEP TWO: Install cloudSwXtch

In this step, users will execute commands in their VMs to manually install a cloudSwXtch instance.

1. Connect to the VM instance that will be used as a cloudSwXtch.

2. Enter the following commands to download the cloudSwXtch installer script:

   1. The recommended method will install with dependencies but without persisting configuration data:

      Shell

      token="si=RDONLY&spr=https&sv=2021-06-08&sr=c&sig=xyPF7SyI1cagUAEIZViqCHz7RroFTy2Fkltn2wwvMzc%3D"
      ver="v4.2.1"
      curl -X GET -H "x-ms-date: $(date -u)"  "https://sdmcdevstorage.blob.core.windows.net/imagebuilder/swx-swxtch-${ver}.tar.gz?$token" -o /tmp/swx-swxtch-${ver}.tar.gz 
      tar -xvf /tmp/swx-swxtch-${ver}.tar.gz -C /tmp; /tmp/swx-swxtch-${ver}/swx-install.sh --auto_deps --persist --components swxtch --omni 10.0.148.55
      

      1. If the dependencies are already in place, the --auto_deps can be omitted

      2. If persistent configuration data is needed, --persist should be added to the last line.    

3. Upon success, the system may automatically reboot.  Additionally note at the end of the install the following message will display to let the Installer know where to obtain the admin-api-key in order to access swx-top.

   
   2026-04-27 14:33:03.426 [INFO] ============= Auto-bootstrap: creating admin user =================
   2026-04-27 14:33:03.592 [INFO] Admin API key written to /var/opt/swxtch/install-keys/admin-api-key
   

4. The system will generate a admin user with a password of “changeme”.  

5. Obtain the apiKey:

   sudo cat /var/opt/swxtch/install-keys/admin-api-key
   

6. Run swx-top to add the api key for authentication and to validate that the cloudSwXtch is running using the command below and then pasting in the key provided by step 5 above.   Checki that the status is OK:

   ubuntu@drs-swx-004-298954:~$ swx-top
   API key: L3iCRh0x2Z5XH6Kqp7xRTb7ELDT2U56s2dL9jWMFvjs
   

   

7. Note that if the cloudSwXtch does not display in swx-top then go to the wXckedEye user interface and add the swxtch to the list of swxtches in wXckedEye to do this see Using wXcked Eye.

   Where to find configuration and log files for a cloudSwXtch.

   Configuration files can be found in /var/opt/swxtch.

   Logs files can be found at /var/log/swxtch.  For more information on logging see How to View cloudSwXtch and swXtchBridge Logs.

   Help Arguements

   To get a list of arguements that can be used during the installation use the help command.

    tar -xvf /tmp/swx-swxtch-${ver}.tar.gz -C /tmp; /tmp/swx-swxtch-${ver}/swx-install.sh --help
   

A list of installation arguements will display as shown below:

ubuntu@oci-swxtch1:/tmp/swx-swxtch-dev.029b31$ ./swx-install.sh --help
Usage: ./swx-install.sh [OPTIONS]
  -c, --ctrl_interface <interface name>   manually select control interface
  -d, --data_interface <interface name>   manually select data interface
  --auto_deps                             automatically install dependencies and setup environment
  --dpdk_driver <mode>                    DPDK driver mode (hardware|igb_uio|af_packet)
  --install_igb_uio                       install igb_uio driver and its required dependencies
  --persist                               keep persistence folder (default: do not keep it)
  --components <list>                     components to install: swxtch,omni (default), omni, swxtch
  --no-bootstrap                          skip automatic admin user creation
  --omni <url>                            OMNI address (required for --components swxtch)
  --install-token <token>                 install token from OMNI
  -h | --help                             shows this help

STEP THREE: License the cloudSwXtch

For more information, see Licensing a cloudSwXtch.