1.. _network_config_v1:
2
3Networking Config Version 1
4===========================
5
6This network configuration format lets users customize their instance's
7networking interfaces by assigning subnet configuration, virtual device
8creation (bonds, bridges, vlans) routes and DNS configuration.
9
10Required elements of a Network Config Version 1 are ``config`` and
11``version``.
12
13Cloud-init will read this format from system config.
14For example the following could be present in
15``/etc/cloud/cloud.cfg.d/custom-networking.cfg``:
16
17.. code-block:: yaml
18
19  network:
20    version: 1
21    config:
22    - type: physical
23      name: eth0
24      subnets:
25        - type: dhcp
26
27The :ref:`datasource_nocloud` datasource can also provide cloud-init
28networking configuration in this Format.
29
30Configuration Types
31-------------------
32Within the network ``config`` portion, users include a list of configuration
33types.  The current list of support ``type`` values are as follows:
34
35- Physical (``physical``)
36- Bond (``bond``)
37- Bridge (``bridge``)
38- VLAN (``vlan``)
39- Nameserver (``nameserver``)
40- Route (``route``)
41
42Physical, Bond, Bridge and VLAN types may also include IP configuration under
43the key ``subnets``.
44
45- Subnet/IP (``subnets``)
46
47
48Physical
49~~~~~~~~
50The ``physical`` type configuration represents a "physical" network device,
51typically Ethernet-based.  At least one of of these entries is required for
52external network connectivity.  Type ``physical`` requires only one key:
53``name``.  A ``physical`` device may contain some or all of the following
54keys:
55
56**name**: *<desired device name>*
57
58A devices name must be less than 15 characters.  Names exceeding the maximum
59will be truncated. This is a limitation of the Linux kernel network-device
60structure.
61
62**mac_address**: *<MAC Address>*
63
64The MAC Address is a device unique identifier that most Ethernet-based network
65devices possess.  Specifying a MAC Address is optional.
66
67.. note::
68
69  MAC addresses must be strings. As MAC addresses which consist of only the
70  digits 0-9 (i.e. no hex a-f) can be interpreted as a base 60 integer per
71  the `YAML 1.1 spec`_ it is best practice to quote all MAC addresses to ensure
72  they are parsed as strings regardless of value.
73
74.. _YAML 1.1 spec: https://yaml.org/type/int.html
75
76.. note::
77
78  Cloud-init will handle the persistent mapping between a
79  device's ``name`` and the ``mac_address``.
80
81**mtu**: *<MTU SizeBytes>*
82
83The MTU key represents a device's Maximum Transmission Unit, the largest size
84packet or frame, specified in octets (eight-bit bytes), that can be sent in a
85packet- or frame-based network.  Specifying ``mtu`` is optional.
86
87.. note::
88
89  The possible supported values of a device's MTU is not available at
90  configuration time.  It's possible to specify a value too large or to
91  small for a device and may be ignored by the device.
92
93
94**Physical Example**::
95
96  network:
97    version: 1
98    config:
99      # Simple network adapter
100      - type: physical
101        name: interface0
102        mac_address: '00:11:22:33:44:55'
103      # Second nic with Jumbo frames
104      - type: physical
105        name: jumbo0
106        mac_address: aa:11:22:33:44:55
107        mtu: 9000
108      # 10G pair
109      - type: physical
110        name: gbe0
111        mac_address: cd:11:22:33:44:00
112      - type: physical
113        name: gbe1
114        mac_address: cd:11:22:33:44:02
115
116Bond
117~~~~
118A ``bond`` type will configure a Linux software Bond with one or more network
119devices.  A ``bond`` type requires the following keys:
120
121**name**: *<desired device name>*
122
123A devices name must be less than 15 characters.  Names exceeding the maximum
124will be truncated. This is a limitation of the Linux kernel network-device
125structure.
126
127**mac_address**: *<MAC Address>*
128
129When specifying MAC Address on a bond this value will be assigned to the bond
130device and may be different than the MAC address of any of the underlying
131bond interfaces.  Specifying a MAC Address is optional.  If ``mac_address`` is
132not present, then the bond will use one of the MAC Address values from one of
133the bond interfaces.
134
135.. note::
136
137  MAC addresses must be strings. As MAC addresses which consist of only the
138  digits 0-9 (i.e. no hex a-f) can be interpreted as a base 60 integer per
139  the `YAML 1.1 spec`_ it is best practice to quote all MAC addresses to ensure
140  they are parsed as strings regardless of value.
141
142.. _YAML 1.1 spec: https://yaml.org/type/int.html
143
144**bond_interfaces**: *<List of network device names>*
145
146The ``bond_interfaces`` key accepts a list of network device ``name`` values
147from the configuration.  This list may be empty.
148
149**mtu**: *<MTU SizeBytes>*
150
151The MTU key represents a device's Maximum Transmission Unit, the largest size
152packet or frame, specified in octets (eight-bit bytes), that can be sent in a
153packet- or frame-based network.  Specifying ``mtu`` is optional.
154
155.. note::
156
157  The possible supported values of a device's MTU is not available at
158  configuration time.  It's possible to specify a value too large or to
159  small for a device and may be ignored by the device.
160
161**params**:  *<Dictionary of key: value bonding parameter pairs>*
162
163The ``params`` key in a bond holds a dictionary of bonding parameters.
164This dictionary may be empty. For more details on what the various bonding
165parameters mean please read the Linux Kernel Bonding.txt.
166
167Valid ``params`` keys are:
168
169  - ``active_slave``: Set bond attribute
170  - ``ad_actor_key``: Set bond attribute
171  - ``ad_actor_sys_prio``: Set bond attribute
172  - ``ad_actor_system``: Set bond attribute
173  - ``ad_aggregator``: Set bond attribute
174  - ``ad_num_ports``: Set bond attribute
175  - ``ad_partner_key``: Set bond attribute
176  - ``ad_partner_mac``: Set bond attribute
177  - ``ad_select``: Set bond attribute
178  - ``ad_user_port_key``: Set bond attribute
179  - ``all_slaves_active``: Set bond attribute
180  - ``arp_all_targets``: Set bond attribute
181  - ``arp_interval``: Set bond attribute
182  - ``arp_ip_target``: Set bond attribute
183  - ``arp_validate``: Set bond attribute
184  - ``downdelay``: Set bond attribute
185  - ``fail_over_mac``: Set bond attribute
186  - ``lacp_rate``: Set bond attribute
187  - ``lp_interval``: Set bond attribute
188  - ``miimon``: Set bond attribute
189  - ``mii_status``: Set bond attribute
190  - ``min_links``: Set bond attribute
191  - ``mode``: Set bond attribute
192  - ``num_grat_arp``: Set bond attribute
193  - ``num_unsol_na``: Set bond attribute
194  - ``packets_per_slave``: Set bond attribute
195  - ``primary``: Set bond attribute
196  - ``primary_reselect``: Set bond attribute
197  - ``queue_id``: Set bond attribute
198  - ``resend_igmp``: Set bond attribute
199  - ``slaves``: Set bond attribute
200  - ``tlb_dynamic_lb``: Set bond attribute
201  - ``updelay``: Set bond attribute
202  - ``use_carrier``: Set bond attribute
203  - ``xmit_hash_policy``: Set bond attribute
204
205**Bond Example**::
206
207   network:
208    version: 1
209    config:
210      # Simple network adapter
211      - type: physical
212        name: interface0
213        mac_address: '00:11:22:33:44:55'
214      # 10G pair
215      - type: physical
216        name: gbe0
217        mac_address: cd:11:22:33:44:00
218      - type: physical
219        name: gbe1
220        mac_address: cd:11:22:33:44:02
221      - type: bond
222        name: bond0
223        bond_interfaces:
224          - gbe0
225          - gbe1
226        params:
227          bond-mode: active-backup
228
229Bridge
230~~~~~~
231Type ``bridge`` requires the following keys:
232
233- ``name``: Set the name of the bridge.
234- ``bridge_interfaces``: Specify the ports of a bridge via their ``name``.
235  This list may be empty.
236- ``params``:  A list of bridge params.  For more details, please read the
237  bridge-utils-interfaces manpage.
238
239Valid keys are:
240
241  - ``bridge_ageing``: Set the bridge's ageing value.
242  - ``bridge_bridgeprio``: Set the bridge device network priority.
243  - ``bridge_fd``: Set the bridge's forward delay.
244  - ``bridge_hello``: Set the bridge's hello value.
245  - ``bridge_hw``: Set the bridge's MAC address.
246  - ``bridge_maxage``: Set the bridge's maxage value.
247  - ``bridge_maxwait``:  Set how long network scripts should wait for the
248    bridge to be up.
249  - ``bridge_pathcost``:  Set the cost of a specific port on the bridge.
250  - ``bridge_portprio``:  Set the priority of a specific port on the bridge.
251  - ``bridge_ports``:  List of devices that are part of the bridge.
252  - ``bridge_stp``:  Set spanning tree protocol on or off.
253  - ``bridge_waitport``: Set amount of time in seconds to wait on specific
254    ports to become available.
255
256
257**Bridge Example**::
258
259   network:
260    version: 1
261    config:
262      # Simple network adapter
263      - type: physical
264        name: interface0
265        mac_address: '00:11:22:33:44:55'
266      # Second nic with Jumbo frames
267      - type: physical
268        name: jumbo0
269        mac_address: aa:11:22:33:44:55
270        mtu: 9000
271      - type: bridge
272        name: br0
273        bridge_interfaces:
274          - jumbo0
275        params:
276          bridge_ageing: 250
277          bridge_bridgeprio: 22
278          bridge_fd: 1
279          bridge_hello: 1
280          bridge_maxage: 10
281          bridge_maxwait: 0
282          bridge_pathcost:
283            - jumbo0 75
284          bridge_pathprio:
285            - jumbo0 28
286          bridge_stp: 'off'
287          bridge_maxwait:
288            - jumbo0 0
289
290
291VLAN
292~~~~
293Type ``vlan`` requires the following keys:
294
295- ``name``: Set the name of the VLAN
296- ``vlan_link``: Specify the underlying link via its ``name``.
297- ``vlan_id``: Specify the VLAN numeric id.
298
299The following optional keys are supported:
300
301**mtu**: *<MTU SizeBytes>*
302
303The MTU key represents a device's Maximum Transmission Unit, the largest size
304packet or frame, specified in octets (eight-bit bytes), that can be sent in a
305packet- or frame-based network.  Specifying ``mtu`` is optional.
306
307.. note::
308
309  The possible supported values of a device's MTU is not available at
310  configuration time.  It's possible to specify a value too large or to
311  small for a device and may be ignored by the device.
312
313
314**VLAN Example**::
315
316   network:
317     version: 1
318     config:
319       # Physical interfaces.
320       - type: physical
321         name: eth0
322         mac_address: c0:d6:9f:2c:e8:80
323       # VLAN interface.
324       - type: vlan
325         name: eth0.101
326         vlan_link: eth0
327         vlan_id: 101
328         mtu: 1500
329
330Nameserver
331~~~~~~~~~~
332
333Users can specify a ``nameserver`` type.  Nameserver dictionaries include
334the following keys:
335
336- ``address``: List of IPv4 or IPv6 address of nameservers.
337- ``search``: List of of hostnames to include in the resolv.conf search path.
338- ``interface``: Optional. Ties the nameserver definition to the specified
339  interface. The value specified here must match the `name` of an interface
340  defined in this config. If unspecified, this nameserver will be considered
341  a global nameserver.
342
343**Nameserver Example**::
344
345  network:
346    version: 1
347    config:
348      - type: physical
349        name: interface0
350        mac_address: '00:11:22:33:44:55'
351        subnets:
352           - type: static
353             address: 192.168.23.14/27
354             gateway: 192.168.23.1
355      - type: nameserver
356        interface: interface0  # Ties nameserver to interface0 only
357        address:
358          - 192.168.23.2
359          - 8.8.8.8
360        search:
361          - exemplary
362
363
364
365Route
366~~~~~
367
368Users can include static routing information as well.  A ``route`` dictionary
369has the following keys:
370
371- ``destination``: IPv4 network address with CIDR netmask notation.
372- ``gateway``: IPv4 gateway address with CIDR netmask notation.
373- ``metric``: Integer which sets the network metric value for this route.
374
375**Route Example**::
376
377  network:
378    version: 1
379    config:
380      - type: physical
381        name: interface0
382        mac_address: '00:11:22:33:44:55'
383        subnets:
384           - type: static
385             address: 192.168.23.14/24
386             gateway: 192.168.23.1
387      - type: route
388        destination: 192.168.24.0/24
389        gateway: 192.168.24.1
390        metric: 3
391
392Subnet/IP
393~~~~~~~~~
394
395For any network device (one of the Config Types) users can define a list of
396``subnets`` which contain ip configuration dictionaries.  Multiple subnet
397entries will create interface alias allowing a single interface to use
398different ip configurations.
399
400Valid keys for ``subnets`` include the following:
401
402- ``type``: Specify the subnet type.
403- ``control``: Specify manual, auto or hotplug.  Indicates how the interface
404  will be handled during boot.
405- ``address``: IPv4 or IPv6 address.  It may include CIDR netmask notation.
406- ``netmask``: IPv4 subnet mask in dotted format or CIDR notation.
407- ``gateway``: IPv4 address of the default gateway for this subnet.
408- ``dns_nameservers``: Specify a list of IPv4 dns server IPs to end up in
409  resolv.conf.
410- ``dns_search``: Specify a list of search paths to be included in
411  resolv.conf.
412- ``routes``:  Specify a list of routes for a given interface
413
414
415Subnet types are one of the following:
416
417- ``dhcp4``: Configure this interface with IPv4 dhcp.
418- ``dhcp``: Alias for ``dhcp4``
419- ``dhcp6``: Configure this interface with IPv6 dhcp.
420- ``static``: Configure this interface with a static IPv4.
421- ``static6``: Configure this interface with a static IPv6 .
422- ``ipv6_dhcpv6-stateful``: Configure this interface with ``dhcp6``
423- ``ipv6_dhcpv6-stateless``: Configure this interface with SLAAC and DHCP
424- ``ipv6_slaac``: Configure address with SLAAC
425
426When making use of ``dhcp`` or either of the ``ipv6_dhcpv6`` types,
427no additional configuration is needed in the subnet dictionary.
428
429Using ``ipv6_dhcpv6-stateless`` or ``ipv6_slaac`` allows the IPv6 address to be
430automatically configured with StateLess Address AutoConfiguration (`SLAAC`_).
431SLAAC requires support from the network, so verify that your cloud or network
432offering has support before trying it out. With ``ipv6_dhcpv6-stateless``,
433DHCPv6 is still used to fetch other subnet details such as gateway or DNS
434servers. If you only want to discover the address, use ``ipv6_slaac``.
435
436
437**Subnet DHCP Example**::
438
439   network:
440     version: 1
441     config:
442       - type: physical
443         name: interface0
444         mac_address: '00:11:22:33:44:55'
445         subnets:
446           - type: dhcp
447
448
449**Subnet Static Example**::
450
451   network:
452     version: 1
453     config:
454       - type: physical
455         name: interface0
456         mac_address: '00:11:22:33:44:55'
457         subnets:
458           - type: static
459             address: 192.168.23.14/27
460             gateway: 192.168.23.1
461             dns_nameservers:
462               - 192.168.23.2
463               - 8.8.8.8
464             dns_search:
465               - exemplary.maas
466
467The following will result in an ``interface0`` using DHCP and ``interface0:1``
468using the static subnet configuration.
469
470**Multiple subnet Example**::
471
472   network:
473     version: 1
474     config:
475       - type: physical
476         name: interface0
477         mac_address: '00:11:22:33:44:55'
478         subnets:
479           - type: dhcp
480           - type: static
481             address: 192.168.23.14/27
482             gateway: 192.168.23.1
483             dns_nameservers:
484               - 192.168.23.2
485               - 8.8.8.8
486             dns_search:
487               - exemplary
488
489**Subnet with routes Example**::
490
491   network:
492     version: 1
493     config:
494       - type: physical
495         name: interface0
496         mac_address: '00:11:22:33:44:55'
497         subnets:
498           - type: dhcp
499           - type: static
500             address: 10.184.225.122
501             netmask: 255.255.255.252
502             routes:
503               - gateway: 10.184.225.121
504                 netmask: 255.240.0.0
505                 network: 10.176.0.0
506               - gateway: 10.184.225.121
507                 netmask: 255.240.0.0
508                 network: 10.208.0.0
509
510
511Multi-layered configurations
512----------------------------
513
514Complex networking sometimes uses layers of configuration.  The syntax allows
515users to build those layers one at a time.  All of the virtual network devices
516supported allow specifying an underlying device by their ``name`` value.
517
518**Bonded VLAN Example**::
519
520  network:
521    version: 1
522    config:
523      # 10G pair
524      - type: physical
525        name: gbe0
526        mac_address: cd:11:22:33:44:00
527      - type: physical
528        name: gbe1
529        mac_address: cd:11:22:33:44:02
530      # Bond.
531      - type: bond
532        name: bond0
533        bond_interfaces:
534          - gbe0
535          - gbe1
536        params:
537          bond-mode: 802.3ad
538          bond-lacp-rate: fast
539      # A Bond VLAN.
540      - type: vlan
541          name: bond0.200
542          vlan_link: bond0
543          vlan_id: 200
544          subnets:
545              - type: dhcp4
546
547More Examples
548-------------
549Some more examples to explore the various options available.
550
551**Multiple VLAN example**::
552
553  network:
554    version: 1
555    config:
556    - id: eth0
557      mac_address: d4:be:d9:a8:49:13
558      mtu: 1500
559      name: eth0
560      subnets:
561      - address: 10.245.168.16/21
562        dns_nameservers:
563        - 10.245.168.2
564        gateway: 10.245.168.1
565        type: static
566      type: physical
567    - id: eth1
568      mac_address: d4:be:d9:a8:49:15
569      mtu: 1500
570      name: eth1
571      subnets:
572      - address: 10.245.188.2/24
573        dns_nameservers: []
574        type: static
575      type: physical
576    - id: eth1.2667
577      mtu: 1500
578      name: eth1.2667
579      subnets:
580      - address: 10.245.184.2/24
581        dns_nameservers: []
582        type: static
583      type: vlan
584      vlan_id: 2667
585      vlan_link: eth1
586    - id: eth1.2668
587      mtu: 1500
588      name: eth1.2668
589      subnets:
590      - address: 10.245.185.1/24
591        dns_nameservers: []
592        type: static
593      type: vlan
594      vlan_id: 2668
595      vlan_link: eth1
596    - id: eth1.2669
597      mtu: 1500
598      name: eth1.2669
599      subnets:
600      - address: 10.245.186.1/24
601        dns_nameservers: []
602        type: static
603      type: vlan
604      vlan_id: 2669
605      vlan_link: eth1
606    - id: eth1.2670
607      mtu: 1500
608      name: eth1.2670
609      subnets:
610      - address: 10.245.187.2/24
611        dns_nameservers: []
612        type: static
613      type: vlan
614      vlan_id: 2670
615      vlan_link: eth1
616    - address: 10.245.168.2
617      search:
618      - dellstack
619      type: nameserver
620
621.. _SLAAC: https://tools.ietf.org/html/rfc4862
622
623.. vi: textwidth=78
624