community / community.general / 2.5.9 / module / nmcli Manage Networking Authors: Chris Long (@alcamie101)community.general.nmcli (2.5.9) — module
Install with ansible-galaxy collection install community.general:==2.5.9
collections: - name: community.general version: 2.5.9
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.
On CentOS 7 and Fedora <=28 like systems, the requirements can be met by installing the following packages: NetworkManager-tui.
On Ubuntu and Debian like systems, the requirements can be met by installing the following packages: network-manager
On openSUSE, the requirements can be met by installing the following packages: NetworkManager.
# 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 ansible.builtin.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 community.general.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 community.general.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 community.general.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 community.general.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 community.general.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 community.general.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 community.general.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 community.general.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 community.general.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 community.general.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 community.general.nmcli: ctype: ethernet name: my-eth1 ifname: '*' state: present - name: Change the property of a setting e.g. MTU community.general.nmcli: conn_name: my-eth1 mtu: 9000 type: ethernet state: present - name: Add VxLan community.general.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 community.general.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 community.general.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 - name: Add zone community.general.nmcli: type: ethernet conn_name: my-eth1 zone: external state: present
gw4: description: - The IPv4 gateway for this interface. - Use the format C(192.0.2.1). - This parameter is mutually_exclusive with never_default4 parameter. 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). - If defined and I(method4) is not specified, automatically set C(ipv4.method) to C(manual). type: str ip6: description: - The IPv6 address to this interface. - Use the format C(abbe::cafe). - If defined and I(method6) is not specified, automatically set C(ipv6.method) to C(manual). 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. type: str 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). elements: str 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). elements: str 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 - infiniband - 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 C(infiniband) is added in community.general 2.0.0. type: str zone: description: - The trust level of the connection. - When updating this property on a currently activated connection, the change takes effect immediately. type: str version_added: 2.0.0 version_added_collection: community.general 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 method4: choices: - auto - link-local - manual - shared - disabled description: - Configuration method to be used for IPv4. - If I(ip4) is set, C(ipv4.method) is automatically set to C(manual) and this parameter is not needed. type: str version_added: 2.2.0 version_added_collection: community.general method6: choices: - ignore - auto - dhcp - link-local - manual - shared description: - Configuration method to be used for IPv6 - If I(ip6) is set, C(ipv6.method) is automatically set to C(manual) and this parameter is not needed. type: str version_added: 2.2.0 version_added_collection: community.general 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 routes4: description: - The list of ipv4 routes. - Use the format '192.0.3.0/24 192.0.2.1' elements: str type: list version_added: 2.0.0 version_added_collection: community.general 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 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. elements: str type: list dns6_search: description: - A list of DNS search domains. elements: str type: list vxlan_local: description: - This is only used with VXLAN - VXLAN local IP address. type: str 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 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 route_metric4: description: - Set metric level of ipv4 routes configured on interface. type: int version_added: 2.0.0 version_added_collection: community.general 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 never_default4: default: false description: - Set as default route. - This parameter is mutually_exclusive with gw4 parameter. type: bool version_added: 2.0.0 version_added_collection: community.general ip_tunnel_local: description: - This is used with IPIP/SIT - IPIP/SIT local IP address. type: str ip_tunnel_remote: description: - This is used with IPIP/SIT - IPIP/SIT destination IP address. type: str