Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs(nm): added documentation for vlan and mtu configuration #4919

Merged
merged 7 commits into from
Nov 8, 2023
Merged

docs(nm): added documentation for vlan and mtu configuration #4919

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
617ec73
docs(nm): added documentation for vlan and mtu configuration
fdizazzo Oct 26, 2023
f8fb07c
fix: Delete nohup.out
fdizazzo Oct 26, 2023
b51dbdb
docs: vlan configuration details page
fdizazzo Nov 7, 2023
0f6af3d
docs: fixed typos, added example for reactivation
fdizazzo Nov 7, 2023
22e824a
docs: fixed typos and broken link in vlan configuration page
fdizazzo Nov 7, 2023
1b5a39b
Update docs/gateway-configuration/vlan-configuration.md
mattdibi Nov 8, 2023
16d818b
Update docs/gateway-configuration/vlan-configuration.md
mattdibi Nov 8, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Binary file added docs/gateway-configuration/images/vlan-interface-example.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
64 changes: 63 additions & 1 deletion docs/gateway-configuration/network-configuration.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -26,6 +26,7 @@ The **TCP/IP** tab contains the following configuration parameters:
- **Gateway** - specifies the default gateway for the unit. (Required field if the interface is designated as WAN and manually configured.)
- **DNS Servers** - provides a list of DNS servers, if the interface is designated as WAN and is manually configured.
- **Search Domains** - Not implemented.
- **MTU** - defines the Maximum Trasmission unit for IPv4 traffic on the selected interface, a value of 0 or empty delegates the MTU definition to the link layer.

If the network interface is *Enabled for LAN* and manually configured (i.e., not a DHCP client), the **DHCP & NAT** tab allows the DHCP server to be configured and/or NAT (IP forwarding with masquerading) to be enabled.

Expand Down Expand Up @@ -102,7 +103,7 @@ The following table describes all the properties related to the Network Configur
Name | Type | Description
-------------------------------------------------|----------|------------------------------------------
`net.interfaces` | String | Comma-separated list of the interface names in the device
`net.interface.<interface>.type` | String | The type of the network interface; possible values are: ETHERNET, WIFI, MODEM and LOOPBACK
`net.interface.<interface>.type` | String | The type of the network interface; possible values are: ETHERNET, WIFI, MODEM, VLAN and LOOPBACK
`net.interface.<interface>.config.wifi.mode` | String | For wifi interfaces, specify the modality; possible values are INFRA and MASTER
`net.interface.<interface>.config.nat.enabled` | Boolean | Enable the NAT feature

Expand All @@ -116,6 +117,7 @@ Name | Type | Description
`net.interface.<interface>.config.ip4.prefix` | Short | The IPv4 netmask assigned to the network interface
`net.interface.<interface>.config.ip4.gateway` | String | The IPv4 address of the default gateway
`net.interface.<interface>.config.ip4.dnsServers` | String | Comma-separated list of dns servers
`net.interface.<interface>.config.ip4.mtu` | Integer | The Maximum Transition Unit (MTU) for this interface

### IPv4 DHCP Server properties

Expand Down Expand Up @@ -148,6 +150,7 @@ Name | Type | Description
`net.interface.<interface>.config.ip6.dnsServers` | String | Comma-separated list of dns servers
`net.interface.<interface>.config.ip6.addr.gen.mode` | String | The IPv6 address generation mode; possible values are EUI64, STABLE_PRIVACY;
`net.interface.<interface>.config.ip6.privacy` | String | The IPv6 Privacy Extensions for SLAAC; possible values are DISABLED, ENABLED_PUBLIC_ADD, ENABLED_TEMP_ADD
`net.interface.<interface>.config.ip6.mtu` | Integer | The Maximum Transition Unit (MTU) for Ipv6 traffic on this interface. Requires NetworkManager 1.40 or newer

### WiFi Master (Access Point) properties

Expand Down Expand Up @@ -203,6 +206,16 @@ Name | Type | Description
`net.interface.<interface>.config.holdoff` | Integer | The holdoff option of the PPP daemon (in seconds)
`net.interface.<interface>.config.pppNum` | Integer | Assigned ppp interface number

### VLAN properties

Name | Type | Description
------------------------------------------------------|----------|------------------------------------------
`net.interface.<interface>.config.vlan.parent` | String | Physical interface Vlan is bound to
`net.interface.<interface>.config.vlan.id` | Integer | Vlan tag identifier, between 0 and 4094
`net.interface.<interface>.config.vlan.ingress` | String | Incoming traffic priorities in the format from:to, as comma separated pairs of unsigned integers (Optional)
`net.interface.<interface>.config.vlan.egress` | String | Outgoing traffic priorities in the format from:to, as comma separated pairs of unsigned integer (Optional)
`net.interface.<interface>.config.vlan.flags` | String | Configuration flags, between 0 and 15, default 1 (Optional)

## Network Configuration recipes

This section presents some snapshot examples to perform basic operations on networking. The snippets can be modified adapting them to the required configuration (i.e. changing the interface name in the property to be applied).
Expand Down Expand Up @@ -529,3 +542,52 @@ This section presents some snapshot examples to perform basic operations on netw
</esf:configuration>
</esf:configurations>
```
### Create a VLAN

```xml
<?xml version="1.0" encoding="UTF-8"?><esf:configurations xmlns:esf="http://eurotech.com/esf/2.0" xmlns:ocd="http://www.osgi.org/xmlns/metatype/v1.2.0">
<esf:configuration pid="org.eclipse.kura.net.admin.NetworkConfigurationService">
<esf:properties>
<esf:property array="false" encrypted="false" name="net.interfaces" type="String">
<esf:value>wlan0,lo,ens33,vlanFull,ens34</esf:value>
</esf:property>
<esf:property array="false" encrypted="false" name="net.interface.vlanFull.config.dhcpServer4.enabled" type="Boolean">
<esf:value>false</esf:value>
</esf:property>
<esf:property array="false" encrypted="false" name="net.interface.vlanFull.config.nat.enabled" type="Boolean">
<esf:value>false</esf:value>
</esf:property>
<esf:property array="false" encrypted="false" name="net.interface.vlanFull.config.dhcpClient4.enabled" type="Boolean">
<esf:value>false</esf:value>
</esf:property>
<esf:property array="false" encrypted="false" name="net.interface.vlanFull.type" type="String">
<esf:value>VLAN</esf:value>
</esf:property>
<esf:property array="false" encrypted="false" name="net.interface.vlanFull.config.ip4.status" type="String">
<esf:value>netIPv4StatusEnabledLAN</esf:value>
</esf:property>
<esf:property array="false" encrypted="false" name="net.interface.vlanFull.config.vlan.parent" type="String">
<esf:value>ens33</esf:value>
</esf:property>
<esf:property array="false" encrypted="false" name="net.interface.vlanFull.config.vlan.id" type="Integer">
<esf:value>41</esf:value>
</esf:property>
<esf:property array="false" encrypted="false" name="net.interface.vlanFull.config.vlan.flags" type="Integer">
<esf:value>1</esf:value>
</esf:property>
<esf:property array="false" encrypted="false" name="net.interface.vlanFull.config.vlan.ingress" type="String">
<esf:value>1:2,3:4</esf:value>
</esf:property>
<esf:property array="false" encrypted="false" name="net.interface.vlanFull.config.vlan.egress" type="String">
<esf:value>5:6</esf:value>
</esf:property>
<esf:property array="false" encrypted="false" name="net.interface.vlanFull.config.ip4.address" type="String">
<esf:value>192.168.41.100</esf:value>
</esf:property>
<esf:property array="false" encrypted="false" name="net.interface.vlanFull.config.ip4.prefix" type="Short">
<esf:value>24</esf:value>
</esf:property>
</esf:properties>
</esf:configuration>
</esf:configurations>
```
144 changes: 144 additions & 0 deletions docs/gateway-configuration/vlan-configuration.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,144 @@
# VLAN Configuration

For devices configured to use [NetworkManager](https://networkmanager.dev), it is possible to configure multiple VLAN interfaces. Take a look at our [installer profiles](../getting-started/install-kura.md#installer-types) to know which are supported.

A VLAN, or Virtual Local Area Network, is a network segmentation technology that allows a single physical network to be logically divided into multiple isolated networks. These virtual networks operate as if they are independent, even though they share the same physical infrastructure.
This is achieved via a VLAN ID, or VLAN tag, a numerical label added to network frames to identify the specific Virtual Local Area Network (VLAN) to which they belong. It's a critical component in VLAN technology, allowing network switches and routers to differentiate and route traffic within a VLAN. VLAN tags are added to the Ethernet frame's header, indicating which virtual network a data packet should be directed to when it traverses the physical network infrastructure. Therefore, VLANs must also be supported and configured on the network equipment a device is connected to.

A VLAN can be named freely, as long as it's 15 or less characters. A typical VLAN naming format is `physicalInterfaceName`.`vlanId` (eg. a vlan with id 100 on the interface eth0 would be named eth0.100).

This is achieved by NetworkManager by creating a virtual device bound to the underlying physical interface when Kura sets up a new VLAN connection.

## VLAN Configuration via Kura Snapshot upload
Currently, VLAN configuration is supported via uploading snapshot.xml fragments.

!!! warning
When creating a new VLAN be sure to include the `net.interfaces` parameter, containing both the previously existing network interfaces, either virtual or physical, and the name of the new VLAN to be created.

### Basic VLAN configuration example

The following example creates a VLAN with ID 40 over the ethernet interface ens33, naming it `ens33.40`, using a predefined IP address, enabled for LAN.

```xml
<?xml version="1.0" encoding="UTF-8"?>
<esf:configurations xmlns:esf="http://eurotech.com/esf/2.0" xmlns:ocd="http://www.osgi.org/xmlns/metatype/v1.2.0">
<esf:configuration pid="org.eclipse.kura.net.admin.NetworkConfigurationService">
<esf:properties>
<esf:property array="false" encrypted="false" name="net.interfaces" type="String">
<esf:value>lo,ens33,ens34,ens33.40</esf:value>
</esf:property>
<esf:property array="false" encrypted="false" name="net.interface.ens33.40.config.dhcpServer4.enabled" type="Boolean">
<esf:value>false</esf:value>
</esf:property>
<esf:property array="false" encrypted="false" name="net.interface.ens33.40.config.nat.enabled" type="Boolean">
<esf:value>false</esf:value>
</esf:property>
<esf:property array="false" encrypted="false" name="net.interface.ens33.40.config.dhcpClient4.enabled" type="Boolean">
<esf:value>false</esf:value>
</esf:property>
<esf:property array="false" encrypted="false" name="net.interface.ens33.40.type" type="String">
<esf:value>VLAN</esf:value>
</esf:property>
<esf:property array="false" encrypted="false" name="net.interface.ens33.40.config.ip4.status" type="String">
<esf:value>netIPv4StatusEnabledLAN</esf:value>
</esf:property>
<esf:property array="false" encrypted="false" name="net.interface.ens33.40.config.vlan.parent" type="String">
<esf:value>ens33</esf:value>
</esf:property>
<esf:property array="false" encrypted="false" name="net.interface.ens33.40.config.vlan.id" type="Integer">
<esf:value>40</esf:value>
</esf:property>
<esf:property array="false" encrypted="false" name="net.interface.ens33.40.config.ip4.address" type="String">
<esf:value>10.0.55.37</esf:value>
</esf:property>
<esf:property array="false" encrypted="false" name="net.interface.ens33.40.config.ip4.prefix" type="Short">
<esf:value>24</esf:value>
</esf:property>
</esf:properties>
</esf:configuration>
</esf:configurations>
```

### Complete VLAN configuration example

The following example creates a VLAN with ID 41 over the ethernet interface ens33, naming it `ens33.41`, using a predefined IP address, enabled for WAN.
This example also sets the 'flags' and 'traffic priority' optional parameters as described in [Network Manager API documentation](https://networkmanager.dev/docs/api/latest/settings-vlan.html).

```xml
<?xml version="1.0" encoding="UTF-8"?>
<esf:configurations xmlns:esf="http://eurotech.com/esf/2.0" xmlns:ocd="http://www.osgi.org/xmlns/metatype/v1.2.0">
<esf:configuration pid="org.eclipse.kura.net.admin.NetworkConfigurationService">
<esf:properties>
<esf:property array="false" encrypted="false" name="net.interfaces" type="String">
<esf:value>lo,ens33,ens34,ens33.41</esf:value>
</esf:property>
<esf:property array="false" encrypted="false" name="net.interface.ens33.41.config.dhcpServer4.enabled" type="Boolean">
<esf:value>false</esf:value>
</esf:property>
<esf:property array="false" encrypted="false" name="net.interface.ens33.41.config.nat.enabled" type="Boolean">
<esf:value>false</esf:value>
</esf:property>
<esf:property array="false" encrypted="false" name="net.interface.ens33.41.config.dhcpClient4.enabled" type="Boolean">
<esf:value>false</esf:value>
</esf:property>
<esf:property array="false" encrypted="false" name="net.interface.ens33.41.type" type="String">
<esf:value>VLAN</esf:value>
</esf:property>
<esf:property array="false" encrypted="false" name="net.interface.ens33.41.config.ip4.gateway" type="String">
<esf:value>192.168.41.254</esf:value>
</esf:property>
<esf:property array="false" encrypted="false" name="net.interface.ens33.41.config.ip4.status" type="String">
<esf:value>netIPv4StatusEnabledWAN</esf:value>
</esf:property>
<esf:property array="false" encrypted="false" name="net.interface.vlanFull.config.ip4.dnsServers" type="String">
<esf:value>8.8.8.8</esf:value>
</esf:property>
<esf:property array="false" encrypted="false" name="net.interface.ens33.41.config.vlan.parent" type="String">
<esf:value>ens33</esf:value>
</esf:property>
<esf:property array="false" encrypted="false" name="net.interface.ens33.41.config.vlan.id" type="Integer">
<esf:value>41</esf:value>
</esf:property>
<esf:property array="false" encrypted="false" name="net.interface.ens33.41.config.ip4.address" type="String">
<esf:value>192.168.41.1</esf:value>
</esf:property>
<esf:property array="false" encrypted="false" name="net.interface.ens33.41.config.ip4.prefix" type="Short">
<esf:value>24</esf:value>
</esf:property>
<esf:property array="false" encrypted="false" name="net.interface.ens33.41.config.vlan.flags" type="Integer">
<esf:value>1</esf:value>
</esf:property>
<esf:property array="false" encrypted="false" name="net.interface.ens33.41.config.vlan.ingress" type="String">
<esf:value>1:2,3:4</esf:value>
</esf:property>
<esf:property array="false" encrypted="false" name="net.interface.ens33.41.config.vlan.egress" type="String">
<esf:value>5:6</esf:value>
</esf:property>
</esf:properties>
</esf:configuration>
</esf:configurations>
```


## VLAN Management
Once a VLAN is created it can be managed via the Kura UI just like any other Ethernet interface.

![VLAN UI management](./images/vlan-interface-example.png)

!!! warning
Setting a VLAN status to "_Disabled_" deletes its configuration in NetworkManager and the related virtual interface from the system. Although it will is no longer be visible on the UI, all the configurations are left in Kura. Therefore the VLAN can be restored by setting the `net.interface.<interface>.config.ip4.status` to `netIPv4StatusEnabledLAN` or `netIPv4StatusEnabledWAN` via snapshot upload, then resume configuration via UI.

As an example, the configuration to reactivate a disabled VLAN named ens33.40 would be as follows:

```xml
<?xml version="1.0" encoding="UTF-8"?>
<esf:configurations xmlns:esf="http://eurotech.com/esf/2.0" xmlns:ocd="http://www.osgi.org/xmlns/metatype/v1.2.0">
<esf:configuration pid="org.eclipse.kura.net.admin.NetworkConfigurationService">
<esf:properties>
<esf:property array="false" encrypted="false" name="net.interface.ens33.40.config.ip4.status" type="String">
<esf:value>netIPv4StatusEnabledLAN</esf:value>
</esf:property>
</esf:properties>
</esf:configuration>
</esf:configurations>
```
1 change: 1 addition & 0 deletions mkdocs.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,7 @@ nav:
- Wi-Fi Configuration: gateway-configuration/wifi-configuration.md
- Wi-Fi 802.1x Configuration: gateway-configuration/wifi-configuration-8021x.md
- Cellular Configuration: gateway-configuration/cellular-configuration.md
- VLAN Configuration: gateway-configuration/vlan-configuration.md
- Firewall Configuration: gateway-configuration/firewall-configuration.md
- Network Threat Manager: gateway-configuration/network-threat-manager.md
- Cloud Connections:
Expand Down
Loading