--- title: "Cloud agnostic cloudSwXtch Install" slug: "cloud-agnostic-cloudswxtch-vm-install" updated: 2026-05-28T15:22:01Z published: 2026-05-28T15:22:01Z canonical: "docs.swxtch.io/cloud-agnostic-cloudswxtch-vm-install" --- > ## Documentation Index > Fetch the complete documentation index at: https://docs.swxtch.io/llms.txt > Use this file to discover all available pages before exploring further. # Cloud agnostic cloudSwXtch Install **WHAT TO EXPECT** **In this article**, users will learn how to install a cloudSwXtch instance on an existing Linux Ubuntu 24.04 virtual machine. This installation procedure can be used on **any** cloud. As with any BYOL deployment, it requires a license file from swXtch.io. For more information about VM prerequisites, please see the [cloudSwXtch System Requirements](/v2/docs/cloudswxtch-prerequisites). ### Pre-Installation Step: Create the environment What is needed: - For Pre-requisites see [cloudSwXtch System Requirements](/v2/docs/cloudswxtch-prerequisites). - 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](/v2/docs/cloudswxtch-prerequisites) page. > [!WARNING] > **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](/v2/docs/install-cloudswxtch-oci-marketplace#step-three-attach-a-secondary-vnic). > > For multicast to work iptables/rules.v4 needs to be altered, refer to steps in [Install cloudSwXtch via OCI Marketplace](/v2/docs/install-cloudswxtch-oci-marketplace#step-three-attach-a-secondary-vnic). > > **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"](/v2/docs/how-to-install-docker-on-rhel-and-ubuntu). > [!TIP] > 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](/v2/docs/cloud-agnostic-cloudswxtch-vm-install#step-two-install-cloudswxtch). ### STEP ONE: Prepare the installation by updating the OS 1. Update all of the currently installed OS packages ```shell apt update && apt upgrade -y ``` 2. Reboot VM ```shell 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 ```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. 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. ```shell 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: ```shell 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: ```shell ubuntu@drs-swx-004-298954:~$ swx-top API key: L3iCRh0x2Z5XH6Kqp7xRTb7ELDT2U56s2dL9jWMFvjs ``` ![](https://cdn.document360.io/84c5db44-f675-4f33-a980-5d3fc63073ca/Images/Documentation/swx-top-validate%20running.png) 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](/v2/docs/using-wxcked-eye-for-cloudswxtch#how-to-access-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**](/v2/docs/how-to-view-cloudswxtch-logs-troubleshooting)**.** #### Help Arguements To get a list of arguements that can be used during the installation use the help command. ```shell 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: ```shell ubuntu@oci-swxtch1:/tmp/swx-swxtch-dev.029b31$ ./swx-install.sh --help Usage: ./swx-install.sh [OPTIONS]  -c, --ctrl_interface   manually select control interface  -d, --data_interface   manually select data interface  --auto_deps                             automatically install dependencies and setup environment  --dpdk_driver                    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                     components to install: swxtch,omni (default), omni, swxtch  --no-bootstrap                          skip automatic admin user creation  --omni                            OMNI address (required for --components swxtch)  --install-token                 install token from OMNI  -h | --help                             shows this help ``` **components arguement** **Without adding the components arguement the cloudSwXtch and OMNI/wXckedEye will be installed. You only really need one OMNI/wXckedEye to display all of your cloudSwXtches. To install just the cloudSwXtch or wXcked Eye add the components arguement to install just one or the other. Note that OMNI is for wXckledEye installation, if just installing the cloudSwXtch then the —omni url needs to be added for the cloudSwXtch to know where the OMNI for authentication as well as wXckedEye user interface exists.** ### STEP THREE: License the cloudSwXtch For more information, see [Licensing a cloudSwXtch](/v2/docs/licensing-cloudswxtch). **NEXT STEPS** **The cloudSwXtch is ready to use**. The next step is to install the xNIC on each client expected to get traffic from the cloudSwXtch, and swXtchBridge if needed. See [Installing xNIC](/v2/docs/xnic-installation) for more information on preparing clients.