# 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.