ansible.builtin.nmcli (v2.4.0.0-1) — module

Install Ansible via pip

Install with pip install ansible==2.4.0.0.post1

Description

Manage the network devices. Create, modify, and manage, ethernet, teams, bonds, vlans etc.

Requirements

• nmcli
• dbus
• NetworkManager-glib

Usage examples

Scanned by Steampunk Spotter

• Success
  Steampunk Spotter scan finished with no errors, warnings or hints.

# 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
    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 }}'

Scanned by Steampunk Spotter

• Success
  Steampunk Spotter scan finished with no errors, warnings or hints.

## 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

# 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
    type: ethernet
    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

Inputs

    
gw4:
    description:
    - 'The IPv4 gateway for this interface using this format ie: "192.0.2.1"'
    required: false

gw6:
    default: None
    description:
    - 'The IPv6 gateway for this interface using this format ie: "2001:db8::1"'
    required: false

ip4:
    default: None
    description:
    - 'The IPv4 address to this interface using this format ie: "192.0.2.24/24"'
    required: false

ip6:
    default: None
    description:
    - 'The IPv6 address to this interface using this format ie: "abbe::cafe"'
    required: false

mac:
    default: None
    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)

      '
    required: false

mtu:
    default: 1500
    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)
    required: false

stp:
    default: None
    description:
    - This is only used with bridge and controls whether Spanning Tree Protocol (STP)
      is enabled for this bridge
    required: false

dns4:
    default: None
    description:
    - '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"'
    required: false

dns6:
    description:
    - '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"'
    required: false

mode:
    choices:
    - balance-rr
    - active-backup
    - balance-xor
    - broadcast
    - 802.3ad
    - balance-tlb
    - balance-alb
    default: balence-rr
    description:
    - This is the type of device or network connection that you wish to create for a bond,
      team or bridge.
    required: false

type:
    choices:
    - ethernet
    - team
    - team-slave
    - bond
    - bond-slave
    - bridge
    - vlan
    description:
    - This is the type of device or network connection that you wish to create or modify.
    required: false

flags:
    default: None
    description:
    - This is only used with VLAN - flags
    required: false

state:
    choices:
    - present
    - absent
    description:
    - Whether the device should exist or not, taking action if the state is different
      from what is stated.
    required: true

egress:
    default: None
    description:
    - This is only used with VLAN - VLAN egress priority mapping
    required: false

ifname:
    default: conn_name
    description:
    - 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.
    required: false

master:
    default: None
    description:
    - master <master (ifname, or connection UUID or conn_name) of bridge, team, bond master
      connection profile.
    required: false

maxage:
    default: 20
    description:
    - This is only used with bridge - [max-age <6-42>] STP maximum message age, in seconds
    required: false

miimon:
    default: 100
    description:
    - This is only used with bond - miimon
    required: false

vlanid:
    default: None
    description:
    - This is only used with VLAN - VLAN ID in range <0-4095>
    required: false

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.
    required: false

ingress:
    default: None
    description:
    - This is only used with VLAN - VLAN ingress priority mapping
    required: false

primary:
    default: None
    description:
    - This is only used with bond and is the primary interface name (for "active-backup"
      mode), this is the usually the 'ifname'
    required: false

updelay:
    default: None
    description:
    - This is only used with bond - updelay
    required: false

vlandev:
    default: None
    description:
    - This is only used with VLAN - parent device this VLAN is on, can use ifname
    required: false

priority:
    default: 128
    description:
    - This is only used with 'bridge' - sets STP priority
    required: false

conn_name:
    description:
    - 'Where conn_name will be the name used to call the connection. when not provided
      a default name is generated: <type>[-<ifname>][-<num>]'
    required: true

downdelay:
    default: None
    description:
    - This is only used with bond - downdelay
    required: false

hellotime:
    default: 2
    description:
    - This is only used with bridge - [hello-time <1-10>] STP hello time, in seconds
    required: false

path_cost:
    default: 100
    description:
    - This is only used with 'bridge-slave' - [<1-65535>] - STP port cost for destinations
      via this slave
    required: false

ageingtime:
    default: 300
    description:
    - This is only used with bridge - [ageing-time <0-1000000>] the Ethernet MAC address
      aging time, in seconds
    required: false

autoconnect:
    choices:
    - 'yes'
    - 'no'
    default: 'yes'
    description:
    - Whether the connection should start on boot.
    - Whether the connection profile can be automatically activated
    required: false

arp_interval:
    default: None
    description:
    - This is only used with bond - ARP interval
    required: false

forwarddelay:
    default: 15
    description:
    - This is only used with bridge - [forward-delay <2-30>] STP forwarding delay, in
      seconds
    required: false

arp_ip_target:
    default: None
    description:
    - This is only used with bond - ARP IP target
    required: false

slavepriority:
    default: 32
    description:
    - This is only used with 'bridge-slave' - [<0-63>] - STP priority of this slave
    required: false