Version: Torizon OS 7.x.y

Is this page helpful?

Networking with Torizon OS

Introduction

Networking with Torizon OS can refer to different topics:

Configuration of the host network, not directly related to containers.
Configuration of networking on a container, and the relationship between the container and the host networks.
Configuration of inter-container networking, often with the purpose of multi-process communication using the network stack (e.g. REST API).

The first part of this article explains about host network configuration: the Torizon OS image currently provides NetworkManager, a program that provides detection and configuration for the system to automatically connect to networks.

The second part of this article explains about container network configuration and how to share a network between containers using docker-compose.

Ethernet Interface Naming on Torizon OS

Torizon OS Ethernet interfaces are always named ethernetX, being X a number starting from 0, for instance, ethernet0, ethernet1 and so on.

This article complies with the Typographic Conventions for Torizon Documentation.

Prerequisites

In order to take full advantage of networking with Torizon OS, see the articles:

Configure Build Environment for Torizon Containers
Operating Toradex Wi-Fi/BT Capable Modules Using Dual and Single Antenna Configuration (to set the antenna and use Wi-Fi properly)

Host Configuration: NetworkManager

The nmcli is a command-line client for NetworkManager. You can show the status of your network devices, detected by NetworkManager:

# nmcli device

Show our available connections and devices, on which the active connection is applied to:

# nmcli connection show

To disconnect from a network:

# nmcli con down id '<Connection_name>'

To delete a connection:

# nmcli con delete '<Connection_name>'

Static Network Configuration

If you looking for a way to configure a Static Network Configuration, nmcli provides the following commands:

# nmcli con mod '<Connection_name>'  ipv4.addresses "<desired IP/mask>"
# nmcli con mod '<Connection_name>'  ipv4.gateway "<desired gateway>"
# nmcli con mod '<Connection_name>'  ipv4.dns "<DNS server 1>,<DNS server 2>"
# nmcli con mod '<Connection_name>'  ipv4.method "manual"

After running the commands above, you can visualize your entire network configuration by opening the <connection-name>.nmconnection file:

# cd /etc/NetworkManager/system-connections/
# sudo cat <connection-name>.nmconnection

Expected file output:

connection_name.nmconnection
[connection]
id=<connection-name>
uuid=a690e7e8-a413-331d-830d-d0df5bad3983
type=ethernet
autoconnect-priority=-999
permissions=
timestamp=1581530428

[ethernet]
mac-address=00:14:2D:63:47:64
mac-address-blacklist=

[ipv4]
address1=<board-ip>,10.0.0.1
dns-search=
method=manual

[ipv6]
addr-gen-mode=stable-privacy
dns-search=
method=auto

After the changes were made, do not forget to reload the configuration file:

# sudo nmcli connection reload

Dynamic Network Configuration

Along with Static Network Configuration, ncmli provides a way to configure a dynamic connection:

# nmcli con mod '<Connection_name>'  ipv4.method "auto"

Other nmcli Commands

You must read the nmcli man page, either running man nmcli on a computer with nmcli installed or Googling after it. For quick reference, man --help is also useful.

Wi-Fi

Torizon OS supports two Wi-Fi modes: client mode and access point (AP) mode.

Wi-Fi Client Mode

This mode is used when you want a Torizon OS Device to connect to a Wi-Fi access point.

To see a list of available Wi-Fi access points:

# nmcli device wifi list

To connect to a Wi-Fi access point:

# nmcli -a device wifi connect <WIFI_NAME>

Now that your device is connected to a Wi-Fi access point, you might want to share the internet to other devices over ethernet.

Note the Wi-Fi interface name(<WIFI_IFACE_NAME>) that NetworkManager used to connect to the Wi-Fi.
```
# nmcli connection show --active | grep wifi | awk '{print $4}'
```
Activate a DHCP server on the ethernet interface(<ETH_IFACE_NAME>). To do that, you can leverage systemd's built-in DHCP server support, creating the file /etc/systemd/network/42-ethernet0.network with the following content (substitute <ETH_IFACE_NAME>, <IPV4_ADDR>, <IPV4_ADDR_NETMASK>, <DHCPD_POOL_OFFSET>, <DHCPD_POOL_SIZE> and <STATIC_DNS_ADDRESS> accordingly):
info
You can refer to Systemd manpages for more configuration possibilities and details.
/etc/systemd/network/42-ethernet0.network
```
[Match]
Name=<ETH_IFACE_NAME>

[Network]
Address=<IPV4_ADDR>/<IPV4_ADDR_NETMASK>
DHCPServer=yes

[DHCPServer]
PoolOffset=<DHCPD_POOL_OFFSET>
PoolSize=<DHCPD_POOL_SIZE>
EmitDNS=yes
DNS=<STATIC_DNS_ADRESS>
```
Now just restart the systemd-networkd service:
```
# sudo systemctl restart systemd-networkd
```
At this point, any device connected to the ethernet will be able to lease an IP address from the DHCP server.
Setup Packet Forwarding and NAT to give internet access to the device connected over the ethernet.
As this is a reverse scenario of Wi-Fi hotspot mode, we can follow the same steps described under the Wi-Fi hotspot mode and just reverse the NAT interfaces like below:(substitute <ETH_IFACE_NAME> and <WIFI_IFACE_NAME> accordingly):
```
# sudo iptables -t nat -A POSTROUTING -o <WIFI_IFACE_NAME> -j MASQUERADE
# sudo iptables -A FORWARD -m conntrack --ctstate RELATED,ESTABLISHED -j ACCEPT
# sudo iptables -A FORWARD -i <ETH_IFACE_NAME> -o <WIFI_IFACE_NAME> -j ACCEPT
```
Now the device connected over ethernet should be able to access the internet.

Wi-Fi Access Point Mode

This mode is used when you want a Torizon OS Device to act as a Wi-Fi access point.

This section is based on the BSP Access Point mode.

Verify that NetworkManager is not managing the uap interface. Check for the file /etc/NetworkManager/conf.d/99-disable-uap.conf with the following content:

/etc/NetworkManager/conf.d/99-disable-uap.conf
[main]
plugins=keyfile

[keyfile]
unmanaged-devices=interface-name:uap*

Set the Access Point interface IP and SSID in Hostapd configuration file. Using 2.4GHz WLAN whit WPA2 security protocol. Change the following variables in /etc/hostapd.conf:

/etc/hostapd.conf
interface=uap0
ssid=<WIFI_SSID>
hw_mode=g
channel=1
own_ip_addr=<IP_ADDR>
wpa=2
wpa_passphrase=<WIFI_PASSWORD>

An alternate hostapd.conf file that creates a WLan in the 5GHz range, protected with WPA2:

/etc/hostapd.conf
interface=uap0
ssid=<WIFI_SSID>
hw_mode=a
channel=40
ieee80211n=1
own_ip_addr=<IP_ADDR>
wpa=2
wpa_passphrase=<WIFI_PASSWORD>
country_code=<CC>

Replace <WIFI_SSID>, <IP_ADDR>, <WIFI_PASSWORD> and <CC> accordingly. In order to complete your file with the correct country code, please take a look at Country Codes. The hostapd.conf is documented in the default hostapd.conf file that is deployed, as well as here: https://w1.fi/cgit/hostap/plain/hostapd/hostapd.conf

To provide the Access Point interface with a static IP address and DHCP, it is necessary to create the file /etc/systemd/network/80-wifi-ap.network:
/etc/systemd/network/80-wifi-ap.network
```
[Match]
Name=uap0
Type=wlan
WLANInterfaceType=ap

[Network]
Address=<IPV4_ADDR>/<IPV4_ADDR_NETMASK>
DHCPServer=yes

[DHCPServer]
PoolOffset=10
PoolSize=30
EmitDNS=yes
DNS=<STATIC_DNS_ADRESS>
```
Replace <IPV4_ADDR>, <IPV4_ADDR_NETMASK> and <STATIC_DNS_ADRESS> accordingly. This also automatically sets up forwarding and the iptables masquerading rules, also including the setup of the AP sharing interface with a DHCP server. You can find more information and examples on the systemd-networkd documentation.

Enable and start hostapd:

# sudo systemctl enable hostapd
# sudo systemctl start hostapd

Change the hostapd permissions:
```
# sudo mount -o remount, rw /usr/
```

AP will not survive a reboot.

The Hostapd service starts by default after the network target. This target is loosely defined and means "start after the network stack is up". That service will fail because the network device (uap0 by default) is not up yet, or not every time. To fix this we can tell systemd that the hostapd.service file depends on a device, named sys-subsystem-net-devices-uap0.device on Torizon OS. To make it persist do the following steps:

Edit hostapd.service located in /usr/lib/systemd/system/ to execute after the desired interface (uap) is created and add these lines:

hostapd.service
[Unit]
Description=Hostapd IEEE 802.11 AP, IEEE 802.1X/WPA/WPA2/EAP/RADIUS Authenticator
BindsTo=sys-subsystem-net-devices-uap0.device
After=sys-subsystem-net-devices-uap0.device

Now you can connect on your access point. If you are willing to have internet access through internet sharing, keep following this guide.

To establish an internet connection, create the /etc/sysctl.d/30-ipforward.conf file, as follows:
/etc/sysctl.d/30-ipforward.conf
```
 net.ipv4.ip_forward=1
 net.ipv6.conf.default.forwarding=1
 net.ipv6.conf.all.forwarding=1
```
Load the kernel modules to deal with IP tables, NAT and COnntrack:
```
# modprobe ip_tables
# modprobe nf_nat
# modprobe nf_conntrack
```

Enable NAT using the iptables command.

# sudo iptables -t nat -A POSTROUTING -o ethernet0 -j MASQUERADE
# sudo iptables -A FORWARD -m conntrack --ctstate RELATED,ESTABLISHED -j ACCEPT
# sudo iptables -A FORWARD -i uap0 -o ethernet0 -j ACCEPT

Save the current configuration on the module. That requires root permissions.

# sudo su 
# cd /etc/iptables
# iptables-save > /etc/iptables/iptables.rules
#exit

Create the etc/systemd/iptables.service file to manage the iptables.

etc/systemd/iptables.service
[Unit]
Description=IPv4 Packet Filtering Framework
Before=network-pre.target
Wants=network-pre.target

[Service]
Type=oneshot
ExecStart=/usr/sbin/iptables-restore /etc/iptables/iptables.rules
ExecReload=/usr/sbin/iptables-restore /etc/iptables/iptables.rules
RemainAfterExit=yes

[Install]
WantedBy=multi-user.target

Reboot the module to apply the changes.
```
# sudo reboot
```

Reload the systemd services and enable iptables:

# sudo systemctl --system daemon-reload
# sudo systemctl enable iptables

Wi-Fi Hotspot Mode

To configure a hotspot, first make sure to follow the steps at the section Wi-Fi Access Point Mode. Then, proceed with the next instructions.

Once AP Mode is configured, it is a common use-case to share an internet connection from another interface (hotspot), when you want your system-on-module with Torizon OS to act as a Wi-Fi hotspot. This section relies on the Internet Sharing article from the Arch Wiki and on BSP internet sharing mode.

Enable the Packet Forwarding settings by editing the 30-ipforward.conf with the following content:
/etc/sysctl.d/30-ipforward.conf
```
net.ipv4.ip_forward=1
net.ipv6.conf.default.forwarding=1
net.ipv6.conf.all.forwarding=1
```

The changes will take effect after a reboot.

Use modprobe to load the kernel modules related to IP tables, NAT and Conntrack.
```
# modprobe ip_tables
# modprobe nf_nat
# modprobe nf_conntrack
```

Use iptables to enable NAT:

# sudo iptables -t nat -A POSTROUTING -o ethernet0 -j MASQUERADE
# sudo iptables -A FORWARD -m conntrack --ctstate RELATED,ESTABLISHED -j ACCEPT
# sudo iptables -A FORWARD -i uap0 -o ethernet0 -j ACCEPT

Save the current config to /etc/iptables/iptables.rules:

# sudo su
# mkdir /etc/iptables/
# iptables-save > /etc/iptables/iptables.rules
# exit

Create a systemd service file iptables.service. The example is modified from the iptables package from Arch Linux:

/etc/systemd/iptables.service
[Unit]
Description=IPv4 Packet Filtering Framework
Before=network-pre.target
Wants=network-pre.target

[Service]
Type=oneshot
ExecStart=/usr/sbin/iptables-restore /etc/iptables/iptables.rules
ExecReload=/usr/sbin/iptables-restore /etc/iptables/iptables.rules
RemainAfterExit=yes

[Install]
WantedBy=multi-user.target

Reload systemd services and enable the new service:

$ sudo systemctl --system daemon-reload
$ sudo systemctl enable iptables

Extra Resources

VPN

It's possible to configure a VPN tunnel in Torizon OS using WireGuard. In order to do this, please follow the instructions described in How to Use VPN on Torizon OS.

ifupdown Plugin

Torizon OS supports the NetworkManager's ifupdown plugin. This plugin makes it possible to configure the network using a /etc/network/interfaces file. For more information on how to use this plugin, please check the official NetworkManager documentation and the NetworkManager.conf manpage.

Production Release

After you make the changes to your device, you can use the command isolate from the TorizonCore Builder Tool to generate your custom Torizon OS image for the Toradex Easy Installer. To learn how to do it, please refer to the article Capturing Changes in the Configuration of a Board on Torizon OS.

Networking Inside Docker Container

This section is a brief introduction on how to use different network configurations inside a Docker container. You must also refer to the Docker Networking documentation, which is a comprehensive source of information.

Show the list of networks:

# docker network ls

Inspect network to see what containers are connected to it:

# docker network inspect <NETWORK_NAME>

Network drivers:

Bridge (containers communicate on the same Docker host)
Host (uses the host's networking directly)
Overlay (when containers running on different Docker hosts to communicate)
Macvlan (when you need your containers to look like physical hosts )
None
3rd-party- network plugins

Bridge

When you run a new container, it automatically connects to the bridge network. A private network internal to the host is created in order to provide communication to the containers.

Create a user-defined bridge network:

# docker network create --subnet=<172.18.0.0/16> <NETWORK_NAME>

Create a container connected to our user-defined network:

# docker run --name <CONTAINER_NAME> -d --net <NETWORK_NAME>  <IMAGE_NAME>

Specify the IP to a container and publish port 80 in the container to port 8080 to allow connections from other machine on the network :

# docker run --name <CONTAINER_NAME> -d --net <NETWORK_NAME> --ip <172.18.0.5>  --publish <8080>:<80> <IMAGE_NAME>

Connect a running container to a network:

# docker network connect <NETWORK_NAME> <CONTAINER_NAME>

Macvlan

Macvlan driver can be configured in different ways. The advantage is to use the newest built-in and a lightweight driver, allowing the container to connect directly to host interfaces.

Create a macvlan network:

# docker network create -d macvlan --subnet=<172.16.86.0/24>  \
  --gateway=<172.16.86.1> -o parent=<ETHERNET_INTERFACE>  \
  <NETWORK_NAME> 

Attach the container to the macvlan network:

# docker run -dit --network <NETWORK_NAME> \
  --name <CONTAINER_NAME>  <IMAGE_NAME> /bin/bash

Docker Networking Drivers Use Cases

To understand more about Docker networking drivers and which one is more advised to use on your application, please take a look at Understanding Docker Networking Driver Use Cases (archived).

Docker Network Using Docker-Compose

When you start your application, Docker Compose sets up a bridge network by default. Each service connects to the network, which makes them reachable with each other.

You can create your own networks to provide isolation and more options:

docker-compose.yml
services:
  app1:
    image: app
    networks:
          - frontend
  app2:
    image: app
    networks:
          - frontend
          - backend
  app3:
    image: app
    networks:
         - backend
networks:
  backend:
    # here you can configure your network 
  frontend:

App2 is connected to frontend and backend network, so it can communicate with app1 and app3. App1 and app3 can't communicate with each other, because they are on separate networks.

Connect to the external network:

networks:
  default:
    external:
      name: <pre-existing-network>

Docker compose looks for the pre-existing-network.

For more information about, please take a look at Docker Compose Documentation.

Networking with Torizon OS

Introduction​

Ethernet Interface Naming on Torizon OS​

Prerequisites​

Host Configuration: NetworkManager​

Static Network Configuration​

Dynamic Network Configuration​

Other nmcli Commands​

Wi-Fi​

Wi-Fi Client Mode​

Share internet over ethernet​

Wi-Fi Access Point Mode​

Wi-Fi Hotspot Mode​

Extra Resources​

VPN​

ifupdown Plugin​

Production Release​

Networking Inside Docker Container​

Bridge​

Macvlan​

Docker Networking Drivers Use Cases​

Docker Network Using Docker-Compose​