1#!/usr/local/bin/python3.8
2# -*- coding: utf-8 -*-
3# Copyright 2019 Red Hat
4# GNU General Public License v3.0+
5# (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
6
7#############################################
8#                WARNING                    #
9#############################################
10#
11# This file is auto generated by the resource
12#   module builder playbook.
13#
14# Do not edit this file manually.
15#
16# Changes to this file will be over written
17#   by the resource module builder.
18#
19# Changes should be made in the model used to
20#   generate this file or in the resource module
21#   builder template.
22#
23#############################################
24"""
25The module file for nxos_acls
26"""
27
28from __future__ import absolute_import, division, print_function
29
30__metaclass__ = type
31
32
33DOCUMENTATION = """
34module: nxos_acls
35short_description: ACLs resource module
36description: Manage named IP ACLs on the Cisco NX-OS platform
37version_added: 1.0.0
38author: Adharsh Srivats Rangarajan (@adharshsrivatsr)
39notes:
40- Tested against NX-OS 7.3.(0)D1(1) on VIRL
41- Unsupported for Cisco MDS
42- As NX-OS allows configuring a rule again with different sequence numbers, the user
43  is expected to provide sequence numbers for the access control entries to preserve
44  idempotency. If no sequence number is given, the rule will be added as a new rule
45  by the device.
46options:
47  running_config:
48    description:
49    - This option is used only with state I(parsed).
50    - The value of this option should be the output received from the NX-OS device
51      by executing the command B(show running-config | section 'ip(v6)* access-list).
52    - The state I(parsed) reads the configuration from C(running_config) option and
53      transforms it into Ansible structured data as per the resource module's argspec
54      and the value is then returned in the I(parsed) key within the result.
55    type: str
56  config:
57    description: A dictionary of ACL options.
58    type: list
59    elements: dict
60    suboptions:
61      afi:
62        description: The Address Family Indicator (AFI) for the ACL.
63        type: str
64        required: true
65        choices:
66        - ipv4
67        - ipv6
68      acls:
69        description: A list of the ACLs.
70        type: list
71        elements: dict
72        suboptions:
73          name:
74            description: Name of the ACL.
75            type: str
76            required: true
77          aces:
78            description: The entries within the ACL.
79            type: list
80            elements: dict
81            suboptions:
82              grant:
83                description: Action to be applied on the rule.
84                type: str
85                choices:
86                - permit
87                - deny
88              destination:
89                description: Specify the packet destination.
90                type: dict
91                suboptions:
92                  address:
93                    description: Destination network address.
94                    type: str
95                  any:
96                    description: Any destination address.
97                    type: bool
98                  host:
99                    description: Host IP address.
100                    type: str
101                  port_protocol:
102                    description: Specify the destination port or protocol (only for
103                      TCP and UDP).
104                    type: dict
105                    suboptions:
106                      eq:
107                        description: Match only packets on a given port number.
108                        type: str
109                      gt:
110                        description: Match only packets with a greater port number.
111                        type: str
112                      lt:
113                        description: Match only packets with a lower port number.
114                        type: str
115                      neq:
116                        description: Match only packets not on a given port number.
117                        type: str
118                      range:
119                        description: Match only packets in the range of port numbers.
120                        type: dict
121                        suboptions:
122                          start:
123                            description: Specify the start of the port range.
124                            type: str
125                          end:
126                            description: Specify the end of the port range.
127                            type: str
128                  prefix:
129                    description: Destination network prefix. Only for prefixes of
130                      value less than 31 for ipv4 and 127 for ipv6. Prefixes of 32
131                      (ipv4) and 128 (ipv6) should be given in the 'host' key.
132                    type: str
133                  wildcard_bits:
134                    description: Destination wildcard bits.
135                    type: str
136              dscp:
137                description: Match packets with given DSCP value.
138                type: str
139              fragments:
140                description: Check non-initial fragments.
141                type: bool
142              remark:
143                description: Access list entry comment.
144                type: str
145              sequence:
146                description: Sequence number.
147                type: int
148              source:
149                description: Specify the packet source.
150                type: dict
151                suboptions:
152                  address:
153                    description: Source network address.
154                    type: str
155                  any:
156                    description: Any source address.
157                    type: bool
158                  host:
159                    description: Host IP address.
160                    type: str
161                  port_protocol:
162                    description: Specify the destination port or protocol (only for
163                      TCP and UDP).
164                    type: dict
165                    suboptions:
166                      eq:
167                        description: Match only packets on a given port number.
168                        type: str
169                      gt:
170                        description: Match only packets with a greater port number.
171                        type: str
172                      lt:
173                        description: Match only packets with a lower port number.
174                        type: str
175                      neq:
176                        description: Match only packets not on a given port number.
177                        type: str
178                      range:
179                        description: Match only packets in the range of port numbers.
180                        type: dict
181                        suboptions:
182                          start:
183                            description: Specify the start of the port range.
184                            type: str
185                          end:
186                            description: Specify the end of the port range.
187                            type: str
188                  prefix:
189                    description: Source network prefix. Only for prefixes of mask
190                      value less than 31 for ipv4 and 127 for ipv6. Prefixes of mask
191                      32 (ipv4) and 128 (ipv6) should be given in the 'host' key.
192                    type: str
193                  wildcard_bits:
194                    description: Source wildcard bits.
195                    type: str
196              log:
197                description: Log matches against this entry.
198                type: bool
199              precedence:
200                description: Match packets with given precedence value.
201                type: str
202              protocol:
203                description: Specify the protocol.
204                type: str
205              protocol_options:
206                description: All possible suboptions for the protocol chosen.
207                type: dict
208                suboptions:
209                  icmp:
210                    description: ICMP protocol options.
211                    type: dict
212                    suboptions:
213                      administratively_prohibited:
214                        description: Administratively prohibited
215                        type: bool
216                      alternate_address:
217                        description: Alternate address
218                        type: bool
219                      conversion_error:
220                        description: Datagram conversion
221                        type: bool
222                      dod_host_prohibited:
223                        description: Host prohibited
224                        type: bool
225                      dod_net_prohibited:
226                        description: Net prohibited
227                        type: bool
228                      echo:
229                        description: Echo (ping)
230                        type: bool
231                      echo_reply:
232                        description: Echo reply
233                        type: bool
234                      echo_request:
235                        description: Echo request (ping)
236                        type: bool
237                      general_parameter_problem:
238                        description: Parameter problem
239                        type: bool
240                      host_isolated:
241                        description: Host isolated
242                        type: bool
243                      host_precedence_unreachable:
244                        description: Host unreachable for precedence
245                        type: bool
246                      host_redirect:
247                        description: Host redirect
248                        type: bool
249                      host_tos_redirect:
250                        description: Host redirect for TOS
251                        type: bool
252                      host_tos_unreachable:
253                        description: Host unreachable for TOS
254                        type: bool
255                      host_unknown:
256                        description: Host unknown
257                        type: bool
258                      host_unreachable:
259                        description: Host unreachable
260                        type: bool
261                      information_reply:
262                        description: Information replies
263                        type: bool
264                      information_request:
265                        description: Information requests
266                        type: bool
267                      mask_reply:
268                        description: Mask replies
269                        type: bool
270                      mask_request:
271                        description: Mask requests
272                        type: bool
273                      message_code:
274                        description: ICMP message code
275                        type: int
276                      message_type:
277                        description: ICMP message type
278                        type: int
279                      mobile_redirect:
280                        description: Mobile host redirect
281                        type: bool
282                      net_redirect:
283                        description: Network redirect
284                        type: bool
285                      net_tos_redirect:
286                        description: Net redirect for TOS
287                        type: bool
288                      net_tos_unreachable:
289                        description: Network unreachable for TOS
290                        type: bool
291                      net_unreachable:
292                        description: Net unreachable
293                        type: bool
294                      network_unknown:
295                        description: Network unknown
296                        type: bool
297                      no_room_for_option:
298                        description: Parameter required but no room
299                        type: bool
300                      option_missing:
301                        description: Parameter required but not present
302                        type: bool
303                      packet_too_big:
304                        description: Fragmentation needed and DF set
305                        type: bool
306                      parameter_problem:
307                        description: All parameter problems
308                        type: bool
309                      port_unreachable:
310                        description: Port unreachable
311                        type: bool
312                      precedence_unreachable:
313                        description: Precedence cutoff
314                        type: bool
315                      protocol_unreachable:
316                        description: Protocol unreachable
317                        type: bool
318                      reassembly_timeout:
319                        description: Reassembly timeout
320                        type: bool
321                      redirect:
322                        description: All redirects
323                        type: bool
324                      router_advertisement:
325                        description: Router discovery advertisements
326                        type: bool
327                      router_solicitation:
328                        description: Router discovery solicitations
329                        type: bool
330                      source_quench:
331                        description: Source quenches
332                        type: bool
333                      source_route_failed:
334                        description: Source route failed
335                        type: bool
336                      time_exceeded:
337                        description: All time exceeded.
338                        type: bool
339                      timestamp_reply:
340                        description: Timestamp replies
341                        type: bool
342                      timestamp_request:
343                        description: Timestamp requests
344                        type: bool
345                      traceroute:
346                        description: Traceroute
347                        type: bool
348                      ttl_exceeded:
349                        description: TTL exceeded
350                        type: bool
351                      unreachable:
352                        description: All unreachables
353                        type: bool
354                  tcp:
355                    description: TCP flags.
356                    type: dict
357                    suboptions:
358                      ack:
359                        description: Match on the ACK bit
360                        type: bool
361                      established:
362                        description: Match established connections
363                        type: bool
364                      fin:
365                        description: Match on the FIN bit
366                        type: bool
367                      psh:
368                        description: Match on the PSH bit
369                        type: bool
370                      rst:
371                        description: Match on the RST bit
372                        type: bool
373                      syn:
374                        description: Match on the SYN bit
375                        type: bool
376                      urg:
377                        description: Match on the URG bit
378                        type: bool
379                  igmp:
380                    description: IGMP protocol options.
381                    type: dict
382                    suboptions:
383                      dvmrp:
384                        description: Distance Vector Multicast Routing Protocol
385                        type: bool
386                      host_query:
387                        description: Host Query
388                        type: bool
389                      host_report:
390                        description: Host Report
391                        type: bool
392  state:
393    description:
394    - The state the configuration should be left in
395    type: str
396    choices:
397    - deleted
398    - gathered
399    - merged
400    - overridden
401    - rendered
402    - replaced
403    - parsed
404    default: merged
405
406"""
407EXAMPLES = """
408# Using merged
409
410# Before state:
411# -------------
412#
413
414- name: Merge new ACLs configuration
415  cisco.nxos.nxos_acls:
416    config:
417    - afi: ipv4
418      acls:
419      - name: ACL1v4
420        aces:
421        - grant: deny
422          destination:
423            address: 192.0.2.64
424            wildcard_bits: 0.0.0.255
425          source:
426            any: true
427            port_protocol:
428              lt: 55
429          protocol: tcp
430          protocol_options:
431            tcp:
432              ack: true
433              fin: true
434          sequence: 50
435
436    - afi: ipv6
437      acls:
438      - name: ACL1v6
439        aces:
440        - grant: permit
441          sequence: 10
442          source:
443            any: true
444          destination:
445            prefix: 2001:db8:12::/32
446          protocol: sctp
447    state: merged
448
449# After state:
450# ------------
451#
452# ip access-list ACL1v4
453#  50 deny tcp any lt 55 192.0.2.64 0.0.0.255 ack fin
454# ipv6 access-list ACL1v6
455#  10 permit sctp any any
456
457# Using replaced
458
459# Before state:
460# ----------------
461#
462# ip access-list ACL1v4
463#   10 permit ip any any
464#   20 deny udp any any
465# ip access-list ACL2v4
466#   10 permit ahp 192.0.2.0 0.0.0.255 any
467# ip access-list ACL1v6
468#   10 permit sctp any any
469#   20 remark IPv6 ACL
470# ip access-list ACL2v6
471#  10 deny ipv6 any 2001:db8:3000::/36
472#  20 permit tcp 2001:db8:2000:2::2/128 2001:db8:2000:ab::2/128
473
474- name: Replace existing ACL configuration with provided configuration
475  cisco.nxos.nxos_acls:
476    config:
477    - afi: ipv4
478    - afi: ipv6
479      acls:
480      - name: ACL1v6
481        aces:
482        - sequence: 20
483          grant: permit
484          source:
485            any: true
486          destination:
487            any: true
488          protocol: pip
489
490        - remark: Replaced ACE
491
492      - name: ACL2v6
493    state: replaced
494
495# After state:
496# ---------------
497#
498# ipv6 access-list ACL1v6
499#   20 permit pip any any
500#   30 remark Replaced ACE
501# ipv6 access-list ACL2v6
502
503# Using overridden
504
505# Before state:
506# ----------------
507#
508# ip access-list ACL1v4
509#   10 permit ip any any
510#   20 deny udp any any
511# ip access-list ACL2v4
512#   10 permit ahp 192.0.2.0 0.0.0.255 any
513# ip access-list ACL1v6
514#   10 permit sctp any any
515#   20 remark IPv6 ACL
516# ip access-list ACL2v6
517#  10 deny ipv6 any 2001:db8:3000::/36
518#  20 permit tcp 2001:db8:2000:2::2/128 2001:db8:2000:ab::2/128
519
520- name: Override existing configuration with provided configuration
521  cisco.nxos.nxos_acls:
522    config:
523    - afi: ipv4
524      acls:
525      - name: NewACL
526        aces:
527        - grant: deny
528          source:
529            address: 192.0.2.0
530            wildcard_bits: 0.0.255.255
531          destination:
532            any: true
533          protocol: eigrp
534        - remark: Example for overridden state
535    state: overridden
536
537# After state:
538# ------------
539#
540# ip access-list NewACL
541#   10 deny eigrp 192.0.2.0 0.0.255.255 any
542#   20 remark Example for overridden state
543
544# Using deleted:
545#
546# Before state:
547# -------------
548#
549# ip access-list ACL1v4
550#   10 permit ip any any
551#   20 deny udp any any
552# ip access-list ACL2v4
553#   10 permit ahp 192.0.2.0 0.0.0.255 any
554# ip access-list ACL1v6
555#   10 permit sctp any any
556#   20 remark IPv6 ACL
557# ip access-list ACL2v6
558#  10 deny ipv6 any 2001:db8:3000::/36
559#  20 permit tcp 2001:db8:2000:2::2/128 2001:db8:2000:ab::2/128
560
561- name: Delete all ACLs
562  cisco.nxos.nxos_acls:
563    config:
564    state: deleted
565
566# After state:
567# -----------
568#
569
570
571# Before state:
572# -------------
573#
574# ip access-list ACL1v4
575#   10 permit ip any any
576#   20 deny udp any any
577# ip access-list ACL2v4
578#   10 permit ahp 192.0.2.0 0.0.0.255 any
579# ip access-list ACL1v6
580#   10 permit sctp any any
581#   20 remark IPv6 ACL
582# ip access-list ACL2v6
583#  10 deny ipv6 any 2001:db8:3000::/36
584#  20 permit tcp 2001:db8:2000:2::2/128 2001:db8:2000:ab::2/128
585
586- name: Delete all ACLs in given AFI
587  cisco.nxos.nxos_acls:
588    config:
589    - afi: ipv4
590    state: deleted
591
592# After state:
593# ------------
594#
595# ip access-list ACL1v6
596#   10 permit sctp any any
597#   20 remark IPv6 ACL
598# ip access-list ACL2v6
599#  10 deny ipv6 any 2001:db8:3000::/36
600#  20 permit tcp 2001:db8:2000:2::2/128 2001:db8:2000:ab::2/128
601
602
603
604# Before state:
605# -------------
606#
607# ip access-list ACL1v4
608#   10 permit ip any any
609#   20 deny udp any any
610# ip access-list ACL2v4
611#   10 permit ahp 192.0.2.0 0.0.0.255 any
612# ipv6 access-list ACL1v6
613#   10 permit sctp any any
614#   20 remark IPv6 ACL
615# ipv6 access-list ACL2v6
616#  10 deny ipv6 any 2001:db8:3000::/36
617#  20 permit tcp 2001:db8:2000:2::2/128 2001:db8:2000:ab::2/128
618
619- name: Delete specific ACLs
620  cisco.nxos.nxos_acls:
621    config:
622    - afi: ipv4
623      acls:
624      - name: ACL1v4
625      - name: ACL2v4
626    - afi: ipv6
627      acls:
628      - name: ACL1v6
629    state: deleted
630
631# After state:
632# ------------
633# ipv6 access-list ACL2v6
634#  10 deny ipv6 any 2001:db8:3000::/36
635#  20 permit tcp 2001:db8:2000:2::2/128 2001:db8:2000:ab::2/128
636
637# Using parsed
638
639- name: Parse given config to structured data
640  cisco.nxos.nxos_acls:
641    running_config: |
642      ip access-list ACL1v4
643        50 deny tcp any lt 55 192.0.2.64 0.0.0.255 ack fin
644      ipv6 access-list ACL1v6
645        10 permit sctp any any
646    state: parsed
647
648# returns:
649# parsed:
650# - afi: ipv4
651#   acls:
652#     - name: ACL1v4
653#       aces:
654#         - grant: deny
655#           destination:
656#             address: 192.0.2.64
657#             wildcard_bits: 0.0.0.255
658#           source:
659#             any: true
660#             port_protocol:
661#               lt: 55
662#           protocol: tcp
663#           protocol_options:
664#             tcp:
665#               ack: true
666#               fin: true
667#           sequence: 50
668#
669# - afi: ipv6
670#   acls:
671#     - name: ACL1v6
672#       aces:
673#         - grant: permit
674#           sequence: 10
675#           source:
676#             any: true
677#           destination:
678#             prefix: 2001:db8:12::/32
679#           protocol: sctp
680
681
682# Using gathered:
683
684# Before state:
685# ------------
686#
687# ip access-list ACL1v4
688#  50 deny tcp any lt 55 192.0.2.64 0.0.0.255 ack fin
689# ipv6 access-list ACL1v6
690#  10 permit sctp any any
691
692- name: Gather existing configuration
693  cisco.nxos.nxos_acls:
694    state: gathered
695
696# returns:
697# gathered:
698# - afi: ipv4
699#   acls:
700#     - name: ACL1v4
701#       aces:
702#         - grant: deny
703#           destination:
704#             address: 192.0.2.64
705#             wildcard_bits: 0.0.0.255
706#           source:
707#             any: true
708#             port_protocol:
709#               lt: 55
710#           protocol: tcp
711#           protocol_options:
712#             tcp:
713#               ack: true
714#               fin: true
715#           sequence: 50
716
717# - afi: ipv6
718#   acls:
719#     - name: ACL1v6
720#       aces:
721#         - grant: permit
722#           sequence: 10
723#           source:
724#             any: true
725#           destination:
726#             prefix: 2001:db8:12::/32
727#           protocol: sctp
728
729
730# Using rendered
731
732- name: Render required configuration to be pushed to the device
733  cisco.nxos.nxos_acls:
734    config:
735    - afi: ipv4
736      acls:
737      - name: ACL1v4
738        aces:
739        - grant: deny
740          destination:
741            address: 192.0.2.64
742            wildcard_bits: 0.0.0.255
743          source:
744            any: true
745            port_protocol:
746              lt: 55
747          protocol: tcp
748          protocol_options:
749            tcp:
750              ack: true
751              fin: true
752          sequence: 50
753
754    - afi: ipv6
755      acls:
756      - name: ACL1v6
757        aces:
758        - grant: permit
759          sequence: 10
760          source:
761            any: true
762          destination:
763            prefix: 2001:db8:12::/32
764          protocol: sctp
765    state: rendered
766
767# returns:
768# rendered:
769#  ip access-list ACL1v4
770#   50 deny tcp any lt 55 192.0.2.64 0.0.0.255 ack fin
771#  ipv6 access-list ACL1v6
772#   10 permit sctp any any
773"""
774RETURN = """
775before:
776  description: The configuration prior to the model invocation.
777  returned: always
778  type: dict
779  sample: >
780    The configuration returned will always be in the same format
781     of the parameters above.
782after:
783  description: The resulting configuration model invocation.
784  returned: when changed
785  type: dict
786  sample: >
787    The configuration returned will always be in the same format
788     of the parameters above.
789commands:
790  description: The set of commands pushed to the remote device.
791  returned: always
792  type: list
793  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']
794"""
795
796from ansible.module_utils.basic import AnsibleModule
797from ansible_collections.cisco.nxos.plugins.module_utils.network.nxos.argspec.acls.acls import (
798    AclsArgs,
799)
800from ansible_collections.cisco.nxos.plugins.module_utils.network.nxos.config.acls.acls import (
801    Acls,
802)
803
804
805def main():
806    """
807    Main entry point for module execution
808
809    :returns: the result form module invocation
810    """
811    module = AnsibleModule(
812        argument_spec=AclsArgs.argument_spec, supports_check_mode=True
813    )
814
815    result = Acls(module).execute_module()
816    module.exit_json(**result)
817
818
819if __name__ == "__main__":
820    main()
821