# nmcli – Manage Networking

- Synopsis

- Requirements

- Parameters

- Examples

- Status

## Synopsis

- Manage the network devices. Create, modify and manage various connection and device type e.g., ethernet, teams, bonds, vlans etc.

- On CentOS 8 and Fedora >=29 like systems, the requirements can be met by installing the following packages: NetworkManager-nmlib, libsemanage-python, policycoreutils-python.

- On CentOS 7 and Fedora <=28 like systems, the requirements can be met by installing the following packages: NetworkManager-glib, libnm-qt-devel.x86_64, nm-connection-editor.x86_64, libsemanage-python, policycoreutils-python.

- On Ubuntu and Debian like systems, the requirements can be met by installing the following packages: network-manager, python-dbus (or python3-dbus, depending on the Python version in use), libnm-dev.

- On older Ubuntu and Debian like systems, the requirements can be met by installing the following packages: network-manager, python-dbus (or python3-dbus, depending on the Python version in use), libnm-glib-dev.

- On openSUSE, the requirements can be met by installing the following packages: NetworkManager, python2-dbus-python (or python3-dbus-python), typelib-1_0-NMClient-1_0 and typelib-1_0-NetworkManager-1_0.

## Requirements

The below requirements are needed on the host that executes this module.

- dbus

- NetworkManager-libnm (or NetworkManager-glib on older systems)

- nmcli

## Parameters

Parameter | Choices/Defaults | Comments
--- | --- | ---
ageingtime integer | Default: 300 | This is only used with bridge - [ageing-time <0-1000000>] the Ethernet MAC address aging time, in seconds.
arp_interval integer |  | This is only used with bond - ARP interval.
arp_ip_target string |  | This is only used with bond - ARP IP target.

autoconnect
boolean

Choices:
- no
- yes ←

Whether the connection should start on boot.
Whether the connection profile can be automatically activated

conn_name string / required |  | The name used to call the connection. Pattern is <type>[-<ifname>][-<num>].
dhcp_client_id string added in 2.5 |  | DHCP Client Identifier sent to the DHCP server.
dns4 list |  | A list of up to 3 dns servers. IPv4 format e.g. to add two IPv4 DNS server addresses, use `192.0.2.53 198.51.100.53`.
dns4_search list added in 2.5 |  | A list of DNS search domains.
dns6 list |  | A list of up to 3 dns servers. IPv6 format e.g. to add two IPv6 DNS server addresses, use `2001:4860:4860::8888 2001:4860:4860::8844`.
dns6_search list added in 2.5 |  | A list of DNS search domains.
downdelay integer |  | This is only used with bond - downdelay.
egress string |  | This is only used with VLAN - VLAN egress priority mapping.
flags string |  | This is only used with VLAN - flags.
forwarddelay integer | Default: 15 | This is only used with bridge - [forward-delay <2-30>] STP forwarding delay, in seconds.
gw4 string |  | The IPv4 gateway for this interface. Use the format `192.0.2.1`.
gw6 string |  | The IPv6 gateway for this interface. Use the format `2001:db8::1`.

hairpin
boolean

Choices:
- no
- yes ←

This is only used with 'bridge-slave' - 'hairpin mode' for the slave, which allows frames to be sent back out through the slave the frame was received on.

hellotime integer | Default: 2 | This is only used with bridge - [hello-time <1-10>] STP hello time, in seconds.
ifname string |  | The interface to bind the connection to. The connection will only be applicable to this interface name. A special value of `'*'` can be used for interface-independent connections. The ifname argument is mandatory for all connection types except bond, team, bridge and vlan. This parameter defaults to `conn_name` when left unset.
ingress string |  | This is only used with VLAN - VLAN ingress priority mapping.
ip4 string |  | The IPv4 address to this interface. Use the format `192.0.2.24/24`.
ip6 string |  | The IPv6 address to this interface. Use the format `abbe::cafe`.
ip_tunnel_dev string added in 2.8 |  | This is used with IPIP/SIT - parent device this IPIP/SIT tunnel, can use ifname.
ip_tunnel_local string added in 2.8 |  | This is used with IPIP/SIT - IPIP/SIT local IP address.
ip_tunnel_remote string added in 2.8 |  | This is used with IPIP/SIT - IPIP/SIT destination IP address.
mac - |  | This is only used with bridge - MAC address of the bridge. Note this requires a recent kernel feature, originally introduced in 3.15 upstream kernel.
master string |  | Master <master (ifname, or connection UUID or conn_name) of bridge, team, bond master connection profile.
maxage integer | Default: 20 | This is only used with bridge - [max-age <6-42>] STP maximum message age, in seconds.
miimon integer |  | This is only used with bond - miimon. This parameter defaults to `100` when unset.

mode
string

Choices:
- 802.3ad
- active-backup
- balance-alb
- balance-rr ←
- balance-tlb
- balance-xor
- broadcast

This is the type of device or network connection that you wish to create for a bond, team or bridge.

mtu integer |  | The connection MTU, e.g. 9000. This can't be applied when creating the interface and is done once the interface has been created. Can be used when modifying Team, VLAN, Ethernet (Future plans to implement wifi, pppoe, infiniband) This parameter defaults to `1500` when unset.
path_cost integer | Default: 100 | This is only used with 'bridge-slave' - [<1-65535>] - STP port cost for destinations via this slave.
primary string |  | This is only used with bond and is the primary interface name (for "active-backup" mode), this is the usually the 'ifname'.
priority integer | Default: 128 | This is only used with 'bridge' - sets STP priority.
slavepriority integer | Default: 32 | This is only used with 'bridge-slave' - [<0-63>] - STP priority of this slave.

state
string / required

Choices:
- absent
- present

Whether the device should exist or not, taking action if the state is different from what is stated.

stp
boolean

Choices:
- no
- yes ←

This is only used with bridge and controls whether Spanning Tree Protocol (STP) is enabled for this bridge.

type
string

Choices:
- bond
- bond-slave
- bridge
- bridge-slave
- ethernet
- generic
- ipip
- sit
- team
- team-slave
- vlan
- vxlan

This is the type of device or network connection that you wish to create or modify.
Type `generic` is added in Ansible 2.5.

updelay integer |  | This is only used with bond - updelay.
vlandev string |  | This is only used with VLAN - parent device this VLAN is on, can use ifname.
vlanid integer |  | This is only used with VLAN - VLAN ID in range <0-4095>.
vxlan_id integer added in 2.8 |  | This is only used with VXLAN - VXLAN ID.
vxlan_local string added in 2.8 |  | This is only used with VXLAN - VXLAN local IP address.
vxlan_remote string added in 2.8 |  | This is only used with VXLAN - VXLAN destination IP address.

## Examples

    # These examples are using the following inventory:
    #
    # ## Directory layout:
    #
    # |_/inventory/cloud-hosts
    # |           /group_vars/openstack-stage.yml
    # |           /host_vars/controller-01.openstack.host.com
    # |           /host_vars/controller-02.openstack.host.com
    # |_/playbook/library/nmcli.py
    # |          /playbook-add.yml
    # |          /playbook-del.yml
    # ```
    #
    # ## inventory examples
    # ### groups_vars
    # ```yml
    # ---
    # #devops_os_define_network
    # storage_gw: "192.0.2.254"
    # external_gw: "198.51.100.254"
    # tenant_gw: "203.0.113.254"
    #
    # #Team vars
    # nmcli_team:
    #   - conn_name: tenant
    #     ip4: '{{ tenant_ip }}'
    #     gw4: '{{ tenant_gw }}'
    #   - conn_name: external
    #     ip4: '{{ external_ip }}'
    #     gw4: '{{ external_gw }}'
    #   - conn_name: storage
    #     ip4: '{{ storage_ip }}'
    #     gw4: '{{ storage_gw }}'
    # nmcli_team_slave:
    #   - conn_name: em1
    #     ifname: em1
    #     master: tenant
    #   - conn_name: em2
    #     ifname: em2
    #     master: tenant
    #   - conn_name: p2p1
    #     ifname: p2p1
    #     master: storage
    #   - conn_name: p2p2
    #     ifname: p2p2
    #     master: external
    #
    # #bond vars
    # nmcli_bond:
    #   - conn_name: tenant
    #     ip4: '{{ tenant_ip }}'
    #     gw4: ''
    #     mode: balance-rr
    #   - conn_name: external
    #     ip4: '{{ external_ip }}'
    #     gw4: ''
    #     mode: balance-rr
    #   - conn_name: storage
    #     ip4: '{{ storage_ip }}'
    #     gw4: '{{ storage_gw }}'
    #     mode: balance-rr
    # nmcli_bond_slave:
    #   - conn_name: em1
    #     ifname: em1
    #     master: tenant
    #   - conn_name: em2
    #     ifname: em2
    #     master: tenant
    #   - conn_name: p2p1
    #     ifname: p2p1
    #     master: storage
    #   - conn_name: p2p2
    #     ifname: p2p2
    #     master: external
    #
    # #ethernet vars
    # nmcli_ethernet:
    #   - conn_name: em1
    #     ifname: em1
    #     ip4: '{{ tenant_ip }}'
    #     gw4: '{{ tenant_gw }}'
    #   - conn_name: em2
    #     ifname: em2
    #     ip4: '{{ tenant_ip1 }}'
    #     gw4: '{{ tenant_gw }}'
    #   - conn_name: p2p1
    #     ifname: p2p1
    #     ip4: '{{ storage_ip }}'
    #     gw4: '{{ storage_gw }}'
    #   - conn_name: p2p2
    #     ifname: p2p2
    #     ip4: '{{ external_ip }}'
    #     gw4: '{{ external_gw }}'
    # ```
    #
    # ### host_vars
    # ```yml
    # ---
    # storage_ip: "192.0.2.91/23"
    # external_ip: "198.51.100.23/21"
    # tenant_ip: "203.0.113.77/23"
    # ```

    ## playbook-add.yml example

    ---
    - hosts: openstack-stage
      remote_user: root
      tasks:

      - name: install needed network manager libs
        package:
          name:
            - NetworkManager-libnm
            - nm-connection-editor
            - libsemanage-python
            - policycoreutils-python
          state: present

    ##### Working with all cloud nodes - Teaming
      - name: Try nmcli add team - conn_name only & ip4 gw4
        nmcli:
          type: team
          conn_name: '{{ item.conn_name }}'
          ip4: '{{ item.ip4 }}'
          gw4: '{{ item.gw4 }}'
          state: present
        with_items:
          - '{{ nmcli_team }}'

      - name: Try nmcli add teams-slave
        nmcli:
          type: team-slave
          conn_name: '{{ item.conn_name }}'
          ifname: '{{ item.ifname }}'
          master: '{{ item.master }}'
          state: present
        with_items:
          - '{{ nmcli_team_slave }}'

    ###### Working with all cloud nodes - Bonding
      - name: Try nmcli add bond - conn_name only & ip4 gw4 mode
        nmcli:
          type: bond
          conn_name: '{{ item.conn_name }}'
          ip4: '{{ item.ip4 }}'
          gw4: '{{ item.gw4 }}'
          mode: '{{ item.mode }}'
          state: present
        with_items:
          - '{{ nmcli_bond }}'

      - name: Try nmcli add bond-slave
        nmcli:
          type: bond-slave
          conn_name: '{{ item.conn_name }}'
          ifname: '{{ item.ifname }}'
          master: '{{ item.master }}'
          state: present
        with_items:
          - '{{ nmcli_bond_slave }}'

    ##### Working with all cloud nodes - Ethernet
      - name: Try nmcli add Ethernet - conn_name only & ip4 gw4
        nmcli:
          type: ethernet
          conn_name: '{{ item.conn_name }}'
          ip4: '{{ item.ip4 }}'
          gw4: '{{ item.gw4 }}'
          state: present
        with_items:
          - '{{ nmcli_ethernet }}'

    ## playbook-del.yml example
    - hosts: openstack-stage
      remote_user: root
      tasks:

      - name: Try nmcli del team - multiple
        nmcli:
          conn_name: '{{ item.conn_name }}'
          state: absent
        with_items:
          - conn_name: em1
          - conn_name: em2
          - conn_name: p1p1
          - conn_name: p1p2
          - conn_name: p2p1
          - conn_name: p2p2
          - conn_name: tenant
          - conn_name: storage
          - conn_name: external
          - conn_name: team-em1
          - conn_name: team-em2
          - conn_name: team-p1p1
          - conn_name: team-p1p2
          - conn_name: team-p2p1
          - conn_name: team-p2p2

      - name: Add an Ethernet connection with static IP configuration
        nmcli:
        conn_name: my-eth1
        ifname: eth1
        type: ethernet
        ip4: 192.0.2.100/24
        gw4: 192.0.2.1
        state: present

      - name: Add an Team connection with static IP configuration
        nmcli:
          conn_name: my-team1
          ifname: my-team1
          type: team
          ip4: 192.0.2.100/24
          gw4: 192.0.2.1
          state: present
          autoconnect: yes

      - name: Optionally, at the same time specify IPv6 addresses for the device
        nmcli:
          conn_name: my-eth1
          ifname: eth1
          type: ethernet
          ip4: 192.0.2.100/24
          gw4: 192.0.2.1
          ip6: 2001:db8::cafe
          gw6: 2001:db8::1
          state: present

      - name: Add two IPv4 DNS server addresses
        nmcli:
          conn_name: my-eth1
          type: ethernet
          dns4:
          - 192.0.2.53
          - 198.51.100.53
          state: present

      - name: Make a profile usable for all compatible Ethernet interfaces
        nmcli:
          ctype: ethernet
          name: my-eth1
          ifname: '*'
          state: present

      - name: Change the property of a setting e.g. MTU
        nmcli:
          conn_name: my-eth1
          mtu: 9000
          type: ethernet
          state: present

      - name: Add VxLan
        nmcli:
          type: vxlan
          conn_name: vxlan_test1
          vxlan_id: 16
          vxlan_local: 192.168.1.2
          vxlan_remote: 192.168.1.5

      - name: Add ipip
        nmcli:
          type: ipip
          conn_name: ipip_test1
          ip_tunnel_dev: eth0
          ip_tunnel_local: 192.168.1.2
          ip_tunnel_remote: 192.168.1.5

      - name: Add sit
        nmcli:
          type: sit
          conn_name: sit_test1
          ip_tunnel_dev: eth0
          ip_tunnel_local: 192.168.1.2
          ip_tunnel_remote: 192.168.1.5

    # nmcli exits with status 0 if it succeeds and exits with a status greater
    # than zero when there is a failure. The following list of status codes may be
    # returned:
    #
    #     - 0 Success - indicates the operation succeeded
    #     - 1 Unknown or unspecified error
    #     - 2 Invalid user input, wrong nmcli invocation
    #     - 3 Timeout expired (see --wait option)
    #     - 4 Connection activation failed
    #     - 5 Connection deactivation failed
    #     - 6 Disconnecting device failed
    #     - 7 Connection deletion failed
    #     - 8 NetworkManager is not running
    #     - 9 nmcli and NetworkManager versions mismatch
    #     - 10 Connection, device, or access point does not exist.

## Status

- This module is not guaranteed to have a backwards compatible interface. [preview]

- This module is maintained by the Ansible Community. [community]

### Authors

- Chris Long (@alcamie101)

Hint

If you notice any issues in this documentation, you can edit this document to improve it.