Install xNIC on Windows

  • Updated on Dec 13, 2024
  • Published on Mar 7, 2023
  • 5 minute(s) read
Prev Next

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 a cloudSwXtch Bridge VM. 

In this article, users will learn how to install the xNIC software on Windows systems. 

Installing xNIC for Windows

BEFORE YOU START

Review xNIC System Requirements. 

Firewall Restrictions
The Windows installation process adds rules to Windows Defender Firewall, which allow for traffic through the UDP ports 10800 and 9999. The rule names are SwXtchControl, SwXtchData, and SwXtchTun. 

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-line shell command. The xNIC is matched to the attached cloudSwXtch instance and should be reinstalled if the cloudSwXtch version changes.

The xNIC takes less than a minute to install on an existing VM.

To run the install: 

1. Open a PowerShell terminal on the Windows VM that you aspire to install the xNIC software on. If you are working on Windows 11, please use Windows Terminal instead for installation.

2. Verify network connectivity to the cloudSwXtch instance by “pinging” the switch.

ping <cloudSwXtch-instance-name>

Ping Fails

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 default DNS settings are changed for the virtual network.

3. The installer script will automatically remove any firewall restrictions to UDP ports 10800 and 9999. The cloudSwXtch sends UDP packets to these ports as part of normal operation. 

Special Rules for Windows Defender Firewall

It is recommended to simply turn off the firewall. Additionally, users can open up additional ports for producing/consuming multicast traffic by using the following command in PowerShell:

New-NetFirewallRule -Name 'rule_name' -DisplayName 'rule_name' -Enabled True -Direction Inbound -Protocol UDP -Action Allow -LocalPort 1234

5. Download and run the installer script in Powershell as an administrator:

Invoke-WebRequest -Uri 'http://<cloudSwXtch-instance-name>/services/install/swxtch-xnic-win-install.ps1' -Outfile swxtch-xnic-win-install.ps1

Additional Arguments

There are additional options when installing the xNIC. To see these options, use the -h argument. 

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 detailed below.

Note: There is an option (-t) for users to switch between xNIC Type 1 and xNIC Type 2 (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. 

PS C:\Users\testadmin> .\swxtch-xnic-win-install.ps1 -h
Running on Microsoft Windows Server 2022 Datacenter
Usage: C:\Users\testadmin\swxtch-xnic-win-install.ps1 [OPTIONS]
  -t <1|2>                              xNIC type to install (default: 2 if supported in this OS, 1 otherwise)
  -u                                    uninstall xcd xNIC only (no other options allowed)
  -unattended                           unattended installation (in case of reboot, the user will not be prompted)
  -ctrl_interface <interface index>     manual selection of the Control interface
  -data_interface <interface index>     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                                    shows this help

Please note: The ctrl_interface and data_interface commands should only be used in complex configurations where the installer cannot locate them. Contact support@swXtch.io for more information. 

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: 

.\swxtch-xnic-win-install.ps1 --ptp

Getting the interface index for ctrl_interface and data_interface 

To get the interface index, you can run the following command:

get-netipconfiguration

A sample of the response will be returned with the InterfaceIndex (***) listed for both:

PS C:\Users\testadmin> get-netipconfiguration

InterfaceAlias       : Ethernet
InterfaceIndex       : 36 ***
InterfaceDescription : Microsoft Hyper-V Network Adapter
NetProfile.Name      : Network
IPv4Address          : 10.2.128.75
IPv6DefaultGateway   :
IPv4DefaultGateway   : 10.2.128.1
DNSServer            : 168.63.129.16

InterfaceAlias       : Ethernet 2
InterfaceIndex       : 60 ***
InterfaceDescription : Microsoft Hyper-V Network Adapter #2
NetProfile.Name      : Unidentified network
IPv4Address          : 10.2.192.82
IPv6DefaultGateway   :
IPv4DefaultGateway   :
DNSServer            : 168.63.129.16

7. The installer script will install a Windows service called swXtchNIC:  Windows%20xNIC%20install%20complete%20normally(1)

8. Reboot your machine once the installation is complete. This will enable you to execute cloudSwXtch tools properly from your user home directory such as swxtch-top. 

Errors

The control and data interfaces should have proper numbers. A 0, or negative number, indicates an error in the configuration of the control or data subnets for the xNIC. The control and data subnets of the cloudSwXtch and the xNICs should be the same.

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

Testing

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

  • swxtch-top.exe: An application to display real-time statistics of the cloudSwXtch instance.

  • swxtch-perf.exe: An application to produce and consume multicast traffic for testing purposes.

Running swxtch-top on Windows

swxtch-top --swxtch <cloudSwXtch-hostname>

  • <cloudSwXtch-hostname>: the name of your existing or "host" cloudSwXtch

Uninstalling xNIC on Windows

To uninstall xNIC on Windows, users can follow the steps in the Uninstall xNIC on Windows guide. 

Upgrading xNIC on Windows 

To upgrade xNIC on Windows, users can follow the steps in the Upgrade xNIC on Windows guide.