nmcli – Manage Networking
nmcli – Manage Networking
New in version 2.0.
Synopsis
- Manage the network devices. Create, modify and manage various connection and device type e.g., ethernet, teams, bonds, vlans etc.
- On CentOS and Fedora 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-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-glib
- 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 |
|
Whether the connection should start on boot. Whether the connection profile can be automatically activated |
conn_name string / required |
Where conn_name will be the name used to call the connection. when not provided a default name is generated: [-][-] | |
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 | |
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 | |
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 | |
gw6 string |
The IPv6 gateway for this interface. Use the format | |
hairpin boolean |
|
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 The ifname argument is mandatory for all connection types except bond, team, bridge and vlan. This parameter defaults to | |
ingress string |
This is only used with VLAN - VLAN ingress priority mapping. | |
ip4 string |
The IPv4 address to this interface. Use the format | |
ip6 string |
The IPv6 address to this interface. Use the format | |
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 | |
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 | |
mode string |
|
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 | |
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 |
|
Whether the device should exist or not, taking action if the state is different from what is stated. |
stp boolean |
|
This is only used with bridge and controls whether Spanning Tree Protocol (STP) is enabled for this bridge. |
type string |
|
This is the type of device or network connection that you wish to create or modify. Type |
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-glib
- 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)
© 2012–2018 Michael DeHaan
© 2018–2019 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/ansible/2.8/modules/nmcli_module.html