Try SpotterManage Networking
Authors: Chris Long (@alcamie101)
Install with ansible-galaxy collection install community.general:==8.5.0
collections:
- name: community.general
version: 8.5.0Manage 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 }}'
# - '{{ second_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"
# second_tenant_ip: "204.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: true
- 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 second ip4 address
community.general.nmcli:
conn_name: my-eth1
ifname: eth1
type: ethernet
ip4:
- 192.0.2.100/24
- 192.0.3.100/24
state: present
- name: Add second ip6 address
community.general.nmcli:
conn_name: my-eth1
ifname: eth1
type: ethernet
ip6:
- 2001:db8::cafe
- 2002:db8::cafe
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 gre
community.general.nmcli:
type: gre
conn_name: gre_test1
ip_tunnel_dev: eth0
ip_tunnel_local: 192.168.1.2
ip_tunnel_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
# nmcli exits with status 0 if it succeeds and exits with a status greater
# than zero when there is a failure. The following list of status codes may be
# returned:
#
# - 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.
- name: Create the wifi connection
community.general.nmcli:
type: wifi
conn_name: Brittany
ifname: wlp4s0
ssid: Brittany
wifi_sec:
key-mgmt: wpa-psk
psk: my_password
autoconnect: true
state: present
- name: Create a hidden AP mode wifi connection
community.general.nmcli:
type: wifi
conn_name: ChocoMaster
ifname: wlo1
ssid: ChocoMaster
wifi:
hidden: true
mode: ap
autoconnect: true
state: present
- name: Create a gsm connection
community.general.nmcli:
type: gsm
conn_name: my-gsm-provider
ifname: cdc-wdm0
gsm:
apn: my.provider.apn
username: my-provider-username
password: my-provider-password
pin: my-sim-pin
autoconnect: true
state: present
- name: Create a macvlan connection
community.general.nmcli:
type: macvlan
conn_name: my-macvlan-connection
ifname: mymacvlan0
macvlan:
mode: 2
parent: eth1
autoconnect: true
state: present
- name: Create a wireguard connection
community.general.nmcli:
type: wireguard
conn_name: my-wg-provider
ifname: mywg0
wireguard:
listen-port: 51820
private-key: my-private-key
autoconnect: true
state: present
- name: >-
Create a VPN L2TP connection for ansible_user to connect on vpn.example.com
authenticating with user 'brittany' and pre-shared key as 'Brittany123'
community.general.nmcli:
type: vpn
conn_name: my-vpn-connection
vpn:
permissions: "{{ ansible_user }}"
service-type: org.freedesktop.NetworkManager.l2tp
gateway: vpn.example.com
password-flags: 2
user: brittany
ipsec-enabled: true
ipsec-psk: "0s{{ 'Brittany123' | ansible.builtin.b64encode }}"
autoconnect: false
state: present
## Creating bond attached to bridge example
- name: Create bond attached to bridge
community.general.nmcli:
type: bond
conn_name: bond0
slave_type: bridge
master: br0
state: present
- name: Create master bridge
community.general.nmcli:
type: bridge
conn_name: br0
method4: disabled
method6: disabled
state: present
## Creating vlan connection attached to bridge
- name: Create master bridge
community.general.nmcli:
type: bridge
conn_name: br0
state: present
- name: Create VLAN 5
community.general.nmcli:
type: vlan
conn_name: eth0.5
slave_type: bridge
master: br0
vlandev: eth0
vlanid: 5
state: present
## Defining ip rules while setting a static IP
## table 'production' is set with id 200 in this example.
- name: Set Static ips for interface with ip rules and routes
community.general.nmcli:
type: ethernet
conn_name: 'eth0'
ip4: '192.168.1.50'
gw4: '192.168.1.1'
state: present
routes4_extended:
- ip: "0.0.0.0/0"
next_hop: "192.168.1.1"
table: "production"
routing_rules4:
- "priority 0 from 192.168.1.50 table 200"
gsm:
description:
- The configuration of the GSM connection.
- Note the list of suboption attributes may vary depending on which version of NetworkManager/nmcli
is installed on the host.
- 'An up-to-date list of supported attributes can be found here: U(https://networkmanager.dev/docs/api/latest/settings-gsm.html).'
- 'For instance to use apn, pin, username and password: V({apn: provider.apn, pin:
1234, username: apn.username, password: apn.password}).'
suboptions:
apn:
description:
- The GPRS Access Point Name specifying the APN used when establishing a data
session with the GSM-based network.
- The APN often determines how the user will be billed for their network usage
and whether the user has access to the Internet or just a provider-specific
walled-garden, so it is important to use the correct APN for the user's mobile
broadband plan.
- The APN may only be composed of the characters a-z, 0-9, ., and - per GSM 03.60
Section 14.9.
type: str
auto-config:
default: false
description: When V(true), the settings such as O(gsm.apn), O(gsm.username), or
O(gsm.password) will default to values that match the network the modem will
register to in the Mobile Broadband Provider database.
type: bool
device-id:
description:
- The device unique identifier (as given by the V(WWAN) management service) which
this connection applies to.
- If given, the connection will only apply to the specified device.
type: str
home-only:
default: false
description:
- When V(true), only connections to the home network will be allowed.
- Connections to roaming networks will not be made.
type: bool
mtu:
default: 0
description: If non-zero, only transmit packets of the specified size or smaller,
breaking larger packets up into multiple Ethernet frames.
type: int
network-id:
description:
- The Network ID (GSM LAI format, ie MCC-MNC) to force specific network registration.
- If the Network ID is specified, NetworkManager will attempt to force the device
to register only on the specified network.
- This can be used to ensure that the device does not roam when direct roaming
control of the device is not otherwise possible.
type: str
number:
description: Legacy setting that used to help establishing PPP data sessions for
GSM-based modems.
type: str
password:
description:
- The password used to authenticate with the network, if required.
- Many providers do not require a password, or accept any password.
- But if a password is required, it is specified here.
type: str
password-flags:
choices:
- 0
- 1
- 2
- 4
default: 0
description:
- NMSettingSecretFlags indicating how to handle the O(gsm.password) property.
- 'Following choices are allowed: V(0) B(NONE): The system is responsible for
providing and storing this secret (default), V(1) B(AGENT_OWNED): A user secret
agent is responsible for providing and storing this secret; when it is required
agents will be asked to retrieve it V(2) B(NOT_SAVED): This secret should not
be saved, but should be requested from the user each time it is needed V(4)
B(NOT_REQUIRED): In situations where it cannot be automatically determined that
the secret is required (some VPNs and PPP providers do not require all secrets)
this flag indicates that the specific secret is not required.'
type: int
pin:
description:
- If the SIM is locked with a PIN it must be unlocked before any other operations
are requested.
- Specify the PIN here to allow operation of the device.
type: str
pin-flags:
choices:
- 0
- 1
- 2
- 4
default: 0
description:
- NMSettingSecretFlags indicating how to handle the O(gsm.pin) property.
- See O(gsm.password-flags) for NMSettingSecretFlags choices.
type: int
sim-id:
description:
- The SIM card unique identifier (as given by the C(WWAN) management service)
which this connection applies to.
- If given, the connection will apply to any device also allowed by O(gsm.device-id)
which contains a SIM card matching the given identifier.
type: str
sim-operator-id:
description:
- A MCC/MNC string like V(310260) or V(21601I) identifying the specific mobile
network operator which this connection applies to.
- If given, the connection will apply to any device also allowed by O(gsm.device-id)
and O(gsm.sim-id) which contains a SIM card provisioned by the given operator.
type: str
username:
description:
- The username used to authenticate with the network, if required.
- Many providers do not require a username, or accept any username.
- But if a username is required, it is specified here.
type: dict
version_added: 3.7.0
version_added_collection: community.general
gw4:
description:
- The IPv4 gateway for this interface.
- Use the format V(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 V(2001:db8::1).
type: str
ip4:
description:
- List of IPv4 addresses to this interface.
- Use the format V(192.0.2.24/24) or V(192.0.2.24).
- If defined and O(method4) is not specified, automatically set C(ipv4.method) to
V(manual).
elements: str
type: list
ip6:
description:
- List of IPv6 addresses to this interface.
- Use the format V(abbe::cafe/128) or V(abbe::cafe).
- If defined and O(method6) is not specified, automatically set C(ipv6.method) to
V(manual).
elements: str
type: list
mac:
description:
- MAC address of the connection.
- 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,
gsm, pppoe, infiniband)
- This parameter defaults to V(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
vpn:
description:
- Configuration of a VPN connection (PPTP and L2TP).
- In order to use L2TP you need to be sure that C(network-manager-l2tp) - and C(network-manager-l2tp-gnome)
if host has UI - are installed on the host.
suboptions:
gateway:
description: The gateway to connection. It can be an IP address (for example V(192.0.2.1))
or a FQDN address (for example V(vpn.example.com)).
required: true
type: str
ipsec-enabled:
description:
- Enable or disable IPSec tunnel to L2TP host.
- This option is need when O(vpn.service-type) is V(org.freedesktop.NetworkManager.l2tp).
type: bool
ipsec-psk:
description:
- The pre-shared key in base64 encoding.
- 'You can encode using this Ansible jinja2 expression: V("0s{{ ''[YOUR PRE-SHARED
KEY]'' | ansible.builtin.b64encode }}").
'
- This is only used when O(vpn.ipsec-enabled=true).
type: str
password-flags:
choices:
- 0
- 1
- 2
- 4
default: 0
description:
- NMSettingSecretFlags indicating how to handle the C(vpn.password) property.
- 'Following choices are allowed: V(0) B(NONE): The system is responsible for
providing and storing this secret (default); V(1) B(AGENT_OWNED): A user secret
agent is responsible for providing and storing this secret; when it is required
agents will be asked to retrieve it; V(2) B(NOT_SAVED): This secret should not
be saved, but should be requested from the user each time it is needed; V(4)
B(NOT_REQUIRED): In situations where it cannot be automatically determined that
the secret is required (some VPNs and PPP providers do not require all secrets)
this flag indicates that the specific secret is not required.'
type: int
permissions:
description: User that will have permission to use the connection.
required: true
type: str
service-type:
description: This defines the service type of connection.
required: true
type: str
user:
description: Username provided by VPN administrator.
required: true
type: str
type: dict
version_added: 5.1.0
version_added_collection: community.general
dns4:
description:
- A list of up to 3 DNS servers.
- The entries must be IPv4 addresses, for example V(192.0.2.53).
elements: str
type: list
dns6:
description:
- A list of up to 3 DNS servers.
- The entries must be IPv6 addresses, for example V(2001:4860:4860::8888).
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
or bridge.
type: str
ssid:
description:
- Name of the Wireless router or the access point.
type: str
version_added: 3.0.0
version_added_collection: community.general
type:
choices:
- bond
- bond-slave
- bridge
- bridge-slave
- dummy
- ethernet
- generic
- gre
- infiniband
- ipip
- macvlan
- sit
- team
- team-slave
- vlan
- vxlan
- wifi
- gsm
- wireguard
- vpn
- loopback
description:
- This is the type of device or network connection that you wish to create or modify.
- Type V(dummy) is added in community.general 3.5.0.
- Type V(gsm) is added in community.general 3.7.0.
- Type V(infiniband) is added in community.general 2.0.0.
- Type V(loopback) is added in community.general 8.1.0.
- Type V(macvlan) is added in community.general 6.6.0.
- Type V(wireguard) is added in community.general 4.3.0.
- Type V(vpn) is added in community.general 5.1.0.
- Using V(bond-slave), V(bridge-slave), or V(team-slave) implies V(ethernet) connection
type with corresponding O(slave_type) option.
- If you want to control non-ethernet connection attached to V(bond), V(bridge), or
V(team) consider using O(slave_type) option.
type: str
wifi:
description:
- The configuration of the WiFi connection.
- Note the list of suboption attributes may vary depending on which version of NetworkManager/nmcli
is installed on the host.
- 'An up-to-date list of supported attributes can be found here: U(https://networkmanager.dev/docs/api/latest/settings-802-11-wireless.html).'
- 'For instance to create a hidden AP mode WiFi connection: V({hidden: true, mode:
ap}).'
suboptions:
ap-isolation:
choices:
- -1
- 0
- 1
default: -1
description:
- Configures AP isolation, which prevents communication between wireless devices
connected to this AP.
- This property can be set to a value different from V(-1) only when the interface
is configured in AP mode.
- If set to V(1), devices are not able to communicate with each other. This increases
security because it protects devices against attacks from other clients in the
network. At the same time, it prevents devices to access resources on the same
wireless networks as file shares, printers, etc.
- If set to V(0), devices can talk to each other.
- When set to V(-1), the global default is used; in case the global default is
unspecified it is assumed to be V(0).
type: int
assigned-mac-address:
description:
- The new field for the cloned MAC address.
- It can be either a hardware address in ASCII representation, or one of the special
values V(preserve), V(permanent), V(random) or V(stable).
- This field replaces the deprecated O(wifi.cloned-mac-address) on D-Bus, which
can only contain explicit hardware addresses.
- Note that this property only exists in D-Bus API. libnm and nmcli continue to
call this property C(cloned-mac-address).
type: str
band:
choices:
- a
- bg
description:
- 802.11 frequency band of the network.
- One of V(a) for 5GHz 802.11a or V(bg) for 2.4GHz 802.11.
- This will lock associations to the Wi-Fi network to the specific band, so for
example, if V(a) is specified, the device will not associate with the same network
in the 2.4GHz band even if the network's settings are compatible.
- This setting depends on specific driver capability and may not work with all
drivers.
type: str
bssid:
description:
- If specified, directs the device to only associate with the given access point.
- This capability is highly driver dependent and not supported by all devices.
- Note this property does not control the BSSID used when creating an Ad-Hoc network
and is unlikely to in the future.
type: str
channel:
default: 0
description:
- Wireless channel to use for the Wi-Fi connection.
- The device will only join (or create for Ad-Hoc networks) a Wi-Fi network on
the specified channel.
- Because channel numbers overlap between bands, this property also requires the
O(wifi.band) property to be set.
type: int
cloned-mac-address:
description:
- This D-Bus field is deprecated in favor of O(wifi.assigned-mac-address) which
is more flexible and allows specifying special variants like V(random).
- For libnm and nmcli, this field is called C(cloned-mac-address).
type: str
generate-mac-address-mask:
description:
- With O(wifi.cloned-mac-address) setting V(random) or V(stable), by default all
bits of the MAC address are scrambled and a locally-administered, unicast MAC
address is created. This property allows to specify that certain bits are fixed.
- Note that the least significant bit of the first MAC address will always be
unset to create a unicast MAC address.
- If the property is V(null), it is eligible to be overwritten by a default connection
setting.
- If the value is still V(null) or an empty string, the default is to create a
locally-administered, unicast MAC address.
- If the value contains one MAC address, this address is used as mask. The set
bits of the mask are to be filled with the current MAC address of the device,
while the unset bits are subject to randomization.
- Setting V(FE:FF:FF:00:00:00) means to preserve the OUI of the current MAC address
and only randomize the lower 3 bytes using the V(random) or V(stable) algorithm.
- If the value contains one additional MAC address after the mask, this address
is used instead of the current MAC address to fill the bits that shall not be
randomized.
- For example, a value of V(FE:FF:FF:00:00:00 68:F7:28:00:00:00) will set the
OUI of the MAC address to 68:F7:28, while the lower bits are randomized.
- A value of V(02:00:00:00:00:00 00:00:00:00:00:00) will create a fully scrambled
globally-administered, burned-in MAC address.
- If the value contains more than one additional MAC addresses, one of them is
chosen randomly. For example, V(02:00:00:00:00:00 00:00:00:00:00:00 02:00:00:00:00:00)
will create a fully scrambled MAC address, randomly locally or globally administered.
type: str
hidden:
default: false
description:
- If V(true), indicates that the network is a non-broadcasting network that hides
its SSID. This works both in infrastructure and AP mode.
- In infrastructure mode, various workarounds are used for a more reliable discovery
of hidden networks, such as probe-scanning the SSID. However, these workarounds
expose inherent insecurities with hidden SSID networks, and thus hidden SSID
networks should be used with caution.
- In AP mode, the created network does not broadcast its SSID.
- Note that marking the network as hidden may be a privacy issue for you (in infrastructure
mode) or client stations (in AP mode), as the explicit probe-scans are distinctly
recognizable on the air.
type: bool
mac-address:
description:
- If specified, this connection will only apply to the Wi-Fi device whose permanent
MAC address matches.
- This property does not change the MAC address of the device (for example for
MAC spoofing).
type: str
mac-address-blacklist:
description:
- A list of permanent MAC addresses of Wi-Fi devices to which this connection
should never apply.
- Each MAC address should be given in the standard hex-digits-and-colons notation
(for example, V(00:11:22:33:44:55)).
elements: str
type: list
mac-address-randomization:
choices:
- 0
- 1
- 2
default: 0
description:
- One of V(0) (never randomize unless the user has set a global default to randomize
and the supplicant supports randomization), V(1) (never randomize the MAC address),
or V(2) (always randomize the MAC address).
- This property is deprecated for O(wifi.cloned-mac-address).
type: int
mode:
choices:
- infrastructure
- mesh
- adhoc
- ap
default: infrastructure
description: Wi-Fi network mode. If blank, V(infrastructure) is assumed.
type: str
mtu:
default: 0
description: If non-zero, only transmit packets of the specified size or smaller,
breaking larger packets up into multiple Ethernet frames.
type: int
powersave:
choices:
- 0
- 1
- 2
- 3
default: 0
description:
- One of V(2) (disable Wi-Fi power saving), V(3) (enable Wi-Fi power saving),
V(1) (don't touch currently configure setting) or V(0) (use the globally configured
value).
- All other values are reserved.
type: int
rate:
default: 0
description:
- If non-zero, directs the device to only use the specified bitrate for communication
with the access point.
- Units are in Kb/s, so for example V(5500) = 5.5 Mbit/s.
- This property is highly driver dependent and not all devices support setting
a static bitrate.
type: int
tx-power:
default: 0
description:
- If non-zero, directs the device to use the specified transmit power.
- Units are dBm.
- This property is highly driver dependent and not all devices support setting
a static transmit power.
type: int
wake-on-wlan:
default: 1
description:
- The NMSettingWirelessWakeOnWLan options to enable. Not all devices support all
options.
- May be any combination of C(NM_SETTING_WIRELESS_WAKE_ON_WLAN_ANY) (V(0x2)),
C(NM_SETTING_WIRELESS_WAKE_ON_WLAN_DISCONNECT) (V(0x4)), C(NM_SETTING_WIRELESS_WAKE_ON_WLAN_MAGIC)
(V(0x8)), C(NM_SETTING_WIRELESS_WAKE_ON_WLAN_GTK_REKEY_FAILURE) (V(0x10)), C(NM_SETTING_WIRELESS_WAKE_ON_WLAN_EAP_IDENTITY_REQUEST)
(V(0x20)), C(NM_SETTING_WIRELESS_WAKE_ON_WLAN_4WAY_HANDSHAKE) (V(0x40)), C(NM_SETTING_WIRELESS_WAKE_ON_WLAN_RFKILL_RELEASE)
(V(0x80)), C(NM_SETTING_WIRELESS_WAKE_ON_WLAN_TCP) (V(0x100)) or the special
values V(0x1) (to use global settings) and V(0x8000) (to disable management
of Wake-on-LAN in NetworkManager).
- Note the option values' sum must be specified in order to combine multiple options.
type: int
type: dict
version_added: 3.5.0
version_added_collection: community.general
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 V('*') can be used for interface-independent connections.
- The ifname argument is mandatory for all connection types except bond, team, bridge,
vlan and vpn.
- This parameter defaults to O(conn_name) when left unset for all connection types
except vpn that removes it.
type: str
master:
description:
- Master <master (ifname, or connection UUID or conn_name) of bridge, team, bond master
connection profile.
- Mandatory if O(slave_type) is defined.
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 V(100) when unset.
type: int
runner:
choices:
- broadcast
- roundrobin
- activebackup
- loadbalance
- lacp
default: roundrobin
description:
- This is the type of device or network connection that you wish to create for a team.
type: str
version_added: 3.4.0
version_added_collection: community.general
vlanid:
description:
- This is only used with VLAN - VLAN ID in range <0-4095>.
type: int
hairpin:
default: false
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.
- The default change to V(false) in community.general 7.0.0. It used to be V(true)
before.
type: bool
ingress:
description:
- This is only used with VLAN - VLAN ingress priority mapping.
type: str
macvlan:
description:
- The configuration of the MAC VLAN connection.
- Note the list of suboption attributes may vary depending on which version of NetworkManager/nmcli
is installed on the host.
- 'An up-to-date list of supported attributes can be found here: U(https://networkmanager.dev/docs/api/latest/settings-macvlan.html).'
suboptions:
mode:
choices:
- 1
- 2
- 3
- 4
- 5
description:
- The macvlan mode, which specifies the communication mechanism between multiple
macvlans on the same lower device.
- 'Following choices are allowed: V(1) B(vepa), V(2) B(bridge), V(3) B(private),
V(4) B(passthru) and V(5) B(source)'
required: true
type: int
parent:
description:
- If given, specifies the parent interface name or parent connection UUID from
which this MAC-VLAN interface should be created. If this property is not specified,
the connection must contain an "802-3-ethernet" setting with a "mac-address"
property.
required: true
type: str
promiscuous:
description:
- Whether the interface should be put in promiscuous mode.
type: bool
tap:
description:
- Whether the interface should be a MACVTAP.
type: bool
type: dict
version_added: 6.6.0
version_added_collection: community.general
method4:
choices:
- auto
- link-local
- manual
- shared
- disabled
description:
- Configuration method to be used for IPv4.
- If O(ip4) is set, C(ipv4.method) is automatically set to V(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
- disabled
description:
- Configuration method to be used for IPv6
- If O(ip6) is set, C(ipv6.method) is automatically set to V(manual) and this parameter
is not needed.
- V(disabled) was added in community.general 3.3.0.
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 V(192.0.3.0/24 192.0.2.1).
- To specify more complex routes, use the O(routes4_extended) option.
elements: str
type: list
version_added: 2.0.0
version_added_collection: community.general
routes6:
description:
- The list of IPv6 routes.
- Use the format V(fd12:3456:789a:1::/64 2001:dead:beef::1).
- To specify more complex routes, use the O(routes6_extended) option.
elements: str
type: list
version_added: 4.4.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
wifi_sec:
description:
- The security configuration of the WiFi connection.
- Note the list of suboption attributes may vary depending on which version of NetworkManager/nmcli
is installed on the host.
- 'An up-to-date list of supported attributes can be found here: U(https://networkmanager.dev/docs/api/latest/settings-802-11-wireless-security.html).'
- 'For instance to use common WPA-PSK auth with a password: V({key-mgmt: wpa-psk,
psk: my_password}).'
suboptions:
auth-alg:
choices:
- open
- shared
- leap
description:
- When WEP is used (that is, if O(wifi_sec.key-mgmt) is V(none) or V(ieee8021x))
indicate the 802.11 authentication algorithm required by the AP here.
- One of V(open) for Open System, V(shared) for Shared Key, or V(leap) for Cisco
LEAP.
- When using Cisco LEAP (that is, if O(wifi_sec.key-mgmt=ieee8021x) and O(wifi_sec.auth-alg=leap))
the O(wifi_sec.leap-username) and O(wifi_sec.leap-password) properties must
be specified.
type: str
fils:
choices:
- 0
- 1
- 2
- 3
default: 0
description:
- Indicates whether Fast Initial Link Setup (802.11ai) must be enabled for the
connection.
- One of V(0) (use global default value), V(1) (disable FILS), V(2) (enable FILS
if the supplicant and the access point support it) or V(3) (enable FILS and
fail if not supported).
- When set to V(0) and no global default is set, FILS will be optionally enabled.
type: int
group:
choices:
- wep40
- wep104
- tkip
- ccmp
description:
- A list of group/broadcast encryption algorithms which prevents connections to
Wi-Fi networks that do not utilize one of the algorithms in the list.
- For maximum compatibility leave this property empty.
elements: str
type: list
key-mgmt:
choices:
- none
- ieee8021x
- owe
- wpa-psk
- sae
- wpa-eap
- wpa-eap-suite-b-192
description:
- Key management used for the connection.
- One of V(none) (WEP or no password protection), V(ieee8021x) (Dynamic WEP),
V(owe) (Opportunistic Wireless Encryption), V(wpa-psk) (WPA2 + WPA3 personal),
V(sae) (WPA3 personal only), V(wpa-eap) (WPA2 + WPA3 enterprise) or V(wpa-eap-suite-b-192)
(WPA3 enterprise only).
- This property must be set for any Wi-Fi connection that uses security.
type: str
leap-password:
description: The login password for legacy LEAP connections (that is, if O(wifi_sec.key-mgmt=ieee8021x)
and O(wifi_sec.auth-alg=leap)).
type: str
leap-password-flags:
description: Flags indicating how to handle the O(wifi_sec.leap-password) property.
elements: int
type: list
leap-username:
description: The login username for legacy LEAP connections (that is, if O(wifi_sec.key-mgmt=ieee8021x)
and O(wifi_sec.auth-alg=leap)).
type: str
pairwise:
choices:
- tkip
- ccmp
description:
- A list of pairwise encryption algorithms which prevents connections to Wi-Fi
networks that do not utilize one of the algorithms in the list.
- For maximum compatibility leave this property empty.
elements: str
type: list
pmf:
choices:
- 0
- 1
- 2
- 3
default: 0
description:
- Indicates whether Protected Management Frames (802.11w) must be enabled for
the connection.
- One of V(0) (use global default value), V(1) (disable PMF), V(2) (enable PMF
if the supplicant and the access point support it) or V(3) (enable PMF and fail
if not supported).
- When set to V(0) and no global default is set, PMF will be optionally enabled.
type: int
proto:
choices:
- wpa
- rsn
description:
- List of strings specifying the allowed WPA protocol versions to use.
- Each element may be V(wpa) (allow WPA) or V(rsn) (allow WPA2/RSN).
- If not specified, both WPA and RSN connections are allowed.
elements: str
type: list
psk:
description:
- Pre-Shared-Key for WPA networks.
- For WPA-PSK, it is either an ASCII passphrase of 8 to 63 characters that is
(as specified in the 802.11i standard) hashed to derive the actual key, or the
key in form of 64 hexadecimal character.
- The WPA3-Personal networks use a passphrase of any length for SAE authentication.
type: str
psk-flags:
description: Flags indicating how to handle the O(wifi_sec.psk) property.
elements: int
type: list
wep-key-flags:
description:
- Flags indicating how to handle the O(wifi_sec.wep-key0), O(wifi_sec.wep-key1),
O(wifi_sec.wep-key2), and O(wifi_sec.wep-key3) properties.
elements: int
type: list
wep-key-type:
choices:
- 1
- 2
description:
- Controls the interpretation of WEP keys.
- Allowed values are V(1), in which case the key is either a 10- or 26-character
hexadecimal string, or a 5- or 13-character ASCII password; or V(2), in which
case the passphrase is provided as a string and will be hashed using the de-facto
MD5 method to derive the actual WEP key.
type: int
wep-key0:
description:
- Index 0 WEP key. This is the WEP key used in most networks.
- See the O(wifi_sec.wep-key-type) property for a description of how this key
is interpreted.
type: str
wep-key1:
description:
- Index 1 WEP key. This WEP index is not used by most networks.
- See the O(wifi_sec.wep-key-type) property for a description of how this key
is interpreted.
type: str
wep-key2:
description:
- Index 2 WEP key. This WEP index is not used by most networks.
- See the O(wifi_sec.wep-key-type) property for a description of how this key
is interpreted.
type: str
wep-key3:
description:
- Index 3 WEP key. This WEP index is not used by most networks.
- See the O(wifi_sec.wep-key-type) property for a description of how this key
is interpreted.
type: str
wep-tx-keyidx:
choices:
- 0
- 1
- 2
- 3
default: 0
description:
- When static WEP is used (that is, if O(wifi_sec.key-mgmt=none)) and a non-default
WEP key index is used by the AP, put that WEP key index here.
- Valid values are V(0) (default key) through V(3).
- Note that some consumer access points (like the Linksys WRT54G) number the keys
V(1) to V(4).
type: int
wps-method:
default: 0
description:
- Flags indicating which mode of WPS is to be used if any.
- There is little point in changing the default setting as NetworkManager will
automatically determine whether it is feasible to start WPS enrollment from
the Access Point capabilities.
- WPS can be disabled by setting this property to a value of V(1).
type: int
type: dict
version_added: 3.0.0
version_added_collection: community.general
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
may_fail4:
default: true
description:
- If you need O(ip4) configured before C(network-online.target) is reached, set this
option to V(false).
- This option applies when O(method4) is not V(disabled).
type: bool
version_added: 3.3.0
version_added_collection: community.general
path_cost:
default: 100
description:
- This is only used with 'bridge-slave' - [<1-65535>] - STP port cost for destinations
via this slave.
type: int
wireguard:
description:
- The configuration of the Wireguard connection.
- Note the list of suboption attributes may vary depending on which version of NetworkManager/nmcli
is installed on the host.
- 'An up-to-date list of supported attributes can be found here: U(https://networkmanager.dev/docs/api/latest/settings-wireguard.html).'
- 'For instance to configure a listen port: V({listen-port: 12345}).'
suboptions:
fwmark:
description:
- The 32-bit fwmark for outgoing packets.
- The use of fwmark is optional and is by default off. Setting it to 0 disables
it.
- Note that O(wireguard.ip4-auto-default-route) or O(wireguard.ip6-auto-default-route)
enabled, implies to automatically choose a fwmark.
type: int
ip4-auto-default-route:
description:
- Whether to enable special handling of the IPv4 default route.
- If enabled, the IPv4 default route from O(wireguard.peer-routes) will be placed
to a dedicated routing-table and two policy routing rules will be added.
- The fwmark number is also used as routing-table for the default-route, and if
fwmark is zero, an unused fwmark/table is chosen automatically. This corresponds
to what wg-quick does with Table=auto and what WireGuard calls "Improved Rule-based
Routing"
type: bool
ip6-auto-default-route:
description:
- Like O(wireguard.ip4-auto-default-route), but for the IPv6 default route.
type: bool
listen-port:
description: The WireGuard connection listen-port. If not specified, the port
will be chosen randomly when the interface comes up.
type: int
mtu:
description:
- If non-zero, only transmit packets of the specified size or smaller, breaking
larger packets up into multiple fragments.
- If zero a default MTU is used. Note that contrary to wg-quick's MTU setting,
this does not take into account the current routes at the time of activation.
type: int
peer-routes:
description:
- Whether to automatically add routes for the AllowedIPs ranges of the peers.
- If V(true) (the default), NetworkManager will automatically add routes in the
routing tables according to C(ipv4.route-table) and C(ipv6.route-table). Usually
you want this automatism enabled.
- If V(false), no such routes are added automatically. In this case, the user
may want to configure static routes in C(ipv4.routes) and C(ipv6.routes), respectively.
- Note that if the peer's AllowedIPs is V(0.0.0.0/0) or V(::/0) and the profile's
C(ipv4.never-default) or C(ipv6.never-default) setting is enabled, the peer
route for this peer won't be added automatically.
type: bool
private-key:
description: The 256 bit private-key in base64 encoding.
type: str
private-key-flags:
choices:
- 0
- 1
- 2
description: C(NMSettingSecretFlags) indicating how to handle the O(wireguard.private-key)
property.
type: int
type: dict
version_added: 4.3.0
version_added_collection: community.general
ageingtime:
default: 300
description:
- This is only used with bridge - [ageing-time <0-1000000>] the Ethernet MAC address
aging time, in seconds.
type: int
slave_type:
choices:
- bond
- bridge
- team
description:
- Type of the device of this slave's master connection (for example V(bond)).
type: str
version_added: 7.0.0
version_added_collection: community.general
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
ip_privacy6:
choices:
- disabled
- prefer-public-addr
- prefer-temp-addr
- unknown
description:
- If enabled, it makes the kernel generate a temporary IPv6 address in addition to
the public one.
type: str
version_added: 4.2.0
version_added_collection: community.general
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
dns4_options:
description:
- A list of DNS options.
elements: str
type: list
version_added: 7.2.0
version_added_collection: community.general
dns6_options:
description:
- A list of DNS options.
elements: str
type: list
version_added: 7.2.0
version_added_collection: community.general
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 GRE/IPIP/SIT - parent device this GRE/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
route_metric6:
description:
- Set metric level of IPv6 routes configured on interface.
type: int
version_added: 4.4.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
addr_gen_mode6:
choices:
- default
- default-or-eui64
- eui64
- stable-privacy
description:
- Configure method for creating the address for use with IPv6 Stateless Address Autoconfiguration.
- V(default) and V(default-or-eui64) have been added in community.general 6.5.0.
type: str
version_added: 4.2.0
version_added_collection: community.general
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
routing_rules4:
description:
- Is the same as in an C(ip rule add) command, except always requires specifying a
priority.
elements: str
type: list
version_added: 3.3.0
version_added_collection: community.general
transport_mode:
choices:
- datagram
- connected
description:
- This option sets the connection type of Infiniband IPoIB devices.
type: str
version_added: 5.8.0
version_added_collection: community.general
gw4_ignore_auto:
default: false
description:
- Ignore automatically configured IPv4 routes.
type: bool
version_added: 3.2.0
version_added_collection: community.general
gw6_ignore_auto:
default: false
description:
- Ignore automatically configured IPv6 routes.
type: bool
version_added: 3.2.0
version_added_collection: community.general
ip_tunnel_local:
description:
- This is used with GRE/IPIP/SIT - GRE/IPIP/SIT local IP address.
type: str
dns4_ignore_auto:
default: false
description:
- Ignore automatically configured IPv4 name servers.
type: bool
version_added: 3.2.0
version_added_collection: community.general
dns6_ignore_auto:
default: false
description:
- Ignore automatically configured IPv6 name servers.
type: bool
version_added: 3.2.0
version_added_collection: community.general
ip_tunnel_remote:
description:
- This is used with GRE/IPIP/SIT - GRE/IPIP/SIT destination IP address.
type: str
routes4_extended:
description:
- The list of IPv4 routes.
elements: dict
suboptions:
cwnd:
description:
- The clamp for congestion window.
type: int
ip:
description:
- IP or prefix of route.
- Use the format V(192.0.3.0/24).
required: true
type: str
metric:
description:
- Route metric.
type: int
mtu:
description:
- If non-zero, only transmit packets of the specified size or smaller.
type: int
next_hop:
description:
- Use the format V(192.0.2.1).
type: str
onlink:
description:
- Pretend that the nexthop is directly attached to this link, even if it does
not match any interface prefix.
type: bool
table:
description:
- The table to add this route to.
- The default depends on C(ipv4.route-table).
type: int
tos:
description:
- The Type Of Service.
type: int
type: list
routes6_extended:
description:
- The list of IPv6 routes but with parameters.
elements: dict
suboptions:
cwnd:
description:
- The clamp for congestion window.
type: int
ip:
description:
- IP or prefix of route.
- Use the format V(fd12:3456:789a:1::/64).
required: true
type: str
metric:
description:
- Route metric.
type: int
mtu:
description:
- If non-zero, only transmit packets of the specified size or smaller.
type: int
next_hop:
description:
- Use the format V(2001:dead:beef::1).
type: str
onlink:
description:
- Pretend that the nexthop is directly attached to this link, even if it does
not match any interface prefix.
type: bool
table:
description:
- The table to add this route to.
- The default depends on C(ipv6.route-table).
type: int
type: list
runner_fast_rate:
description:
- Option specifies the rate at which our link partner is asked to transmit LACPDU
packets. If this is V(true) then packets will be sent once per second. Otherwise
they will be sent every 30 seconds.
- Only allowed for O(runner=lacp).
type: bool
version_added: 6.5.0
version_added_collection: community.general
xmit_hash_policy:
description:
- This is only used with bond - xmit_hash_policy type.
type: str
version_added: 5.6.0
version_added_collection: community.general
ip_tunnel_input_key:
description:
- The key used for tunnel input packets.
- Only used when O(type=gre).
type: str
version_added: 3.6.0
version_added_collection: community.general
ip_tunnel_output_key:
description:
- The key used for tunnel output packets.
- Only used when O(type=gre).
type: str
version_added: 3.6.0
version_added_collection: community.general
runner_hwaddr_policy:
choices:
- same_all
- by_active
- only_active
description:
- This defines the policy of how hardware addresses of team device and port devices
should be set during the team lifetime.
type: str
version_added: 3.4.0
version_added_collection: community.general
ignore_unsupported_suboptions:
default: false
description:
- Ignore suboptions which are invalid or unsupported by the version of NetworkManager/nmcli
installed on the host.
- Only O(wifi) and O(wifi_sec) options are currently affected.
type: bool
version_added: 3.6.0
version_added_collection: community.general