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
_______________________________________________ Mailing list: https://launchpad.net/~cloud-init-dev Post to : [email protected] Unsubscribe : https://launchpad.net/~cloud-init-dev More help : https://help.launchpad.net/ListHelp
