.. meta::
    :description: This documentation will guide you through the use of the Memset API.

.. index::
   double: Methods; firewalling

.. _firewalling:

Firewalling Methods
-------------------

API for Firewalling services.

This API can be used to retrieve and change firewalling configuration for your
servers. Read only methods are provided for all servers. Configuration may only be changed for servers with Self-managed or Memset-managed firewalling.

Firewall rules are grouped together in firewall rule groups. When creating firewall
rule groups, the rule group name will be created by the system.

Information about the firewall rule group currently applied to a server can be found
in the ``firewall_rule_group`` entry of the dictionary returned by :func:`server.info`.

An :ref:`example <python-firewalling-example>` is provided in Python.

.. function:: firewalling.rule_create

    Create a firewall rule within a rule group. Rules cannot be created in public rule groups.
    
    The rule will be validated to ensure it is not malformed.
    
    :param rule_group_name: The name of the firewall rule group to which this rule is to be added.
    :type rule_group_name: String
    
    :param ip_version: The Internet Protocol version. Defaults to "any". Acceptable values
        
        'any'
            any
        'ipv4'
            IPv4
        'ipv6'
            IPv6
        
    :type ip_version: String, Optional
    
    :param action: The action for this rule. Acceptable values: 'ACCEPT', 'DROP', 'REJECT'.
    :type action: String
    
    :param source_ips: 'any' or a comma separated list of source IPv4 addresses without spaces. These can be CIDR notation, eg 1.2.3.4/24.
    :type source_ips: String, Optional
    
    :param source_ports: 'any' or a comma separated list of port numbers without spaces
    :type source_ports: String, Optional
    
    :param dest_ips: 'any' or a comma separated list of source IPv4 addresses without spaces.
    :type dest_ips: String, Optional
    
    :param source_ip6s: 'any' or a comma separated list of source IPv6 addresses without spaces. These can be CIDR notation, eg 2001:db8::/120.
    :type source_ip6s: String, Optional
    
    :param dest_ip6s: 'any' or a comma separated list of source IPv6 addresses without spaces.
    :type dest_ip6s: String, Optional
    
    :param dest_ports: 'any' or a comma separated list of port numbers without spaces
    :type dest_ports: String
    
    :param protocols: The protocol(s). If 'any', the protocol and dst ports are not used for matching. Acceptable values
        
        'tcp'
            TCP
        'udp'
            UDP
        'icmp'
            ICMP
        'tcp,udp'
            TCP,UDP
        'gre'
            GRE
        'esp'
            ESP
        'ah'
            AH
        'ipip'
            IPIP
        'sctp'
            SCTP
        'any'
            any
        
    :type protocols: String, Optional
    
    :param ordering: The ordering for this rule. Ensure this value is greater than or equal to 1. Ensure this value is less than or equal to 30.
    :type ordering: Integer
    
    :param comment: Optional comment about this rule.
    :type comment: String, Optional
    
    :param direction: The direction of traffic that this rule should be applied to. Either 'Inbound' or 'Outbound'. Defaults to Inbound Acceptable values
        
        'Inbound'
            Inbound
        'Outbound'
            Outbound
        
    :type direction: String, Optional
    
    :returns: A dictionary of the newly created rule as described in :func:`firewalling.rule_info`.
    
    :raises: May raise:
    
        * :class:`ApiErrorPreconditionFailed` if the rule group has the maximum number of rules already.
        * :class:`ApiErrorDoesNotExist` if the firewall rule group with provided name or nickname does not exist.
        * :class:`ApiErrorBadParameters` if the firewall rule parameters are invalid or malformed.

.. function:: firewalling.rule_delete

    Delete the firewall rule with id ``rule_id``.
    
    :param rule_id: The unique id of the rule
    :type rule_id: String
    
    :returns: The id of the successfully deleted rule.
    
    :raises: May raise:
    
        * :class:`ApiErrorDoesNotExist` if the firewall rule with id ``rule_id`` does not exist for this account. Rules within public firewall groups may not be deleted and therefore won't be searched.

.. function:: firewalling.rule_group_create

    Add a new firewall rule group for this account.
    
    :param nickname: A nickname for this firewall rule group. Ensure this value has at most 225 characters.
    :type nickname: String
    
    :param notes: Notes about this firewall rule group.
    :type notes: String, Optional
    
    :param rules: A List of dictionaries describing firewall rules to create as described in :func:`firewalling.rule_info` excluding the ``rule_group_name`` parameter (which is created automatically). Maximum number of rules per rule group: 30 
    :type rules: List, Optional
    
    :param default_outbound_policy: The default policy to be applied to outbound traffic. Supports 'Accept', 'Drop' or 'Reject'. Defaults to 'Accept'. This option is only available for customers using the outbound firewalling beta Acceptable values
        
        'RETURN'
            Accept
        'REJECT'
            Reject
        'DROP'
            Drop
        
    :type default_outbound_policy: String, Optional
    
    :returns: A dictionary as detailed in :func:`firewalling.rule_group_info` for the newly created firewall rule group.
    
    :raises: May raise:
    
        * :class:`ApiErrorPreconditionFailed` if the nickname is already in use for another firewall rule group on the account.
        * :class:`ApiErrorBadParameters` if more than the maximum number of rules for a group provided.
        * :class:`ApiErrorBadParameters` if any of the provided firewall rules are invalid or malformed.

.. function:: firewalling.rule_group_delete

    Delete a firewall rule group for this account.
    
    :param rule_group_name: The name of the firewall rule group.
    :type rule_group_name: String
    
    :returns: the name of the deleted rule group.
    
    :raises: May raise:
    
        * :class:`ApiErrorDoesNotExist` if the rule group is not found. Public rule groups may not be deleted and therefore will not be searched.
        * :class:`ApiErrorPreconditionFailed` if there are servers using the rule group.

.. function:: firewalling.rule_group_info

    Get information about a rule group.
    
    :param rule_group_name: The name of the firewall rule group.
    :type rule_group_name: String
    
    :returns: A dictionary with the following keys
    
        **name**
            String: The unique identifier for this rule group.
    
        **nickname**
            String: The nickname of this rule group.
    
        **public**
            Boolean: Whether this rule group is public.
    
        **notes**
            String: Any notes associated with this rule group.
    
        **default_outbound_policy**
            String: The default policy applied to outbound traffic.
    
        **rules**
            Dictionary: As provided by :func:`firewalling.rule_info`.
            
    :raises: :class:`ApiErrorDoesNotExist` if the rule group does not exist.

.. function:: firewalling.rule_group_list

    Retrieve a list of firewall rule groups for this account.
    
    :param include_public: Include public rule groups. Default: True.
    :type include_public: Boolean, Optional
    
    :returns: A list of dictionaries as described in :func:`firewalling.rule_group_info`.

.. function:: firewalling.rule_group_status

    Check the status of a rule group for a specific server.
    
    :param name: Name of the service. Service names are 1-64 characters A-Z, a-z, 0-9, -, . and _. Ensure this value has at most 64 characters.
    :type name: String
    
    :param rule_group_name: The name of the firewall rule group.
    :type rule_group_name: String
    
    :returns: String: The status of the rule group for a server. The status
              may be one of the following:
    
              **active**
                    rule group is active and up to date for this server
              **pending**
                    rule group is active but there are pending changes which are not yet loaded in the firewall
              **na**
                    rule group is not currently applicable to this server
    
    :raises: :class:`ApiErrorDoesNotExist` if the `name` or `rule_group_name` does not exist.

.. function:: firewalling.rule_info

    Retrieve firewall rule information.
    
    :param rule_id: The unique id of the rule
    :type rule_id: String
    
    :returns: A dictionary with the following keys:
    
        **rule_id**
            String: The unique id of the rule.
    
        **rule_group_name**
            String: The name of the firewall rule group this rule belongs to.
    
        **ip_version**
            String: 'ipv4', 'ipv6' or 'all'.
    
        **action**
            String: 'ACCEPT', 'DROP' or 'REJECT'.
    
        **source_ips**
            String: 'any' or a comma separated list of source IP addresses without spaces. These can be CIDR notation, eg 1.2.3.4/24.
    
        **source_ip6s**
            String: 'any' or a comma separated list of source IPv6 addresses without spaces. These can be CIDR notation, eg 2001:db8::/120.
    
        **dest_ips**
            String: 'any' or a comma separated list of destination IP addresses without spaces.
        
        **dest_ip6s**
            String: 'any' or a comma separated list of destination IPv6 addresses without spaces.
    
        **source_ports**
            String: 'any' or a comma separated list of port numbers without spaces.
    
        **dest_ports**
            String: 'any' or a comma separated list of port numbers without spaces.
        
        **protocols**
            String: 'any' or a comma separated list of protocols without spaces.
        
        **ordering**
            Integer: The position of this rule within the rule group.
    
        **comment**
            String: Any comment associated with the rule.
    
        **direction**
            String: 'Inbound' or 'Outbound'. This option is only supported for customers using the outbound firewalling beta.
    
    :raises: May raise:
    
        * :class:`ApiErrorBadParameters` if ``rule_id`` is malformed.
        * :class:`ApiErrorDoesNotExist` if the firewall rule with id ``rule_id`` is not found.

.. function:: firewalling.rule_update

    Update a firewall rule. Rules which are part of public rule groups may not be changed and therefore will not be searched.
    
    Cannot be used to change the direction of a rule.
    
    :param rule_id: The unique id of the rule
    :type rule_id: String
    
    :param ip_version: The Internet Protocol version. Acceptable values
        
        'any'
            any
        'ipv4'
            IPv4
        'ipv6'
            IPv6
        
    :type ip_version: String, Optional
    
    :param action: The action for this rule. Acceptable values: 'ACCEPT', 'DROP', 'REJECT'.
    :type action: String, Optional
    
    :param source_ips: 'any' or a comma separated list of source IPv4 addresses without spaces. These can be CIDR notation, eg 1.2.3.4/24.
    :type source_ips: String, Optional
    
    :param dest_ips: 'any' or a comma separated list of source IPv4 addresses without spaces.
    :type dest_ips: String, Optional
    
    :param source_ip6s: 'any' or a comma separated list of source IPv6 addresses without spaces. These can be CIDR notation, eg 2001:db8::/120.
    :type source_ip6s: String, Optional
    
    :param dest_ip6s: 'any' or a comma separated list of source IPv6 addresses without spaces.
    :type dest_ip6s: String, Optional
    
    :param source_ports: 'any' or a comma separated list of port numbers without spaces
    :type source_ports: String, Optional
    
    :param dest_ports: 'any' or a comma separated list of port numbers without spaces
    :type dest_ports: String, Optional
    
    :param protocols: 'any' or a comma separated list of protocols without spaces. If 'any', the protocol and dst ports are not used for matching. Acceptable values
        
        'tcp'
            TCP
        'udp'
            UDP
        'icmp'
            ICMP
        'tcp,udp'
            TCP,UDP
        'gre'
            GRE
        'esp'
            ESP
        'ah'
            AH
        'ipip'
            IPIP
        'sctp'
            SCTP
        'any'
            any
        
    :type protocols: String, Optional
    
    :param ordering: The ordering for this rule. Ensure this value is greater than or equal to 1. Ensure this value is less than or equal to 30.
    :type ordering: Integer, Optional
    
    :param comment: Optional comment about this rule
    :type comment: String, Optional
    
    :returns: A dictionary as detailed in :func:`firewalling.rule_info` for the modified firewall rule.
    
    :raises: May raise:
    
        * :class:`ApiErrorDoesNotExist` if the firewall rule with id ``rule_id`` is not found.
        * :class:`ApiErrorBadParameters` if ``rule_id`` is malformed.
        * :class:`ApiErrorBadParameters` if the submitted rule parameters result in an invalid/malformed rule.

.. function:: firewalling.update

    Apply a different firewall rule group to ``name``.
    
    The specified firewall rule group can be either a private rule group or one of Memset's public rule groups.
    
    :param name: Name of the service. Service names are 1-64 characters A-Z, a-z, 0-9, -, . and _. Ensure this value has at most 64 characters.
    :type name: String
    
    :param rule_group_name: The name of the firewall rule group to apply to this server.
    :type rule_group_name: String
    
    :returns: A dictionary as provided by :func:`firewalling.rule_group_info` for the server.
    
    :raises: May raise: 
    
        * :class:`ApiErrorDoesNotExist` if the server ``name`` does not exist or if the rule group with the given ``rule_group_name`` does not exist.
        * :class:`ApiErrorPreconditionFailed` if the server ``name`` does not have 'managed' firewalling type.