ansible / ansible.builtin / v2.9.13 / module / nmcli Manage Networking | "added in version" 2.0 of ansible.builtin" Authors: Chris Long (@alcamie101) preview | supported by communityansible.builtin.nmcli (v2.9.13) — module
pip
Install with pip install ansible==2.9.13
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.
# 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
gw4: description: - The IPv4 gateway for this interface. - Use the format C(192.0.2.1). type: str gw6: description: - The IPv6 gateway for this interface. - Use the format C(2001:db8::1). type: str ip4: description: - The IPv4 address to this interface. - Use the format C(192.0.2.24/24). type: str ip6: description: - The IPv6 address to this interface. - Use the format C(abbe::cafe). type: str mac: description: - 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. mtu: description: - 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 C(1500) when unset. type: int stp: default: true description: - This is only used with bridge and controls whether Spanning Tree Protocol (STP) is enabled for this bridge. type: bool dns4: description: - A list of up to 3 dns servers. - IPv4 format e.g. to add two IPv4 DNS server addresses, use C(192.0.2.53 198.51.100.53). type: list dns6: description: - A list of up to 3 dns servers. - IPv6 format e.g. to add two IPv6 DNS server addresses, use C(2001:4860:4860::8888 2001:4860:4860::8844). type: list mode: choices: - 802.3ad - active-backup - balance-alb - balance-rr - balance-tlb - balance-xor - broadcast default: balance-rr description: - This is the type of device or network connection that you wish to create for a bond, team or bridge. type: str type: choices: - bond - bond-slave - bridge - bridge-slave - ethernet - generic - ipip - sit - team - team-slave - vlan - vxlan description: - This is the type of device or network connection that you wish to create or modify. - Type C(generic) is added in Ansible 2.5. type: str flags: description: - This is only used with VLAN - flags. type: str state: choices: - absent - present description: - Whether the device should exist or not, taking action if the state is different from what is stated. required: true type: str egress: description: - This is only used with VLAN - VLAN egress priority mapping. type: str ifname: description: - The interface to bind the connection to. - The connection will only be applicable to this interface name. - A special value of C('*') 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 C(conn_name) when left unset. type: str master: description: - Master <master (ifname, or connection UUID or conn_name) of bridge, team, bond master connection profile. type: str maxage: default: 20 description: - This is only used with bridge - [max-age <6-42>] STP maximum message age, in seconds. type: int miimon: description: - This is only used with bond - miimon. - This parameter defaults to C(100) when unset. type: int vlanid: description: - This is only used with VLAN - VLAN ID in range <0-4095>. type: int hairpin: default: true description: - 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. type: bool ingress: description: - This is only used with VLAN - VLAN ingress priority mapping. type: str primary: description: - This is only used with bond and is the primary interface name (for "active-backup" mode), this is the usually the 'ifname'. type: str updelay: description: - This is only used with bond - updelay. type: int vlandev: description: - This is only used with VLAN - parent device this VLAN is on, can use ifname. type: str priority: default: 128 description: - This is only used with 'bridge' - sets STP priority. type: int vxlan_id: description: - This is only used with VXLAN - VXLAN ID. type: int version_added: '2.8' version_added_collection: ansible.builtin conn_name: description: - The name used to call the connection. Pattern is <type>[-<ifname>][-<num>]. required: true type: str downdelay: description: - This is only used with bond - downdelay. type: int hellotime: default: 2 description: - This is only used with bridge - [hello-time <1-10>] STP hello time, in seconds. type: int path_cost: default: 100 description: - This is only used with 'bridge-slave' - [<1-65535>] - STP port cost for destinations via this slave. type: int ageingtime: default: 300 description: - This is only used with bridge - [ageing-time <0-1000000>] the Ethernet MAC address aging time, in seconds. type: int autoconnect: default: true description: - Whether the connection should start on boot. - Whether the connection profile can be automatically activated type: bool dns4_search: description: - A list of DNS search domains. type: list version_added: '2.5' version_added_collection: ansible.builtin dns6_search: description: - A list of DNS search domains. type: list version_added: '2.5' version_added_collection: ansible.builtin vxlan_local: description: - This is only used with VXLAN - VXLAN local IP address. type: str version_added: '2.8' version_added_collection: ansible.builtin arp_interval: description: - This is only used with bond - ARP interval. type: int forwarddelay: default: 15 description: - This is only used with bridge - [forward-delay <2-30>] STP forwarding delay, in seconds. type: int vxlan_remote: description: - This is only used with VXLAN - VXLAN destination IP address. type: str version_added: '2.8' version_added_collection: ansible.builtin arp_ip_target: description: - This is only used with bond - ARP IP target. type: str ip_tunnel_dev: description: - This is used with IPIP/SIT - parent device this IPIP/SIT tunnel, can use ifname. type: str version_added: '2.8' version_added_collection: ansible.builtin slavepriority: default: 32 description: - This is only used with 'bridge-slave' - [<0-63>] - STP priority of this slave. type: int dhcp_client_id: description: - DHCP Client Identifier sent to the DHCP server. type: str version_added: '2.5' version_added_collection: ansible.builtin ip_tunnel_local: description: - This is used with IPIP/SIT - IPIP/SIT local IP address. type: str version_added: '2.8' version_added_collection: ansible.builtin ip_tunnel_remote: description: - This is used with IPIP/SIT - IPIP/SIT destination IP address. type: str version_added: '2.8' version_added_collection: ansible.builtin