.. _network_config_v1: Networking Config Version 1 =========================== This network configuration format lets users customize their instance's networking interfaces by assigning subnet configuration, virtual device creation (bonds, bridges, vlans) routes and DNS configuration. Required elements of a Network Config Version 1 are ``config`` and ``version``. Cloud-init will read this format from system config. For example the following could be present in ``/etc/cloud/cloud.cfg.d/custom-networking.cfg``: .. code-block:: yaml network: version: 1 config: - type: physical name: eth0 subnets: - type: dhcp The :ref:`datasource_nocloud` datasource can also provide cloud-init networking configuration in this Format. Configuration Types ------------------- Within the network ``config`` portion, users include a list of configuration types. The current list of support ``type`` values are as follows: - Physical (``physical``) - Bond (``bond``) - Bridge (``bridge``) - VLAN (``vlan``) - Nameserver (``nameserver``) - Route (``route``) Physical, Bond, Bridge and VLAN types may also include IP configuration under the key ``subnets``. - Subnet/IP (``subnets``) Physical ~~~~~~~~ The ``physical`` type configuration represents a "physical" network device, typically Ethernet-based. At least one of these entries is required for external network connectivity. Type ``physical`` requires only one key: ``name``. A ``physical`` device may contain some or all of the following keys: **name**: ** A devices name must be less than 15 characters. Names exceeding the maximum will be truncated. This is a limitation of the Linux kernel network-device structure. **mac_address**: ** The MAC Address is a device unique identifier that most Ethernet-based network devices possess. Specifying a MAC Address is optional. Letters must be lowercase. .. note:: MAC addresses must be strings. As MAC addresses which consist of only the digits 0-9 (i.e. no hex a-f) can be interpreted as a base 60 integer per the `YAML 1.1 spec`_ it is best practice to quote all MAC addresses to ensure they are parsed as strings regardless of value. .. _YAML 1.1 spec: https://yaml.org/type/int.html .. note:: Cloud-init will handle the persistent mapping between a device's ``name`` and the ``mac_address``. **mtu**: ** The MTU key represents a device's Maximum Transmission Unit, the largest size packet or frame, specified in octets (eight-bit bytes), that can be sent in a packet- or frame-based network. Specifying ``mtu`` is optional. .. note:: The possible supported values of a device's MTU is not available at configuration time. It's possible to specify a value too large or to small for a device and may be ignored by the device. **Physical Example**:: network: version: 1 config: # Simple network adapter - type: physical name: interface0 mac_address: '00:11:22:33:44:55' # Second nic with Jumbo frames - type: physical name: jumbo0 mac_address: aa:11:22:33:44:55 mtu: 9000 # 10G pair - type: physical name: gbe0 mac_address: cd:11:22:33:44:00 - type: physical name: gbe1 mac_address: cd:11:22:33:44:02 Bond ~~~~ A ``bond`` type will configure a Linux software Bond with one or more network devices. A ``bond`` type requires the following keys: **name**: ** A devices name must be less than 15 characters. Names exceeding the maximum will be truncated. This is a limitation of the Linux kernel network-device structure. **mac_address**: ** When specifying MAC Address on a bond this value will be assigned to the bond device and may be different than the MAC address of any of the underlying bond interfaces. Specifying a MAC Address is optional. If ``mac_address`` is not present, then the bond will use one of the MAC Address values from one of the bond interfaces. .. note:: MAC addresses must be strings. As MAC addresses which consist of only the digits 0-9 (i.e. no hex a-f) can be interpreted as a base 60 integer per the `YAML 1.1 spec`_ it is best practice to quote all MAC addresses to ensure they are parsed as strings regardless of value. .. _YAML 1.1 spec: https://yaml.org/type/int.html **bond_interfaces**: ** The ``bond_interfaces`` key accepts a list of network device ``name`` values from the configuration. This list may be empty. **mtu**: ** The MTU key represents a device's Maximum Transmission Unit, the largest size packet or frame, specified in octets (eight-bit bytes), that can be sent in a packet- or frame-based network. Specifying ``mtu`` is optional. .. note:: The possible supported values of a device's MTU is not available at configuration time. It's possible to specify a value too large or to small for a device and may be ignored by the device. **params**: ** The ``params`` key in a bond holds a dictionary of bonding parameters. This dictionary may be empty. For more details on what the various bonding parameters mean please read the Linux Kernel Bonding.txt. Valid ``params`` keys are: - ``active_slave``: Set bond attribute - ``ad_actor_key``: Set bond attribute - ``ad_actor_sys_prio``: Set bond attribute - ``ad_actor_system``: Set bond attribute - ``ad_aggregator``: Set bond attribute - ``ad_num_ports``: Set bond attribute - ``ad_partner_key``: Set bond attribute - ``ad_partner_mac``: Set bond attribute - ``ad_select``: Set bond attribute - ``ad_user_port_key``: Set bond attribute - ``all_slaves_active``: Set bond attribute - ``arp_all_targets``: Set bond attribute - ``arp_interval``: Set bond attribute - ``arp_ip_target``: Set bond attribute - ``arp_validate``: Set bond attribute - ``downdelay``: Set bond attribute - ``fail_over_mac``: Set bond attribute - ``lacp_rate``: Set bond attribute - ``lp_interval``: Set bond attribute - ``miimon``: Set bond attribute - ``mii_status``: Set bond attribute - ``min_links``: Set bond attribute - ``mode``: Set bond attribute - ``num_grat_arp``: Set bond attribute - ``num_unsol_na``: Set bond attribute - ``packets_per_slave``: Set bond attribute - ``primary``: Set bond attribute - ``primary_reselect``: Set bond attribute - ``queue_id``: Set bond attribute - ``resend_igmp``: Set bond attribute - ``slaves``: Set bond attribute - ``tlb_dynamic_lb``: Set bond attribute - ``updelay``: Set bond attribute - ``use_carrier``: Set bond attribute - ``xmit_hash_policy``: Set bond attribute **Bond Example**:: network: version: 1 config: # Simple network adapter - type: physical name: interface0 mac_address: '00:11:22:33:44:55' # 10G pair - type: physical name: gbe0 mac_address: cd:11:22:33:44:00 - type: physical name: gbe1 mac_address: cd:11:22:33:44:02 - type: bond name: bond0 bond_interfaces: - gbe0 - gbe1 params: bond-mode: active-backup Bridge ~~~~~~ Type ``bridge`` requires the following keys: - ``name``: Set the name of the bridge. - ``bridge_interfaces``: Specify the ports of a bridge via their ``name``. This list may be empty. - ``params``: A list of bridge params. For more details, please read the bridge-utils-interfaces manpage. Valid keys are: - ``bridge_ageing``: Set the bridge's ageing value. - ``bridge_bridgeprio``: Set the bridge device network priority. - ``bridge_fd``: Set the bridge's forward delay. - ``bridge_hello``: Set the bridge's hello value. - ``bridge_hw``: Set the bridge's MAC address. - ``bridge_maxage``: Set the bridge's maxage value. - ``bridge_maxwait``: Set how long network scripts should wait for the bridge to be up. - ``bridge_pathcost``: Set the cost of a specific port on the bridge. - ``bridge_portprio``: Set the priority of a specific port on the bridge. - ``bridge_ports``: List of devices that are part of the bridge. - ``bridge_stp``: Set spanning tree protocol on or off. - ``bridge_waitport``: Set amount of time in seconds to wait on specific ports to become available. **Bridge Example**:: network: version: 1 config: # Simple network adapter - type: physical name: interface0 mac_address: '00:11:22:33:44:55' # Second nic with Jumbo frames - type: physical name: jumbo0 mac_address: aa:11:22:33:44:55 mtu: 9000 - type: bridge name: br0 bridge_interfaces: - jumbo0 params: bridge_ageing: 250 bridge_bridgeprio: 22 bridge_fd: 1 bridge_hello: 1 bridge_maxage: 10 bridge_maxwait: 0 bridge_pathcost: - jumbo0 75 bridge_pathprio: - jumbo0 28 bridge_stp: 'off' bridge_maxwait: - jumbo0 0 VLAN ~~~~ Type ``vlan`` requires the following keys: - ``name``: Set the name of the VLAN - ``vlan_link``: Specify the underlying link via its ``name``. - ``vlan_id``: Specify the VLAN numeric id. The following optional keys are supported: **mtu**: ** The MTU key represents a device's Maximum Transmission Unit, the largest size packet or frame, specified in octets (eight-bit bytes), that can be sent in a packet- or frame-based network. Specifying ``mtu`` is optional. .. note:: The possible supported values of a device's MTU is not available at configuration time. It's possible to specify a value too large or to small for a device and may be ignored by the device. **VLAN Example**:: network: version: 1 config: # Physical interfaces. - type: physical name: eth0 mac_address: c0:d6:9f:2c:e8:80 # VLAN interface. - type: vlan name: eth0.101 vlan_link: eth0 vlan_id: 101 mtu: 1500 Nameserver ~~~~~~~~~~ Users can specify a ``nameserver`` type. Nameserver dictionaries include the following keys: - ``address``: List of IPv4 or IPv6 address of nameservers. - ``search``: List of hostnames to include in the resolv.conf search path. - ``interface``: Optional. Ties the nameserver definition to the specified interface. The value specified here must match the `name` of an interface defined in this config. If unspecified, this nameserver will be considered a global nameserver. **Nameserver Example**:: network: version: 1 config: - type: physical name: interface0 mac_address: '00:11:22:33:44:55' subnets: - type: static address: 192.168.23.14/27 gateway: 192.168.23.1 - type: nameserver interface: interface0 # Ties nameserver to interface0 only address: - 192.168.23.2 - 8.8.8.8 search: - exemplary Route ~~~~~ Users can include static routing information as well. A ``route`` dictionary has the following keys: - ``destination``: IPv4 network address with CIDR netmask notation. - ``gateway``: IPv4 gateway address with CIDR netmask notation. - ``metric``: Integer which sets the network metric value for this route. **Route Example**:: network: version: 1 config: - type: physical name: interface0 mac_address: '00:11:22:33:44:55' subnets: - type: static address: 192.168.23.14/24 gateway: 192.168.23.1 - type: route destination: 192.168.24.0/24 gateway: 192.168.24.1 metric: 3 Subnet/IP ~~~~~~~~~ For any network device (one of the Config Types) users can define a list of ``subnets`` which contain ip configuration dictionaries. Multiple subnet entries will create interface alias allowing a single interface to use different ip configurations. Valid keys for ``subnets`` include the following: - ``type``: Specify the subnet type. - ``control``: Specify manual, auto or hotplug. Indicates how the interface will be handled during boot. - ``address``: IPv4 or IPv6 address. It may include CIDR netmask notation. - ``netmask``: IPv4 subnet mask in dotted format or CIDR notation. - ``gateway``: IPv4 address of the default gateway for this subnet. - ``dns_nameservers``: Specify a list of IPv4 dns server IPs to end up in resolv.conf. - ``dns_search``: Specify a list of search paths to be included in resolv.conf. - ``routes``: Specify a list of routes for a given interface Subnet types are one of the following: - ``dhcp4``: Configure this interface with IPv4 dhcp. - ``dhcp``: Alias for ``dhcp4`` - ``dhcp6``: Configure this interface with IPv6 dhcp. - ``static``: Configure this interface with a static IPv4. - ``static6``: Configure this interface with a static IPv6 . - ``ipv6_dhcpv6-stateful``: Configure this interface with ``dhcp6`` - ``ipv6_dhcpv6-stateless``: Configure this interface with SLAAC and DHCP - ``ipv6_slaac``: Configure address with SLAAC When making use of ``dhcp`` or either of the ``ipv6_dhcpv6`` types, no additional configuration is needed in the subnet dictionary. Using ``ipv6_dhcpv6-stateless`` or ``ipv6_slaac`` allows the IPv6 address to be automatically configured with StateLess Address AutoConfiguration (`SLAAC`_). SLAAC requires support from the network, so verify that your cloud or network offering has support before trying it out. With ``ipv6_dhcpv6-stateless``, DHCPv6 is still used to fetch other subnet details such as gateway or DNS servers. If you only want to discover the address, use ``ipv6_slaac``. **Subnet DHCP Example**:: network: version: 1 config: - type: physical name: interface0 mac_address: '00:11:22:33:44:55' subnets: - type: dhcp **Subnet Static Example**:: network: version: 1 config: - type: physical name: interface0 mac_address: '00:11:22:33:44:55' subnets: - type: static address: 192.168.23.14/27 gateway: 192.168.23.1 dns_nameservers: - 192.168.23.2 - 8.8.8.8 dns_search: - exemplary.maas The following will result in an ``interface0`` using DHCP and ``interface0:1`` using the static subnet configuration. **Multiple subnet Example**:: network: version: 1 config: - type: physical name: interface0 mac_address: '00:11:22:33:44:55' subnets: - type: dhcp - type: static address: 192.168.23.14/27 gateway: 192.168.23.1 dns_nameservers: - 192.168.23.2 - 8.8.8.8 dns_search: - exemplary **Subnet with routes Example**:: network: version: 1 config: - type: physical name: interface0 mac_address: '00:11:22:33:44:55' subnets: - type: dhcp - type: static address: 10.184.225.122 netmask: 255.255.255.252 routes: - gateway: 10.184.225.121 netmask: 255.240.0.0 network: 10.176.0.0 - gateway: 10.184.225.121 netmask: 255.240.0.0 network: 10.208.0.0 Multi-layered configurations ---------------------------- Complex networking sometimes uses layers of configuration. The syntax allows users to build those layers one at a time. All of the virtual network devices supported allow specifying an underlying device by their ``name`` value. **Bonded VLAN Example**:: network: version: 1 config: # 10G pair - type: physical name: gbe0 mac_address: cd:11:22:33:44:00 - type: physical name: gbe1 mac_address: cd:11:22:33:44:02 # Bond. - type: bond name: bond0 bond_interfaces: - gbe0 - gbe1 params: bond-mode: 802.3ad bond-lacp-rate: fast # A Bond VLAN. - type: vlan name: bond0.200 vlan_link: bond0 vlan_id: 200 subnets: - type: dhcp4 More Examples ------------- Some more examples to explore the various options available. **Multiple VLAN example**:: network: version: 1 config: - id: eth0 mac_address: d4:be:d9:a8:49:13 mtu: 1500 name: eth0 subnets: - address: 10.245.168.16/21 dns_nameservers: - 10.245.168.2 gateway: 10.245.168.1 type: static type: physical - id: eth1 mac_address: d4:be:d9:a8:49:15 mtu: 1500 name: eth1 subnets: - address: 10.245.188.2/24 dns_nameservers: [] type: static type: physical - id: eth1.2667 mtu: 1500 name: eth1.2667 subnets: - address: 10.245.184.2/24 dns_nameservers: [] type: static type: vlan vlan_id: 2667 vlan_link: eth1 - id: eth1.2668 mtu: 1500 name: eth1.2668 subnets: - address: 10.245.185.1/24 dns_nameservers: [] type: static type: vlan vlan_id: 2668 vlan_link: eth1 - id: eth1.2669 mtu: 1500 name: eth1.2669 subnets: - address: 10.245.186.1/24 dns_nameservers: [] type: static type: vlan vlan_id: 2669 vlan_link: eth1 - id: eth1.2670 mtu: 1500 name: eth1.2670 subnets: - address: 10.245.187.2/24 dns_nameservers: [] type: static type: vlan vlan_id: 2670 vlan_link: eth1 - address: 10.245.168.2 search: - dellstack type: nameserver .. _SLAAC: https://tools.ietf.org/html/rfc4862 .. vi: textwidth=79