os-net-config/doc/source/config.rst

Network configuration reference

This section describes the supported /etc/os-net-config/config.yaml YAML format and how they map to networking backend providers. The root element is a network_config attribute, and the value is an array of dicts entries describing the physical and virtual interfaces to configure. Each interface entry has a mandatory type attribute, and the value determines what other attributes are supported for that type.

Common attributes

The following attributes are used in many types. See multiple-nics for examples.

addresses

A list of ip_netmask entries to specify the network addresses for this interface. For example:

addresses:
  - ip_netmask: 192.0.2.2/24
  - ip_netmask: 192.0.3.2/32

ifcfg implementation

Sets BOOTPROTO=static and populates IPADDR and NETMASK, followed byIPADDR<i>,NETMASK<i>for subsequent addresses with<i>incrementing from1. defroute ======== A boolean which defaults totrue. Whenfalsethe default route given by an IPV4 DHCP server will be ignored. ifcfg implementation ^^^^^^^^^^^^^^^^^^^^ SetsDEFROUTE=nowhen set tofalse. dhclient_args ============= Arguments to append to the call to the dhclient command, as a single string. ifcfg implementation ^^^^^^^^^^^^^^^^^^^^ SetsDHCLIENTARGSto the supplied value dns_servers =========== A list of DNS servers (maximum of 2) to use for name resolution. ifcfg implementation ^^^^^^^^^^^^^^^^^^^^ SetsDNS1,DNS2to support up to 2 DNS resolvers. domain ====== A string or a list of strings containing DNS search domains ifcfg implementation ^^^^^^^^^^^^^^^^^^^^ SetsDOMAINcontaining all values as a space-separated list. mtu === Maximum transmission unit for this interface. ifcfg implementation ^^^^^^^^^^^^^^^^^^^^ SetsMTUto the specified value. If unspecified the default is1500. name ==== This is the name for the interface which is one of: - the name of existing physical interface (NIC) - the identifier from the mapping file which maps to a NIC - the desired name of a bridge or bond - a numbered identifiernic<i>starting with1for each active NIC:nic1,nic2etc ifcfg implementation ^^^^^^^^^^^^^^^^^^^^ When the name is an identifier in the mapping file or anic<i>identifier, the actual name used will be the mapping value, not the identifier. The name format of a physical interfaces depends onbiosdevnameornet.ifnamessysctl settings or udev rules for persistent names. Names will begin withethif both sysctl settings are disabled and there are no udev rules. The sort order used to allocatenic<i>identifiers are: - Embedded interfaces first (em<j>,eth<j>,eno<j>) ordered alphanumerically - Then, other active NICs ordered alphanumerically Each interface definition is written to/etc/sysconfig/network-scripts/ifcfg-<name>and the first value in the file isDEVICE=<name>. nm_controlled ============= Boolean whether this interface is managed by `NetworkManager`_, defaults tofalse. ifcfg implementation ^^^^^^^^^^^^^^^^^^^^ SetsNM_CONTROLLED=yesorNM_CONTROLLED=noonboot ====== Boolean which determines whether to enable the interface on machine boot, defaults totrue. ifcfg implementation ^^^^^^^^^^^^^^^^^^^^ SetsONBOOT=yesorONBOOT=no. primary ======= In themembersentries for a bond or bridge this may be set totruefor the primary interface. This results in the bond or bridge inheriting the MAC address of the primary interface. routes ====== A list of route entries for this interface containing attributes: -defaultBoolean whether this is the default route for this interface -ip_netmaskordestinationDestination network address whendefaultisfalse-next_hopornexthopGateway address for route destination Other supported attributes include: -route_tableThe table ID or name to add this route to -route_optionsString of extra options to append to the end of the route For example: .. code-block:: yaml routes: - default: true next_hop: 198.51.100.1 - ip_netmask: 192.0.2.2/24 next_hop: 203.0.113.254 route_table: 2 route_options: metric 100 ifcfg implementation ^^^^^^^^^^^^^^^^^^^^ A routes file for each interface definition is written to/etc/sysconfig/network-scripts/route-<name>. rules ===== A list of commented route rules, for example: .. code-block:: yaml rules: - rule: "iif em1 table 200" comment: "Route incoming traffic to em1 with table 200" - rule: "from 192.0.2.0/24 table 200" comment: "Route all traffic from 192.0.2.0/24 with table 200" - rule: "add blackhole from 172.19.40.0/24 table 200" - rule: "add unreachable iif em1 from 192.168.1.0/24" ifcfg implementation ^^^^^^^^^^^^^^^^^^^^ Each interface is iterated in order and its rules are compared to existing rules then converged by runningip rule del <rule>andip rule add <rule>. use_dhcp ======== Boolean for whether to use DHCP for the IPv4 boot protocol. ifcfg implementation ^^^^^^^^^^^^^^^^^^^^ SetsPEERDNS=nowhenfalse. use_dhcpv6 ========== Boolean for whether to use DHCP for the IPv6 boot protocol. ifcfg implementation ^^^^^^^^^^^^^^^^^^^^ SetsDHCPV6C=yeswhentrue. .. Undocumented: rules nic_mapping persist_mapping .. _ovs-attributes: Open vSwitch attributes ----------------------- The `Open vSwitch`_ types support some or all of these attributes: .. _ovs-options: ovs_options =========== String of other options to pass to Open vSwitch for this bond or bridge. ifcfg implementation ^^^^^^^^^^^^^^^^^^^^ Sets theOVS_OPTIONSvalue. .. _ovs-extra: ovs_extra ========= A list of extra options to pass to Open vSwitch. ifcfg implementation ^^^^^^^^^^^^^^^^^^^^ Will set theOVS_EXTRAvalue with all the provided values. ovs_fail_mode ============= Failure mode for a bridge, defaults tostandard, can also be set tosecureifcfg implementation ^^^^^^^^^^^^^^^^^^^^ Will be appended to theOVS_OPTIONSvalue and the concatenated list ofOVS_EXTRAvalues. type: interface --------------- Configures a physical NIC. See :ref:`multiple-nics` for examples. All of the :ref:`common-attributes` can be used with this type along with the following attributes: ethtool_opts ============ Device-specific options supported by `ethtool`_. ifcfg implementation ^^^^^^^^^^^^^^^^^^^^ SetsETHTOOL_OPTSto the value. hotplug ======= A boolean for whether to activate the device when it is plugged in. ifcfg implementation ^^^^^^^^^^^^^^^^^^^^ SetsHOTPLUG=yesorHOTPLUG=nolinkdelay ========= Integer number of seconds to wait for link negotiation before configuring the device. ifcfg implementation ^^^^^^^^^^^^^^^^^^^^ SetsLINKDELAYto the delay value. type: ovs_bridge ---------------- Configures an `Open vSwitch`_ bridge. See :ref:`control-plane-bridge` for an example. All of the :ref:`common-attributes` and :ref:`ovs-attributes` can be used with this type. Themembersattribute contains a list of entries for interfaces to bridge typically oftype: -interface-linux_bond-ovs_bond-vlan- other Open vSwitch internal interfaces ifcfg implementation ==================== ValuesDEVICETYPE=ovsandTYPE=OVSBridgeare set. Whenuse_dhcporuse_dhcpv6istrue,OVSBOOTPROTO=dhcpis set andOVSDHCPINTERFACESis populated. type: ovs_bond -------------- Configures an `Open vSwitch`_ bond. See :ref:`ovs-bond` for an example. All of the :ref:`common-attributes` and :ref:`ovs-attributes` can be used with this type. Themembersattribute contains a list of entries for interfaces to be bonded. ifcfg implementation ==================== ValuesDEVICETYPE=ovsandTYPE=OVSBridgeare set. Whenuse_dhcporuse_dhcpv6istrue,OVSBOOTPROTO=dhcpis set andOVSDHCPINTERFACESis populated. type: vlan ---------- Configures VLAN tagging for one VLAN. See :ref:`bonds-with-vlans` for an example. :ref:`common-attributes` are supported but generally onlymtu,addressesorroutesare used. Other attributes forvlanare: device ====== Thenameof an existing interface entry, which will typically be oftype: interface,type: ovs_bond, ortype: linux_bond. Usuallydeviceis only used when the VLAN is not part of anovs_bridge. A VLAN on anovs_bridgeis part of thememberslist for the bridge, where a Linux VLAN is associated with aninterfaceorlinux_bondusing thedeviceparameter. vlan_id ======= The VLAN ID to tag when passing through thedeviceinterface. ifcfg implementation ==================== SetsVLAN=yesandPHYSDEVto thedevicevalue. type: linux_bridge ------------------ Configures a `Linux bridge`_. See :ref:`linux-bridge` for an example. All of the :ref:`common-attributes` can be used with this type. Themembersattribute contains a list of entries for interfaces to bridge. ifcfg implementation ==================== SetsTYPE=BridgeandDELAY=0. The MAC address of themembersinterface which hasprimary: truewill be used for theMACADDRvalue. type: linux_bond ---------------- Configures a `Linux bond`_. See :ref:`bonds-vlans-dpdk` for an example. All of the :ref:`common-attributes` can be used with this type. Themembersattribute contains a list of entries for interfaces to be bonded. Extra bonding options are specified in thebonding_optionsstring. ifcfg implementation ==================== The MAC address of themembersinterface which hasprimary: truewill be used for theMACADDRvalue.BONDING_OPTSwill contain the value of thebonding_optionsattribute. type: ovs_user_bridge --------------------- Configures an `Open vSwitch`_ bridge where the members are user ports. This is generally used to set up `DPDK vHost User Ports`_. See :ref:`bonds-vlans-dpdk` for an example. All of the :ref:`common-attributes` and :ref:`ovs-attributes` can be used with this type. Themembersattribute usually contains a singletype: ovs_dpdk_bondentry. ifcfg implementation ==================== ValuesDEVICETYPE=ovsandTYPE=OVSUserBridgeare set. Whenuse_dhcporuse_dhcpv6istrue,OVSBOOTPROTO=dhcpis set andOVSDHCPINTERFACESis populated. Eachmembersinterface also hasOVS_BRIDGEset, as well as other values depending on the type of the member. type: ovs_dpdk_bond ------------------- Configures an `Open vSwitch`_ bond for binding DPDK ports. See :ref:`bonds-vlans-dpdk` for an example. All of the :ref:`common-attributes` and :ref:`ovs-attributes` can be used with this type. Themembersattribute contains a list oftype: ovs_dpdk_portports to be bonded. The value for attributerx_queuewill determine the RX queue length. ifcfg implementation ==================== ValuesDEVICETYPE=ovs,TYPE=OVSDPDKBond, andRX_QUEUEare set.BOND_IFACESis populated with thenameof all members.OVS_EXTRAis extended with aset Interface...directive for each member. type: ovs_dpdk_port ------------------- Creates an Open vSwitch DPDK port, usually in themembersof atype: ovs_dpdk_bondbond interface. See :ref:`bonds-vlans-dpdk` for an example. All of the :ref:`common-attributes` and :ref:`ovs-attributes` can be used with this type. Each port must have amemberslist with a single interface entry. A port can have its ownrx_queuespecifed. Thedriverattribute can override the default kernel driver module ofvfio-pci. ifcfg implementation ==================== ValuesDEVICETYPE=ovsandTYPE=OVSDPDKPort, andRX_QUEUEare set.OVS_EXTRAis extended with aset Interface...directive for the onemembers`` interface.