diff options
Diffstat (limited to 'doc/rtd/topics/network-config-format-v1.rst')
| -rw-r--r-- | doc/rtd/topics/network-config-format-v1.rst | 625 |
1 files changed, 0 insertions, 625 deletions
diff --git a/doc/rtd/topics/network-config-format-v1.rst b/doc/rtd/topics/network-config-format-v1.rst deleted file mode 100644 index a9dd31af..00000000 --- a/doc/rtd/topics/network-config-format-v1.rst +++ /dev/null @@ -1,625 +0,0 @@ -.. _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 :ref:`base_config_reference`. - -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**: *<desired device 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**: *<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**: *<MTU SizeBytes>* - -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**: *<desired device 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**: *<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**: *<List of network device names>* - -The ``bond_interfaces`` key accepts a list of network device ``name`` values -from the configuration. This list may be empty. - -**mtu**: *<MTU SizeBytes>* - -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**: *<Dictionary of key: value bonding parameter pairs>* - -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**: *<MTU SizeBytes>* - -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 |