Manage the configuration of a specific policy term.

    filter_name
        The name of the policy filter.

    term_name
        The name of the term.

    filter_options
        Additional filter options. These options are platform-specific.
        See the complete list of options_.

        .. _options: https://github.com/google/capirca/wiki/Policy-format#header-section

    pillar_key: ``acl``
        The key in the pillar containing the default attributes values. Default: ``acl``.

    pillarenv
        Query the master to generate fresh pillar data on the fly,
        specifically from the requested pillar environment.

    saltenv
        Included only for compatibility with
        :conf_minion:`pillarenv_from_saltenv`, and is otherwise ignored.

    merge_pillar: ``False``
        Merge the CLI variables with the pillar. Default: ``False``.

        The properties specified through the state arguments have higher priority than the pillar.

    revision_id
        Add a comment in the term config having the description for the changes applied.

    revision_no
        The revision count.

    revision_date: ``True``
        Boolean flag: display the date when the term configuration was generated. Default: ``True``.

    revision_date_format: ``%Y/%m/%d``
        The date format to be used when generating the perforce data. Default: ``%Y/%m/%d`` (<year>/<month>/<day>).

    test: ``False``
        Dry run? If set as ``True``, will apply the config, discard and return the changes.
        Default: ``False`` and will commit the changes on the device.

    commit: ``True``
        Commit? Default: ``True``.

    debug: ``False``
        Debug mode. Will insert a new key under the output dictionary,
        as ``loaded_config`` containing the raw configuration loaded on the device.

    source_service
        A special service to choose from. This is a helper so the user is able to
        select a source just using the name, instead of specifying a source_port and protocol.

        As this module is available on Unix platforms only,
        it reads the IANA_ port assignment from /etc/services.

        If the user requires additional shortcuts to be referenced, they can add entries under /etc/services,
        which can be managed using the :mod:`file state <salt.states.file>`.

        .. _IANA: http://www.iana.org/assignments/port-numbers

    destination_service
        A special service to choose from. This is a helper so the user is able to
        select a source just using the name, instead of specifying a destination_port and protocol.
        Allows the same options as ``source_service``.

    term_fields
        Term attributes. To see what fields are supported, please consult the
        list of supported keywords_. Some platforms have few other optional_
        keywords.

        .. _keywords: https://github.com/google/capirca/wiki/Policy-format#keywords
        .. _optional: https://github.com/google/capirca/wiki/Policy-format#optionally-supported-keywords

    .. note::
        The following fields are accepted:

        - action
        - address
        - address_exclude
        - comment
        - counter
        - expiration
        - destination_address
        - destination_address_exclude
        - destination_port
        - destination_prefix
        - forwarding_class
        - forwarding_class_except
        - logging
        - log_name
        - loss_priority
        - option
        - policer
        - port
        - precedence
        - principals
        - protocol
        - protocol_except
        - qos
        - pan_application
        - routing_instance
        - source_address
        - source_address_exclude
        - source_port
        - source_prefix
        - verbatim
        - packet_length
        - fragment_offset
        - hop_limit
        - icmp_type
        - ether_type
        - traffic_class_count
        - traffic_type
        - translated
        - dscp_set
        - dscp_match
        - dscp_except
        - next_ip
        - flexible_match_range
        - source_prefix_except
        - destination_prefix_except
        - vpn
        - source_tag
        - destination_tag
        - source_interface
        - destination_interface
        - flattened
        - flattened_addr
        - flattened_saddr
        - flattened_daddr
        - priority

    .. note::
        The following fields can be also a single value and a list of values:

        - action
        - address
        - address_exclude
        - comment
        - destination_address
        - destination_address_exclude
        - destination_port
        - destination_prefix
        - forwarding_class
        - forwarding_class_except
        - logging
        - option
        - port
        - precedence
        - principals
        - protocol
        - protocol_except
        - pan_application
        - source_address
        - source_address_exclude
        - source_port
        - source_prefix
        - verbatim
        - icmp_type
        - ether_type
        - traffic_type
        - dscp_match
        - dscp_except
        - flexible_match_range
        - source_prefix_except
        - destination_prefix_except
        - source_tag
        - destination_tag
        - source_service
        - destination_service

        Example: ``destination_address`` can be either defined as:

        .. code-block:: yaml

            destination_address: 172.17.17.1/24

        or as a list of destination IP addresses:

        .. code-block:: yaml

            destination_address:
                - 172.17.17.1/24
                - 172.17.19.1/24

        or a list of services to be matched:

        .. code-block:: yaml

            source_service:
                - ntp
                - snmp
                - ldap
                - bgpd

    .. note::
        The port fields ``source_port`` and ``destination_port`` can be used as
        above to select either a single value, either a list of values, but
        also they can select port ranges. Example:

        .. code-block:: yaml

            source_port:
                - [1000, 2000]
                - [3000, 4000]

        With the configuration above, the user is able to select the 1000-2000 and 3000-4000 source port ranges.

    CLI Example:

    .. code-block:: bash

        salt 'edge01.bjm01' state.sls router.acl

    Output Example:

    .. code-block:: text

        edge01.bjm01:
        ----------
                  ID: update_icmp_first_term
            Function: netacl.term
              Result: None
             Comment: Testing mode: Configuration discarded.
             Started: 12:49:09.174179
            Duration: 5751.882 ms
             Changes:
                      ----------
                      diff:
                          [edit firewall]
                          +    family inet {
                          +        /*
                          +         ** $Id: update_icmp_first_term $
                          +         ** $Date: 2017/02/30 $
                          +         **
                          +         */
                          +        filter block-icmp {
                          +            term first-term {
                          +                from {
                          +                    protocol icmp;
                          +                }
                          +                then {
                          +                    reject;
                          +                }
                          +            }
                          +        }
                          +    }

        Summary for edge01.bjm01
        ------------
        Succeeded: 1 (unchanged=1, changed=1)
        Failed:    0
        ------------
        Total states run:     1
        Total run time:   5.752 s

    Pillar example:

    .. code-block:: yaml

        firewall:
          - block-icmp:
              terms:
                - first-term:
                    protocol:
                      - icmp
                    action: reject

    State SLS example:

    .. code-block:: jinja

        {%- set filter_name = 'block-icmp' -%}
        {%- set term_name = 'first-term' -%}
        {%- set my_term_cfg = salt.netacl.get_term_pillar(filter_name, term_name) -%}

        update_icmp_first_term:
          netacl.term:
            - filter_name: {{ filter_name }}
            - filter_options:
                - not-interface-specific
            - term_name: {{ term_name }}
            - {{ my_term_cfg | json }}

    Or directly referencing the pillar keys:

    .. code-block:: yaml

        update_icmp_first_term:
          netacl.term:
            - filter_name: block-icmp
            - filter_options:
                - not-interface-specific
            - term_name: first-term
            - merge_pillar: true

    .. note::
        The first method allows the user to eventually apply complex manipulation
        and / or retrieve the data from external services before passing the
        data to the state. The second one is more straightforward, for less
        complex cases when loading the data directly from the pillar is sufficient.

    .. note::
        When passing retrieved pillar data into the state file, it is strongly
        recommended to use the json serializer explicitly (`` | json``),
        instead of relying on the default Python serializer.

def term(name,
         filter_name,
         term_name,
         filter_options=None,
         pillar_key='acl',
         pillarenv=None,
         saltenv=None,
         merge_pillar=False,
         revision_id=None,
         revision_no=None,
         revision_date=True,
         revision_date_format='%Y/%m/%d',
         test=False,
         commit=True,
         debug=False,
         source_service=None,
         destination_service=None,
         **term_fields):
    '''
    Manage the configuration of a specific policy term.

    filter_name
        The name of the policy filter.

    term_name
        The name of the term.

    filter_options
        Additional filter options. These options are platform-specific.
        See the complete list of options_.

        .. _options: https://github.com/google/capirca/wiki/Policy-format#header-section

    pillar_key: ``acl``
        The key in the pillar containing the default attributes values. Default: ``acl``.

    pillarenv
        Query the master to generate fresh pillar data on the fly,
        specifically from the requested pillar environment.

    saltenv
        Included only for compatibility with
        :conf_minion:`pillarenv_from_saltenv`, and is otherwise ignored.

    merge_pillar: ``False``
        Merge the CLI variables with the pillar. Default: ``False``.

        The properties specified through the state arguments have higher priority than the pillar.

    revision_id
        Add a comment in the term config having the description for the changes applied.

    revision_no
        The revision count.

    revision_date: ``True``
        Boolean flag: display the date when the term configuration was generated. Default: ``True``.

    revision_date_format: ``%Y/%m/%d``
        The date format to be used when generating the perforce data. Default: ``%Y/%m/%d`` (<year>/<month>/<day>).

    test: ``False``
        Dry run? If set as ``True``, will apply the config, discard and return the changes.
        Default: ``False`` and will commit the changes on the device.

    commit: ``True``
        Commit? Default: ``True``.

    debug: ``False``
        Debug mode. Will insert a new key under the output dictionary,
        as ``loaded_config`` containing the raw configuration loaded on the device.

    source_service
        A special service to choose from. This is a helper so the user is able to
        select a source just using the name, instead of specifying a source_port and protocol.

        As this module is available on Unix platforms only,
        it reads the IANA_ port assignment from /etc/services.

        If the user requires additional shortcuts to be referenced, they can add entries under /etc/services,
        which can be managed using the :mod:`file state <salt.states.file>`.

        .. _IANA: http://www.iana.org/assignments/port-numbers

    destination_service
        A special service to choose from. This is a helper so the user is able to
        select a source just using the name, instead of specifying a destination_port and protocol.
        Allows the same options as ``source_service``.

    term_fields
        Term attributes. To see what fields are supported, please consult the
        list of supported keywords_. Some platforms have few other optional_
        keywords.

        .. _keywords: https://github.com/google/capirca/wiki/Policy-format#keywords
        .. _optional: https://github.com/google/capirca/wiki/Policy-format#optionally-supported-keywords

    .. note::
        The following fields are accepted:

        - action
        - address
        - address_exclude
        - comment
        - counter
        - expiration
        - destination_address
        - destination_address_exclude
        - destination_port
        - destination_prefix
        - forwarding_class
        - forwarding_class_except
        - logging
        - log_name
        - loss_priority
        - option
        - policer
        - port
        - precedence
        - principals
        - protocol
        - protocol_except
        - qos
        - pan_application
        - routing_instance
        - source_address
        - source_address_exclude
        - source_port
        - source_prefix
        - verbatim
        - packet_length
        - fragment_offset
        - hop_limit
        - icmp_type
        - ether_type
        - traffic_class_count
        - traffic_type
        - translated
        - dscp_set
        - dscp_match
        - dscp_except
        - next_ip
        - flexible_match_range
        - source_prefix_except
        - destination_prefix_except
        - vpn
        - source_tag
        - destination_tag
        - source_interface
        - destination_interface
        - flattened
        - flattened_addr
        - flattened_saddr
        - flattened_daddr
        - priority

    .. note::
        The following fields can be also a single value and a list of values:

        - action
        - address
        - address_exclude
        - comment
        - destination_address
        - destination_address_exclude
        - destination_port
        - destination_prefix
        - forwarding_class
        - forwarding_class_except
        - logging
        - option
        - port
        - precedence
        - principals
        - protocol
        - protocol_except
        - pan_application
        - source_address
        - source_address_exclude
        - source_port
        - source_prefix
        - verbatim
        - icmp_type
        - ether_type
        - traffic_type
        - dscp_match
        - dscp_except
        - flexible_match_range
        - source_prefix_except
        - destination_prefix_except
        - source_tag
        - destination_tag
        - source_service
        - destination_service

        Example: ``destination_address`` can be either defined as:

        .. code-block:: yaml

            destination_address: 172.17.17.1/24

        or as a list of destination IP addresses:

        .. code-block:: yaml

            destination_address:
                - 172.17.17.1/24
                - 172.17.19.1/24

        or a list of services to be matched:

        .. code-block:: yaml

            source_service:
                - ntp
                - snmp
                - ldap
                - bgpd

    .. note::
        The port fields ``source_port`` and ``destination_port`` can be used as
        above to select either a single value, either a list of values, but
        also they can select port ranges. Example:

        .. code-block:: yaml

            source_port:
                - [1000, 2000]
                - [3000, 4000]

        With the configuration above, the user is able to select the 1000-2000 and 3000-4000 source port ranges.

    CLI Example:

    .. code-block:: bash

        salt 'edge01.bjm01' state.sls router.acl

    Output Example:

    .. code-block:: text

        edge01.bjm01:
        ----------
                  ID: update_icmp_first_term
            Function: netacl.term
              Result: None
             Comment: Testing mode: Configuration discarded.
             Started: 12:49:09.174179
            Duration: 5751.882 ms
             Changes:
                      ----------
                      diff:
                          [edit firewall]
                          +    family inet {
                          +        /*
                          +         ** $Id: update_icmp_first_term $
                          +         ** $Date: 2017/02/30 $
                          +         **
                          +         */
                          +        filter block-icmp {
                          +            term first-term {
                          +                from {
                          +                    protocol icmp;
                          +                }
                          +                then {
                          +                    reject;
                          +                }
                          +            }
                          +        }
                          +    }

        Summary for edge01.bjm01
        ------------
        Succeeded: 1 (unchanged=1, changed=1)
        Failed:    0
        ------------
        Total states run:     1
        Total run time:   5.752 s

    Pillar example:

    .. code-block:: yaml

        firewall:
          - block-icmp:
              terms:
                - first-term:
                    protocol:
                      - icmp
                    action: reject

    State SLS example:

    .. code-block:: jinja

        {%- set filter_name = 'block-icmp' -%}
        {%- set term_name = 'first-term' -%}
        {%- set my_term_cfg = salt.netacl.get_term_pillar(filter_name, term_name) -%}

        update_icmp_first_term:
          netacl.term:
            - filter_name: {{ filter_name }}
            - filter_options:
                - not-interface-specific
            - term_name: {{ term_name }}
            - {{ my_term_cfg | json }}

    Or directly referencing the pillar keys:

    .. code-block:: yaml

        update_icmp_first_term:
          netacl.term:
            - filter_name: block-icmp
            - filter_options:
                - not-interface-specific
            - term_name: first-term
            - merge_pillar: true

    .. note::
        The first method allows the user to eventually apply complex manipulation
        and / or retrieve the data from external services before passing the
        data to the state. The second one is more straightforward, for less
        complex cases when loading the data directly from the pillar is sufficient.

    .. note::
        When passing retrieved pillar data into the state file, it is strongly
        recommended to use the json serializer explicitly (`` | json``),
        instead of relying on the default Python serializer.
    '''
    ret = salt.utils.napalm.default_ret(name)
    test = __opts__['test'] or test
    if not filter_options:
        filter_options = []
    loaded = __salt__['netacl.load_term_config'](filter_name,
                                                 term_name,
                                                 filter_options=filter_options,
                                                 pillar_key=pillar_key,
                                                 pillarenv=pillarenv,
                                                 saltenv=saltenv,
                                                 merge_pillar=merge_pillar,
                                                 revision_id=revision_id if revision_id else name,
                                                 revision_no=revision_no,
                                                 revision_date=revision_date,
                                                 revision_date_format=revision_date_format,
                                                 source_service=source_service,
                                                 destination_service=destination_service,
                                                 test=test,
                                                 commit=commit,
                                                 debug=debug,
                                                 **term_fields)
    return salt.utils.napalm.loaded_ret(ret, loaded, test, debug)