Skip to content

Commit 1b0845b

Browse files
jukkarjukkar
committed
doc: net: Add yaml configuration information
Add documentation about the network stack initialization using a yaml file. Signed-off-by: Jukka Rissanen <[email protected]>
1 parent a1aa2c7 commit 1b0845b

File tree

2 files changed

+311
-0
lines changed

2 files changed

+311
-0
lines changed

‎doc/connectivity/networking/index.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,7 @@ operation of the stacks and how they were implemented.
1313
overview.rst
1414
net-stack-architecture.rst
1515
net_config_guide.rst
16+
net_init_config.rst
1617
networking_with_host.rst
1718
network_monitoring.rst
1819
network_tracing.rst

‎doc/connectivity/networking/net_init_config.rst‎

Lines changed: 310 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,310 @@
1+
.. _network_initial_configuration:
2+
3+
Network Stack Initial Configuration
4+
###################################
5+
6+
.. contents::
7+
:local:
8+
:depth: 2
9+
10+
This document describes how the network config library can be used to do initial
11+
network stack configuration at runtime when the device boots. The network config
12+
library was mainly developed for testing purposes when a pre-defined setup is
13+
applied to the device when it is starting up. The configuration data is static
14+
and stored in ROM so the device is applied same initial network configuration at
15+
boot.
16+
17+
The configuration library can be used for example to enable DHCPv4 client at boot,
18+
or setup VLAN tags etc.
19+
20+
Network Configuration Options
21+
*****************************
22+
23+
The :kconfig:option:`CONFIG_NET_CONFIG_SETTINGS` enables the network configuration
24+
library. If it is not set, then no network setup is done and the application must
25+
setup network settings itself.
26+
27+
If the above setting is enabled, then two configuration options can be used to setup
28+
the network stack:
29+
30+
* Normal Kconfig options from ``CONFIG_NET_CONFIG_*`` branch.
31+
This is the legacy way and only suitable for simpler setups where there is only
32+
one network interface that needs to be setup at boot.
33+
See available Kconfig options in the network API documentation.
34+
35+
* A yaml configuration file ``net-init-config.yaml``.
36+
This allows user to describe the device hardware setup and what options to set
37+
even when the device have multiple network interfaces.
38+
39+
The net-init-config.yaml Syntax
40+
*******************************
41+
42+
The ``net-init-config.yaml`` can be placed to the application directory. When the
43+
application is compiled, this file is used to generate configuration that is then
44+
applied at runtime. The yaml file contents is verified using a schema located in
45+
``scripts/schemas/net-configuration-schema.yaml`` file.
46+
47+
User can use a different configuration yaml file by setting ``NET_INIT_CONFIG_FILE``
48+
when calling cmake or west.
49+
50+
.. code-block:: console
51+
52+
west build -p -b native_sim myapp -d build -- -DNET_INIT_CONFIG_FILE=my-net-init-config.yaml
53+
54+
The yaml file contains configuration sections for each network interface in the
55+
system, IEEE 802.15.4 configuration or SNTP configuration.
56+
57+
Example:
58+
59+
.. code-block:: yaml
60+
61+
net_init_config:
62+
network_interfaces:
63+
- &main-interface
64+
name: eth0
65+
set_name: main-eth0
66+
set_default: true
67+
flags:
68+
- NET_IF_NO_AUTO_START
69+
ipv6:
70+
status: true
71+
ipv6_addresses:
72+
- 2001:db8:110::1
73+
ipv6_multicast_addresses:
74+
- ff05::114
75+
- ff15::115
76+
prefixes:
77+
- address: "2001:db8::"
78+
len: 64
79+
lifetime: 1024
80+
hop_limit: 48
81+
multicast_hop_limit: 2
82+
dhcpv6:
83+
status: true
84+
do_request_address: true
85+
do_request_prefix: false
86+
ipv4:
87+
status: true
88+
ipv4_addresses:
89+
- 192.0.2.10/24
90+
ipv4_multicast_addresses:
91+
- 234.0.0.10
92+
gateway: 192.0.2.1
93+
time_to_live: 128
94+
multicast_time_to_live: 3
95+
dhcpv4_enabled: true
96+
ipv4_autoconf_enabled: true
97+
98+
- &vlan-interface
99+
set_name: vlan0
100+
bind_to: *main-interface
101+
flags:
102+
- ^NET_IF_PROMISC
103+
vlan:
104+
status: true
105+
tag: 2432
106+
ipv4:
107+
status: true
108+
dhcpv4_enabled: true
109+
110+
sntp:
111+
status: true
112+
server: sntp.example.com
113+
timeout: 30
114+
bind_to: *main-interface
115+
116+
In the above example, there are two network interfaces. One with name ``eth0`` which
117+
is changed to ``main-eth0`` and which is made the default interface. It has both
118+
IPv6 and IPv4 supported. There is also a VLAN interface that is bound to the first
119+
one. Its name is set to ``vlan0`` and it is enabled with tag ``2432``. The VLAN
120+
interface does not have IPv6 enabled, but IPv4 is together with DHCPv4 client support.
121+
Also SNTP is enabled and is using ``sntp.example.com`` server address. The SNTP is
122+
configured to use the first network interface.
123+
124+
The yaml File Configuration Options
125+
***********************************
126+
127+
These options are available for each network configuration domain.
128+
129+
.. table:: The ``network_interface`` options
130+
:align: left
131+
132+
+-------------+-------------+-----------------------------------------------------------------+
133+
| Option name | Type | Description |
134+
+=============+=============+=================================================================+
135+
| bind_to | reference | Bind this object to another network interface. |
136+
| | | This is useful for example for VLANs or other types of virtual |
137+
| | | interfaces. |
138+
+-------------+-------------+-----------------------------------------------------------------+
139+
| name | string | Existing name of the network interface. |
140+
| | | This is used to find the interface so that we can apply the |
141+
| | | subsequent configuration to it. |
142+
| | | Either this option or the ``device_name`` option must be given. |
143+
+-------------+-------------+-----------------------------------------------------------------+
144+
| device_name | string | Name of the device of the network interface. |
145+
| | | Either this or the ``name`` option must be set in the yaml file.|
146+
+-------------+-------------+-----------------------------------------------------------------+
147+
| set_name | string | New name of the network interface. |
148+
| | | This can be used to change the name of the interface if |
149+
| | | the default name is not suitable. |
150+
+-------------+-------------+-----------------------------------------------------------------+
151+
| set_default | bool | Set this network interface as default one which will be returned|
152+
| | | by the :c:func:`net_if_get_default` function call. |
153+
+-------------+-------------+-----------------------------------------------------------------+
154+
| flags | string list | Array of network interface flags that should be applied to this |
155+
| | | interface. See ``net_if_flag`` documentation for descriptions of|
156+
| | | the flags. If the flag starts with ``^`` then the flag value is |
157+
| | | cleared. |
158+
| | | Following flags can be set/cleared: |
159+
| | | ``NET_IF_POINTOPOINT``, ``NET_IF_PROMISC``, |
160+
| | | ``NET_IF_NO_AUTO_START``, ``NET_IF_FORWARD_MULTICASTS``, |
161+
| | | ``NET_IF_IPV6_NO_ND``, ``NET_IF_IPV6_NO_MLD`` |
162+
+-------------+-------------+-----------------------------------------------------------------+
163+
| ipv6 | struct | IPv6 configuration options. |
164+
+-------------+-------------+-----------------------------------------------------------------+
165+
| ipv4 | struct | IPv4 configuration options. |
166+
+-------------+-------------+-----------------------------------------------------------------+
167+
| vlan | struct | VLAN configuration options. |
168+
| | | Only applicable for Ethernet based interfaces. |
169+
+-------------+-------------+-----------------------------------------------------------------+
170+
171+
.. table:: The ``ipv6`` options
172+
:align: left
173+
174+
+--------------------------+-------------+----------------------------------------------------+
175+
| Option name | Type | Description |
176+
+==========================+=============+====================================================+
177+
| status | bool | Is the IPv6 enabled for this interface. |
178+
| | | If set to ``false``, then these options are no-op. |
179+
+--------------------------+-------------+----------------------------------------------------+
180+
| ipv6_addresses | string list | IPv6 addresses applied to this interface. |
181+
| | | The value can contain prefix length. |
182+
| | | Example: ``2001:db8::1/64`` |
183+
+--------------------------+-------------+----------------------------------------------------+
184+
| ipv6_multicast_addresses | string list | IPv6 multicast addresses applied to this interface.|
185+
+--------------------------+-------------+----------------------------------------------------+
186+
| hop_limit | int | Hop limit for the interface. |
187+
+--------------------------+-------------+----------------------------------------------------+
188+
| multicast_hop_limit | int | Multicast hop limit for the interface. |
189+
+--------------------------+-------------+----------------------------------------------------+
190+
| dhcpv6 | struct | DHCPv6 client options. |
191+
+--------------------------+-------------+----------------------------------------------------+
192+
| prefixes | list of | IPv6 prefixes. |
193+
| | structs | |
194+
+--------------------------+-------------+----------------------------------------------------+
195+
196+
.. table:: The ``dhcpv6`` options
197+
:align: left
198+
199+
+--------------------+------+-----------------------------------------------------------------+
200+
| Option name | Type | Description |
201+
+====================+======+=================================================================+
202+
| status | bool | Is DHCPv6 client enabled for this interface. |
203+
+--------------------+------+-----------------------------------------------------------------+
204+
| do_request_address | bool | Request IPv6 address. |
205+
+--------------------+------+-----------------------------------------------------------------+
206+
| do_request_prefix | bool | Requeest IPv6 prefix. |
207+
+--------------------+------+-----------------------------------------------------------------+
208+
209+
.. table:: The ``prefixes`` options
210+
:align: left
211+
212+
+-------------+--------+----------------------------------------------------------------------+
213+
| Option name | Type | Description |
214+
+=============+========+======================================================================+
215+
| address | string | IPv6 address. |
216+
+-------------+--------+----------------------------------------------------------------------+
217+
| len | int | Prefix length. |
218+
+-------------+--------+----------------------------------------------------------------------+
219+
| lifetime | int | Prefix lifetime. |
220+
+-------------+--------+----------------------------------------------------------------------+
221+
222+
.. table:: The ``ipv4`` options
223+
:align: left
224+
225+
+--------------------------+-------------+----------------------------------------------------+
226+
| Option name | Type | Description |
227+
+==========================+=============+====================================================+
228+
| status | bool | Is the IPv4 enabled for this interface. |
229+
| | | If set to ``false``, then these options are no-op. |
230+
+--------------------------+-------------+----------------------------------------------------+
231+
| ipv4_addresses | string list | IPv4 addresses applied to this interface. |
232+
| | | The value can contain netmask length. |
233+
| | | Example: ``192.0.2.1/24`` |
234+
+--------------------------+-------------+----------------------------------------------------+
235+
| ipv4_multicast_addresses | string list | IPv4 multicast addresses applied to this interface.|
236+
+--------------------------+-------------+----------------------------------------------------+
237+
| time_to_live | int | Time-to-live value for this interface. |
238+
+--------------------------+-------------+----------------------------------------------------+
239+
| multicast_time_to_live | int | Multicast time-to-live value for this interface. |
240+
+--------------------------+-------------+----------------------------------------------------+
241+
| gateway | string | Gateway IPv4 address. |
242+
+--------------------------+-------------+----------------------------------------------------+
243+
| ipv4_autoconf_enabled | bool | Is IPv4 auto-conf enabled to this interface. |
244+
+--------------------------+-------------+----------------------------------------------------+
245+
| dhcpv4_enabled | bool | Is DHCPv4 client enabled for this interface. |
246+
+--------------------------+-------------+----------------------------------------------------+
247+
| dhcpv4_server | struct | DHCPv4 server options. |
248+
+--------------------------+-------------+----------------------------------------------------+
249+
250+
.. table:: The ``dhcpv4_server`` options
251+
:align: left
252+
253+
+--------------------+--------+---------------------------------------------------------------+
254+
| Option name | Type | Description |
255+
+====================+========+===============================================================+
256+
| status | bool | Is DHCPv4 server enabled for this interface. |
257+
+--------------------+--------+---------------------------------------------------------------+
258+
| base_address | string | Request IPv6 address. |
259+
+--------------------+--------+---------------------------------------------------------------+
260+
261+
.. table:: The ``vlan`` options
262+
:align: left
263+
264+
+-------------+--------+----------------------------------------------------------------------+
265+
| Option name | Type | Description |
266+
+=============+========+======================================================================+
267+
| status | bool | Is VLAN enabled for this interface. |
268+
+-------------+--------+----------------------------------------------------------------------+
269+
| tag | int | VLAN tag applied to this interface. |
270+
+-------------+--------+----------------------------------------------------------------------+
271+
272+
.. table:: The ``sntp`` options
273+
:align: left
274+
275+
+-------------+-------------+-----------------------------------------------------------------+
276+
| Option name | Type | Description |
277+
+=============+=============+=================================================================+
278+
| status | bool | Is SNTP enabled. |
279+
+-------------+-------------+-----------------------------------------------------------------+
280+
| server | string | SNTP server address. |
281+
+-------------+-------------+-----------------------------------------------------------------+
282+
| timeout | int | SNTP server connection timeout. |
283+
+-------------+-------------+-----------------------------------------------------------------+
284+
| bind_to | reference | Connect to server using this network interface. |
285+
+-------------+-------------+-----------------------------------------------------------------+
286+
287+
.. table:: The ``ieee_802_15_4`` options
288+
:align: left
289+
290+
+-------------------+-----------+-------------------------------------------------------------+
291+
| Option name | Type | Description |
292+
+===================+===========+=============================================================+
293+
| status | bool | Is IEEE 802.15.4 enabled. |
294+
+-------------------+-----------+-------------------------------------------------------------+
295+
| bind_to | reference | Apply the options to this network interface. |
296+
+-------------------+-------------+-----------------------------------------------------------+
297+
| pan_id | int | PAN identifier. |
298+
+-------------------+-----------+-------------------------------------------------------------+
299+
| channel | int | Channel number. |
300+
+-------------------+-----------+-------------------------------------------------------------+
301+
| tx_power | int | Transmit power. |
302+
+-------------------+-----------+-------------------------------------------------------------+
303+
| ack_required | bool | Require acknowledgment. |
304+
+-------------------+-----------+-------------------------------------------------------------+
305+
| security_key | int array | IEEE 802.15.4 security key. Maximum length is 16. |
306+
+-------------------+-----------+-------------------------------------------------------------+
307+
| security_key_mode | int | IEEE 802.15.4 security key mode. |
308+
+-------------------+-----------+-------------------------------------------------------------+
309+
| security_level | int | IEEE 802.15.4 security level. |
310+
+-------------------+-----------+-------------------------------------------------------------+

0 commit comments

Comments
 (0)