ansible / ansible.builtin / v2.9.3 / module / nmcli Manage Networking | "added in version" 2.0 of ansible.builtin" Authors: Chris Long (@alcamie101) preview | supported by communityansible.builtin.nmcli (v2.9.3) — module
pip
Install with pip install ansible==2.9.3
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.
# 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
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