nmcli - Manage Networking

New in version 2.0.

Synopsis
Requirements (on host that executes module)
Options
Examples
- Status

Synopsis

Manage the network devices. Create, modify, and manage, ethernet, teams, bonds, vlans etc.

Requirements (on host that executes module)

nmcli
dbus
NetworkManager-glib

Options

parameter	required	default	choices	comments
ageingtime	no	300		This is only used with bridge - [ageing-time <0-1000000>] the Ethernet MAC address aging time, in seconds
arp_interval	no	None		This is only used with bond - ARP interval
arp_ip_target	no	None		This is only used with bond - ARP IP target
autoconnect	no	yes	yes no	Whether the connection should start on boot. Whether the connection profile can be automatically activated
conn_name	yes			Where conn_name will be the name used to call the connection. when not provided a default name is generated: <type>[-<ifname>][-<num>]
dns4	no	None		A list of upto 3 dns servers, ipv4 format e.g. To add two IPv4 DNS server addresses: "192.0.2.53 198.51.100.53"
dns6	no			A list of upto 3 dns servers, ipv6 format e.g. To add two IPv6 DNS server addresses: "2001:4860:4860::8888 2001:4860:4860::8844"
downdelay	no	None		This is only used with bond - downdelay
egress	no	None		This is only used with VLAN - VLAN egress priority mapping
flags	no	None		This is only used with VLAN - flags
forwarddelay	no	15		This is only used with bridge - [forward-delay <2-30>] STP forwarding delay, in seconds
gw4	no			The IPv4 gateway for this interface using this format ie: "192.0.2.1"
gw6	no	None		The IPv6 gateway for this interface using this format ie: "2001:db8::1"
hairpin	no	True		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	no	2		This is only used with bridge - [hello-time <1-10>] STP hello time, in seconds
ifname	no	conn_name		Where IFNAME will be the what we call the interface name. 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.
ingress	no	None		This is only used with VLAN - VLAN ingress priority mapping
ip4	no	None		The IPv4 address to this interface using this format ie: "192.0.2.24/24"
ip6	no	None		The IPv6 address to this interface using this format ie: "abbe::cafe"
mac	no	None		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	no	None		master <master (ifname, or connection UUID or conn_name) of bridge, team, bond master connection profile.
maxage	no	20		This is only used with bridge - [max-age <6-42>] STP maximum message age, in seconds
miimon	no	100		This is only used with bond - miimon
mode	no	balence-rr	balance-rr active-backup balance-xor broadcast 802.3ad balance-tlb balance-alb	This is the type of device or network connection that you wish to create for a bond, team or bridge.
mtu	no	1500		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)
path_cost	no	100		This is only used with 'bridge-slave' - [<1-65535>] - STP port cost for destinations via this slave
primary	no	None		This is only used with bond and is the primary interface name (for "active-backup" mode), this is the usually the 'ifname'
priority	no	128		This is only used with 'bridge' - sets STP priority
slavepriority	no	32		This is only used with 'bridge-slave' - [<0-63>] - STP priority of this slave
state	yes		present absent	Whether the device should exist or not, taking action if the state is different from what is stated.
stp	no	None		This is only used with bridge and controls whether Spanning Tree Protocol (STP) is enabled for this bridge
type	no		ethernet team team-slave bond bond-slave bridge vlan	This is the type of device or network connection that you wish to create or modify.
updelay	no	None		This is only used with bond - updelay
vlandev	no	None		This is only used with VLAN - parent device this VLAN is on, can use ifname
vlanid	no	None		This is only used with VLAN - VLAN ID in range <0-4095>

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
    yum:
      name: '{{ item }}'
      state: installed
    with_items:
      - NetworkManager-glib
      - libnm-qt-devel.x86_64
      - nm-connection-editor.x86_64
      - libsemanage-python
      - policycoreutils-python

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

# To add an Ethernet connection with static IP configuration, issue a command as follows
  - nmcli:
    conn_name: my-eth1
    ifname: eth1
    type: ethernet
    ip4: 192.0.2.100/24
    gw4: 192.0.2.1
    state: present

# To add an Team connection with static IP configuration, issue a command as follows
  - 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

# Optionally, at the same time specify IPv6 addresses for the device as follows:
  - 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

# To add two IPv4 DNS server addresses:
  - nmcli:
    conn_name: my-eth1
    type: ethernet
    dns4:
      - 192.0.2.53
      - 198.51.100.53
    state: present

# To make a profile usable for all compatible Ethernet interfaces, issue a command as follows
  - nmcli:
    ctype: ethernet
    name: my-eth1
    ifname: '*'
    state: present

# To change the property of a setting e.g. MTU, issue a command as follows:
  - nmcli:
    conn_name: my-eth1
    mtu: 9000
    type: ethernet
    state: present

# Exit Status's:
#     - nmcli exits with status 0 if it succeeds, a value greater than 0 is
#     returned if an error occurs.
#     - 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 flagged as preview which means that it is not guaranteed to have a backwards compatible interface.

For help in developing on modules, should you be so inclined, please read Community Information & Contributing, Testing Ansible and Developing Modules.

© 2012–2018 Michael DeHaan
© 2018–2019 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/ansible/2.4/nmcli_module.html