community.general.nmcli – Manage Networking

Note

This plugin is part of the community.general collection (version 2.2.0).

To install it use: ansible-galaxy collection install community.general.

To use it in a playbook, specify: community.general.nmcli.

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.

  • On CentOS 7 and Fedora <=28 like systems, the requirements can be met by installing the following packages: NetworkManager-tui.

  • On Ubuntu and Debian like systems, the requirements can be met by installing the following packages: network-manager

  • On openSUSE, the requirements can be met by installing the following packages: NetworkManager.

Requirements

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

  • 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
DHCP Client Identifier sent to the DHCP server.
dns4
list / elements=string
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 / elements=string
A list of DNS search domains.
dns6
list / elements=string
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 / elements=string
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.
This parameter is mutually_exclusive with never_default4 parameter.
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.
If defined and method4 is not specified, automatically set ipv4.method to manual.
ip6
string
The IPv6 address to this interface.
Use the format abbe::cafe.
If defined and method6 is not specified, automatically set ipv6.method to manual.
ip_tunnel_dev
string
This is used with IPIP/SIT - parent device this IPIP/SIT tunnel, can use ifname.
ip_tunnel_local
string
This is used with IPIP/SIT - IPIP/SIT local IP address.
ip_tunnel_remote
string
This is used with IPIP/SIT - IPIP/SIT destination IP address.
mac
string
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.
method4
string
added in 2.2.0 of community.general
    Choices:
  • auto
  • link-local
  • manual
  • shared
  • disabled
Configuration method to be used for IPv4.
If ip4 is set, ipv4.method is automatically set to manual and this parameter is not needed.
method6
string
added in 2.2.0 of community.general
    Choices:
  • ignore
  • auto
  • dhcp
  • link-local
  • manual
  • shared
Configuration method to be used for IPv6
If ip6 is set, ipv6.method is automatically set to manual and this parameter is not needed.
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.
never_default4
boolean
added in 2.0.0 of community.general
    Choices:
  • no ←
  • yes
Set as default route.
This parameter is mutually_exclusive with gw4 parameter.
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.
route_metric4
integer
added in 2.0.0 of community.general
Set metric level of ipv4 routes configured on interface.
routes4
list / elements=string
added in 2.0.0 of community.general
The list of ipv4 routes.
Use the format '192.0.3.0/24 192.0.2.1'
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
  • infiniband
  • 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.
Type infiniband is added in community.general 2.0.0.
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
This is only used with VXLAN - VXLAN ID.
vxlan_local
string
This is only used with VXLAN - VXLAN local IP address.
vxlan_remote
string
This is only used with VXLAN - VXLAN destination IP address.
zone
string
added in 2.0.0 of community.general
The trust level of the connection.
When updating this property on a currently activated connection, the change takes effect immediately.

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
    ansible.builtin.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
    community.general.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
    community.general.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
    community.general.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
    community.general.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
    community.general.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
    community.general.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
    community.general.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
    community.general.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
    community.general.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
    community.general.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
    community.general.nmcli:
      ctype: ethernet
      name: my-eth1
      ifname: '*'
      state: present

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

  - name: Add VxLan
    community.general.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
    community.general.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
    community.general.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

  - name: Add zone
    community.general.nmcli:
      type: ethernet
      conn_name: my-eth1
      zone: external
      state: present

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

Authors

  • Chris Long (@alcamie101)