salt.states.network

Configuration of network interfaces

The network module is used to create and manage network settings, interfaces can be set as either managed or ignored. By default all interfaces are ignored unless specified.

Note

RedHat-based systems (RHEL, CentOS, Scientific, etc.) have been supported since version 2014.1.0.

Debian-based systems (Debian, Ubuntu, etc.) have been supported since version 2017.7.0. The following options are not supported: ipaddr_start, and ipaddr_end.

Other platforms are not yet supported.

Note

On Debian-based systems, networking configuration can be specified in /etc/network/interfaces or via included files such as (by default) /etc/network/interfaces.d/*. This can be problematic for configuration management. It is recommended to use either file.managed or network.managed.

If using network.managed, it can be useful to ensure interfaces.d/ is empty. This can be done using the following state

/etc/network/interfaces.d:
  file.directory:
    - clean: True

Configuring Global Network Settings

Use the network.system state to set global network settings:

system:
  network.system:
    - enabled: True
    - hostname: server1.example.com
    - gateway: 192.168.0.1
    - gatewaydev: eth0
    - nozeroconf: True
    - nisdomain: example.com
    - require_reboot: True
    - apply_hostname: True

Note

The use of apply_hostname above will apply changes to the hostname immediately.

Changed in version 2015.5.0: apply_hostname added

retain_settings

New in version 2016.11.0.

Use retain_settings to retain current network settings that are not otherwise specified in the state. Particularly useful if only setting the hostname. Default behavior is to delete unspecified network settings.

system:
  network.system:
    - hostname: server2.example.com
    - apply_hostname: True
    - retain_settings: True

Configuring Network Routes

Use the network.routes state to set network routes.

routes:
  network.routes:
    - name: eth0
    - routes:
      - name: secure_network
        ipaddr: 10.2.0.0
        netmask: 255.255.255.0
        gateway: 10.1.0.3
      - name: HQ_network
        ipaddr: 10.100.0.0
        netmask: 255.255.0.0
        gateway: 10.1.0.10

Managing Network Interfaces

The network.managed state is used to configure network interfaces. Here are several examples:

Ethernet Interface

eth0:
  network.managed:
    - enabled: True
    - type: eth
    - proto: static
    - ipaddr: 10.1.0.7
    - netmask: 255.255.255.0
    - gateway: 10.1.0.1
    - enable_ipv6: true
    - ipv6proto: static
    - ipv6addrs:
      - 2001:db8:dead:beef::3/64
      - 2001:db8:dead:beef::7/64
    - ipv6gateway: 2001:db8:dead:beef::1
    - ipv6netmask: 64
    - dns:
      - 8.8.8.8
      - 8.8.4.4
    - channels:
        rx: 4
        tx: 4
        other: 4
        combined: 4

Ranged Interfaces (RHEL/CentOS Only)

New in version 2015.8.0.

Ranged interfaces can be created by including the word range in the interface name.

Important

The interface type must be eth.

eth0-range0:
  network.managed:
    - type: eth
    - ipaddr_start: 192.168.1.1
    - ipaddr_end: 192.168.1.10
    - clonenum_start: 10
    - mtu: 9000

bond0-range0:
  network.managed:
    - type: eth
    - ipaddr_start: 192.168.1.1
    - ipaddr_end: 192.168.1.10
    - clonenum_start: 10
    - mtu: 9000

eth1.0-range0:
  network.managed:
    - type: eth
    - ipaddr_start: 192.168.1.1
    - ipaddr_end: 192.168.1.10
    - clonenum_start: 10
    - vlan: True
    - mtu: 9000

bond0.1-range0:
  network.managed:
    - type: eth
    - ipaddr_start: 192.168.1.1
    - ipaddr_end: 192.168.1.10
    - clonenum_start: 10
    - vlan: True
    - mtu: 9000

Bond Interfaces

To configure a bond, you must do the following:

Configure the bond slaves with a type of slave, and a master option set to the name of the bond interface.
Configure the bond interface with a type of bond, and a slaves option defining the bond slaves for the bond interface.

eth2:
  network.managed:
    - enabled: True
    - type: slave
    - master: bond0

eth3:
  network.managed:
    - enabled: True
    - type: slave
    - master: bond0

bond0:
  network.managed:
    - type: bond
    - ipaddr: 10.1.0.1
    - netmask: 255.255.255.0
    - mode: gre
    - proto: static
    - dns:
      - 8.8.8.8
      - 8.8.4.4
    - enabled: False
    - slaves: eth2 eth3
    - require:
      - network: eth2
      - network: eth3
    - miimon: 100
    - arp_interval: 250
    - downdelay: 200
    - lacp_rate: fast
    - max_bonds: 1
    - updelay: 0
    - use_carrier: on
    - hashing-algorithm: layer2
    - mtu: 9000
    - autoneg: on
    - speed: 1000
    - duplex: full
    - rx: on
    - tx: off
    - sg: on
    - tso: off
    - ufo: off
    - gso: off
    - gro: off
    - lro: off

VLANs

Set type to vlan to configure a VLANs. These VLANs are configured on the bond interface defined above.

bond0.2:
  network.managed:
    - type: vlan
    - ipaddr: 10.1.0.2
    - use:
      - network: bond0
    - require:
      - network: bond0

bond0.3:
  network.managed:
    - type: vlan
    - ipaddr: 10.1.0.3
    - use:
      - network: bond0
    - require:
      - network: bond0

bond0.10:
  network.managed:
    - type: vlan
    - ipaddr: 10.1.0.4
    - use:
      - network: bond0
    - require:
      - network: bond0

bond0.12:
  network.managed:
    - type: vlan
    - ipaddr: 10.1.0.5
    - use:
      - network: bond0
    - require:
      - network: bond0

Bridge Interfaces

eth4:
  network.managed:
    - enabled: True
    - type: eth
    - proto: dhcp
    - bridge: br0

br0:
  network.managed:
    - enabled: True
    - type: bridge
    - proto: dhcp
    - bridge: br0
    - delay: 0
    - ports: eth4
    - bypassfirewall: True
    - use:
      - network: eth4
    - require:
      - network: eth4

Note

When managing bridged interfaces on a Debian/Ubuntu based system, the ports argument is required. RedHat-based systems will ignore the argument.

Network Teaming (RHEL/CentOS 7 and later)

New in version 3002.

Configure the members of the team interface with a type of teamport, and a team_master option set to the name of the bond interface.
- master also works, but will be ignored if both team_master and master are present.
- If applicable, include a team_port_config option. This should be formatted as a dictionary. Keep in mind that due to a quirk of PyYAML, dictionaries nested under a list item must be double-indented (see example below for interface eth5).
Configure the team interface with a type of team. The team configuration should be passed via the team_config option. As with team_port_config, the dictionary should be double-indented.

eth5:
  network.managed:
    - type: teamport
    - team_master: team0
    - team_port_config:
        prio: 100

eth6:
  network.managed:
    - type: teamport
    - team_master: team0

team0:
  network.managed:
    - type: team
    - ipaddr: 172.24.90.42
    - netmask: 255.255.255.128
    - enable_ipv6: True
    - ipv6addr: 'fee1:dead:beef:af43::'
    - team_config:
        runner:
          hwaddr_policy: by_active
          name: activebackup
          link_watch:
            name: ethtool

Note

While teamd must be installed to manage a team interface, it is not required to configure a separate pkg.installed state for it, as it will be silently installed if needed.

Configuring the Loopback Interface

Use network.managed with a type of eth and a proto of loopback.

lo:
  network.managed:
    - name: lo
    - type: eth
    - proto: loopback
    - onboot: yes
    - userctl: no
    - ipv6_autoconf: no
    - enable_ipv6: true

Other Useful Options

noifupdown

The noifupdown option, if set to True, will keep Salt from restart the interface if changes are made, requiring them to be restarted manually. Here are a couple examples:

eth7:
  network.managed:
    - enabled: True
    - type: eth
    # Automatic IP/DNS
    - proto: dhcp
    - noifupdown: True

eth8:
  network.managed:
    - type: eth
    - noifupdown: True

    # IPv4
    - proto: static
    - ipaddr: 192.168.4.9
    - netmask: 255.255.255.0
    - gateway: 192.168.4.1
    - enable_ipv6: True

    # IPv6
    - ipv6proto: static
    - ipv6addr: 2001:db8:dead:c0::3
    - ipv6netmask: 64
    - ipv6gateway: 2001:db8:dead:c0::1
    # override shared; makes those options v4-only
    - ipv6ttl: 15

    # Shared
    - mtu: 1480
    - ttl: 18
    - dns:
      - 8.8.8.8
      - 8.8.4.4

salt.states.network.managed(name, enabled=True, **kwargs)

Ensure that the named interface is configured properly.

name: The name of the interface to manage
typeeth: Type of interface and configuration

Changed in version 3002.
enabled: Designates the state of this interface.

salt.states.network.routes(name, **kwargs)

Manage network interface static routes.

name: Interface name to apply the route to.
kwargs: Named routes

salt.states.network.system(name, **kwargs)

Ensure that global network settings are configured properly.

name: Custom name to represent this configuration change.
kwargs: The global parameters for the system.

© 2021 SaltStack.
Licensed under the Apache License, Version 2.0.
https://docs.saltproject.io/en/latest/ref/states/all/salt.states.network.html