New in version 2.0.
Manage the network devices. Create, modify, and manage, ethernet, teams, bonds, vlans etc.
| 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 |
|
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 |
| 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 |
| 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 |
| This is the type of device or network connection that you wish to create. |
|
| 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> |
The following examples are working examples that I have run in the field. I followed follow the structure:
```
|_/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
```yml
---
- 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
```yml
---
- 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 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.
For more information on what this means please read Extras Modules
For help in developing on modules, should you be so inclined, please read Community Information & Contributing, developing_test_pr and Developing Modules.
© 2012–2016 Michael DeHaan
© 2016 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/ansible/nmcli_module.html