cisco.nxos.nxos_acls – ACLs resource module

Note

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

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

  • 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
    Choices:
  • 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
    Choices:
  • no
  • yes
Check non-initial fragments.
grant
string
    Choices:
  • permit
  • deny
Action to be applied on the rule.
log
boolean
    Choices:
  • 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
    Choices:
  • no
  • yes
Administratively prohibited
alternate_address
boolean
    Choices:
  • no
  • yes
Alternate address
conversion_error
boolean
    Choices:
  • no
  • yes
Datagram conversion
dod_host_prohibited
boolean
    Choices:
  • no
  • yes
Host prohibited
dod_net_prohibited
boolean
    Choices:
  • no
  • yes
Net prohibited
echo
boolean
    Choices:
  • no
  • yes
Echo (ping)
echo_reply
boolean
    Choices:
  • no
  • yes
Echo reply
echo_request
boolean
    Choices:
  • no
  • yes
Echo request (ping)
general_parameter_problem
boolean
    Choices:
  • no
  • yes
Parameter problem
host_isolated
boolean
    Choices:
  • no
  • yes
Host isolated
host_precedence_unreachable
boolean
    Choices:
  • no
  • yes
Host unreachable for precedence
host_redirect
boolean
    Choices:
  • no
  • yes
Host redirect
host_tos_redirect
boolean
    Choices:
  • no
  • yes
Host redirect for TOS
host_tos_unreachable
boolean
    Choices:
  • no
  • yes
Host unreachable for TOS
host_unknown
boolean
    Choices:
  • no
  • yes
Host unknown
host_unreachable
boolean
    Choices:
  • no
  • yes
Host unreachable
information_reply
boolean
    Choices:
  • no
  • yes
Information replies
information_request
boolean
    Choices:
  • no
  • yes
Information requests
mask_reply
boolean
    Choices:
  • no
  • yes
Mask replies
mask_request
boolean
    Choices:
  • no
  • yes
Mask requests
message_code
integer
ICMP message code
message_type
integer
ICMP message type
mobile_redirect
boolean
    Choices:
  • no
  • yes
Mobile host redirect
net_redirect
boolean
    Choices:
  • no
  • yes
Network redirect
net_tos_redirect
boolean
    Choices:
  • no
  • yes
Net redirect for TOS
net_tos_unreachable
boolean
    Choices:
  • no
  • yes
Network unreachable for TOS
net_unreachable
boolean
    Choices:
  • no
  • yes
Net unreachable
network_unknown
boolean
    Choices:
  • no
  • yes
Network unknown
no_room_for_option
boolean
    Choices:
  • no
  • yes
Parameter required but no room
option_missing
boolean
    Choices:
  • no
  • yes
Parameter required but not present
packet_too_big
boolean
    Choices:
  • no
  • yes
Fragmentation needed and DF set
parameter_problem
boolean
    Choices:
  • no
  • yes
All parameter problems
port_unreachable
boolean
    Choices:
  • no
  • yes
Port unreachable
precedence_unreachable
boolean
    Choices:
  • no
  • yes
Precedence cutoff
protocol_unreachable
boolean
    Choices:
  • no
  • yes
Protocol unreachable
reassembly_timeout
boolean
    Choices:
  • no
  • yes
Reassembly timeout
redirect
boolean
    Choices:
  • no
  • yes
All redirects
router_advertisement
boolean
    Choices:
  • no
  • yes
Router discovery advertisements
router_solicitation
boolean
    Choices:
  • no
  • yes
Router discovery solicitations
source_quench
boolean
    Choices:
  • no
  • yes
Source quenches
source_route_failed
boolean
    Choices:
  • no
  • yes
Source route failed
time_exceeded
boolean
    Choices:
  • no
  • yes
All time exceeded.
timestamp_reply
boolean
    Choices:
  • no
  • yes
Timestamp replies
timestamp_request
boolean
    Choices:
  • no
  • yes
Timestamp requests
traceroute
boolean
    Choices:
  • no
  • yes
Traceroute
ttl_exceeded
boolean
    Choices:
  • no
  • yes
TTL exceeded
unreachable
boolean
    Choices:
  • no
  • yes
All unreachables
igmp
dictionary
IGMP protocol options.
dvmrp
boolean
    Choices:
  • no
  • yes
Distance Vector Multicast Routing Protocol
host_query
boolean
    Choices:
  • no
  • yes
Host Query
host_report
boolean
    Choices:
  • no
  • yes
Host Report
tcp
dictionary
TCP flags.
ack
boolean
    Choices:
  • no
  • yes
Match on the ACK bit
established
boolean
    Choices:
  • no
  • yes
Match established connections
fin
boolean
    Choices:
  • no
  • yes
Match on the FIN bit
psh
boolean
    Choices:
  • no
  • yes
Match on the PSH bit
rst
boolean
    Choices:
  • no
  • yes
Match on the RST bit
syn
boolean
    Choices:
  • no
  • yes
Match on the SYN bit
urg
boolean
    Choices:
  • 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
    Choices:
  • 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
    Choices:
  • 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
    Choices:
  • 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)