Install xNIC on Linux

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. 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 in the Linux systems.

Installing xNIC for Linux

BEFORE YOU START

Review xNIC System requirements.

Network Acceleration

If using Azure, the data-subnet must have the "Network Acceleration" feature enabled.

Running the Install Script

To make installation easy, the xNIC is installed from the cloudSwXtch instance via a one-time shell command. 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 you wish to install the xNIC software on.
Verify network connectivity to the cloudSwXtch instance by "pinging" the switch.
```
ping <cloudSwXtch-instance-name>
```
Text
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, 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.

Review Firewall Exceptions

The installer script will automatically open ports 10800 and 9999.

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

Run the following installer script:

curl http://<cloudSwXtch-instance-name>/services/install/swxtch-xnic-install.sh | bash

Alternatively, you can run the install script after downloading it using the wget command:

wget http://<cloudSwXtch-ip>/services/install/swxtch-xnic-install.sh
chmod +x swxtch-xnic-install.sh
./swxtch-xnic-install.sh

The installer script will install the xNIC as a service and a set of utility applications that can be used to verify the operation of your cloudSwXtch network. Refer to Testing for more details.

A successful install is shown below:

IF THE INSTALL FAILS:

Validate that the VM has at least two NICs and the NICs are on the same subnets for control and data as the cloudSwXtch. The ctrl-subnet should be assigned to the primary NIC.

If you are using Azure, validate that the data-subnet has "Network Acceleration" feature enabled.

Setting the rp_filter on Linux

During xNIC installation, the Linux rp_filter is set to loose mode by default at runtime. This allows for the xNIC to work on asymmetric networks, meaning that it can receive packets from machines outside of its subnet if the source is routable.

To opt out of this configuration, navigate to the xnic.json file after completing the xNIC installation process. This file can be found in /var/opt/swxtch/xnic.json. To edit the file, one option is to use nano as shown below:

sudo nano /var/opt/swxtch/xnic.json

Next to "overrideSourceIP" in the json file, change the parameter to true. Save the file and restart the xNIC VM. This will set the rp_filter back to the original mode and will remain like that for future reboots. Note that this means our software will do source network address translation on incoming packets.

Additional Arguments

There are additional arguments when installing the xNIC.

Note that the ctrl- and data- interfaces are from the VM the xNIC is installed. These will be set automatically by the installer. There may be some instances where you will need to specify them. For example, if you have three network interfaces and you want to specify what you want to use for ctrl or data, you can manually select them using the -ctrl_interface <interface index> or -data_interface <interface index> arguments. Also, these argument help in complex contexts where the agent is in a different vNet/VPC from the cloudSwXtch.

A full list of arguments is detailed below:

$ ./swxtch-xnic-install.sh -h
Usage: ./swxtch-xnic-install.sh [OPTIONS]
  -t <1|2>                            xNIC type to install (default: 2 if supported in this OS, 1 otherwise)
  -u                                  uninstall xNIC instances
  --ctrl_interface <interface name>   manual selection of the Control interface
  --data_interface <interface name>   manual selection of the Data interface
  --ptp                               installing of Precision Time Protocol (default: false)
  --verify                            Verify install package with respective signature file (sig_public.pem if public_key is not setted).
  --public_key <public key file>      Public key file to use for signature verification (used with verify parameter).
  -h | --help                         shows this help

Note: There is an option for users to switch between xNIC Type 1 and Type 2, latter being the default. All installation instructions and system requirements are solely for Type 2. It is not recommended to use Type 1 unless otherwise suggested by swXtch.io Support.

Precision Time Protocol Installation
By default, precision time protocol is not enabled during xNIC installation. To install the Precision Time Protocol feature, please run the following command:
wget http://<swxtch-ip>/services/install/swxtch-xnic-install.sh
chmod +x swxtch-xnic-install.sh
./swxtch-xnic-install.sh --ptp 

Verifying Installer Files [Optional]

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. Please note: This option is only available in cloudSwXtch versions 2.2 or greater.

After downloading the swxtch-xnic-install.sh file on your VM, run the following steps:

Download the public key from swXtch.io using the following command on your VM:
ShellShell
```
curl https://services/swxtch.io/assets/sig_public.pem
```
Move the public key into the same directory as the swxtch-xnic-install.sh file.
Run the install command with the --verify argument:
ShellShell
```
./swxtch-xnic-install.sh --verify
```

The --verify 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.

Testing

xNIC installation includes a set of utility applications that you can use to verify the operation of your cloudSwXtch network. Refer to Testing for details.

swx-top: An application to display real-time statistics of the cloudSwXtch instance.
swx-perf: An application to produce and consume unicast and multicast traffic for testing purposes.

Running swx-top on Linux

<swxtch-hostname>: name of your existing swxtch or "host" swxtch

swx-top dashboard --swxtch <swxtch-hostname>

Increasing the Number of Groups Being Consumed by the xNIC

Linux environments limit the amount of groups that can be consumed by the xNIC. By default, the value is set to 20. If a user needs to consume more than 20 groups through a single xNIC, they need to make a change to the kernel parameter, net.ipv4.igmp_max_memberships, in the systctl.conf file.

To do this:

Open the /etc/sysctl.conf to begin editing.
Add the following line:
```
net.ipv4.igmp_max_memberships=4096
```
Save the file and apply the changes immediately:
```
sysctl -p
```
Verify the change:
```
sysctl net.ipv4.igmp_max_memberships
```

The xNIC should now be able to consume more groups.

Unistalling xNIC on Linux

To uninstall xNIC on Linux, users can follow the steps in the xNIC Linux Uninstall Guide.

Upgrading xNIC on Linux

To upgrade xNIC on Linux, users can follow the steps in the xNIC Linux Upgrade Guide.