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