cisco.nxos.nxos_acls – ACLs resource module

Note

This plugin is part of the cisco.nxos collection (version 1.3.1).

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							Choices/Defaults	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			no yes	Any destination address.
				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				no yes	Check non-initial fragments.
			grant string				permit deny	Action to be applied on the rule.
			log boolean				no yes	Log matches against this entry.
			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		no yes	Administratively prohibited
					alternate_address boolean		no yes	Alternate address
					conversion_error boolean		no yes	Datagram conversion
					dod_host_prohibited boolean		no yes	Host prohibited
					dod_net_prohibited boolean		no yes	Net prohibited
					echo boolean		no yes	Echo (ping)
					echo_reply boolean		no yes	Echo reply
					general_parameter_problem boolean		no yes	Parameter problem
					host_isolated boolean		no yes	Host isolated
					host_precedence_unreachable boolean		no yes	Host unreachable for precedence
					host_redirect boolean		no yes	Host redirect
					host_tos_redirect boolean		no yes	Host redirect for TOS
					host_tos_unreachable boolean		no yes	Host unreachable for TOS
					host_unknown boolean		no yes	Host unknown
					host_unreachable boolean		no yes	Host unreachable
					information_reply boolean		no yes	Information replies
					information_request boolean		no yes	Information requests
					mask_reply boolean		no yes	Mask replies
					mask_request boolean		no yes	Mask requests
					message_code integer			ICMP message code
					message_type integer			ICMP message type
					mobile_redirect boolean		no yes	Mobile host redirect
					net_redirect boolean		no yes	Network redirect
					net_tos_redirect boolean		no yes	Net redirect for TOS
					net_tos_unreachable boolean		no yes	Network unreachable for TOS
					net_unreachable boolean		no yes	Net unreachable
					network_unknown boolean		no yes	Network unknown
					no_room_for_option boolean		no yes	Parameter required but no room
					option_missing boolean		no yes	Parameter required but not present
					packet_too_big boolean		no yes	Fragmentation needed and DF set
					parameter_problem boolean		no yes	All parameter problems
					port_unreachable boolean		no yes	Port unreachable
					precedence_unreachable boolean		no yes	Precedence cutoff
					protocol_unreachable boolean		no yes	Protocol unreachable
					reassembly_timeout boolean		no yes	Reassembly timeout
					redirect boolean		no yes	All redirects
					router_advertisement boolean		no yes	Router discovery advertisements
					router_solicitation boolean		no yes	Router discovery solicitations
					source_quench boolean		no yes	Source quenches
					source_route_failed boolean		no yes	Source route failed
					time_exceeded boolean		no yes	All time exceeded.
					timestamp_reply boolean		no yes	Timestamp replies
					timestamp_request boolean		no yes	Timestamp requests
					traceroute boolean		no yes	Traceroute
					ttl_exceeded boolean		no yes	TTL exceeded
					unreachable boolean		no yes	All unreachables
				igmp dictionary				IGMP protocol options.
					dvmrp boolean		no yes	Distance Vector Multicast Routing Protocol
					host_query boolean		no yes	Host Query
					host_report boolean		no yes	Host Report
				tcp dictionary				TCP flags.
					ack boolean		no yes	Match on the ACK bit
					established boolean		no yes	Match established connections
					fin boolean		no yes	Match on the FIN bit
					psh boolean		no yes	Match on the PSH bit
					rst boolean		no yes	Match on the RST bit
					syn boolean		no yes	Match on the SYN bit
					urg boolean		no yes	Match on the URG bit
			remark string					Access list entry comment.
			sequence integer					Sequence number.
			source dictionary					Specify the packet source.
				address string				Source network address.
				any boolean			no yes	Any source address.
				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						ipv4 ipv6	The Address Family Indicator (AFI) for the ACL.
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							deleted gathered merged ← overridden rendered replaced parsed	The state the configuration should be left in

Notes

Note

Tested against NX-OS 7.3.(0)D1(1) on VIRL
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	Returned	Description
after dictionary	when changed	The resulting configuration model invocation. Sample: The configuration returned will always be in the same format of the parameters above.
before dictionary	always	The configuration prior to the model invocation. Sample: The configuration returned will always be in the same format of the parameters above.
commands list / elements=string	always	The set of commands pushed to the remote device. 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)

© 2012–2018 Michael DeHaan
© 2018–2019 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/ansible/2.10/collections/cisco/nxos/nxos_acls_module.html