cisco.meraki.meraki_ms_switchport – Manage switchports on a switch in the Meraki cloud

Note

This plugin is part of the cisco.meraki collection (version 2.5.0).

You might already have this collection installed if you are using the ansible package. It is not included in ansible-core. To check whether it is installed, run ansible-galaxy collection list.

To install it, use: ansible-galaxy collection install cisco.meraki.

To use it in a playbook, specify: cisco.meraki.meraki_ms_switchport.

Synopsis

  • Allows for management of switchports settings for Meraki MS switches.

Parameters

Parameter Choices/Defaults Comments
access_policy_number
integer
Number of the access policy to apply.
Only applicable to access port types.
access_policy_type
string
    Choices:
  • Open
  • Custom access policy
  • MAC allow list
  • Sticky MAC allow list
Type of access policy to apply to port.
allowed_vlans
list / elements=string
Default:
"all"
List of VLAN numbers to be allowed on switchport.
auth_key
string / required
Authentication key provided by the dashboard. Required if environmental variable MERAKI_KEY is not set.
enabled
boolean
    Choices:
  • no
  • yes ←
Whether a switchport should be enabled or disabled.
host
string
Default:
"api.meraki.com"
Hostname for Meraki dashboard.
Can be used to access regional Meraki environments, such as China.
internal_error_retry_time
integer
Default:
60
Number of seconds to retry if server returns an internal server error.
isolation_enabled
boolean
    Choices:
  • no ←
  • yes
Isolation status of switchport.
link_negotiation
string
    Choices:
  • Auto negotiate ←
  • 100 Megabit (auto)
  • 100 Megabit full duplex (forced)
Link speed for the switchport.
mac_allow_list
dictionary
MAC addresses list that are allowed on a port.
Only applicable to access port type.
Only applicable to access_policy_type "MAC allow list".
macs
list / elements=string
List of MAC addresses to update with based on state option.
state
string
    Choices:
  • merged
  • replaced ←
  • deleted
The state the configuration should be left in.
Merged, MAC addresses provided will be added to the current allow list.
Replaced, All MAC addresses are overwritten, only the MAC addresses provided with exist in the allow list.
Deleted, Remove the MAC addresses provided from the current allow list.
name
string
Switchport description.

aliases: description
number
string
Port number.
org_id
string
ID of organization.
org_name
string
Name of organization.

aliases: organization
output_format
string
    Choices:
  • snakecase ←
  • camelcase
Instructs module whether response keys should be snake case (ex. net_id) or camel case (ex. netId).
output_level
string
    Choices:
  • debug
  • normal ←
Set amount of debug output during module execution.
poe_enabled
boolean
    Choices:
  • no
  • yes ←
Enable or disable Power Over Ethernet on a port.
rate_limit_retry_time
integer
Default:
165
Number of seconds to retry if rate limiter is triggered.
rstp_enabled
boolean
    Choices:
  • no
  • yes ←
Enable or disable Rapid Spanning Tree Protocol on a port.
serial
string / required
Serial nubmer of the switch.
state
string
    Choices:
  • query ←
  • present
Specifies whether a switchport should be queried or modified.
sticky_mac_allow_list
dictionary
MAC addresses list that are allowed on a port.
Only applicable to access port type.
Only applicable to access_policy_type "Sticky MAC allow list".
macs
list / elements=string
List of MAC addresses to update with based on state option.
state
string
    Choices:
  • merged
  • replaced ←
  • deleted
The state the configuration should be left in.
Merged, MAC addresses provided will be added to the current allow list.
Replaced, All MAC addresses are overwritten, only the MAC addresses provided with exist in the allow list.
Deleted, Remove the MAC addresses provided from the current allow list.
sticky_mac_allow_list_limit
integer
The number of MAC addresses allowed in the sticky port allow list.
Only applicable to access port type.
Only applicable to access_policy_type "Sticky MAC allow list".
The value must be equal to or greater then the list size of sticky_mac_allow_list. Value will be checked for validity, during processing.
stp_guard
string
    Choices:
  • disabled ←
  • root guard
  • bpdu guard
  • loop guard
Set state of STP guard.
tags
list / elements=string
List of tags to assign to a port.
timeout
integer
Default:
30
Time to timeout for HTTP requests.
type
string
    Choices:
  • access ←
  • trunk
Set port type.
use_https
boolean
    Choices:
  • no
  • yes ←
If no, it will use HTTP. Otherwise it will use HTTPS.
Only useful for internal Meraki developers.
use_proxy
boolean
    Choices:
  • no ←
  • yes
If no, it will not use a proxy, even if one is defined in an environment variable on the target hosts.
validate_certs
boolean
    Choices:
  • no
  • yes ←
Whether to validate HTTP certificates.
vlan
integer
VLAN number assigned to port.
If a port is of type trunk, the specified VLAN is the native VLAN.
voice_vlan
integer
VLAN number assigned to a port for voice traffic.
Only applicable to access port type.
Only applicable if voice_vlan_state is set to present.
voice_vlan_state
string
    Choices:
  • absent
  • present ←
Specifies whether voice vlan configuration should be present or absent.

Notes

Note

  • More information about the Meraki API can be found at https://dashboard.meraki.com/api_docs.
  • Some of the options are likely only used for developers within Meraki.
  • As of Ansible 2.9, Meraki modules output keys as snake case. To use camel case, set the ANSIBLE_MERAKI_FORMAT environment variable to camelcase.
  • Ansible’s Meraki modules will stop supporting camel case output in Ansible 2.13. Please update your playbooks.
  • Check Mode downloads the current configuration from the dashboard, then compares changes against this download. Check Mode will report changed if there are differences in the configurations, but does not submit changes to the API for validation of change.

Examples

- name: Query information about all switchports on a switch
  meraki_switchport:
    auth_key: abc12345
    state: query
    serial: ABC-123
  delegate_to: localhost

- name: Query information about all switchports on a switch
  meraki_switchport:
    auth_key: abc12345
    state: query
    serial: ABC-123
    number: 2
  delegate_to: localhost

- name: Name switchport
  meraki_switchport:
    auth_key: abc12345
    state: present
    serial: ABC-123
    number: 7
    name: Test Port
  delegate_to: localhost

- name: Configure access port with voice VLAN
  meraki_switchport:
    auth_key: abc12345
    state: present
    serial: ABC-123
    number: 7
    enabled: true
    name: Test Port
    tags: desktop
    type: access
    vlan: 10
    voice_vlan: 11
  delegate_to: localhost

- name: Check access port for idempotency
  meraki_switchport:
    auth_key: abc12345
    state: present
    serial: ABC-123
    number: 7
    enabled: true
    name: Test Port
    tags: desktop
    type: access
    vlan: 10
    voice_vlan: 11
  delegate_to: localhost

- name: Configure trunk port with specific VLANs
  meraki_switchport:
    auth_key: abc12345
    state: present
    serial: ABC-123
    number: 7
    enabled: true
    name: Server port
    tags: server
    type: trunk
    allowed_vlans:
      - 10
      - 15
      - 20
  delegate_to: localhost

- name: Configure access port with sticky MAC allow list and limit.
  meraki_switchport:
    auth_key: abc12345
    state: present
    serial: ABC-123
    number: 5
    sticky_mac_allow_limit: 3
    sticky_mac_allow_list:
        macs:
          - aa:aa:bb:bb:cc:cc
          - bb:bb:aa:aa:cc:cc
          - 11:aa:bb:bb:cc:cc
        state: replaced
    delegate_to: localhost

- name: Delete an existing MAC address from the sticky MAC allow list.
  meraki_switchport:
    auth_key: abc12345
    state: present
    serial: ABC-123
    number: 5
    sticky_mac_allow_list:
        macs:
          - aa:aa:bb:bb:cc:cc
        state: deleted
    delegate_to: localhost

- name: Add a MAC address to sticky MAC allow list.
  meraki_switchport:
    auth_key: abc12345
    state: present
    serial: ABC-123
    number: 5
    sticky_mac_allow_list:
        macs:
          - 22:22:bb:bb:cc:cc
        state: merged
    delegate_to: localhost

Return Values

Common return values are documented here, the following are the fields unique to this module:

Key Returned Description
data
complex
success
Information queried or updated switchports.
access_policy_number
integer
success
Number of assigned access policy. Only applicable to access ports.

Sample:
1234
access_policy_type
string
success, when assigned
Type of access policy assigned to port

Sample:
MAC allow list
allowed_vlans
string
success, when port is set as access
List of VLANs allowed on an access port

Sample:
all
enabled
boolean
success
Enabled state of port.

Sample:
True
isolation_enabled
boolean
success
Port isolation status of port.

Sample:
True
link_negotiation
string
success
Link speed for the port.

Sample:
Auto negotiate
mac_allow_list
list / elements=string
success
List of MAC addresses currently allowed on a non-sticky port. Used with access_policy_type of MAC allow list.

Sample:
['11:aa:bb:bb:cc:cc', '22:aa:bb:bb:cc:cc', '33:aa:bb:bb:cc:cc']
name
string
success
Human friendly description of port.

Sample:
Jim Phone Port
number
integer
success
Number of port.

Sample:
1
poe_enabled
boolean
success
Power Over Ethernet enabled state of port.

Sample:
True
port_schedule_id
string
success
Unique ID of assigned port schedule
rstp_enabled
boolean
success
Enabled or disabled state of Rapid Spanning Tree Protocol (RSTP)

Sample:
True
sticky_mac_allow_list
list / elements=string
success
List of MAC addresses currently allowed on a sticky port. Used with access_policy_type of Sticky MAC allow list.

Sample:
['11:aa:bb:bb:cc:cc', '22:aa:bb:bb:cc:cc', '33:aa:bb:bb:cc:cc']
sticky_mac_allow_list_limit
integer
success
Number of MAC addresses allowed on a sticky port.

Sample:
6
stp_guard
string
success
State of STP guard

Sample:
Root Guard
tags
list / elements=string
success
List of tags assigned to port.

Sample:
['phone', 'marketing']
type
string
success
Type of switchport.

Sample:
trunk
udld
string
success
Alert state of UDLD

Sample:
Alert only
vlan
integer
success
VLAN assigned to port.

Sample:
10
voice_vlan
integer
success
VLAN assigned to port with voice VLAN enabled devices.

Sample:
20


Authors

  • Kevin Breit (@kbreit)

© 2012–2018 Michael DeHaan
© 2018–2021 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/ansible/latest/collections/cisco/meraki/meraki_ms_switchport_module.html