WHAT TO EXPECT
The xNIC is a lightweight service that must be installed on every VM sending or receiving multicast traffic to and from a cloudSwXtch network. An xNIC should not be installed on a cloudSwXtch or cloudSwXtch Bridge VM.
In this article, users will learn how to install the xNIC software on Linux systems.
Installing xNIC for Linux
BEFORE STARTING
Review the xNIC System requirements page.
Network Acceleration
If using Azure and plan to use xNIC Type 3, the data-subnet NIC must have the "Network Acceleration" feature enabled.
Before installation
Verify network connectivity to the cloudSwXtch instance by "pinging" the cloudSwXtch.
ping <cloudSwXtch-instance-name or cloudSwXch-ctrl-IP>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 <switch-instance-name> in all further commands. This can happen if the DNS settings are not configured for the virtual network.
If the ping command still fails using the IP, the VM may not have a direct connection to the cloudSwXtch and can potentially fail trying to download the installation script. Check the firewall rules and the security groups on the cloud.
The installer will install all dependencies. To know the dependencies, see How to determine xNIC dependencies.
Running the Install Script
To make installation easy, the xNIC is installed from the cloudSwXtch instance via a one-time set of shell commands. The xNIC is matched to the attached cloudSwXtch instance and should be reinstalled if the cloudSwXtch version changes.
To run the install
Open a terminal on the VM where the xNIC should be installed, and run the following commands, which will download the installation script, change its permissions, and then execute it:
wget http://<cloudSwXtch-ctrl-ip>/swx/services/install/swx-xnic-install.sh;
chmod +x swx-xnic-install.sh;
./swx-xnic-install.shThe installer script will automatically open UDP ports 10800 and 9999. The cloudSwXtch sends UDP packets to these ports as part of normal operation.
A successful install for an xNIC Type 2 is shown below:
$ curl http://172.51.128.132/swx/services/install/swx-xnic-install.sh | bash -s --
% Total % Received % Xferd Average Speed Time Time Time Current
Dload Upload Total Spent Left Speed
100 134k 0 134k 0 0 2394k 0 --:--:-- --:--:-- --:--:-- 2366k
2025-11-13 21:15:53.883 ========== swXtch.io xNIC Installer ==========
2025-11-13 21:15:53.887 [INFO] xNIC Installalation requested.
2025-11-13 21:15:53.890 Install of jq package requested.
2025-11-13 21:15:54.043 jq is already installed.
2025-11-13 21:15:54.071 Success: downloaded 122 bytes.
2025-11-13 21:15:54.087 Linux Distribution: ubuntu (version: '24.04'; major version: '24').
2025-11-13 21:15:54.090 Kernel version: 6.14.0
2025-11-13 21:15:54.093 Tag/Release is : v4.1.0
2025-11-13 21:15:54.097 Arguments (0):
2025-11-13 21:15:54.114 [INFO] No instances of swxtch-xnic detected.
2025-11-13 21:15:54.129 [INFO] No instances of swx-xnic detected.
2025-11-13 21:15:54.133 [INFO] Removing persistence folder.
2025-11-13 21:15:54.137 [INFO] Updating package manager list, please wait...
2025-11-13 21:16:07.982 Install of libpcap-dev package requested.
2025-11-13 21:16:19.334 libpcap-dev installed successfully.
2025-11-13 21:16:19.338 Install of binutils package requested.
2025-11-13 21:16:23.751 binutils installed successfully.
2025-11-13 21:16:23.754 Install of iproute2 package requested.
2025-11-13 21:16:24.102 iproute2 is already installed.
2025-11-13 21:16:24.106 Install of linux-tools-generic package requested.
2025-11-13 21:16:27.709 linux-tools-generic installed successfully.
2025-11-13 21:16:27.713 Install of libatomic1 package requested.
2025-11-13 21:16:30.991 libatomic1 installed successfully.
2025-11-13 21:16:30.995 Install of libnl-route-3-200 package requested.
2025-11-13 21:16:31.345 libnl-route-3-200 is already installed.
2025-11-13 21:16:31.349 Install of libarchive-dev package requested.
2025-11-13 21:16:38.601 libarchive-dev installed successfully.
2025-11-13 21:16:38.616 Download of /tmp/swx-xnic_1.0.0_ubuntu24.04_amd64.deb requested.
2025-11-13 21:16:38.621 attempt number 1
2025-11-13 21:16:38.684 Success: downloaded 18763362 bytes.
2025-11-13 21:16:38.811 Success: /tmp/swx-xnic_1.0.0_ubuntu24.04_amd64.deb verification.
2025-11-13 21:16:38.814 Installing a package from a file: '/tmp/swx-xnic_1.0.0_ubuntu24.04_amd64.deb' (distro: ubuntu 24.04)...
2025-11-13 21:16:39.759 /tmp/swx-xnic_1.0.0_ubuntu24.04_amd64.deb installed successfully.
2025-11-13 21:16:39.763 [INFO] Leaving xNIC type 2 installed.
2025-11-13 21:16:39.779 [INFO] Found ens5 in Control subnet, using it as Control NIC.
2025-11-13 21:16:39.795 [INFO] Found ens6 in Data subnet, using it as Data NIC.
2025-11-13 21:16:39.799 [INFO] Updating configuration file /var/opt/swxtch/swx-xnic-config.json.
2025-11-13 21:16:39.832 [INFO] /var/opt/swxtch/swx-xnic-config.json has been updated.
2025-11-13 21:16:39.837 {
"persistenceFolder": "/var/opt/swxtch/persistence",
"logFolder": "/var/log/swxtch",
"httpPort": 80,
"disableLogTimestamp": true,
"logStackTraceTag": null,
"logTags": [
"info",
"error",
"warning"
],
"logsFolder": null,
"clientTlsConfig": null,
"component": {
"ctrlInterfaceName": "ens5",
"dataInterfaceNames": [
"ens6"
],
"nicsConfig": null,
"dataPort": 9999,
"dataPlaneSpecs": {
"verbosity": 0,
"virtualInterface": {
"name": "swx0",
"type": "tap",
"mtu": 4096,
"ip": "172.30.0.0",
"subnet": "255.255.0.0",
"persistent": false
},
"x2Settings": {
"cpu": -1,
"TapCpu": -1,
"timestamp": "none",
"pacing": {
"enabled": false,
"bufferSize": 0,
"playoutDelayMs": 0,
"inOrder": false
}
}
},
"xnicType": 2,
"ssmConfig": null,
"statsReportWait": 60,
"overrideSrcIp": false,
"subscriptionsPollingIntervalMs": 100,
"maxTimeStatsNs": null,
"dataGatewaysIp": null,
"processes": {
"swxXnicData": {
"launch": true,
"options": null,
"args": null
},
"swxCore": {
"launch": true,
"options": null,
"args": null
}
},
"filterSSMGroups": null,
"installedConnection": {
"ip": "172.51.128.132",
"port": 80
}
}
}
2025-11-13 21:16:39.841 Download of /tmp/swx-tools_1.0.0_ubuntu24.04_amd64.deb requested.
2025-11-13 21:16:39.845 attempt number 1
2025-11-13 21:16:39.884 Success: downloaded 6093824 bytes.
2025-11-13 21:16:39.943 Success: /tmp/swx-tools_1.0.0_ubuntu24.04_amd64.deb verification.
2025-11-13 21:16:39.947 Installing a package from a file: '/tmp/swx-tools_1.0.0_ubuntu24.04_amd64.deb' (distro: ubuntu 24.04)...
2025-11-13 21:16:40.244 /tmp/swx-tools_1.0.0_ubuntu24.04_amd64.deb installed successfully.
2025-11-13 21:16:40.248 [INFO] Swxtch tools were installed successfully.
2025-11-13 21:16:40.285 [INFO] Service swx-xnic.service restarted.
2025-11-13 21:16:40.289 ------------------------------------------------
2025-11-13 21:16:40.292 *** xNIC installation finished successfully! ***
2025-11-13 21:16:40.296 ------------------------------------------------Additional Arguments
There are additional arguments when installing the xNIC. To see these options, use the -h argument.
Note that the control and data interfaces are from the VM in which the xNIC is installed. These will be set automatically by the installer. Under some circumstances, the user may need to manually specify them. For example, if there are three NICs, the user may need to instruct the installer which interface to use for control, and which for data..This can be manually selected using the --ctrl_interface <interface name> or --data_interface <interface name> arguments. Also, these arguments help in complex contexts where the agent is in a different vNet/VPC from the cloudSwXtch.
Note: There is an option (-t) for users to switch between xNIC Type 1, 2 (default), or 3. All installation instructions and system requirements are solely for Type 2.
A full list of arguments is detailed below:
$ ./swx-xnic-install.sh -h
2025-09-22 21:18:33.260 ========== swXtch.io xNIC Installer ==========
Usage: ./swx-xnic-install.sh [OPTIONS]
-u just uninstall swXtch.io xNic (default: no)
-t <1|2|3> NIC type to install (default: 2 if supported by the OS, 1 otherwise)
For type 3, the script must be executed as root.
-c, --ctrl_interface <interface name> manually select control interface
-d, --data_interface <interface name> manually select data interface
--ptp install Precision Time Protocol (default: do not install it) **At this time PTP can only be manually installed please contact support@swxtch.io for further instructions.
--verify_signature verify install package with respective signature file (sig_public.pem if public_key is not set).
--public_key <public key file> public key file to use for signature verification (used with verify parameter).
--override_src_ip override the source IP of incoming packets (default: false)
--persist keep persistence folder (default: do not keep it)
-h | --help shows this helpPrecision Time Protocol Installation
At this time PTP can only be manually installed please contact support@swxtch.io for further instructions.
Signature verification
Prior to installing the xNIC, the user may need to verify the authenticity of swXtch.io's installer files. While it is not a necessary step in the installation process, it is still an available option to users with security protocols that require files to be validated.
After downloading the swxtch-xnic-install.sh file on the VM, run the following steps:
Download the public key from swXtch.io using the following command on the VM:
curl https://services.swxtch.io/assets/sig_public.pemMove the public key into the same directory as the swxtch-xnic-install.sh file.
Run the install command with the --verify argument:
./swxtch-xnic-install.sh --verify_signature
The --verify_signature argument will download the .sig file associated with the xNIC installer file based on the VM's operating system, verify with the public key, and proceed to install the xNIC onto the VM as a service.
Additional resources
For other xNIC types, see the How to determine correct xNIC Type page.
For setting up rp_filters , see the How to set-up rp_filter on a Linux xNIC page.
For increasing the maximum number of groups that can be consumed, see the How to Increase the Number of Groups Being Consumed by the xNIC page.
For opening firewall ports, see How to open Firewall ports on VMs page.
Testing
xNIC installation includes a set of utility applications that can be used to verify the operation of the cloudSwXtch network. Refer to Tools and Testing for details.
Upgrading xNIC on Linux
To upgrade xNIC on Linux, users can follow the steps in the xNIC Linux Upgrade page.
Uninstalling xNIC on Linux
To uninstall xNIC on Linux, users can follow the steps in the xNIC Linux Uninstall page.