cloud-init-dev team mailing list archive
-
cloud-init-dev team
-
Mailing list archive
-
Message #01852
[Merge] ~raharper/cloud-init:network-config-doc into cloud-init:master
Ryan Harper has proposed merging ~raharper/cloud-init:network-config-doc into cloud-init:master.
Requested reviews:
cloud init development team (cloud-init-dev)
For more details, see:
https://code.launchpad.net/~raharper/cloud-init/+git/cloud-init/+merge/321397
doc: document network configuration defaults, policy, formats and examples
Add documentation for cloud-init networking configuration formats, default
behavior, policy and other specific details about how network config is
consumed and utilized.
--
Your team cloud init development team is requested to review the proposed merge of ~raharper/cloud-init:network-config-doc into cloud-init:master.
diff --git a/doc/rtd/topics/network-config-format-eni.rst b/doc/rtd/topics/network-config-format-eni.rst
new file mode 100644
index 0000000..e4bcbe7
--- /dev/null
+++ b/doc/rtd/topics/network-config-format-eni.rst
@@ -0,0 +1,14 @@
+.. _network_config_eni:
+
+Network Configuration ENI
+-------------------------
+
+`Cloud-init`_ supports reading and writing network config in the ``ENI`` format
+which is consumed by the ``ifupdown`` tool to parse and apply network configuration.
+
+Please reference existing `documentation`_ for the ``/etc/network/interfaces(5)``
+format.
+
+.. _Cloud-init: https://launchpad.net/cloud-init
+.. _documentation: http://manpages.ubuntu.com/manpages/trusty/en/man5/interfaces.5.html
+.. vi: textwidth=78
diff --git a/doc/rtd/topics/network-config-format-v1.rst b/doc/rtd/topics/network-config-format-v1.rst
new file mode 100644
index 0000000..dc78657
--- /dev/null
+++ b/doc/rtd/topics/network-config-format-v1.rst
@@ -0,0 +1,545 @@
+.. _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.
+
+Cloud-init accepts a YAML input under the ``system_info`` config
+namespace. The ``network_config`` key indicate that a user would like to
+specify a custom networking configuration. Required elements of a network
+configuration are ``config`` and ``version``. ::
+
+ system_info:
+ network:
+ config: []
+ version: 1
+
+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 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.
+
+
+.. 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.
+
+
+**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.
+
+**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.
+
+**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 of hostnames to include in the resolv.conf search path.
+
+**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:
+ 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 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_nameserver``: 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 .
+
+When making use of ``dhcp`` types, no additional configuration is needed in the
+subnet dictionary.
+
+
+**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
+
+.. vi: textwidth=78
diff --git a/doc/rtd/topics/network-config-format-v2.rst b/doc/rtd/topics/network-config-format-v2.rst
new file mode 100644
index 0000000..c76e585
--- /dev/null
+++ b/doc/rtd/topics/network-config-format-v2.rst
@@ -0,0 +1,498 @@
+.. _network_config_v2:
+
+Networking Config Version 2
+===========================
+
+Cloud-init's support for Version 2 network config is a subset of the
+version 2 format defined for the `netplan`_ tool. Cloud-init supports
+both reading and writing of Version 2; the latter support requires a
+distro with `netplan`_ present.
+
+Cloud-init accepts a YAML input under the ``system_info`` config
+namespace. The ``network`` key indicate that a user would like to specify a
+custom networking configuration. Required elements of a network configuration
+are ``version`` and one or more of possible device types. ::
+
+ system_info:
+ network:
+ version: 2
+ ethernets: []
+
+Supported device ``types`` values are as follows:
+
+- Ethernets (``ethernets``)
+- Bonds (``bonds``)
+- Bridges (``bridges``)
+- VLANs (``vlans``)
+
+Each type block contains device definitions as a map where the keys (called
+"configuration IDs"). Each entry under the ``types`` may include IP and/or
+device configuration.
+
+Cloud-init does not current support ``wifis`` type that is present in native
+`netplan`_.
+
+
+Device configuration IDs
+------------------------
+
+The key names below the per-device-type definition maps (like ``ethernets:``)
+are called "ID"s. They must be unique throughout the entire set of
+configuration files. Their primary purpose is to serve as anchor names for
+composite devices, for example to enumerate the members of a bridge that is
+currently being defined.
+
+There are two physically/structurally different classes of device definitions,
+and the ID field has a different interpretation for each:
+
+Physical devices
+
+: (Examples: ethernet, wifi) These can dynamically come and go between
+ reboots and even during runtime (hotplugging). In the generic case, they
+ can be selected by ``match:`` rules on desired properties, such as name/name
+ pattern, MAC address, driver, or device paths. In general these will match
+ any number of devices (unless they refer to properties which are unique
+ such as the full path or MAC address), so without further knowledge about
+ the hardware these will always be considered as a group.
+
+ It is valid to specify no match rules at all, in which case the ID field is
+ simply the interface name to be matched. This is mostly useful if you want
+ to keep simple cases simple, and it's how network device configuration has
+ been done for a long time.
+
+ If there are ``match``: rules, then the ID field is a purely opaque name
+ which is only being used for references from definitions of compound
+ devices in the config.
+
+Virtual devices
+
+: (Examples: veth, bridge, bond) These are fully under the control of the
+ config file(s) and the network stack. I. e. these devices are being created
+ instead of matched. Thus ``match:`` and ``set-name:`` are not applicable for
+ these, and the ID field is the name of the created virtual device.
+
+Common properties for physical device types
+-------------------------------------------
+
+**match**: *<(mapping)>*
+
+This selects a subset of available physical devices by various hardware
+properties. The following configuration will then apply to all matching
+devices, as soon as they appear. *All* specified properties must match.
+The following properties for creating matches are supported:
+
+**name**: *<(scalar)>*
+
+Current interface name. Globs are supported, and the primary use case
+for matching on names, as selecting one fixed name can be more easily
+achieved with having no ``match:`` at all and just using the ID (see
+above). Note that currently only networkd supports globbing,
+NetworkManager does not.
+
+**macaddress**: *<(scalar)>*
+
+Device's MAC address in the form "XX:XX:XX:XX:XX:XX". Globs are not allowed.
+
+**driver**: *<(scalar)>*
+
+Kernel driver name, corresponding to the ``DRIVER`` udev property. Globs are
+supported. Matching on driver is *only* supported with networkd.
+
+**Examples**::
+
+ # all cards on second PCI bus
+ match:
+ name: enp2*
+
+ # fixed MAC address
+ match:
+ macaddress: 11:22:33:AA:BB:FF
+
+ # first card of driver ``ixgbe``
+ match:
+ driver: ixgbe
+ name: en*s0
+
+**set-name**: *<(scalar)>*
+
+When matching on unique properties such as path or MAC, or with additional
+assumptions such as "there will only ever be one wifi device",
+match rules can be written so that they only match one device. Then this
+property can be used to give that device a more specific/desirable/nicer
+name than the default from udev’s ifnames. Any additional device that
+satisfies the match rules will then fail to get renamed and keep the
+original kernel name (and dmesg will show an error).
+
+**wakeonlan**: *<(bool)>*
+
+Enable wake on LAN. Off by default.
+
+
+Common properties for all device types
+--------------------------------------
+
+**renderer**: *<(scalar)>*
+
+Use the given networking backend for this definition. Currently supported are
+``networkd`` and ``NetworkManager``. This property can be specified globally
+in ``networks:``, for a device type (in e. g. ``ethernets:``) or
+for a particular device definition. Default is ``networkd``.
+
+.. note::
+
+ Cloud-init only supports networkd backend if rendering version2 config
+ to the instance.
+
+**dhcp4**: *<(bool)>*
+
+Enable DHCP for IPv4. Off by default.
+
+**dhcp6**: *<(bool)>*
+
+Enable DHCP for IPv6. Off by default.
+
+**addresses**: *<(sequence of scalars)>*
+
+Add static addresses to the interface in addition to the ones received
+through DHCP or RA. Each sequence entry is in CIDR notation, i. e. of the
+form ``addr/prefixlen`` . ``addr`` is an IPv4 or IPv6 address as recognized
+by ``inet_pton``(3) and ``prefixlen`` the number of bits of the subnet.
+
+Example: ``addresses: [192.168.14.2/24, 2001:1::1/64]``
+
+**gateway4**: or **gateway6**: *<(scalar)>*
+
+Set default gateway for IPv4/6, for manual address configuration. This
+requires setting ``addresses`` too. Gateway IPs must be in a form
+recognized by ``inet_pton(3)``
+
+Example for IPv4: ``gateway4: 172.16.0.1``
+Example for IPv6: ``gateway6: 2001:4::1``
+
+**nameservers**: *<(mapping)>*
+
+Set DNS servers and search domains, for manual address configuration. There
+are two supported fields: ``addresses:`` is a list of IPv4 or IPv6 addresses
+similar to ``gateway*``, and ``search:`` is a list of search domains.
+
+Example: ::
+
+ nameservers:
+ search: [lab, home]
+ addresses: [8.8.8.8, FEDC::1]
+
+**routes**: *<(sequence of mapping)>*
+
+Add device specific routes. Each mapping includes a ``to``, ``via`` key
+with an IPv4 or IPv6 address as value. ``metric`` is an optional value.
+
+Example: ::
+
+ routes:
+ - to: 0.0.0.0/0
+ via: 10.23.2.1
+ metric: 3
+
+Ethernets
+~~~~~~~~~
+Ethernet device definitions do not support any specific properties beyond the
+common ones described above.
+
+Bonds
+~~~~~
+
+**interfaces** *<(sequence of scalars)>*
+
+All devices matching this ID list will be added to the bond.
+
+Example: ::
+
+ ethernets:
+ switchports:
+ match: {name: "enp2*"}
+ [...]
+ bonds:
+ bond0:
+ interfaces: [switchports]
+
+**parameters**: *<(mapping)>*
+
+Customization parameters for special bonding options. Time values are specified
+in seconds unless otherwise specified.
+
+**mode**: *<(scalar)>*
+
+Set the bonding mode used for the interfaces. The default is
+``balance-rr`` (round robin). Possible values are ``balance-rr``,
+``active-backup``, ``balance-xor``, ``broadcast``, ``802.3ad``,
+``balance-tlb``, and ``balance-alb``.
+
+**lacp-rate**: *<(scalar)>*
+
+Set the rate at which LACPDUs are transmitted. This is only useful
+in 802.3ad mode. Possible values are ``slow`` (30 seconds, default),
+and ``fast`` (every second).
+
+**mii-monitor-interval**: *<(scalar)>*
+
+Specifies the interval for MII monitoring (verifying if an interface
+of the bond has carrier). The default is ``0``; which disables MII
+monitoring.
+
+**min-links**: *<(scalar)>*
+
+The minimum number of links up in a bond to consider the bond
+interface to be up.
+
+**transmit-hash-policy**: <*(scalar)>*
+
+Specifies the transmit hash policy for the selection of slaves. This
+is only useful in balance-xor, 802.3ad and balance-tlb modes.
+Possible values are ``layer2``, ``layer3+4``, ``layer2+3``,
+``encap2+3``, and ``encap3+4``.
+
+**ad-select**: <*(scalar)>*
+
+Set the aggregation selection mode. Possible values are ``stable``,
+``bandwidth``, and ``count``. This option is only used in 802.3ad mode.
+
+**all-slaves-active**: <*(bool)>*
+
+If the bond should drop duplicate frames received on inactive ports,
+set this option to ``false``. If they should be delivered, set this
+option to ``true``. The default value is false, and is the desirable
+behavior in most situations.
+
+**arp-interval**: <*(scalar)>*
+
+Set the interval value for how frequently ARP link monitoring should
+happen. The default value is ``0``, which disables ARP monitoring.
+
+**arp-ip-targets**: <*(sequence of scalars)>*
+
+IPs of other hosts on the link which should be sent ARP requests in
+order to validate that a slave is up. This option is only used when
+``arp-interval`` is set to a value other than ``0``. At least one IP
+address must be given for ARP link monitoring to function. Only IPv4
+addresses are supported. You can specify up to 16 IP addresses. The
+default value is an empty list.
+
+**arp-validate**: <*(scalar)>*
+
+Configure how ARP replies are to be validated when using ARP link
+monitoring. Possible values are ``none``, ``active``, ``backup``,
+and ``all``.
+
+**arp-all-targets**: <*(scalar)>*
+
+Specify whether to use any ARP IP target being up as sufficient for
+a slave to be considered up; or if all the targets must be up. This
+is only used for ``active-backup`` mode when ``arp-validate`` is
+enabled. Possible values are ``any`` and ``all``.
+
+**up-delay**: <*(scalar)>*
+
+Specify the delay before enabling a link once the link is physically
+up. The default value is ``0``.
+
+**down-delay**: <*(scalar)>*
+
+Specify the delay before disabling a link once the link has been
+lost. The default value is ``0``.
+
+**fail-over-mac-policy**: <*(scalar)>*
+
+Set whether to set all slaves to the same MAC address when adding
+them to the bond, or how else the system should handle MAC addresses.
+The possible values are ``none``, ``active``, and ``follow``.
+
+**gratuitious-arp**: <*(scalar)>*
+
+Specify how many ARP packets to send after failover. Once a link is
+up on a new slave, a notification is sent and possibly repeated if
+this value is set to a number greater than ``1``. The default value
+is ``1`` and valid values are between ``1`` and ``255``. This only
+affects ``active-backup`` mode.
+
+**packets-per-slave**: <*(scalar)>*
+
+In ``balance-rr`` mode, specifies the number of packets to transmit
+on a slave before switching to the next. When this value is set to
+``0``, slaves are chosen at random. Allowable values are between
+``0`` and ``65535``. The default value is ``1``. This setting is
+only used in ``balance-rr`` mode.
+
+**primary-reselect-policy**: <*(scalar)>*
+
+Set the reselection policy for the primary slave. On failure of the
+active slave, the system will use this policy to decide how the new
+active slave will be chosen and how recovery will be handled. The
+possible values are ``always``, ``better``, and ``failure``.
+
+**learn-packet-interval**: <*(scalar)>*
+
+Specify the interval between sending learning packets to each slave.
+The value range is between ``1`` and ``0x7fffffff``. The default
+value is ``1``. This option only affects ``balance-tlb`` and
+``balance-alb`` modes.
+
+
+Bridges
+~~~~~~~
+
+**interfaces**: <*(sequence of scalars)>*
+
+All devices matching this ID list will be added to the bridge.
+
+Example: ::
+
+ ethernets:
+ switchports:
+ match: {name: "enp2*"}
+ [...]
+ bridges:
+ br0:
+ interfaces: [switchports]
+
+**parameters**: <*(mapping)>*
+
+Customization parameters for special bridging options. Time values are specified
+in seconds unless otherwise specified.
+
+**ageing-time**: <*(scalar)>*
+
+Set the period of time to keep a MAC address in the forwarding
+database after a packet is received.
+
+**priority**: <*(scalar)>*
+
+Set the priority value for the bridge. This value should be an
+number between ``0`` and ``65535``. Lower values mean higher
+priority. The bridge with the higher priority will be elected as
+the root bridge.
+
+**forward-delay**: <*(scalar)>*
+
+Specify the period of time the bridge will remain in Listening and
+Learning states before getting to the Forwarding state. This value
+should be set in seconds for the systemd backend, and in milliseconds
+for the NetworkManager backend.
+
+**hello-time**: <*(scalar)>*
+
+Specify the interval between two hello packets being sent out from
+the root and designated bridges. Hello packets communicate
+information about the network topology.
+
+**max-age**: <*(scalar)>*
+
+Set the maximum age of a hello packet. If the last hello packet is
+older than that value, the bridge will attempt to become the root
+bridge.
+
+**path-cost**: <*(scalar)>*
+
+Set the cost of a path on the bridge. Faster interfaces should have
+a lower cost. This allows a finer control on the network topology
+so that the fastest paths are available whenever possible.
+
+**stp**: <*(bool)>*
+
+Define whether the bridge should use Spanning Tree Protocol. The
+default value is "true", which means that Spanning Tree should be
+used.
+
+
+VLANs
+~~~~~
+
+**id**: <*(scalar)>*
+
+VLAN ID, a number between 0 and 4094.
+
+**link**: <*(scalar)>*
+
+ID of the underlying device definition on which this VLAN gets
+created.
+
+Example: ::
+
+ ethernets:
+ eno1: {...}
+ vlans:
+ en-intra:
+ id: 1
+ link: eno1
+ dhcp4: yes
+ en-vpn:
+ id: 2
+ link: eno1
+ address: ...
+
+
+Examples
+--------
+Configure an ethernet device with networkd, identified by its name, and enable
+DHCP: ::
+
+ network:
+ version: 2
+ ethernets:
+ eno1:
+ dhcp4: true
+
+This is a complex example which shows most available features: ::
+
+ network:
+ version: 2
+ ethernets:
+ # opaque ID for physical interfaces, only referred to by other stanzas
+ id0:
+ match:
+ macaddress: 00:11:22:33:44:55
+ wakeonlan: true
+ dhcp4: true
+ addresses:
+ - 192.168.14.2/24
+ - 2001:1::1/64
+ gateway4: 192.168.14.1
+ gateway6: 2001:1::2
+ nameservers:
+ search: [foo.local, bar.local]
+ addresses: [8.8.8.8]
+ lom:
+ match:
+ driver: ixgbe
+ # you are responsible for setting tight enough match rules
+ # that only match one device if you use set-name
+ set-name: lom1
+ dhcp6: true
+ switchports:
+ # all cards on second PCI bus; unconfigured by themselves, will be added
+ # to br0 below
+ match:
+ name: enp2*
+ mtu: 1280
+ bonds:
+ bond0:
+ interfaces: [id0, lom]
+ bridges:
+ # the key name is the name for virtual (created) interfaces; no match: and
+ # set-name: allowed
+ br0:
+ # IDs of the components; switchports expands into multiple interfaces
+ interfaces: [wlp1s0, switchports]
+ dhcp4: true
+ vlans:
+ en-intra:
+ id: 1
+ link: id0
+ dhcp4: yes
+ # static routes
+ routes:
+ - to: 0.0.0.0/0
+ via: 11.0.0.1
+ metric: 3
+
+.. _netplan: https://launchpad.net/netplan
+.. vi: textwidth=78
diff --git a/doc/rtd/topics/network-config.rst b/doc/rtd/topics/network-config.rst
new file mode 100644
index 0000000..c69b593
--- /dev/null
+++ b/doc/rtd/topics/network-config.rst
@@ -0,0 +1,291 @@
+*********************
+Network Configuration
+*********************
+
+- Default Behavior
+- Disabling Network Configuration
+- Fallback Networking
+- Network Configuration Sources
+- Network Configuration Outputs
+- Network Output Policy
+- Controlling and specifying network configuration
+- Network Configuration Tools
+- Examples
+
+Default Behavior
+================
+
+`Cloud-init`_ 's network configuration behavior can be configured via
+user-data. In the absense of user-data specifying network configuration,
+`Cloud-init`_ will write out a network configuration that will issue a
+DHCP request on a "first" network interface.
+
+Disabling Network Configuration
+===============================
+
+Users may disable `Cloud-init`_ 's network configuration capability and rely
+on other methods, such as embedded configuration or other customizations.
+
+`Cloud-init`_ supports the following methods for disabling cloud-init.
+
+
+**/var/lib/cloud/data/upgraded-network**
+
+If this file is present, cloud-init's network config is disabled
+
+**kernel command-line**
+
+
+Cloud-init will check for a parameter ``network-config`` and the
+value is expected to be Base64 encoded YAML string in the
+``NETWORK_CONFIG_V1`` format. Specifially for disabling networking
+the required string looks like: ::
+
+ network-config={config: disabled}
+
+The actual string passed must be Base64 encoded: ::
+
+ network-config=bmV0d29yay1jb25maWc9e2NvbmZpZzogZGlzYWJsZWR9Cg==
+
+**system_info config**
+
+In the combined cloud-init system_info configuration dictionary. ::
+
+ system_info:
+ network:
+ config: disabled
+
+If `Cloud-init`_ 's networking config has not been disabled, then
+it will proceed to generate a fallback networking configuration.
+
+
+Fallback Network Configuration
+==============================
+
+`Cloud-init`_ will attempt to determine which of any attached network devices
+is most likely to have a a connection and then generate a network
+configuration to issue a DHCP request on that interface.
+
+`Cloud-init`_ does not consider the following interface types as likely 'first'
+network interfaces for fallback configuration; they are filtered out from
+being selected.
+
+- **loopback**: ``lo``
+- **Virtual Ethernet**: ``veth``
+- **Software Bridges**: ``bridge``
+
+`Cloud-init`_ will prefer network interfaces that indicate they are connected
+via the Linux ``carrier`` flag being set. If no interfaces are marked
+connected, then all unfiltered interfaces are potential connections.
+
+Of the potential interfaces, `Cloud-init`` will first check for an interface
+named ``eth0``. If such an interface is not present, then `Cloud-init`_ picks
+the first element in the list of interface name based on the output of
+Python's sorted() method applied to the list.
+
+Finally after selecting the most likely interface, a configuration is
+generated internally and applied to the system.
+
+
+Network Configuration Sources
+=============================
+
+`Cloud-init`_ accepts a number of different network configuration formats in
+support of different cloud substrates. The Datasource for these clouds in
+`Cloud-init`_ will detect and convert Datasource specific network configuration
+from the datasource format into `Cloud-init`_ 's `NETWORK_CONFIG_V1` format.
+
+The following Datasources optionally provide network configuration:
+
+- ConfigDrive
+
+ - :ref:`network_config_v1`
+ - :ref:`network_config_v2`
+ - :ref:`network_config_eni`
+
+- DigitalOcean
+
+ - `DigitalOcean JSON metadata`_
+
+- NoCloud
+
+ - :ref:`network_config_v1`
+ - :ref:`network_config_v2`
+ - :ref:`network_config_eni`
+
+- OpenNebula
+
+ - :ref:`network_config_eni`
+
+- OpenStack
+
+ - :ref:`network_config_eni`
+ - `OpenStack Metadata Service Network`_
+
+- SmartOS
+
+ - `SmartOS JSON Metadata`_
+
+For more information on network configuration formats
+
+.. toctree::
+ :maxdepth: 1
+
+ network-config-format-eni.rst
+ network-config-format-v1.rst
+ network-config-format-v2.rst
+
+
+Network Configuration Outputs
+=============================
+
+`Cloud-init`_ converts various forms of user supplied or automatically
+generated configuration into an internal network configuration state. From
+this state `Cloud-init`_ delegates rendering of the configuration to Distro
+supported formats. The following ``renderers`` are supported in cloud-init:
+
+- ENI
+
+/etc/network/interfaces or ``ENI`` is supported by the ``ifupdown`` package
+found in Ubuntu and Debian.
+
+- Netplan
+
+Since Ubuntu 16.10 Yakkety, the ``netplan`` project has been an optional
+network configuration tool which consumes :ref:`network_config_v2` input
+and renders network configuration for supported backends such as
+``systemd-networkd`` and ``NetworkManager``.
+
+- Sysconfig
+
+
+Network Output Policy
+=====================
+Default network configuration for Fedora/RHEL/CentOS based distributions.
+
+The default policy for selecting a network ``renderer`` in `Cloud-init`_ is
+
+- ENI
+- Sysconfig
+- Netplan
+
+When applying the policy, `Cloud-init`_ checks if the current instance has the
+correct binaries and paths to support the renderer. The first renderer that
+can be used is selected. Users may override the network renderer policy by
+supplying an updated configuration in cloud-config. ::
+
+ system_info:
+ network:
+ renderers: ['netplan', 'eni', 'sysconfig']
+
+
+Controlling and specifying network configuration
+================================================
+
+
+Network Configuration Tools
+===========================
+
+`Cloud-init`_ contains one tool used to test input/output conversion between
+formats. The ``tools/net-convert.py`` in the `Cloud-init`_ source repository
+is helpful for examining expected output for a given input format.
+
+CLI Interface ::
+
+ % tools/net-convert.py --help
+ usage: net-convert.py [-h] --network-data PATH --kind
+ {eni,network_data.json,yaml} -d PATH [-m name,mac]
+ --output-kind {eni,netplan,sysconfig}
+
+ optional arguments:
+ -h, --help show this help message and exit
+ --network-data PATH, -p PATH
+ --kind {eni,network_data.json,yaml}, -k {eni,network_data.json,yaml}
+ -d PATH, --directory PATH
+ directory to place output in
+ -m name,mac, --mac name,mac
+ interface name to mac mapping
+ --output-kind {eni,netplan,sysconfig}, -ok {eni,netplan,sysconfig}
+
+
+Example output convertion V2 to sysconfig ::
+
+ % tools/net-convert.py --network-data v2.yaml --kind yaml --output-kind sysconfig -d target
+ Input YAML
+ ethernets:
+ eth7:
+ addresses:
+ - 192.168.1.5/255.255.255.0
+ gateway4: 192.168.1.254
+ eth9:
+ dhcp4: true
+ version: 2
+
+
+ Internal State
+ !!python/object:cloudinit.net.network_state.NetworkState
+ _network_state:
+ dns:
+ nameservers: []
+ search: []
+ interfaces:
+ eth7:
+ address: null
+ gateway: null
+ inet: inet
+ mac_address: null
+ mode: manual
+ mtu: null
+ name: eth7
+ subnets:
+ - address: 192.168.1.5/255.255.255.0
+ gateway: 192.168.1.254
+ type: static
+ type: physical
+ eth9:
+ address: null
+ gateway: null
+ inet: inet
+ mac_address: null
+ mode: manual
+ mtu: null
+ name: eth9
+ subnets:
+ - type: dhcp4
+ type: physical
+ routes: []
+ use_ipv6: false
+ _version: 2
+ use_ipv6: false
+
+ % cat target/etc/sysconfig/network-scripts/ifcfg-eth*
+ # Created by cloud-init on instance boot automatically, do not edit.
+ #
+ BOOTPROTO=static
+ DEVICE=eth7
+ IPADDR=192.168.1.5/255.255.255.0
+ NM_CONTROLLED=no
+ ONBOOT=yes
+ TYPE=Ethernet
+ USERCTL=no
+ # Created by cloud-init on instance boot automatically, do not edit.
+ #
+ BOOTPROTO=dhcp
+ DEVICE=eth9
+ NM_CONTROLLED=no
+ ONBOOT=yes
+ TYPE=Ethernet
+ USERCTL=no
+
+
+Examples
+========
+
+
+
+.. _Cloud-init: https://launchpad.net/cloud-init
+.. _DigitalOcean JSON metadata: https://developers.digitalocean.com/documentation/metadata/#network-interfaces-index
+.. _OpenStack Metadata Service Network: https://specs.openstack.org/openstack/nova-specs/specs/liberty/implemented/metadata-service-network-info.html
+.. _SmartOS JSON Metadata: https://eng.joyent.com/mdata/datadict.html
+
+.. vi: textwidth=78
Follow ups
