You are reading an unmaintained version of the Ansible documentation. Unmaintained Ansible versions can contain unfixed security vulnerabilities (CVE). Please upgrade to a maintained version. See the latest Ansible documentation.

cisco.nxos.nxos_acls module – ACLs resource module

Note

This module is part of the cisco.nxos collection (version 2.9.1).

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.nxos.

To use it in a playbook, specify: cisco.nxos.nxos_acls.

New in version 1.0.0: of cisco.nxos

Synopsis
Parameters
Notes
Examples
Return Values

Synopsis 

Manage named IP ACLs on the Cisco NX-OS platform

Note

This module has a corresponding action plugin.

Parameters 

Parameter	Comments
config list / elements=dictionary	A dictionary of ACL options.
acls list / elements=dictionary	A list of the ACLs.
aces list / elements=dictionary	The entries within the ACL.
destination dictionary	Specify the packet destination.
address string	Destination network address.
any boolean	Any destination address. Choices: no yes
host string	Host IP address.
port_protocol dictionary	Specify the destination port or protocol (only for TCP and UDP).
eq string	Match only packets on a given port number.
gt string	Match only packets with a greater port number.
lt string	Match only packets with a lower port number.
neq string	Match only packets not on a given port number.
range dictionary	Match only packets in the range of port numbers.
end string	Specify the end of the port range.
start string	Specify the start of the port range.
prefix string	Destination network prefix. Only for prefixes of value less than 31 for ipv4 and 127 for ipv6. Prefixes of 32 (ipv4) and 128 (ipv6) should be given in the ‘host’ key.
wildcard_bits string	Destination wildcard bits.
dscp string	Match packets with given DSCP value.
fragments boolean	Check non-initial fragments. Choices: no yes
grant string	Action to be applied on the rule. Choices: permit deny
log boolean	Log matches against this entry. Choices: no yes
precedence string	Match packets with given precedence value.
protocol string	Specify the protocol.
protocol_options dictionary	All possible suboptions for the protocol chosen.
icmp dictionary	ICMP protocol options.
administratively_prohibited boolean	Administratively prohibited Choices: no yes
alternate_address boolean	Alternate address Choices: no yes
conversion_error boolean	Datagram conversion Choices: no yes
dod_host_prohibited boolean	Host prohibited Choices: no yes
dod_net_prohibited boolean	Net prohibited Choices: no yes
echo boolean	Echo (ping) Choices: no yes
echo_reply boolean	Echo reply Choices: no yes
echo_request boolean	Echo request (ping) Choices: no yes
general_parameter_problem boolean	Parameter problem Choices: no yes
host_isolated boolean	Host isolated Choices: no yes
host_precedence_unreachable boolean	Host unreachable for precedence Choices: no yes
host_redirect boolean	Host redirect Choices: no yes
host_tos_redirect boolean	Host redirect for TOS Choices: no yes
host_tos_unreachable boolean	Host unreachable for TOS Choices: no yes
host_unknown boolean	Host unknown Choices: no yes
host_unreachable boolean	Host unreachable Choices: no yes
information_reply boolean	Information replies Choices: no yes
information_request boolean	Information requests Choices: no yes
mask_reply boolean	Mask replies Choices: no yes
mask_request boolean	Mask requests Choices: no yes
message_code integer	ICMP message code
message_type integer	ICMP message type
mobile_redirect boolean	Mobile host redirect Choices: no yes
net_redirect boolean	Network redirect Choices: no yes
net_tos_redirect boolean	Net redirect for TOS Choices: no yes
net_tos_unreachable boolean	Network unreachable for TOS Choices: no yes
net_unreachable boolean	Net unreachable Choices: no yes
network_unknown boolean	Network unknown Choices: no yes
no_room_for_option boolean	Parameter required but no room Choices: no yes
option_missing boolean	Parameter required but not present Choices: no yes
packet_too_big boolean	Fragmentation needed and DF set Choices: no yes
parameter_problem boolean	All parameter problems Choices: no yes
port_unreachable boolean	Port unreachable Choices: no yes
precedence_unreachable boolean	Precedence cutoff Choices: no yes
protocol_unreachable boolean	Protocol unreachable Choices: no yes
reassembly_timeout boolean	Reassembly timeout Choices: no yes
redirect boolean	All redirects Choices: no yes
router_advertisement boolean	Router discovery advertisements Choices: no yes
router_solicitation boolean	Router discovery solicitations Choices: no yes
source_quench boolean	Source quenches Choices: no yes
source_route_failed boolean	Source route failed Choices: no yes
time_exceeded boolean	All time exceeded. Choices: no yes
timestamp_reply boolean	Timestamp replies Choices: no yes
timestamp_request boolean	Timestamp requests Choices: no yes
traceroute boolean	Traceroute Choices: no yes
ttl_exceeded boolean	TTL exceeded Choices: no yes
unreachable boolean	All unreachables Choices: no yes
igmp dictionary	IGMP protocol options.
dvmrp boolean	Distance Vector Multicast Routing Protocol Choices: no yes
host_query boolean	Host Query Choices: no yes
host_report boolean	Host Report Choices: no yes
tcp dictionary	TCP flags.
ack boolean	Match on the ACK bit Choices: no yes
established boolean	Match established connections Choices: no yes
fin boolean	Match on the FIN bit Choices: no yes
psh boolean	Match on the PSH bit Choices: no yes
rst boolean	Match on the RST bit Choices: no yes
syn boolean	Match on the SYN bit Choices: no yes
urg boolean	Match on the URG bit Choices: no yes
remark string	Access list entry comment.
sequence integer	Sequence number.
source dictionary	Specify the packet source.
address string	Source network address.
any boolean	Any source address. Choices: no yes
host string	Host IP address.
port_protocol dictionary	Specify the destination port or protocol (only for TCP and UDP).
eq string	Match only packets on a given port number.
gt string	Match only packets with a greater port number.
lt string	Match only packets with a lower port number.
neq string	Match only packets not on a given port number.
range dictionary	Match only packets in the range of port numbers.
end string	Specify the end of the port range.
start string	Specify the start of the port range.
prefix string	Source network prefix. Only for prefixes of mask value less than 31 for ipv4 and 127 for ipv6. Prefixes of mask 32 (ipv4) and 128 (ipv6) should be given in the ‘host’ key.
wildcard_bits string	Source wildcard bits.
name string / required	Name of the ACL.
afi string / required	The Address Family Indicator (AFI) for the ACL. Choices: ipv4 ipv6
running_config string	This option is used only with state parsed. The value of this option should be the output received from the NX-OS device by executing the command show running-config \| section ‘ip(v6* access-list). The state parsed reads the configuration from `running_config` option and transforms it into Ansible structured data as per the resource module’s argspec and the value is then returned in the parsed key within the result.
state string	The state the configuration should be left in Choices: deleted gathered merged ← (default) overridden rendered replaced parsed

Notes 

Note

Tested against NX-OS 7.3.(0)D1(1) on VIRL
Unsupported for Cisco MDS
As NX-OS allows configuring a rule again with different sequence numbers, the user is expected to provide sequence numbers for the access control entries to preserve idempotency. If no sequence number is given, the rule will be added as a new rule by the device.

Examples 

# Using merged

# Before state:
# -------------
#

- name: Merge new ACLs configuration
  cisco.nxos.nxos_acls:
    config:
    - afi: ipv4
      acls:
      - name: ACL1v4
        aces:
        - grant: deny
          destination:
            address: 192.0.2.64
            wildcard_bits: 0.0.0.255
          source:
            any: true
            port_protocol:
              lt: 55
          protocol: tcp
          protocol_options:
            tcp:
              ack: true
              fin: true
          sequence: 50

    - afi: ipv6
      acls:
      - name: ACL1v6
        aces:
        - grant: permit
          sequence: 10
          source:
            any: true
          destination:
            prefix: 2001:db8:12::/32
          protocol: sctp
    state: merged

# After state:
# ------------
#
# ip access-list ACL1v4
#  50 deny tcp any lt 55 192.0.2.64 0.0.0.255 ack fin
# ipv6 access-list ACL1v6
#  10 permit sctp any any

# Using replaced

# Before state:
# ----------------
#
# ip access-list ACL1v4
#   10 permit ip any any
#   20 deny udp any any
# ip access-list ACL2v4
#   10 permit ahp 192.0.2.0 0.0.0.255 any
# ip access-list ACL1v6
#   10 permit sctp any any
#   20 remark IPv6 ACL
# ip access-list ACL2v6
#  10 deny ipv6 any 2001:db8:3000::/36
#  20 permit tcp 2001:db8:2000:2::2/128 2001:db8:2000:ab::2/128

- name: Replace existing ACL configuration with provided configuration
  cisco.nxos.nxos_acls:
    config:
    - afi: ipv4
    - afi: ipv6
      acls:
      - name: ACL1v6
        aces:
        - sequence: 20
          grant: permit
          source:
            any: true
          destination:
            any: true
          protocol: pip

        - remark: Replaced ACE

      - name: ACL2v6
    state: replaced

# After state:
# ---------------
#
# ipv6 access-list ACL1v6
#   20 permit pip any any
#   30 remark Replaced ACE
# ipv6 access-list ACL2v6

# Using overridden

# Before state:
# ----------------
#
# ip access-list ACL1v4
#   10 permit ip any any
#   20 deny udp any any
# ip access-list ACL2v4
#   10 permit ahp 192.0.2.0 0.0.0.255 any
# ip access-list ACL1v6
#   10 permit sctp any any
#   20 remark IPv6 ACL
# ip access-list ACL2v6
#  10 deny ipv6 any 2001:db8:3000::/36
#  20 permit tcp 2001:db8:2000:2::2/128 2001:db8:2000:ab::2/128

- name: Override existing configuration with provided configuration
  cisco.nxos.nxos_acls:
    config:
    - afi: ipv4
      acls:
      - name: NewACL
        aces:
        - grant: deny
          source:
            address: 192.0.2.0
            wildcard_bits: 0.0.255.255
          destination:
            any: true
          protocol: eigrp
        - remark: Example for overridden state
    state: overridden

# After state:
# ------------
#
# ip access-list NewACL
#   10 deny eigrp 192.0.2.0 0.0.255.255 any
#   20 remark Example for overridden state

# Using deleted:
#
# Before state:
# -------------
#
# ip access-list ACL1v4
#   10 permit ip any any
#   20 deny udp any any
# ip access-list ACL2v4
#   10 permit ahp 192.0.2.0 0.0.0.255 any
# ip access-list ACL1v6
#   10 permit sctp any any
#   20 remark IPv6 ACL
# ip access-list ACL2v6
#  10 deny ipv6 any 2001:db8:3000::/36
#  20 permit tcp 2001:db8:2000:2::2/128 2001:db8:2000:ab::2/128

- name: Delete all ACLs
  cisco.nxos.nxos_acls:
    config:
    state: deleted

# After state:
# -----------
#


# Before state:
# -------------
#
# ip access-list ACL1v4
#   10 permit ip any any
#   20 deny udp any any
# ip access-list ACL2v4
#   10 permit ahp 192.0.2.0 0.0.0.255 any
# ip access-list ACL1v6
#   10 permit sctp any any
#   20 remark IPv6 ACL
# ip access-list ACL2v6
#  10 deny ipv6 any 2001:db8:3000::/36
#  20 permit tcp 2001:db8:2000:2::2/128 2001:db8:2000:ab::2/128

- name: Delete all ACLs in given AFI
  cisco.nxos.nxos_acls:
    config:
    - afi: ipv4
    state: deleted

# After state:
# ------------
#
# ip access-list ACL1v6
#   10 permit sctp any any
#   20 remark IPv6 ACL
# ip access-list ACL2v6
#  10 deny ipv6 any 2001:db8:3000::/36
#  20 permit tcp 2001:db8:2000:2::2/128 2001:db8:2000:ab::2/128



# Before state:
# -------------
#
# ip access-list ACL1v4
#   10 permit ip any any
#   20 deny udp any any
# ip access-list ACL2v4
#   10 permit ahp 192.0.2.0 0.0.0.255 any
# ipv6 access-list ACL1v6
#   10 permit sctp any any
#   20 remark IPv6 ACL
# ipv6 access-list ACL2v6
#  10 deny ipv6 any 2001:db8:3000::/36
#  20 permit tcp 2001:db8:2000:2::2/128 2001:db8:2000:ab::2/128

- name: Delete specific ACLs
  cisco.nxos.nxos_acls:
    config:
    - afi: ipv4
      acls:
      - name: ACL1v4
      - name: ACL2v4
    - afi: ipv6
      acls:
      - name: ACL1v6
    state: deleted

# After state:
# ------------
# ipv6 access-list ACL2v6
#  10 deny ipv6 any 2001:db8:3000::/36
#  20 permit tcp 2001:db8:2000:2::2/128 2001:db8:2000:ab::2/128

# Using parsed

- name: Parse given config to structured data
  cisco.nxos.nxos_acls:
    running_config: |
      ip access-list ACL1v4
        50 deny tcp any lt 55 192.0.2.64 0.0.0.255 ack fin
      ipv6 access-list ACL1v6
        10 permit sctp any any
    state: parsed

# returns:
# parsed:
# - afi: ipv4
#   acls:
#     - name: ACL1v4
#       aces:
#         - grant: deny
#           destination:
#             address: 192.0.2.64
#             wildcard_bits: 0.0.0.255
#           source:
#             any: true
#             port_protocol:
#               lt: 55
#           protocol: tcp
#           protocol_options:
#             tcp:
#               ack: true
#               fin: true
#           sequence: 50
#
# - afi: ipv6
#   acls:
#     - name: ACL1v6
#       aces:
#         - grant: permit
#           sequence: 10
#           source:
#             any: true
#           destination:
#             prefix: 2001:db8:12::/32
#           protocol: sctp


# Using gathered:

# Before state:
# ------------
#
# ip access-list ACL1v4
#  50 deny tcp any lt 55 192.0.2.64 0.0.0.255 ack fin
# ipv6 access-list ACL1v6
#  10 permit sctp any any

- name: Gather existing configuration
  cisco.nxos.nxos_acls:
    state: gathered

# returns:
# gathered:
# - afi: ipv4
#   acls:
#     - name: ACL1v4
#       aces:
#         - grant: deny
#           destination:
#             address: 192.0.2.64
#             wildcard_bits: 0.0.0.255
#           source:
#             any: true
#             port_protocol:
#               lt: 55
#           protocol: tcp
#           protocol_options:
#             tcp:
#               ack: true
#               fin: true
#           sequence: 50

# - afi: ipv6
#   acls:
#     - name: ACL1v6
#       aces:
#         - grant: permit
#           sequence: 10
#           source:
#             any: true
#           destination:
#             prefix: 2001:db8:12::/32
#           protocol: sctp


# Using rendered

- name: Render required configuration to be pushed to the device
  cisco.nxos.nxos_acls:
    config:
    - afi: ipv4
      acls:
      - name: ACL1v4
        aces:
        - grant: deny
          destination:
            address: 192.0.2.64
            wildcard_bits: 0.0.0.255
          source:
            any: true
            port_protocol:
              lt: 55
          protocol: tcp
          protocol_options:
            tcp:
              ack: true
              fin: true
          sequence: 50

    - afi: ipv6
      acls:
      - name: ACL1v6
        aces:
        - grant: permit
          sequence: 10
          source:
            any: true
          destination:
            prefix: 2001:db8:12::/32
          protocol: sctp
    state: rendered

# returns:
# rendered:
#  ip access-list ACL1v4
#   50 deny tcp any lt 55 192.0.2.64 0.0.0.255 ack fin
#  ipv6 access-list ACL1v6
#   10 permit sctp any any

Return Values 

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

Key	Description
after dictionary	The resulting configuration model invocation. Returned: when changed Sample: “The configuration returned will always be in the same format\n of the parameters above.\n”
before dictionary	The configuration prior to the model invocation. Returned: always Sample: “The configuration returned will always be in the same format\n of the parameters above.\n”
commands list / elements=string	The set of commands pushed to the remote device. Returned: always Sample: [“ip access-list ACL1v4”, “10 permit ip any any precedence critical log”, “20 deny tcp any lt smtp host 192.0.2.64 ack fin”]

Authors

Adharsh Srivats Rangarajan (@adharshsrivatsr)

Collection links

Issue Tracker Repository (Sources)

cisco.nxos.nxos_acls module – ACLs resource module

Synopsis

Parameters

Notes

Examples

Return Values

Authors

Collection links

Synopsis 

Parameters 

Notes 

Examples 

Return Values 