11. Hypervisor Host Network

Note

This section introduces the networking capabilities of the Hypervisor Host. You will learn how the Host manages the internal virtual network, configures forwarding or bridging for external access, and adjusts the interface settings for different network scenarios. By following the steps below, you can fine-tune how the Hypervisor Host and its guests communicate both internally and with external networks.

11.1. Virtual network

The hypervisor provides a virtual network. The Hypervisor Host and all the guests can be connected to this virtual network.
The IP addresses are set to fixed values.
The default IP addresses are:
Hypervisor Host: 192.168.157.1
First RTOS: 192.168.157.2
Windows or Linux example guest: 192.168.157.3

Hint

The Hypervisor Host virtual network IP address is initially set when installing the Hypervisor (via calling the /hv/bin/inithv.sh script). For more details, see Internal virtual network.

11.2. Network Forwarding from external computer to the RTOS

11.2.1. Hypervisor Host preparation

If the RTOS (or any other OS connected to the virtual network) shall be accessed via TCP/IP from a single external system, traffic can be forwarded to the virtual network. Execute the following steps to forward traffic from a specific external computer to the RTOS:

enable temporary network forwarding in the Hypervisor Host:

sudo sysctl -w net.ipv4.ip_forward=1

or, alternatively, enable permanent network forwarding in the Hypervisor Host:

sudo mousepad /etc/sysctl.conf

uncomment the following line:
  net.ipv4.ip_forward=1

determine the IP address of the Hypervisor Host. You can use the ifconfig command to accomplish this.

Caution

Assure the Default Gateway in the RTOS is set to the Hypervisor Host virtual network IP address (192.168.157.1)!

For RT-Linux it is set by default. For other RTOS you need to check the RTOS documentation how to accomplish this.

11.2.1.1. IPTables Setup

In case you have multiple network adapters connected to the Hypervisor Host or installed Docker in the Hypervisor host, you may have to create iptable rules for correct IP forwarding. This section provides steps to configure iptables rules on the Hypervisor Host and ensure they are persistent across reboots by using a custom script and a systemd service.

11.2.1.1.1. Step 1: Create a Script to Apply the Rules

Below we assume the network device ens33 is connected to the outside network and shall be used for IP forwarding. You may have to adjust this device according to your setup.

Create a script file to store the iptables rules:

sudo mkdir /etc/iptables
sudo nano /etc/iptables/rules.sh

Add the iptables rules to this script. Example content:

#!/bin/sh
iptables -A FORWARD -i ens33 -o vnet0 -j ACCEPT
iptables -A FORWARD -i vnet0 -o ens33 -j ACCEPT
iptables -t nat -A POSTROUTING -o ens33 -j MASQUERADE

Make the script executable:
```
sudo chmod +x /etc/iptables/rules.sh
```

11.2.1.1.2. Step 2: Create a systemd Service to Run the Script on Boot

Create a systemd service file:

sudo nano /etc/systemd/system/iptables-rules.service

Add the following content to the service file:

[Unit]
Description=Load iptables rules

[Service]
Type=oneshot
ExecStart=/etc/iptables/rules.sh
RemainAfterExit=yes

[Install]
WantedBy=multi-user.target

Enable the systemd service to ensure it runs on boot:
```
sudo systemctl enable iptables-rules.service
```
Start the systemd service to make if effective:
```
sudo systemctl start iptables-rules.service
```

11.2.1.1.3. Verification

After completing the setup, you can verify that the rules are applied correctly by checking the iptables configuration and the status of the systemd service.

Check the iptables rules:
```
sudo iptables -L -v -n
```

Check the status of the systemd service:

sudo systemctl status iptables-rules.service

By following these steps, you ensure that your iptables rules are persistent and automatically applied whenever your system reboots.

11.2.2. Forwarding from external Windows computer

open a Command Window with Administrator rights on your Windows PC
run the following command (replace AAA.BBB.CCC.DDD with the appropriate IP address of the Hypervisor Host):
```
route add 192.168.157.0 mask 255.255.255.0 AAA.BBB.CCC.DDD
```

11.2.3. Forwarding from external Linux computer

open a Terminal Window on your Linux PC
run the following command (replace AAA.BBB.CCC.DDD with the appropriate IP address of the Hypervisor Host):
```
ip route add 192.168.157.0/24 via AAA.BBB.CCC.DDD
```

11.3. Bridge virtual and physical network

If the RTOS (or any other OS connected to the virtual network) shall be accessed via TCP/IP from any external system, the virtual network and the respective physical network have to be bridged.

In the folder /hv/config you can find the template configuration file brvnetconfig.sh for the bridge configuration. Note, the IP address of the virtual network inside the RTOS guest need to be adjusted appropriately, see below for more details.

11.3.1. Bridge configuration

First step: determine, which network adapter should be bridged. Search for <link> entry and get the adapter name.

ifconfig -a

In this case it’s enp2s0. The current $IP$ address of enp2s0 is inet 172.17.10.53 and the network mask is 255.255.0.0.

 rtv@rtv-TEST:~$ ifconfig -a
 enp2s0: flags=4163<UP,BROADCAST,RUNNING,MULTICAST>  mtu 1500
     inet 172.17.10.53  netmask 255.255.0.0  broadcast 172.17.255.255
     inet6 2a02:590:801:2c00:7170:3747:f835:a1cb  prefixlen 64  scopeid 0x0<global>
     inet6 fe80::fe6f:c5f8:c5cd:e3cd  prefixlen 64  scopeid 0x20<link>
     inet6 2a02:590:801:2c00:96b0:b8a:2c58:6c91  prefixlen 64  scopeid 0x0<global>
     ether 90:1b:0e:18:c9:83  txqueuelen 1000  (Ethernet)
     RX packets 116751  bytes 22127837 (22.1 MB)
     RX errors 0  dropped 0  overruns 0  frame 0
     TX packets 74453  bytes 551331072 (551.3 MB)
     TX errors 0  dropped 0 overruns 0  carrier 0  collisions 0

 enp3s5: flags=4099<UP,BROADCAST,MULTICAST>  mtu 1500
     ether 74:ea:3a:81:4b:1d  txqueuelen 1000  (Ethernet)
     RX packets 0  bytes 0 (0.0 B)
     RX errors 0  dropped 0  overruns 0  frame 0
     TX packets 0  bytes 0 (0.0 B)
     TX errors 0  dropped 0 overruns 0  carrier 0  collisions 0

 lo: flags=73<UP,LOOPBACK,RUNNING>  mtu 65536
     inet 127.0.0.1  netmask 255.0.0.0
     inet6 ::1  prefixlen 128  scopeid 0x10<host>
     loop  txqueuelen 1000  (Local Loopback)
     RX packets 201  bytes 14798 (14.7 KB)
     RX errors 0  dropped 0  overruns 0  frame 0
     TX packets 201  bytes 14798 (14.7 KB)
     TX errors 0  dropped 0 overruns 0  carrier 0  collisions 0

 vnet0: flags=99<UP,BROADCAST,NOTRAILERS,RUNNING>  mtu 1500
     inet 192.168.157.1  netmask 255.255.255.0  broadcast 192.168.157.255
     ether 00:60:c8:00:00:00  txqueuelen 1000  (Ethernet)
     RX packets 0  bytes 0 (0.0 B)
     RX errors 0  dropped 0  overruns 0  frame 0
     TX packets 59  bytes 10381 (10.3 KB)
     TX errors 0  dropped 0 overruns 0  carrier 0  collisions 0

Next step: determine the default gateway.

ip route ls

You will get an output like default via 172.17.5.2 dev enp2s0 proto dhcp metric 100.

Next step: determine the DNS server.

resolvectl status | grep "Current DNS Server"

You will get an output like Current DNS Server: 172.17.5.9.

Next step: Adjust brvnetconfig.sh with the detected values of ifconfig:

mousepad /hv/config/brvnetconfig.sh

Values:

netif="enp2s0"
defaultgw="172.17.5.2"
dns="172.17.5.9"
vnetbrip="172.17.10.53"
vnetbrnm="255.255.0.0"
#vnetbrmac= comment in and adjust value only if there are collisions with ‘same’ MAC-IDs on the network.

 #!/bin/bash

 # Ethernet network interface to bridge with VM.
 # ethernet interface to bridge with vnet
 netif="enp2s0"

 # Default gateway
 # How to determine the default gateway:
 #       Use the command ip route ls
 #           default via 172.17.5.2 dev enp2s0 proto dhcp metric 100
 #           172.17.0.0/16 dev enp2s0 proto kernel scope link src 172.17.10.4 metric 100
 #       The default gateway here is "172.17.5.2"
 defaultgw="172.17.5.2"       # default gateway

 # DNS server
 # How to determine the default gateway:
 #       Use the following command: resolvectl status | grep "Current DNS Server"
 #            Current DNS Server: 172.17.5.9
 #       The DNS server here is "172.17.5.9"
 dns="172.17.5.9"

 # Bridge settings
 # The bridge replaces the former network device used by the hypervisor to connect to the network.
 # See above results provided by the ifconfig -a command
 #       enp2s0: flags=4163<UP,BROADCAST,RUNNING,MULTICAST>  mtu 1500
 #               inet 172.17.10.53  netmask 255.255.0.0  broadcast 172.17.255.255
 #       In this example, the bridge IP address is 172.17.10.53 and the network mask is 255.255.0.0
 vnetbrip="172.17.10.53"
 vnetbrnm="255.255.0.0"

 # the values below are default values, typically not to be changed
 vnetip="192.168.157.1"
 vnetnm="255.255.255.0"
 #vnetbrmac="54:52:00:ac:30:10       # by default, the MAC address of the physical network is used
 vnet="vnet0"
 vnetbr="vnetbr"

11.3.1.1. RT-Linux Guest IP address settings

If the network is bridged, the IP address of RT-Linux must be adjusted properly. The settings are stored in /hv/guests/guestrtlinux/guest.config. The IpAddress has to be set to a unique address in your company network, assure the entries are uncommented! The MacAddress has to be adjusted to a unique value only if more than one RT-Linux guest is bridged, in that case, please adjust the last value from 12 to 13, 14 etc.

 ; This must be set correctly if the vnet device is bridged in the Hypervisor Host
 [Rtos\Vnet\0]
     "IpAddress"="172.17.10.239"
     "MacAddress"="AA:BB:CC:DD:E0:12"

11.3.1.2. Bridge activation

After configuring the bridge parameters, you can create the bridge:
- First, start the RTOS to assure the virtual network is available.
- Run the hv_brvnetset command.
Remove the bridge - Run the hv_brvnetclr command.

11.4. Hypervisor Host network configuration

The Hypervisor Host network can be configured using automatic IP address configuration (DHCP), manual IP address configuration or disabled network. To simplify the process, the hv_netconf command is provided.

Caution

The Hypervisor Host network configuration has to match with the KVM guest network settings (e.g. Windows or Ubuntu guest)
One of the guest network settings is  determined by parameter netif_mode in the guest configuration file (e.g. usr_guest_config.sh located in the GUEST_FOLDER).
If the Hypervisor Host and guest settings do not match, the behaviour is undefined.

11.4.1. Automatic network configuration

This is the default mode. Nothing has to be changed if this mode shall be used. In case the networking had been adjusted manually, you can switch back to the automatic configuration as follows.

hv_netconf -auto

A single network interface can be set into automatic mode as follows.

hv_netconf %DEVICE% -auto

For example:

hv_netconf enp1s0 -auto

11.4.2. Manual network configuration

If you want the Hypervisor Host to be configured manually, you need to adjust the settings accordingly.

hv_netconf %DEVICE% -manual IP-address netmask-bits gateway-IP dns-IP

For example:

hv_netconf enp1s0 -manual 192.168.178.188 24 192.168.178.1 8.8.8.8

Then, configure the guest.

cd GUEST_FOLDER
mousepad usr_guest_config.sh

Change the respective configuration values.

netif_mode=0
netif_m=...
defaultgw_m=...
dnsgw_m=...
brip_m=...
brnm_m=...

11.4.3. Disabled network

If you want the Hypervisor Host not to use the network, you need to adjust the settings accordingly. In case the PC currently is connected with the LAN and you want to use this connection for a guest, you need to determine the device name before disabling the Hypervisor Host network. You may use the ifconfig command for that purpose.

sudo ifconfig

Next, disable the network of the Hypervisor Host.

hv_netconf -off

You need to turn off IPv6 as follows.

sudo mousepad /etc/sysctl.conf

Insert the following lines at the bottom of this file:

net.ipv6.conf.all.disable_ipv6=1
net.ipv6.conf.default.disable_ipv6=1
net.ipv6.conf.lo.disable_ipv6 = 1

Make this effective:

sudo sysctl -p

Then, configure the guest.

cd GUEST_FOLDER
mousepad usr_guest_config.sh

Change the respective configuration values.

netif_mode=2
netif_m=...

Caution

You must define the network device that shall be used in the guest by setting the parameter netif_m to the name you have determined above.

Hint

To re-enable the Hypervisor Host network in automatic mode, run the hv_netconf command again:

hv_netconf -auto

And change the netif_mode configuration value.

cd GUEST_FOLDER
mousepad usr_guest_config.sh

netif_mode=1

11.4.4. Internal virtual network

The Hypervisor provides an internal virtual network using fixed IP address settings. The Hypervisor Host and all the guests can be connected to this virtual network. All guests also need to use fixed IP address settings. The device name for the virual network is vnet0. This device is not managed by the NetworkManager and settings cannot be changed using the hv_netconf command.

To change the settings, please adjust the configuration file /etc/network/interfaces. The IP addresses of the RTOS and KVM guests have to be adjusted accordingly.

Hint

If the vnet0 device would be managed by the NetworkManager, a specific network connection for vnet0 may be created using a fixed IP address. But even in such case, the NetworkManager may try to use one of the default network connections (e.g. Wired Connection 1) which are not bound to a specific device. As a result, the NetworkManager will try to get the IP address for vnet0 via DHCP. As there is no DHCP server on this network, this will lead to a timeout. In addition, additional (physical) network devices will also not work (or work only after a very long time) unless there is a specific connection defined for such device (using the hv_netconf command).

11.5. Hypervisor network service/port management

In many scenarios, you must manage network-related services on the Hypervisor Host — for example, to ensure unnecessary services are disabled (for security reasons) or to enable services like SSH, FTP, and SMB.

Additionally, you may want to see which TCP/UDP ports are currently in use, identify which processes own them, and forcefully terminate any unwanted processes.

11.5.1. Introduction

The following steps outline how you can:

Determine which network services exist on your system and verify if they are installed.
Enable or disable specific network services (or all at once) for security or configuration reasons.
Check which network ports are in use and identify processes (e.g., daemons like SSH, FTP, or custom applications) associated with those ports.
Terminate processes bound to a port, including their child processes, if necessary for security or troubleshooting.

All of these functions are accessible through the hv_netsvc_mgr command, which you can run at any time on the Hypervisor Host. It supports multiple command-line options for listing and managing services as well as ports and processes.

11.5.2. Command Reference

Below is a high-level overview of the hv_netsvc_mgr command. It can:

Enable/disable/show a predefined list of network services.
Show open ports, filtering by “all,” “open,” or “connected” states.
Show or kill all processes using a particular port (including their child processes).

11.5.2.1. Usage Examples

# Show the status of all service:
hv_netsvc_mgr -svcshow

# Show the status of a specific service:
hv_netsvc_mgr -svcshow ssh

# Enable a single service:
hv_netsvc_mgr -svcena smbd

# Disable all network services:
hv_netsvc_mgr -svcdis all

# Show all open ports:
hv_netsvc_mgr -portshow all

# Show only actively established (ESTAB) connections:
hv_netsvc_mgr -portshow conn

# Show processes associated with port 80:
hv_netsvc_mgr -prcshow 80

# Kill all processes associated with port 22 (e.g., SSH):
hv_netsvc_mgr -prckill 22

11.5.2.2. Notes and Tips

Service Management: By default, hv_netsvc_mgr references a built-in array of known network services (e.g., SSH, vsftpd, smbd). If a service is missing from this array, the command won’t manage it unless you add it to the array.
Sockets: Some services also have corresponding socket units (e.g., rpcbind.socket). These are included so you can enable/disable or show them as needed.
Systemd vs. Manual Processes: For ephemeral ports or user processes, you might not see a direct systemd “service.” In that case, the process-oriented commands (-prcshow / -prckill) help identify the actual PID and any child processes that hold a port.
Security Considerations: Disabling unneeded services or stopping processes on unused ports lowers the attack surface. But ensure you do not disable essential services (for instance, SSH if you rely on remote access).

By using hv_netsvc_mgr, you have a single tool to audit and control the Hypervisor Host’s network services and ports, keeping it both functional and secure.

11.5.3. Network airgapping

For security reasons, you may want the Hypervisor to stay completely disconnected from the externel network. For that purpose the network must be disabled and all network related services should be stopped and disabled. Furthermore, you may also want to terminate all processes that currently have open network connections.

In a first step, disable the network itself as described in Disabled network.

Then proceed according to the following steps:

# stop and disable the System Manager service
hv_sysmgr stop
hv_sysmgr disable

# stop and disable all network related services
hv_netsvc_mgr -svcdis all

# reboot the system
sudo reboot

Instead of rebooting, you may also forcibly terminate all processes with open network connections.

hv_netsvc_mgr -prckill all

Most likely, an automatic logout wil then occur. You will have to log in again. Verify, if no services are active and no ports are open.

hv_netsvc_mgr -svcshow
hv_netsvc_mgr -portshow

If there are open ports, check which processes are using them:

hv_netsvc_mgr -prcshow

Hint

If you disable the Hypervisor host from the network, you need to assure that the mode for the KVM guest networking is set up properly. The default mode will not work in such cases. See Automatic external network connection (dynamically bridged).

11.5.4. Re-enable network access

Follow the below steps to re-enable the network access again.

# enable and start all network related services
hv_netsvc_mgr -svcena all

# enable and start the System Manager service
hv_sysmgr enable
hv_sysmgr start

Finally, re-enable the network itself as described in Disabled network.