From 42eb57c2c90653d3623a4b5bf087b58f29b2e94f Mon Sep 17 00:00:00 2001 From: Reto Gantenbein Date: Sun, 24 Apr 2016 15:39:34 +0200 Subject: [PATCH 1/8] Add initial suggestion for firewall rules documentation --- docs/index.rst | 1 + docs/rules.rst | 622 +++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 623 insertions(+) create mode 100644 docs/rules.rst diff --git a/docs/index.rst b/docs/index.rst index 3afb704..c498953 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -11,6 +11,7 @@ Ansible role: debops.ferm getting-started defaults defaults-configuration + rules copyright credits changelog diff --git a/docs/rules.rst b/docs/rules.rst new file mode 100644 index 0000000..c07eca9 --- /dev/null +++ b/docs/rules.rst @@ -0,0 +1,622 @@ +Firewall Rules Configuration +============================ + +Firewall configuration in ``debops.ferm`` is done through a flexible +definition of rules. There are a number of variables which are used to +reference a set of default rules and can be extended by user defined +rules. Here a description of the involved configurations should be given +so that everyone can customize the ruleset according to individual +requirements. + +.. contents:: + :local: + :depth: 1 + +.. _default_rules: + +Default rules +------------- + +By default ``debops.ferm`` configures a number of rules as soon as a +host is part of the ``[debops_all_hosts]`` Ansible host group. In case +a firewall is not required or preferred this behaviour can be disabled +by setting ``ferm__enabled: no`` in the inventory. The rules created +by default are defined in ``defaults/main.yml`` and activated by being +listed in `ferm__default_rules`_. They consist of basic rules for +setting the ``iptables`` default policies, restricting extensive +connection attempts, logging and more. + +.. _ferm__default_rules: defaults.html#envvar-ferm__default_rules + +.. _custom_rules: + +Custom rules +------------ + +A custom rule can be enabled by adding a rule definition to one of the +pre-defined rule lists (`ferm__rules`_, `ferm__group_rules`_, +`ferm__host_rules`_ or `ferm__dependent_rules`_) in the Ansible +inventory. Each rule has to be defined as a YAML dict using some of +the following keys: + +``type`` + Type of the rule template used for creating the corresponding ferm + configuration, required. See `rule_templates`_ for a description of + the available rule templates. + +``chain`` + Optional. ``iptables`` chain to which the rule is added or from which it + is removed. Defaults to ``INPUT``. + +``comment`` + Optional. Comment which should be added to the generated rule configuration. + +``delete`` + Optional. Delete rule from ferm configuration. Possible values ``True`` + or ``False``. Defaults to ``False``. + +``domain`` + Optional. ``iptables`` domain used for the firewall rule. Possible values: + ``ip``, ``ip6``. Defaults to `ferm__domains`_. + +``table`` + Optional. ``iptables`` table to which the rule is added or from which it + is removed. Defaults to ``filter``. + +``filename`` + Optional. Set custom filename for ferm rule definition instead of generated + one. + +``role`` + Optional. Custom name used in the generated ferm rule definition file. + +``role_weight`` + Optional. This allows to set the same ``weight`` for all rules of a + particular Ansible role. + +``rule_state`` + Optional. Specify if rule is to be added or removed. Possible values: + ``present`` or ``absent``. Defaults to ``present``. + +``weight`` + Optional. Helps with file sorting in rule directory. + +``weight_class`` + Optional. Helps to manage order of firewall rules. The ``item.weight_class`` + will be checked in the `ferm__weight_map`_ dictionary. If a corresponding + entry is found, its weight will be used for that rule, if not, the + ``item.weight`` specified in the rule will be used instead. + +``when`` + Optional. Define condition for the rule to be enabled. + +.. _ferm__rules: defaults.html#envvar-ferm__rules +.. _ferm__group_rules: defaults.html#envvar-ferm__group_rules +.. _ferm__host_rules: defaults.html#envvar-ferm__host_rules +.. _ferm__dependent_rules: defaults.html#envvar-ferm__dependent-rules +.. _ferm__domains: defaults.html#envvar-ferm__domains +.. _ferm__weight_map: defaults.html#envvar-ferm__weight_map + +.. _rule_templates: + +Depending on the choosen type, many additional variables are supported. +Please check the individual template description below. + + +Rule templates +-------------- + +There exist a number of predefined rule templates for generating firewall +rules through ferm. Each rule definition is referencing the used template +through its ``type`` key. The templates are located in the +``templates/etc/ferm/ferm.d/`` directory. + +Following a list of the available rule templates which can be used to +create custom rules: + +* ``accept``: Template to create rules that match interfaces, ports, remote + IP addresses/subnets and can accept the packets, reject, or redirect to + a different chain. The following template-specific YAML keys are supported: + + ``accept_any`` + Optional. ? + + ``daddr`` + Optional. List of destination IP addresses or networks to which the + rule is applied. + + ``dport`` + Optional. List of destination ports to which the rule is applied. + + ``enabled`` + Optional. Enable rule definition. Possible values: ``True`` or + ``False``. Defaults to ``True``. + + ``include`` + Optional. Custom ferm configuration file to include. + + ``interface`` + Optional. List of network interfaces for incoming packets to which + the rule is applied. + + ``interface_present`` + Optional. Same as ``item.interface`` but first check if specified + network interfaces exists before adding the firewall rules. + + ``multiport`` + Optional. Use ``iptables multiport`` extension. Possible values: + ``True`` or ``False``. Defaults to ``False``. + + ``name`` + Optional. Set rule name in places where it is referenced. + + ``outerface`` + Optional. List of network interfaces for outgoing packets to which + the rule is applied. + + ``outerface_present`` + Optional. Same as ``item.outerface`` but first check if specified + network interface exists before adding the firewall rule. + + ``protocol`` + Optional. Network protocol to which the rule is applied. + + ``protocol_syn`` + Optional. Match TCP packet with only the SYN flag set. Possible + values ``True`` or ``False``. If set to ``False`` it will match all + other packets except the ones with only the SYN flag set. Defaults + to unset. + + ``realgoto`` + Optional. ? + + ``reject_with`` + Optional. Define reject message being sent when the rule ``item.target`` + is set to ``REJECT``. Defaults to ``icmp-admin-prohibited``. + + ``saddr`` + Optional. List of source IP addresses or networks to which this rule is + applied. + + ``sport`` + Optional. List fo source ports to which the rule is applied. + + ``state`` + Optional. Connection state which should be matched. Possible values: + ``INVALID``, ``ESTABLISHED``, ``NEW``, ``RELATED``, ``UNTRACKED`` or + comma-separated combination thereof. + + ``subchain`` + Optional. ? + + ``target`` + Optional. ``iptables`` jump target. Possible values: ``ACCEPT``, + ``DROP``, ``REJECT``, ``RETURN``, ``NOP`` or a custom target. Defaults + to ``ACCEPT``. + + ``when`` + Optional. Define condition for the rule to be disabled. + +* ``ansible_controller``: Similar to the ``accept`` template but defaults + to the SSH target port and sets the source address to the host running + Ansible if not overwritten through the ``ansible_controllers`` key. + The following template-specific YAML keys are supported: + + ``ansible_controllers`` + Optional. List of source IP address which are added to ``item.saddr``. + Overwrites auto-detection of the Ansible controller address. + + ``daddr`` + Optional. List of destination IP addresses or networks to which the + rule is applied. + + ``dport`` + Optional. List of destination ports to which the rule is applied. + Defaults to ``ssh``. + + ``enabled`` + Optional. Enable rule definition. Possible values: ``True`` or + ``False``. Defaults to ``True``. + + ``include`` + Optional. Custom ferm configuration file to include. + + ``interface`` + Optional. List of network interfaces for incoming packets to which + the rule is applied. + + ``multiport`` + Optional. Use `iptables multiport`_ extension. Possible values: + ``True`` or ``False``. Defaults to ``False``. + + ``name`` + Optional. Set rule name in places where it is referenced. + + ``outerface`` + Optional. List of network interfaces for outgoing packets to which + the rule is applied. + + ``protocol`` + Optional. Network protocol to which the rule is applied. Defaults to + ``tcp``. + + ``protocol_syn`` + Optional. Match TCP packet with only the SYN flag set. Possible + values ``True`` or ``False``. If set to ``False`` it will match all + other packets except the ones with only the SYN flag set. Defaults + to unset. + + ``realgoto`` + Optional. ? + + ``reject_with`` + Optional. Define reject message being sent when the rule ``item.target`` + is set to ``REJECT``. Defaults to ``icmp-admin-prohibited``. + + ``saddr`` + Optional. List of source IP addresses or networks to which this rule is + applied. + + ``sport`` + Optional. List fo source ports to which the rule is applied. + + ``state`` + Optional. Connection state which should be matched. Possible values: + ``INVALID``, ``ESTABLISHED``, ``NEW``, ``RELATED``, ``UNTRACKED`` or + comma-separated combination thereof. + + ``subchain`` + Optional. ? + + ``target`` + Optional. ``iptables`` jump target. Possible values: ``ACCEPT``, + ``DROP``, ``REJECT``, ``RETURN``, ``NOP`` or a custom target. Defaults + to ``ACCEPT``. + + This template is used in the default rule `ferm__rules_filter_ansible_controller`_ + which enables SSH connections from the Ansible controller host. + +.. _iptables multiport: http://ipset.netfilter.org/iptables-extensions.man.html#lbBM +.. _ferm__rules_filter_ansible_controller: defaults.html#envvar-ferm__rules_filter_ansible_controller + +* ``connection_tracking``: Template to enable connection tracking using the + `iptables conntrack`_ or `iptables state`_ extension. The following + template-specific YAML keys are supported: + + ``active_target`` + Optional. ``iptables`` jump target for valid connections. Defaults to + ``ACCEPT``. + + ``invalid_target`` + Optional. ``iptables`` jump target for invalid connections. Defaults to + ``DROP``. + + ``module`` + Optional. ``iptables`` module used for connection tracking. Possible + values: ``state`` or ``conntrack``. Defaults to ``conntrack``. + + ``interface`` + Optional. List of network interfaces for incoming packets to which + the rule is applied. + + ``outerface`` + Optional. List of network interfaces for outgoing packets to which + the rule is applied. + + ``interface_not`` + Optional. List of network interfaces for incoming packets which are + excluded from the rule. + + ``outerface_not`` + Optional. List of network interfaces for outgoing packets which are + excluded from the rule. + + This template is used in the default rule `ferm__rules_filter_conntrack`_ + which enables connection tracking in the ``INPUT``, ``OUTPUT`` and + ``FORWARD`` chain. + +.. _iptables conntrack: http://ipset.netfilter.org/iptables-extensions.man.html#lbAO +.. _iptables state: http://ipset.netfilter.org/iptables-extensions.man.html#lbCC +.. _ferm__rules_filter_conntrack: defaults.html#envvar-ferm__rules_filter_conntrack + +* ``custom``: Template to define custom ferm rules. The following additional + YAML keys are supported: + + ``rule`` + ferm rule definition, required. + + ``by_role`` + Optional. Add comment to generated ferm rule definition file that + rule is defined in the given Ansible role. + + This template is used among others in the ``debops.libvirtd`` ferm rule + `libvirtd__ferm__dependent_rules`_. + +* ``default_policy``: Template to define ``iptables`` default policies. The + following template-specific YAML keys are supported: + + ``policy`` + ``iptables`` chain policy, required. + + This template is used in the default rule `ferm__rules_default_policy`_ + which sets the ``INPUT``, ``FORWARD`` and ``OUTPUT`` chain policies + according to `ferm__default_policy_input`_, `ferm__default_policy_forward`_ + and `ferm__default_policy_output`_. + +.. _ferm__rules_default_policy: defaults.html#envvar-ferm__rules_default_policy +.. _ferm__default_policy_input: defaults.html#envvar-ferm__default_policy_input +.. _ferm__default_policy_forward: defaults.html#envvar-ferm__default_policy_forward +.. _ferm__default_policy_output: defaults.html#envvar-ferm__default_policy_output + +* ``dmz``: Template to enable connection forwarding to another host. If ``port`` + is not specified, all traffic is forwarded. The following template-specific + YAML keys are supported: + + ``multiport`` + Optional. Use `iptables multiport`_ extension. Possible values: + ``True`` or ``False``. Defaults to ``False``. + + ``public_ip`` + IPv4 address on the public network which accepts connections, required. + + ``private_ip`` + IPv4 address of the host on the internal network, required. + + ``protocol(s)`` + Optional. List of protocols to forward. Defaults to ``tcp``. + + ``port(s)`` + Optional. List of ports to forward. + + ``dport`` + Optional. Destination port to forward to. Only needs to be specified + if internal destination port is different from the original destination + port. + +* ``fail2ban``: Template to integrate fail2ban with ``ferm``. As the fail2ban + service is defining its own ``iptables`` chains the template will make sure + that they are properly refreshed if the ``ferm`` configuration changes. + + This template is used in the default rule `ferm__rules_fail2ban`_. + +.. _ferm__rules_fail2ban: defaults.html#envvar-ferm__rules_fail2ban + +* ``hashlimit``: Template to define rate limit rules using the + `iptables hashlimit`_ extension. The following template-specific YAML + keys are supported: + + ``dport`` + Optional. List of destination ports to which the rule is applied. + + ``enabled`` + Optional. Enable rule definition. Possible values: ``True`` and + ``False``. Defaults to ``True``. + + ``hashlimit_burst`` + Optional. Number of packets to match within the expiration time. + Defaults to ``5``. + + ``hashlimit_expire`` + Optional. Expiration time of hash entries in seconds. Defaults to + ``1.8``. + + ``hashlimit_target`` + Optional. ? Defaults to ``RETURN``. + + ``hashlimit_mode`` + Optional. Options to take into consideration when associating packet + streams. Possible values: ``srcip``, ``srcport``, ``dstip``, ``dstport`` + or a comma-separated list thereof. Defaults to ``srcip``. + + ``include`` + Optional. Custom ferm configuration file to include. + + ``log`` + Optional. Write rate limit hits to syslog. Possible values: ``True`` + and ``False``. Defaults to ``True``. + + ``name`` + Optional. Set rule name in places where it is referenced. + + ``protocol`` + Optional. Network protocol to which the rule is applied. + + ``protocol_syn`` + Optional. Match TCP packet with only the SYN flag set. Possible + values ``True`` or ``False``. If set to ``False`` it will match all + other packets except the ones with only the SYN flag set. Defaults + to unset. + + ``reject_with`` + Optional. Define reject message being sent when the rule ``item.target`` + is set to ``REJECT``. Defaults to ``icmp-admin-prohibited``. + + ``state`` + Optional. Connection state which should be matched. Possible values: + ``INVALID``, ``ESTABLISHED``, ``NEW``, ``RELATED``, ``UNTRACKED`` or + comma-separated combination thereof. + + ``subchain`` + Optional. ? + + ``target`` + Optional. ``iptables`` jump target in case the rate limit is reached. + Defaults to ``REJECT``. + + This template is used in the default rules `ferm__rules_filter_icmp`_ and + `ferm__rules_filter_syn`_ which limits the packet rate for ICMP packets + and new connection attempts. + +.. _iptables hashlimit: http://ipset.netfilter.org/iptables-extensions.man.html#lbAY +.. _ferm__rules_filter_icmp: defaults.html#envvar-ferm__rules_filter_icmp +.. _ferm__rules_filter_syn: defaults.html#envvar-ferm__rules_filter_syn + +* ``include``: Template to include custom ferm configuration files. The + following template-specific YAML keys are supported: + + ``include`` + Required. Custom ferm configuration file to include. + +* ``log``: Template to specify logging rules using the `iptables log`_ + extension. The following template-specific YAML keys are supported: + + ``include`` + Optional. Custom ferm configuration file to include. + + ``log_burst`` + Optional. Burst limit of packets being logged. Defaults to + `ferm__log_burst`_. + + ``log_ip_options`` + Optional. Log IP options of packet. Possible values: ``True`` or + ``False``. Defaults to ``True``. + + ``log_level`` + Optional. Log level for firewall messages. Possible values are: + ``emerg``, ``alert``, ``crit``, ``error``, ``warning``, ``notice``, + ``info`` or ``debug``. Defaults to ``warning``. + + ``log_limit`` + Optional. Rate limit of packets being logged. Defaults to + `ferm__log_limit`_. + + ``log_prefix`` + Optional. Prefix (up to 29 characters) for firewall log messages. + Defaults to ``iptables-log: `` + + ``log_target`` + Optional. Select how ``iptables`` performs logging. Possible values: + ``LOG``, ``ULOG``, ``NFLOG``. Defaults to ``LOG``. + + ``log_tcp_options`` + Optional. Log TCP options of packet. Possible values: ``True`` or + ``False``. Defaults to ``False``. + + ``log_tcp_sequence`` + Optional. Log TCP sequence of packet. Possible values: ``True`` or + ``False``. Defaults to ``False``. + + ``realgoto`` + Optional. ? + + ``reject_with`` + Optional. Define reject message being sent when the rule ``item.target`` + is set to ``REJECT``. Defaults to ``icmp-admin-prohibited``. + + ``target`` + Optional. ? + +.. _iptables log: http://ipset.netfilter.org/iptables-extensions.man.html#lbDD +.. _ferm__log_burst: defaults.html#envvar-ferm__log_burst +.. _ferm__log_limit: defaults.html#envvar-ferm__log_limit + +* ``recent``: Template to track connections and respond accordingly by using + the `iptables recent`_ extension. The following template-specific YAML keys + are supported: + + ``dport`` + Optional. List of destination ports to which the rule is applied. + + ``include`` + Optional. Custom ferm configuration file to include. + + ``multiport`` + Optional. Use `iptables multiport`_ extension. Possible values: + ``True`` or ``False``. Defaults to ``False``. + + ``name`` + Optional. Set rule name in places where it is referenced. + + ``protocol`` + Optional. Network protocol to which the rule is applied. + + ``protocol_syn`` + Optional. Match TCP packet with only the SYN flag set. Possible + values ``True`` or ``False``. If set to ``False`` it will match all + other packets except the ones with only the SYN flag set. Defaults + to unset. + + ``recent_hitcount`` + Optional. Must be used in combination with ``item.recent_update``. + Match if address is in the list and at least the given number of + packets were received so far. + + ``recent_log`` + Optional. Log packets hitting + + ``recent_name`` + Optional. Name of the list. Defaults to ``DEFAULT``. + + ``recent_remove`` + Optional. Remove address from the list. Possible values: ``True`` or + ``False``. Defaults to ``False``. Mutually exclusive with + ``item.recent_update``. + + ``recent_seconds`` + Optional. Must be used in combination with ``item.recent_update``. + Match if address is in the list and was last seen within the given + number of seconds. + + ``recent_set_name`` + Optional. ? + + ``recent_target`` + Optional. ``iptables`` jump target when packet has hit the recent list. + Possible values: ``ACCEPT``, ``DROP``, ``REJECT``, ``RETURN``, ``NOP`` + or a custom target. Defaults to ``NOP``. + + ``recent_update`` + Optional. Update "last-seen" timestamp. Possible values: ``True`` or + ``False``. Defaults to ``False``. Mutually exclusive with + ``item.recent_remove``. + + ``reject_with`` + Optional. Define reject message being sent when the rule ``item.target`` + is set to ``REJECT``. Defaults to ``icmp-admin-prohibited``. + + ``state`` + Optional. Connection state which should be matched. Possible values: + ``INVALID``, ``ESTABLISHED``, ``NEW``, ``RELATED``, ``UNTRACKED`` or + comma-separated combination thereof. + + ``subchain`` + Optional. ? + + When using the ``recent`` template make sure to always define two rules. + One for matching the packet against the address list using the + ``item.recent_update`` feature. If this filter matches you likely want + to set the ``item.recent_target`` to ``DROP`` or ``REJECT``. To clear + the source address from the list again in case the connection restrictions + are not met, add a second role using ``item.recent_remove``. + + This template is used in the default role `ferm__rules_filter_recent_badguys`_ + which will block IP addresses which are doing excessive connection attempts. + +.. _iptables recent: http://ipset.netfilter.org/iptables-extensions.man.html#lbBW +.. _ferm__rules_filter_recent_badguys: defaults.html#envvar-ferm__rules_filter_recent_badguys + +* ``reject``: Template to reject all traffic. + +.. _legacy_rules: + +Legacy rules +------------ + +Legacy rules are the (old) deprecated way to configure firewall rules +using a simpler less flexible syntax than described above. As support +for these is likely going to be removed in the future, they shouldn't be +used anymore. + +Support for legacy rules is still enabled by default. However, they are +stored in a separate ``iptables`` INPUT chain called +``debops-legacy-input-rules``. In case you haven't defined any legacy +rules and none of the DebOps roles you are using are still depending +on it, disable support completely by setting ``ferm__include_legacy: False`` +which will avoid the additional chain from being created. + +If you're not sure if you still have legacy rules defined, look for +variable names with only on '_' after the ``ferm`` prefix (e.g. +`ferm_input_list`_ and `ferm_input_dependent_list`_. + +.. _ferm_input_list: defaults.html#envvar-ferm_input_list +.. _ferm_input_dependent_list: defaults.html#envvar-ferm_input_dependent_list From 9b98909464e3eed3a11718c7a1298e95ad42f2a0 Mon Sep 17 00:00:00 2001 From: Reto Gantenbein Date: Mon, 25 Apr 2016 00:04:46 +0200 Subject: [PATCH 2/8] fix variable references --- docs/rules.rst | 70 +++++++++++++++++--------------------------------- 1 file changed, 23 insertions(+), 47 deletions(-) diff --git a/docs/rules.rst b/docs/rules.rst index c07eca9..18526b6 100644 --- a/docs/rules.rst +++ b/docs/rules.rst @@ -20,13 +20,12 @@ Default rules By default ``debops.ferm`` configures a number of rules as soon as a host is part of the ``[debops_all_hosts]`` Ansible host group. In case a firewall is not required or preferred this behaviour can be disabled -by setting ``ferm__enabled: no`` in the inventory. The rules created +by setting ``ferm__enabled: False`` in the inventory. The rules created by default are defined in ``defaults/main.yml`` and activated by being -listed in `ferm__default_rules`_. They consist of basic rules for +listed in :ref:`ferm__default_rules`. They consist of basic rules for setting the ``iptables`` default policies, restricting extensive connection attempts, logging and more. -.. _ferm__default_rules: defaults.html#envvar-ferm__default_rules .. _custom_rules: @@ -34,14 +33,14 @@ Custom rules ------------ A custom rule can be enabled by adding a rule definition to one of the -pre-defined rule lists (`ferm__rules`_, `ferm__group_rules`_, -`ferm__host_rules`_ or `ferm__dependent_rules`_) in the Ansible +pre-defined rule lists (:ref:`ferm__rules`, :ref:`ferm__group_rules`, +:ref:`ferm__host_rules` or :ref:`ferm__dependent_rules`) in the Ansible inventory. Each rule has to be defined as a YAML dict using some of the following keys: ``type`` Type of the rule template used for creating the corresponding ferm - configuration, required. See `rule_templates`_ for a description of + configuration, required. See `Rule templates`_ for a description of the available rule templates. ``chain`` @@ -57,7 +56,7 @@ the following keys: ``domain`` Optional. ``iptables`` domain used for the firewall rule. Possible values: - ``ip``, ``ip6``. Defaults to `ferm__domains`_. + ``ip``, ``ip6``. Defaults to :ref:`ferm__domains`. ``table`` Optional. ``iptables`` table to which the rule is added or from which it @@ -83,19 +82,13 @@ the following keys: ``weight_class`` Optional. Helps to manage order of firewall rules. The ``item.weight_class`` - will be checked in the `ferm__weight_map`_ dictionary. If a corresponding + will be checked in the :ref:`ferm__weight_map` dictionary. If a corresponding entry is found, its weight will be used for that rule, if not, the ``item.weight`` specified in the rule will be used instead. ``when`` Optional. Define condition for the rule to be enabled. -.. _ferm__rules: defaults.html#envvar-ferm__rules -.. _ferm__group_rules: defaults.html#envvar-ferm__group_rules -.. _ferm__host_rules: defaults.html#envvar-ferm__host_rules -.. _ferm__dependent_rules: defaults.html#envvar-ferm__dependent-rules -.. _ferm__domains: defaults.html#envvar-ferm__domains -.. _ferm__weight_map: defaults.html#envvar-ferm__weight_map .. _rule_templates: @@ -108,7 +101,7 @@ Rule templates There exist a number of predefined rule templates for generating firewall rules through ferm. Each rule definition is referencing the used template -through its ``type`` key. The templates are located in the +through its ``item.type`` key. The templates are located in the ``templates/etc/ferm/ferm.d/`` directory. Following a list of the available rule templates which can be used to @@ -273,11 +266,10 @@ create custom rules: ``DROP``, ``REJECT``, ``RETURN``, ``NOP`` or a custom target. Defaults to ``ACCEPT``. - This template is used in the default rule `ferm__rules_filter_ansible_controller`_ + This template is used in the default rule :ref:`ferm__rules_filter_ansible_controller` which enables SSH connections from the Ansible controller host. .. _iptables multiport: http://ipset.netfilter.org/iptables-extensions.man.html#lbBM -.. _ferm__rules_filter_ansible_controller: defaults.html#envvar-ferm__rules_filter_ansible_controller * ``connection_tracking``: Template to enable connection tracking using the `iptables conntrack`_ or `iptables state`_ extension. The following @@ -311,13 +303,12 @@ create custom rules: Optional. List of network interfaces for outgoing packets which are excluded from the rule. - This template is used in the default rule `ferm__rules_filter_conntrack`_ + This template is used in the default rule :ref:`ferm__rules_filter_conntrack` which enables connection tracking in the ``INPUT``, ``OUTPUT`` and ``FORWARD`` chain. .. _iptables conntrack: http://ipset.netfilter.org/iptables-extensions.man.html#lbAO .. _iptables state: http://ipset.netfilter.org/iptables-extensions.man.html#lbCC -.. _ferm__rules_filter_conntrack: defaults.html#envvar-ferm__rules_filter_conntrack * ``custom``: Template to define custom ferm rules. The following additional YAML keys are supported: @@ -338,19 +329,14 @@ create custom rules: ``policy`` ``iptables`` chain policy, required. - This template is used in the default rule `ferm__rules_default_policy`_ + This template is used in the default rule :ref:`ferm__rules_default_policy` which sets the ``INPUT``, ``FORWARD`` and ``OUTPUT`` chain policies - according to `ferm__default_policy_input`_, `ferm__default_policy_forward`_ - and `ferm__default_policy_output`_. + according to :ref:`ferm__default_policy_input`, :ref:`ferm__default_policy_forward` + and :ref:`ferm__default_policy_output`. -.. _ferm__rules_default_policy: defaults.html#envvar-ferm__rules_default_policy -.. _ferm__default_policy_input: defaults.html#envvar-ferm__default_policy_input -.. _ferm__default_policy_forward: defaults.html#envvar-ferm__default_policy_forward -.. _ferm__default_policy_output: defaults.html#envvar-ferm__default_policy_output - -* ``dmz``: Template to enable connection forwarding to another host. If ``port`` - is not specified, all traffic is forwarded. The following template-specific - YAML keys are supported: +* ``dmz``: Template to enable connection forwarding to another host. If + ``item.port`` is not specified, all traffic is forwarded. The following + template-specific YAML keys are supported: ``multiport`` Optional. Use `iptables multiport`_ extension. Possible values: @@ -377,9 +363,7 @@ create custom rules: service is defining its own ``iptables`` chains the template will make sure that they are properly refreshed if the ``ferm`` configuration changes. - This template is used in the default rule `ferm__rules_fail2ban`_. - -.. _ferm__rules_fail2ban: defaults.html#envvar-ferm__rules_fail2ban + This template is used in the default rule :ref:`ferm__rules_fail2ban`. * ``hashlimit``: Template to define rate limit rules using the `iptables hashlimit`_ extension. The following template-specific YAML @@ -443,13 +427,11 @@ create custom rules: Optional. ``iptables`` jump target in case the rate limit is reached. Defaults to ``REJECT``. - This template is used in the default rules `ferm__rules_filter_icmp`_ and - `ferm__rules_filter_syn`_ which limits the packet rate for ICMP packets + This template is used in the default rules :ref:`ferm__rules_filter_icmp` and + :ref:`ferm__rules_filter_syn` which limits the packet rate for ICMP packets and new connection attempts. .. _iptables hashlimit: http://ipset.netfilter.org/iptables-extensions.man.html#lbAY -.. _ferm__rules_filter_icmp: defaults.html#envvar-ferm__rules_filter_icmp -.. _ferm__rules_filter_syn: defaults.html#envvar-ferm__rules_filter_syn * ``include``: Template to include custom ferm configuration files. The following template-specific YAML keys are supported: @@ -465,7 +447,7 @@ create custom rules: ``log_burst`` Optional. Burst limit of packets being logged. Defaults to - `ferm__log_burst`_. + :ref:`ferm__log_burst`. ``log_ip_options`` Optional. Log IP options of packet. Possible values: ``True`` or @@ -478,7 +460,7 @@ create custom rules: ``log_limit`` Optional. Rate limit of packets being logged. Defaults to - `ferm__log_limit`_. + :ref:`ferm__log_limit`. ``log_prefix`` Optional. Prefix (up to 29 characters) for firewall log messages. @@ -507,8 +489,6 @@ create custom rules: Optional. ? .. _iptables log: http://ipset.netfilter.org/iptables-extensions.man.html#lbDD -.. _ferm__log_burst: defaults.html#envvar-ferm__log_burst -.. _ferm__log_limit: defaults.html#envvar-ferm__log_limit * ``recent``: Template to track connections and respond accordingly by using the `iptables recent`_ extension. The following template-specific YAML keys @@ -589,11 +569,10 @@ create custom rules: the source address from the list again in case the connection restrictions are not met, add a second role using ``item.recent_remove``. - This template is used in the default role `ferm__rules_filter_recent_badguys`_ + This template is used in the default role :ref:`ferm__rules_filter_recent_badguys` which will block IP addresses which are doing excessive connection attempts. .. _iptables recent: http://ipset.netfilter.org/iptables-extensions.man.html#lbBW -.. _ferm__rules_filter_recent_badguys: defaults.html#envvar-ferm__rules_filter_recent_badguys * ``reject``: Template to reject all traffic. @@ -616,7 +595,4 @@ which will avoid the additional chain from being created. If you're not sure if you still have legacy rules defined, look for variable names with only on '_' after the ``ferm`` prefix (e.g. -`ferm_input_list`_ and `ferm_input_dependent_list`_. - -.. _ferm_input_list: defaults.html#envvar-ferm_input_list -.. _ferm_input_dependent_list: defaults.html#envvar-ferm_input_dependent_list +:ref:`ferm_input_list` and :ref:`ferm_input_dependent_list`. From 302c8e939c71bdfc56638e23d9cfa4dee010f412 Mon Sep 17 00:00:00 2001 From: Reto Gantenbein Date: Mon, 25 Apr 2016 07:18:48 +0200 Subject: [PATCH 3/8] Update key descriptions according to feedback --- docs/rules.rst | 59 +++++++++++++++++++++++++++++++++++--------------- 1 file changed, 42 insertions(+), 17 deletions(-) diff --git a/docs/rules.rst b/docs/rules.rst index 18526b6..7ba1eb3 100644 --- a/docs/rules.rst +++ b/docs/rules.rst @@ -112,7 +112,11 @@ create custom rules: a different chain. The following template-specific YAML keys are supported: ``accept_any`` - Optional. ? + Optional. Match all source addresses by default. Possible values: + ``True`` or ``False``. Defaults to ``True``. If this option is + disabled and ``item.target`` is set to ``REJECT`` all traffic is + blocked by default. As soon as ``item.saddr`` is not empty, this + configuration doesn't matter anymore. ``daddr`` Optional. List of destination IP addresses or networks to which the @@ -126,7 +130,8 @@ create custom rules: ``False``. Defaults to ``True``. ``include`` - Optional. Custom ferm configuration file to include. + Optional. Custom ferm configuration file to include. See + `ferm include`_ for more details. ``interface`` Optional. List of network interfaces for incoming packets to which @@ -161,7 +166,8 @@ create custom rules: to unset. ``realgoto`` - Optional. ? + Optional. After packet match jump to custom chain. See `ferm realgoto`_ + for more details. ``reject_with`` Optional. Define reject message being sent when the rule ``item.target`` @@ -172,7 +178,7 @@ create custom rules: applied. ``sport`` - Optional. List fo source ports to which the rule is applied. + Optional. List of source ports to which the rule is applied. ``state`` Optional. Connection state which should be matched. Possible values: @@ -180,7 +186,9 @@ create custom rules: comma-separated combination thereof. ``subchain`` - Optional. ? + Optional. Subchain name. If more than 3 addresses are listed in + ``target.saddr`` move resulting ``iptables`` rules into a separate + subchain with the given name. See `ferm subchain`_ for more details. ``target`` Optional. ``iptables`` jump target. Possible values: ``ACCEPT``, @@ -190,6 +198,10 @@ create custom rules: ``when`` Optional. Define condition for the rule to be disabled. +.. _ferm include: http://ferm.foo-projects.org/download/2.1/ferm.html#includes +.. _ferm realgoto: http://ferm.foo-projects.org/download/2.1/ferm.html#realgoto_custom_chain_name +.. _ferm subchain: http://ferm.foo-projects.org/download/2.1/ferm.html#_subchain + * ``ansible_controller``: Similar to the ``accept`` template but defaults to the SSH target port and sets the source address to the host running Ansible if not overwritten through the ``ansible_controllers`` key. @@ -212,7 +224,8 @@ create custom rules: ``False``. Defaults to ``True``. ``include`` - Optional. Custom ferm configuration file to include. + Optional. Custom ferm configuration file to include. See + `ferm include`_ for more details. ``interface`` Optional. List of network interfaces for incoming packets to which @@ -240,7 +253,8 @@ create custom rules: to unset. ``realgoto`` - Optional. ? + Optional. After packet match jump to custom chain. See `ferm realgoto`_ + for more details. ``reject_with`` Optional. Define reject message being sent when the rule ``item.target`` @@ -251,7 +265,7 @@ create custom rules: applied. ``sport`` - Optional. List fo source ports to which the rule is applied. + Optional. List of source ports to which the rule is applied. ``state`` Optional. Connection state which should be matched. Possible values: @@ -259,7 +273,9 @@ create custom rules: comma-separated combination thereof. ``subchain`` - Optional. ? + Optional. Subchain name. If more than 3 addresses are listed in + ``target.saddr`` move resulting ``iptables`` rules into a separate + subchain with the given name. See `ferm subchain`_ for more details. ``target`` Optional. ``iptables`` jump target. Possible values: ``ACCEPT``, @@ -393,7 +409,8 @@ create custom rules: or a comma-separated list thereof. Defaults to ``srcip``. ``include`` - Optional. Custom ferm configuration file to include. + Optional. Custom ferm configuration file to include. See + `ferm include`_ for more details. ``log`` Optional. Write rate limit hits to syslog. Possible values: ``True`` @@ -421,7 +438,9 @@ create custom rules: comma-separated combination thereof. ``subchain`` - Optional. ? + Optional. Subchain name. Move resulting ``iptables`` rules into a + separate subchain with the given name. See `ferm subchain`_ for more + details. ``target`` Optional. ``iptables`` jump target in case the rate limit is reached. @@ -437,13 +456,15 @@ create custom rules: following template-specific YAML keys are supported: ``include`` - Required. Custom ferm configuration file to include. + Optional. Custom ferm configuration file to include. See + `ferm include`_ for more details. * ``log``: Template to specify logging rules using the `iptables log`_ extension. The following template-specific YAML keys are supported: ``include`` - Optional. Custom ferm configuration file to include. + Optional. Custom ferm configuration file to include. See + `ferm include`_ for more details. ``log_burst`` Optional. Burst limit of packets being logged. Defaults to @@ -479,14 +500,15 @@ create custom rules: ``False``. Defaults to ``False``. ``realgoto`` - Optional. ? + Optional. After packet match jump to custom chain. See `ferm realgoto`_ + for more details. ``reject_with`` Optional. Define reject message being sent when the rule ``item.target`` is set to ``REJECT``. Defaults to ``icmp-admin-prohibited``. ``target`` - Optional. ? + Optional. ``iptables`` jump target for logged packets. .. _iptables log: http://ipset.netfilter.org/iptables-extensions.man.html#lbDD @@ -498,7 +520,8 @@ create custom rules: Optional. List of destination ports to which the rule is applied. ``include`` - Optional. Custom ferm configuration file to include. + Optional. Custom ferm configuration file to include. See + `ferm include`_ for more details. ``multiport`` Optional. Use `iptables multiport`_ extension. Possible values: @@ -560,7 +583,9 @@ create custom rules: comma-separated combination thereof. ``subchain`` - Optional. ? + Optional. Subchain name. Move resulting ``iptables`` rules into a + separate subchain with the name given. See `ferm subchain`_ for more + details. When using the ``recent`` template make sure to always define two rules. One for matching the packet against the address list using the From edf47ac5206aaf3715a2d6b7a30007c877e18c76 Mon Sep 17 00:00:00 2001 From: Reto Gantenbein Date: Thu, 28 Apr 2016 00:03:35 +0200 Subject: [PATCH 4/8] add proper subsections which can be referenced --- docs/rules.rst | 817 ++++++++++++++++++++++++++----------------------- 1 file changed, 442 insertions(+), 375 deletions(-) diff --git a/docs/rules.rst b/docs/rules.rst index 7ba1eb3..dd5135f 100644 --- a/docs/rules.rst +++ b/docs/rules.rst @@ -1,5 +1,5 @@ -Firewall Rules Configuration -============================ +Firewall Rule Definition +======================== Firewall configuration in ``debops.ferm`` is done through a flexible definition of rules. There are a number of variables which are used to @@ -10,7 +10,7 @@ requirements. .. contents:: :local: - :depth: 1 + :depth: 2 .. _default_rules: @@ -18,13 +18,14 @@ Default rules ------------- By default ``debops.ferm`` configures a number of rules as soon as a -host is part of the ``[debops_all_hosts]`` Ansible host group. In case -a firewall is not required or preferred this behaviour can be disabled -by setting ``ferm__enabled: False`` in the inventory. The rules created -by default are defined in ``defaults/main.yml`` and activated by being -listed in :ref:`ferm__default_rules`. They consist of basic rules for -setting the ``iptables`` default policies, restricting extensive -connection attempts, logging and more. +host is part of the ``[debops_all_hosts]`` Ansible host group. The rules +created by default are defined in ``defaults/main.yml`` and activated by +being listed in :ref:`ferm__default_rules`. They consist of basic rules for +setting the ``iptables`` default policies, restricting extensive connection +attempts, logging and more. + +In case a firewall is not required or preferred this behaviour can be +disabled by setting ``ferm__enabled: False`` in the inventory. .. _custom_rules: @@ -89,517 +90,583 @@ the following keys: ``when`` Optional. Define condition for the rule to be enabled. - -.. _rule_templates: - Depending on the choosen type, many additional variables are supported. Please check the individual template description below. +.. _rule_templates: + Rule templates -------------- There exist a number of predefined rule templates for generating firewall rules through ferm. Each rule definition is referencing the used template through its ``item.type`` key. The templates are located in the -``templates/etc/ferm/ferm.d/`` directory. +:file:`templates/etc/ferm/ferm.d/` directory. Following a list of the available rule templates which can be used to -create custom rules: +create custom rules. -* ``accept``: Template to create rules that match interfaces, ports, remote - IP addresses/subnets and can accept the packets, reject, or redirect to - a different chain. The following template-specific YAML keys are supported: - ``accept_any`` - Optional. Match all source addresses by default. Possible values: - ``True`` or ``False``. Defaults to ``True``. If this option is - disabled and ``item.target`` is set to ``REJECT`` all traffic is - blocked by default. As soon as ``item.saddr`` is not empty, this - configuration doesn't matter anymore. +.. _accept_template: - ``daddr`` - Optional. List of destination IP addresses or networks to which the - rule is applied. +accept +^^^^^^ - ``dport`` - Optional. List of destination ports to which the rule is applied. +Template to create rules that match interfaces, ports, remote IP +addresses/subnets and can accept the packets, reject, or redirect to a +different chain. The following template-specific YAML keys are supported: - ``enabled`` - Optional. Enable rule definition. Possible values: ``True`` or - ``False``. Defaults to ``True``. +``accept_any`` + Optional. Match all source addresses by default. Possible values: ``True`` + or ``False``. Defaults to ``True``. If this option is set to ``False`` and + ``item.target`` is set to ``REJECT`` all traffic is blocked by default. + As soon as ``item.saddr`` is not empty, this configuration doesn't matter + anymore. - ``include`` - Optional. Custom ferm configuration file to include. See - `ferm include`_ for more details. +``daddr`` + Optional. List of destination IP addresses or networks to which the + rule is applied. - ``interface`` - Optional. List of network interfaces for incoming packets to which - the rule is applied. +``dport`` + Optional. List of destination ports to which the rule is applied. - ``interface_present`` - Optional. Same as ``item.interface`` but first check if specified - network interfaces exists before adding the firewall rules. +``enabled`` + Optional. Enable rule definition. Possible values: ``True`` or ``False``. + Defaults to ``True``. - ``multiport`` - Optional. Use ``iptables multiport`` extension. Possible values: - ``True`` or ``False``. Defaults to ``False``. +``include`` + Optional. Custom ferm configuration file to include. See `ferm include`_ + for more details. - ``name`` - Optional. Set rule name in places where it is referenced. +``interface`` + Optional. List of network interfaces for incoming packets to which the + rule is applied. - ``outerface`` - Optional. List of network interfaces for outgoing packets to which - the rule is applied. +``interface_present`` + Optional. Same as ``item.interface`` but first check if specified network + interfaces exists before adding the firewall rules. - ``outerface_present`` - Optional. Same as ``item.outerface`` but first check if specified - network interface exists before adding the firewall rule. +``multiport`` + Optional. Use ``iptables multiport`` extension. Possible values: ``True`` + or ``False``. Defaults to ``False``. - ``protocol`` - Optional. Network protocol to which the rule is applied. +``name`` + Optional. Set rule name in places where it is referenced. - ``protocol_syn`` - Optional. Match TCP packet with only the SYN flag set. Possible - values ``True`` or ``False``. If set to ``False`` it will match all - other packets except the ones with only the SYN flag set. Defaults - to unset. +``outerface`` + Optional. List of network interfaces for outgoing packets to which the + rule is applied. - ``realgoto`` - Optional. After packet match jump to custom chain. See `ferm realgoto`_ - for more details. +``outerface_present`` + Optional. Same as ``item.outerface`` but first check if specified network + interface exists before adding the firewall rule. - ``reject_with`` - Optional. Define reject message being sent when the rule ``item.target`` - is set to ``REJECT``. Defaults to ``icmp-admin-prohibited``. +``protocol`` + Optional. Network protocol to which the rule is applied. - ``saddr`` - Optional. List of source IP addresses or networks to which this rule is - applied. +``protocol_syn`` + Optional. Match TCP packet with only the SYN flag set. Possible values + ``True`` or ``False``. If set to ``False`` it will match all other packets + except the ones with only the SYN flag set. Defaults to unset. - ``sport`` - Optional. List of source ports to which the rule is applied. +``realgoto`` + Optional. After packet match jump to custom chain. See `ferm realgoto`_ for + more details. - ``state`` - Optional. Connection state which should be matched. Possible values: - ``INVALID``, ``ESTABLISHED``, ``NEW``, ``RELATED``, ``UNTRACKED`` or - comma-separated combination thereof. +``reject_with`` + Optional. Define reject message being sent when the rule ``item.target``is + set to ``REJECT``. Defaults to ``icmp-admin-prohibited``. - ``subchain`` - Optional. Subchain name. If more than 3 addresses are listed in - ``target.saddr`` move resulting ``iptables`` rules into a separate - subchain with the given name. See `ferm subchain`_ for more details. +``saddr`` + Optional. List of source IP addresses or networks to which this rule is + applied. - ``target`` - Optional. ``iptables`` jump target. Possible values: ``ACCEPT``, - ``DROP``, ``REJECT``, ``RETURN``, ``NOP`` or a custom target. Defaults - to ``ACCEPT``. +``sport`` + Optional. List of source ports to which the rule is applied. - ``when`` - Optional. Define condition for the rule to be disabled. +``state`` + Optional. Connection state which should be matched. Possible values: + ``INVALID``, ``ESTABLISHED``, ``NEW``, ``RELATED``, ``UNTRACKED`` or + comma-separated combination thereof. + +``subchain`` + Optional. Subchain name. If more than 3 addresses are listed in + ``target.saddr`` move resulting ``iptables`` rules into a separate subchain + with the given name. See `ferm subchain`_ for more details. + +``target`` + Optional. ``iptables`` jump target. Possible values: ``ACCEPT``, ``DROP``, + ``REJECT``, ``RETURN``, ``NOP`` or a custom target. Defaults to ``ACCEPT``. + +``when`` + Optional. Define condition for the rule to be disabled. .. _ferm include: http://ferm.foo-projects.org/download/2.1/ferm.html#includes .. _ferm realgoto: http://ferm.foo-projects.org/download/2.1/ferm.html#realgoto_custom_chain_name .. _ferm subchain: http://ferm.foo-projects.org/download/2.1/ferm.html#_subchain -* ``ansible_controller``: Similar to the ``accept`` template but defaults - to the SSH target port and sets the source address to the host running - Ansible if not overwritten through the ``ansible_controllers`` key. - The following template-specific YAML keys are supported: - ``ansible_controllers`` - Optional. List of source IP address which are added to ``item.saddr``. - Overwrites auto-detection of the Ansible controller address. +.. _ansible_controller_template: + +ansible_controller +^^^^^^^^^^^^^^^^^^ - ``daddr`` - Optional. List of destination IP addresses or networks to which the - rule is applied. +Similar to the `accept_template`_ template but defaults to the SSH target +port and sets the source address to the host running Ansible if not +overwritten through the ``item.ansible_controllers`` key. The following +template-specific YAML keys are supported: - ``dport`` - Optional. List of destination ports to which the rule is applied. - Defaults to ``ssh``. +``ansible_controllers`` + Optional. List of source IP address which are added to ``item.saddr``. + Overwrites auto-detection of the Ansible controller address. - ``enabled`` - Optional. Enable rule definition. Possible values: ``True`` or - ``False``. Defaults to ``True``. +``daddr`` + Optional. List of destination IP addresses or networks to which the rule + is applied. - ``include`` - Optional. Custom ferm configuration file to include. See - `ferm include`_ for more details. +``dport`` + Optional. List of destination ports to which the rule is applied. Defaults + to ``ssh``. - ``interface`` - Optional. List of network interfaces for incoming packets to which - the rule is applied. +``enabled`` + Optional. Enable rule definition. Possible values: ``True`` or ``False``. + Defaults to ``True``. - ``multiport`` - Optional. Use `iptables multiport`_ extension. Possible values: - ``True`` or ``False``. Defaults to ``False``. +``include`` + Optional. Custom ferm configuration file to include. See `ferm include`_ + for more details. - ``name`` - Optional. Set rule name in places where it is referenced. +``interface`` + Optional. List of network interfaces for incoming packets to which the + rule is applied. - ``outerface`` - Optional. List of network interfaces for outgoing packets to which - the rule is applied. +``multiport`` + Optional. Use `iptables multiport`_ extension. Possible values: ``True`` + or ``False``. Defaults to ``False``. - ``protocol`` - Optional. Network protocol to which the rule is applied. Defaults to - ``tcp``. +``name`` + Optional. Set rule name in places where it is referenced. - ``protocol_syn`` - Optional. Match TCP packet with only the SYN flag set. Possible - values ``True`` or ``False``. If set to ``False`` it will match all - other packets except the ones with only the SYN flag set. Defaults - to unset. +``outerface`` + Optional. List of network interfaces for outgoing packets to which the + rule is applied. - ``realgoto`` - Optional. After packet match jump to custom chain. See `ferm realgoto`_ - for more details. +``protocol`` + Optional. Network protocol to which the rule is applied. Defaults to ``tcp``. - ``reject_with`` - Optional. Define reject message being sent when the rule ``item.target`` - is set to ``REJECT``. Defaults to ``icmp-admin-prohibited``. +``protocol_syn`` + Optional. Match TCP packet with only the SYN flag set. Possible values + ``True`` or ``False``. If set to ``False`` it will match all other packets + except the ones with only the SYN flag set. Defaults to unset. - ``saddr`` - Optional. List of source IP addresses or networks to which this rule is - applied. +``realgoto`` + Optional. After packet match jump to custom chain. See `ferm realgoto`_ for + more details. - ``sport`` - Optional. List of source ports to which the rule is applied. +``reject_with`` + Optional. Define reject message being sent when the rule ``item.target`` is + set to ``REJECT``. Defaults to ``icmp-admin-prohibited``. - ``state`` - Optional. Connection state which should be matched. Possible values: - ``INVALID``, ``ESTABLISHED``, ``NEW``, ``RELATED``, ``UNTRACKED`` or - comma-separated combination thereof. +``saddr`` + Optional. List of source IP addresses or networks to which this rule is + applied. - ``subchain`` - Optional. Subchain name. If more than 3 addresses are listed in - ``target.saddr`` move resulting ``iptables`` rules into a separate - subchain with the given name. See `ferm subchain`_ for more details. +``sport`` + Optional. List of source ports to which the rule is applied. - ``target`` - Optional. ``iptables`` jump target. Possible values: ``ACCEPT``, - ``DROP``, ``REJECT``, ``RETURN``, ``NOP`` or a custom target. Defaults - to ``ACCEPT``. +``state`` + Optional. Connection state which should be matched. Possible values: + ``INVALID``, ``ESTABLISHED``, ``NEW``, ``RELATED``, ``UNTRACKED`` or + comma-separated combination thereof. - This template is used in the default rule :ref:`ferm__rules_filter_ansible_controller` - which enables SSH connections from the Ansible controller host. +``subchain`` + Optional. Subchain name. If more than 3 addresses are listed in + ``target.saddr`` move resulting ``iptables`` rules into a separate subchain + with the given name. See `ferm subchain`_ for more details. + +``target`` + Optional. ``iptables`` jump target. Possible values: ``ACCEPT``, ``DROP``, + ``REJECT``, ``RETURN``, ``NOP`` or a custom target. Defaults to ``ACCEPT``. + +This template is used in the default rule :ref:`ferm__rules_filter_ansible_controller` +which enables SSH connections from the Ansible controller host. .. _iptables multiport: http://ipset.netfilter.org/iptables-extensions.man.html#lbBM -* ``connection_tracking``: Template to enable connection tracking using the - `iptables conntrack`_ or `iptables state`_ extension. The following - template-specific YAML keys are supported: - ``active_target`` - Optional. ``iptables`` jump target for valid connections. Defaults to - ``ACCEPT``. +.. connection_tracking_template: + +connection_tracking +^^^^^^^^^^^^^^^^^^^ - ``invalid_target`` - Optional. ``iptables`` jump target for invalid connections. Defaults to - ``DROP``. +Template to enable connection tracking using the `iptables conntrack`_ or +`iptables state`_ extension. The following template-specific YAML keys are +supported: - ``module`` - Optional. ``iptables`` module used for connection tracking. Possible - values: ``state`` or ``conntrack``. Defaults to ``conntrack``. +``active_target`` + Optional. ``iptables`` jump target for valid connections. Defaults to + ``ACCEPT``. - ``interface`` - Optional. List of network interfaces for incoming packets to which - the rule is applied. +``invalid_target`` + Optional. ``iptables`` jump target for invalid connections. Defaults to + ``DROP``. - ``outerface`` - Optional. List of network interfaces for outgoing packets to which - the rule is applied. +``module`` + Optional. ``iptables`` module used for connection tracking. Possible values: + ``state`` or ``conntrack``. Defaults to ``conntrack``. - ``interface_not`` - Optional. List of network interfaces for incoming packets which are - excluded from the rule. +``interface`` + Optional. List of network interfaces for incoming packets to which the rule + is applied. - ``outerface_not`` - Optional. List of network interfaces for outgoing packets which are - excluded from the rule. +``outerface`` + Optional. List of network interfaces for outgoing packets to which the rule + is applied. - This template is used in the default rule :ref:`ferm__rules_filter_conntrack` - which enables connection tracking in the ``INPUT``, ``OUTPUT`` and - ``FORWARD`` chain. +``interface_not`` + Optional. List of network interfaces for incoming packets which are excluded + from the rule. + +``outerface_not`` + Optional. List of network interfaces for outgoing packets which are excluded + from the rule. + +This template is used in the default rule :ref:`ferm__rules_filter_conntrack` +which enables connection tracking in the ``INPUT``, ``OUTPUT`` and ``FORWARD`` +chain. .. _iptables conntrack: http://ipset.netfilter.org/iptables-extensions.man.html#lbAO .. _iptables state: http://ipset.netfilter.org/iptables-extensions.man.html#lbCC -* ``custom``: Template to define custom ferm rules. The following additional - YAML keys are supported: - ``rule`` - ferm rule definition, required. +.. _custom_template: + +custom +^^^^^^ - ``by_role`` - Optional. Add comment to generated ferm rule definition file that - rule is defined in the given Ansible role. +Template to define custom ferm rules. The following additional YAML keys are +supported: - This template is used among others in the ``debops.libvirtd`` ferm rule - `libvirtd__ferm__dependent_rules`_. +``rule`` + ferm rule definition, required. -* ``default_policy``: Template to define ``iptables`` default policies. The - following template-specific YAML keys are supported: +``by_role`` + Optional. Add comment to generated ferm rule definition file that rule is + defined in the given Ansible role. - ``policy`` - ``iptables`` chain policy, required. +This template is used among others in the ``debops.libvirtd`` ferm rule +`libvirtd__ferm__dependent_rules`_. - This template is used in the default rule :ref:`ferm__rules_default_policy` - which sets the ``INPUT``, ``FORWARD`` and ``OUTPUT`` chain policies - according to :ref:`ferm__default_policy_input`, :ref:`ferm__default_policy_forward` - and :ref:`ferm__default_policy_output`. -* ``dmz``: Template to enable connection forwarding to another host. If - ``item.port`` is not specified, all traffic is forwarded. The following - template-specific YAML keys are supported: +.. _default_policy_template: - ``multiport`` - Optional. Use `iptables multiport`_ extension. Possible values: - ``True`` or ``False``. Defaults to ``False``. +default_policy +^^^^^^^^^^^^^^ - ``public_ip`` - IPv4 address on the public network which accepts connections, required. +Template to define ``iptables`` default policies. The following +template-specific YAML keys are supported: - ``private_ip`` - IPv4 address of the host on the internal network, required. +``policy`` + ``iptables`` chain policy, required. - ``protocol(s)`` - Optional. List of protocols to forward. Defaults to ``tcp``. +This template is used in the default rule :ref:`ferm__rules_default_policy` +which sets the ``INPUT``, ``FORWARD`` and ``OUTPUT`` chain policies according +to :ref:`ferm__default_policy_input`, :ref:`ferm__default_policy_forward` +and :ref:`ferm__default_policy_output`. + + +.. _dmz_template: + +dmz +^^^ + +Template to enable connection forwarding to another host. If ``item.port`` +is not specified, all traffic is forwarded. The following template-specific +YAML keys are supported: + +``multiport`` + Optional. Use `iptables multiport`_ extension. Possible values: ``True`` + or ``False``. Defaults to ``False``. - ``port(s)`` - Optional. List of ports to forward. +``public_ip`` + IPv4 address on the public network which accepts connections, required. - ``dport`` - Optional. Destination port to forward to. Only needs to be specified - if internal destination port is different from the original destination - port. +``private_ip`` + IPv4 address of the host on the internal network, required. -* ``fail2ban``: Template to integrate fail2ban with ``ferm``. As the fail2ban - service is defining its own ``iptables`` chains the template will make sure - that they are properly refreshed if the ``ferm`` configuration changes. +``protocol(s)`` + Optional. List of protocols to forward. Defaults to ``tcp``. - This template is used in the default rule :ref:`ferm__rules_fail2ban`. +``port(s)`` + Optional. List of ports to forward. -* ``hashlimit``: Template to define rate limit rules using the - `iptables hashlimit`_ extension. The following template-specific YAML - keys are supported: +``dport`` + Optional. Destination port to forward to. Only needs to be specified if + internal destination port is different from the original destination port. - ``dport`` - Optional. List of destination ports to which the rule is applied. - ``enabled`` - Optional. Enable rule definition. Possible values: ``True`` and - ``False``. Defaults to ``True``. +.. _fail2ban_template: - ``hashlimit_burst`` - Optional. Number of packets to match within the expiration time. - Defaults to ``5``. +fail2ban +^^^^^^^^ - ``hashlimit_expire`` - Optional. Expiration time of hash entries in seconds. Defaults to - ``1.8``. +Template to integrate fail2ban with ``ferm``. As the fail2ban service is +defining its own ``iptables`` chains the template will make sure that they +are properly refreshed if the ``ferm`` configuration changes. - ``hashlimit_target`` - Optional. ? Defaults to ``RETURN``. +This template is used in the default rule :ref:`ferm__rules_fail2ban`. - ``hashlimit_mode`` - Optional. Options to take into consideration when associating packet - streams. Possible values: ``srcip``, ``srcport``, ``dstip``, ``dstport`` - or a comma-separated list thereof. Defaults to ``srcip``. - ``include`` - Optional. Custom ferm configuration file to include. See - `ferm include`_ for more details. +.. _hashlimit_template: - ``log`` - Optional. Write rate limit hits to syslog. Possible values: ``True`` - and ``False``. Defaults to ``True``. +hashlimit +^^^^^^^^^ - ``name`` - Optional. Set rule name in places where it is referenced. +Template to define rate limit rules using the `iptables hashlimit`_ extension. +The following template-specific YAML keys are supported: - ``protocol`` - Optional. Network protocol to which the rule is applied. +``dport`` + Optional. List of destination ports to which the rule is applied. - ``protocol_syn`` - Optional. Match TCP packet with only the SYN flag set. Possible - values ``True`` or ``False``. If set to ``False`` it will match all - other packets except the ones with only the SYN flag set. Defaults - to unset. +``enabled`` + Optional. Enable rule definition. Possible values: ``True`` and ``False``. + Defaults to ``True``. - ``reject_with`` - Optional. Define reject message being sent when the rule ``item.target`` - is set to ``REJECT``. Defaults to ``icmp-admin-prohibited``. +``hashlimit_burst`` + Optional. Number of packets to match within the expiration time. Defaults + to ``5``. - ``state`` - Optional. Connection state which should be matched. Possible values: - ``INVALID``, ``ESTABLISHED``, ``NEW``, ``RELATED``, ``UNTRACKED`` or - comma-separated combination thereof. +``hashlimit_expire`` + Optional. Expiration time of hash entries in seconds. Defaults to ``1.8``. - ``subchain`` - Optional. Subchain name. Move resulting ``iptables`` rules into a - separate subchain with the given name. See `ferm subchain`_ for more - details. +``hashlimit_target`` + Optional. ? Defaults to ``RETURN``. - ``target`` - Optional. ``iptables`` jump target in case the rate limit is reached. - Defaults to ``REJECT``. +``hashlimit_mode`` + Optional. Options to take into consideration when associating packet + streams. Possible values: ``srcip``, ``srcport``, ``dstip``, ``dstport`` + or a comma-separated list thereof. Defaults to ``srcip``. - This template is used in the default rules :ref:`ferm__rules_filter_icmp` and - :ref:`ferm__rules_filter_syn` which limits the packet rate for ICMP packets - and new connection attempts. +``include`` + Optional. Custom ferm configuration file to include. See `ferm include`_ for + more details. + +``log`` + Optional. Write rate limit hits to syslog. Possible values: ``True`` and + ``False``. Defaults to ``True``. + +``name`` + Optional. Set rule name in places where it is referenced. + +``protocol`` + Optional. Network protocol to which the rule is applied. + +``protocol_syn`` + Optional. Match TCP packet with only the SYN flag set. Possible values + ``True`` or ``False``. If set to ``False`` it will match all other packets + except the ones with only the SYN flag set. Defaults to unset. + +``reject_with`` + Optional. Define reject message being sent when the rule ``item.target`` is + set to ``REJECT``. Defaults to ``icmp-admin-prohibited``. + +``state`` + Optional. Connection state which should be matched. Possible values: + ``INVALID``, ``ESTABLISHED``, ``NEW``, ``RELATED``, ``UNTRACKED`` or + comma-separated combination thereof. + +``subchain`` + Optional. Subchain name. Move resulting ``iptables`` rules into a + separate subchain with the given name. See `ferm subchain`_ for more + details. + +``target`` + Optional. ``iptables`` jump target in case the rate limit is reached. + Defaults to ``REJECT``. + +This template is used in the default rules :ref:`ferm__rules_filter_icmp` and +:ref:`ferm__rules_filter_syn` which limits the packet rate for ICMP packets +and new connection attempts. .. _iptables hashlimit: http://ipset.netfilter.org/iptables-extensions.man.html#lbAY -* ``include``: Template to include custom ferm configuration files. The - following template-specific YAML keys are supported: - ``include`` - Optional. Custom ferm configuration file to include. See - `ferm include`_ for more details. +.. _include_template: + +include +^^^^^^^ + +Template to include custom ferm configuration files. The following +template-specific YAML keys are supported: + +``include`` + Optional. Custom ferm configuration file to include. See + `ferm include`_ for more details. -* ``log``: Template to specify logging rules using the `iptables log`_ - extension. The following template-specific YAML keys are supported: - ``include`` - Optional. Custom ferm configuration file to include. See - `ferm include`_ for more details. +.. _log_template: - ``log_burst`` - Optional. Burst limit of packets being logged. Defaults to - :ref:`ferm__log_burst`. +log +^^^ - ``log_ip_options`` - Optional. Log IP options of packet. Possible values: ``True`` or - ``False``. Defaults to ``True``. +Template to specify logging rules using the `iptables log`_ extension. +The following template-specific YAML keys are supported: - ``log_level`` - Optional. Log level for firewall messages. Possible values are: - ``emerg``, ``alert``, ``crit``, ``error``, ``warning``, ``notice``, - ``info`` or ``debug``. Defaults to ``warning``. +``include`` + Optional. Custom ferm configuration file to include. See + `ferm include`_ for more details. - ``log_limit`` - Optional. Rate limit of packets being logged. Defaults to - :ref:`ferm__log_limit`. +``log_burst`` + Optional. Burst limit of packets being logged. Defaults to + :ref:`ferm__log_burst`. - ``log_prefix`` - Optional. Prefix (up to 29 characters) for firewall log messages. - Defaults to ``iptables-log: `` +``log_ip_options`` + Optional. Log IP options of packet. Possible values: ``True`` or ``False``. + Defaults to ``True``. - ``log_target`` - Optional. Select how ``iptables`` performs logging. Possible values: - ``LOG``, ``ULOG``, ``NFLOG``. Defaults to ``LOG``. +``log_level`` + Optional. Log level for firewall messages. Possible values are: ``emerg``, + ``alert``, ``crit``, ``error``, ``warning``, ``notice``, ``info`` or + ``debug``. Defaults to ``warning``. - ``log_tcp_options`` - Optional. Log TCP options of packet. Possible values: ``True`` or - ``False``. Defaults to ``False``. +``log_limit`` + Optional. Rate limit of packets being logged. Defaults to + :ref:`ferm__log_limit`. - ``log_tcp_sequence`` - Optional. Log TCP sequence of packet. Possible values: ``True`` or - ``False``. Defaults to ``False``. +``log_prefix`` + Optional. Prefix (up to 29 characters) for firewall log messages. Defaults + to ``iptables-log: `` - ``realgoto`` - Optional. After packet match jump to custom chain. See `ferm realgoto`_ - for more details. +``log_target`` + Optional. Select how ``iptables`` performs logging. Possible values: + ``LOG``, ``ULOG``, ``NFLOG``. Defaults to ``LOG``. - ``reject_with`` - Optional. Define reject message being sent when the rule ``item.target`` - is set to ``REJECT``. Defaults to ``icmp-admin-prohibited``. +``log_tcp_options`` + Optional. Log TCP options of packet. Possible values: ``True`` or ``False``. + Defaults to ``False``. - ``target`` - Optional. ``iptables`` jump target for logged packets. +``log_tcp_sequence`` + Optional. Log TCP sequence of packet. Possible values: ``True`` or + ``False``. Defaults to ``False``. + +``realgoto`` + Optional. After packet match jump to custom chain. See `ferm realgoto`_ for + more details. + +``reject_with`` + Optional. Define reject message being sent when the rule ``item.target`` is + set to ``REJECT``. Defaults to ``icmp-admin-prohibited``. + +``target`` + Optional. ``iptables`` jump target for logged packets. .. _iptables log: http://ipset.netfilter.org/iptables-extensions.man.html#lbDD -* ``recent``: Template to track connections and respond accordingly by using - the `iptables recent`_ extension. The following template-specific YAML keys - are supported: - ``dport`` - Optional. List of destination ports to which the rule is applied. +.. _recent_template: + +recent +^^^^^^ + +Template to track connections and respond accordingly by using the +`iptables recent`_ extension. The following template-specific YAML keys are +supported: + +``dport`` + Optional. List of destination ports to which the rule is applied. - ``include`` - Optional. Custom ferm configuration file to include. See - `ferm include`_ for more details. +``include`` + Optional. Custom ferm configuration file to include. See + `ferm include`_ for more details. - ``multiport`` - Optional. Use `iptables multiport`_ extension. Possible values: - ``True`` or ``False``. Defaults to ``False``. +``multiport`` + Optional. Use `iptables multiport`_ extension. Possible values: ``True`` + or ``False``. Defaults to ``False``. + +``name`` + Optional. Set rule name in places where it is referenced. - ``name`` - Optional. Set rule name in places where it is referenced. +``protocol`` + Optional. Network protocol to which the rule is applied. - ``protocol`` - Optional. Network protocol to which the rule is applied. +``protocol_syn`` + Optional. Match TCP packet with only the SYN flag set. Possible values + ``True`` or ``False``. If set to ``False`` it will match all other packets + except the ones with only the SYN flag set. Defaults to unset. - ``protocol_syn`` - Optional. Match TCP packet with only the SYN flag set. Possible - values ``True`` or ``False``. If set to ``False`` it will match all - other packets except the ones with only the SYN flag set. Defaults - to unset. +``recent_hitcount`` + Optional. Must be used in combination with ``item.recent_update``. Match + if address is in the list and at least the given number of packets were + received so far. - ``recent_hitcount`` - Optional. Must be used in combination with ``item.recent_update``. - Match if address is in the list and at least the given number of - packets were received so far. +``recent_log`` + Optional. Log packets hitting - ``recent_log`` - Optional. Log packets hitting +``recent_name`` + Optional. Name of the list. Defaults to ``DEFAULT``. - ``recent_name`` - Optional. Name of the list. Defaults to ``DEFAULT``. +``recent_remove`` + Optional. Remove address from the list. Possible values: ``True`` or + ``False``. Defaults to ``False``. Mutually exclusive with + ``item.recent_update``. - ``recent_remove`` - Optional. Remove address from the list. Possible values: ``True`` or - ``False``. Defaults to ``False``. Mutually exclusive with - ``item.recent_update``. +``recent_seconds`` + Optional. Must be used in combination with ``item.recent_update``. Match + if address is in the list and was last seen within the given number of + seconds. - ``recent_seconds`` - Optional. Must be used in combination with ``item.recent_update``. - Match if address is in the list and was last seen within the given - number of seconds. +``recent_set_name`` + Optional. ? - ``recent_set_name`` - Optional. ? +``recent_target`` + Optional. ``iptables`` jump target when packet has hit the recent list. + Possible values: ``ACCEPT``, ``DROP``, ``REJECT``, ``RETURN``, ``NOP`` or + a custom target. Defaults to ``NOP``. - ``recent_target`` - Optional. ``iptables`` jump target when packet has hit the recent list. - Possible values: ``ACCEPT``, ``DROP``, ``REJECT``, ``RETURN``, ``NOP`` - or a custom target. Defaults to ``NOP``. +``recent_update`` + Optional. Update "last-seen" timestamp. Possible values: ``True`` or + ``False``. Defaults to ``False``. Mutually exclusive with + ``item.recent_remove``. - ``recent_update`` - Optional. Update "last-seen" timestamp. Possible values: ``True`` or - ``False``. Defaults to ``False``. Mutually exclusive with - ``item.recent_remove``. +``reject_with`` + Optional. Define reject message being sent when the rule ``item.target`` is + set to ``REJECT``. Defaults to ``icmp-admin-prohibited``. - ``reject_with`` - Optional. Define reject message being sent when the rule ``item.target`` - is set to ``REJECT``. Defaults to ``icmp-admin-prohibited``. +``state`` + Optional. Connection state which should be matched. Possible values: + ``INVALID``, ``ESTABLISHED``, ``NEW``, ``RELATED``, ``UNTRACKED`` or + comma-separated combination thereof. - ``state`` - Optional. Connection state which should be matched. Possible values: - ``INVALID``, ``ESTABLISHED``, ``NEW``, ``RELATED``, ``UNTRACKED`` or - comma-separated combination thereof. +``subchain`` + Optional. Subchain name. Move resulting ``iptables`` rules into a + separate subchain with the name given. See `ferm subchain`_ for more + details. - ``subchain`` - Optional. Subchain name. Move resulting ``iptables`` rules into a - separate subchain with the name given. See `ferm subchain`_ for more - details. +When using the `recent_template`_ template make sure to always define two +rules: - When using the ``recent`` template make sure to always define two rules. - One for matching the packet against the address list using the +* One for matching the packet against the address list using the ``item.recent_update`` feature. If this filter matches you likely want - to set the ``item.recent_target`` to ``DROP`` or ``REJECT``. To clear - the source address from the list again in case the connection restrictions - are not met, add a second role using ``item.recent_remove``. + to set the ``item.recent_target`` to ``DROP`` or ``REJECT``. + +* To clear the source address from the list again in case the connection + restrictions are not met, add a second role using ``item.recent_remove``. - This template is used in the default role :ref:`ferm__rules_filter_recent_badguys` - which will block IP addresses which are doing excessive connection attempts. +This template is used in the default role :ref:`ferm__rules_filter_recent_badguys` +which will block IP addresses which are doing excessive connection attempts. .. _iptables recent: http://ipset.netfilter.org/iptables-extensions.man.html#lbBW -* ``reject``: Template to reject all traffic. + +.. _reject_template: + +reject +^^^^^^ + +Template to reject all traffic. It can be added for example as a final rule +in a custom chain. + .. _legacy_rules: @@ -615,9 +682,9 @@ Support for legacy rules is still enabled by default. However, they are stored in a separate ``iptables`` INPUT chain called ``debops-legacy-input-rules``. In case you haven't defined any legacy rules and none of the DebOps roles you are using are still depending -on it, disable support completely by setting ``ferm__include_legacy: False`` +on it, disable support completely by setting :envvar:`ferm__include_legacy: False` which will avoid the additional chain from being created. If you're not sure if you still have legacy rules defined, look for variable names with only on '_' after the ``ferm`` prefix (e.g. -:ref:`ferm_input_list` and :ref:`ferm_input_dependent_list`. +:ref:`ferm_input_list` and :ref:`ferm_input_dependent_list`). From 2d13616f923c10c0631b8dc185f2827a9a248dd9 Mon Sep 17 00:00:00 2001 From: Reto Gantenbein Date: Thu, 28 Apr 2016 00:22:36 +0200 Subject: [PATCH 5/8] fix default variable references --- docs/rules.rst | 52 ++++++++++++++++++++++++++------------------------ 1 file changed, 27 insertions(+), 25 deletions(-) diff --git a/docs/rules.rst b/docs/rules.rst index dd5135f..3ff911c 100644 --- a/docs/rules.rst +++ b/docs/rules.rst @@ -19,13 +19,13 @@ Default rules By default ``debops.ferm`` configures a number of rules as soon as a host is part of the ``[debops_all_hosts]`` Ansible host group. The rules -created by default are defined in ``defaults/main.yml`` and activated by -being listed in :ref:`ferm__default_rules`. They consist of basic rules for +created by default are defined in :file:`defaults/main.yml` and activated by +being listed in :envvar:`ferm__default_rules`. They consist of basic rules for setting the ``iptables`` default policies, restricting extensive connection attempts, logging and more. In case a firewall is not required or preferred this behaviour can be -disabled by setting ``ferm__enabled: False`` in the inventory. +disabled by setting :envvar:`ferm__enabled` to ``False`` in the inventory. .. _custom_rules: @@ -34,8 +34,8 @@ Custom rules ------------ A custom rule can be enabled by adding a rule definition to one of the -pre-defined rule lists (:ref:`ferm__rules`, :ref:`ferm__group_rules`, -:ref:`ferm__host_rules` or :ref:`ferm__dependent_rules`) in the Ansible +pre-defined rule lists (:envvar:`ferm__rules`, :envvar:`ferm__group_rules`, +:envvar:`ferm__host_rules` or :envvar:`ferm__dependent_rules`) in the Ansible inventory. Each rule has to be defined as a YAML dict using some of the following keys: @@ -57,7 +57,7 @@ the following keys: ``domain`` Optional. ``iptables`` domain used for the firewall rule. Possible values: - ``ip``, ``ip6``. Defaults to :ref:`ferm__domains`. + ``ip``, ``ip6``. Defaults to :envvar:`ferm__domains`. ``table`` Optional. ``iptables`` table to which the rule is added or from which it @@ -71,7 +71,7 @@ the following keys: Optional. Custom name used in the generated ferm rule definition file. ``role_weight`` - Optional. This allows to set the same ``weight`` for all rules of a + Optional. This allows to set the same ``item.weight`` for all rules of a particular Ansible role. ``rule_state`` @@ -83,7 +83,7 @@ the following keys: ``weight_class`` Optional. Helps to manage order of firewall rules. The ``item.weight_class`` - will be checked in the :ref:`ferm__weight_map` dictionary. If a corresponding + will be checked in the :envvar:`ferm__weight_map` dictionary. If a corresponding entry is found, its weight will be used for that rule, if not, the ``item.weight`` specified in the rule will be used instead. @@ -175,7 +175,7 @@ different chain. The following template-specific YAML keys are supported: more details. ``reject_with`` - Optional. Define reject message being sent when the rule ``item.target``is + Optional. Define reject message being sent when the rule ``item.target`` is set to ``REJECT``. Defaults to ``icmp-admin-prohibited``. ``saddr`` @@ -289,7 +289,7 @@ template-specific YAML keys are supported: Optional. ``iptables`` jump target. Possible values: ``ACCEPT``, ``DROP``, ``REJECT``, ``RETURN``, ``NOP`` or a custom target. Defaults to ``ACCEPT``. -This template is used in the default rule :ref:`ferm__rules_filter_ansible_controller` +This template is used in the default rule :envvar:`ferm__rules_filter_ansible_controller` which enables SSH connections from the Ansible controller host. .. _iptables multiport: http://ipset.netfilter.org/iptables-extensions.man.html#lbBM @@ -332,7 +332,7 @@ supported: Optional. List of network interfaces for outgoing packets which are excluded from the rule. -This template is used in the default rule :ref:`ferm__rules_filter_conntrack` +This template is used in the default rule :envvar:`ferm__rules_filter_conntrack` which enables connection tracking in the ``INPUT``, ``OUTPUT`` and ``FORWARD`` chain. @@ -355,8 +355,10 @@ supported: Optional. Add comment to generated ferm rule definition file that rule is defined in the given Ansible role. -This template is used among others in the ``debops.libvirtd`` ferm rule -`libvirtd__ferm__dependent_rules`_. +This template is used among others in the `debops.libvirtd`_ ferm rule +:envvar:`libvirtd__ferm__dependent_rules`. + +.. _debops.libvirtd: http://docs.debops.org/en/latest/ansible/roles/ansible-libvirtd/docs/ .. _default_policy_template: @@ -370,10 +372,10 @@ template-specific YAML keys are supported: ``policy`` ``iptables`` chain policy, required. -This template is used in the default rule :ref:`ferm__rules_default_policy` +This template is used in the default rule :envvar:`ferm__rules_default_policy` which sets the ``INPUT``, ``FORWARD`` and ``OUTPUT`` chain policies according -to :ref:`ferm__default_policy_input`, :ref:`ferm__default_policy_forward` -and :ref:`ferm__default_policy_output`. +to :envvar:`ferm__default_policy_input`, :envvar:`ferm__default_policy_forward` +and :envvar:`ferm__default_policy_output`. .. _dmz_template: @@ -415,7 +417,7 @@ Template to integrate fail2ban with ``ferm``. As the fail2ban service is defining its own ``iptables`` chains the template will make sure that they are properly refreshed if the ``ferm`` configuration changes. -This template is used in the default rule :ref:`ferm__rules_fail2ban`. +This template is used in the default rule :envvar:`ferm__rules_fail2ban`. .. _hashlimit_template: @@ -485,8 +487,8 @@ The following template-specific YAML keys are supported: Optional. ``iptables`` jump target in case the rate limit is reached. Defaults to ``REJECT``. -This template is used in the default rules :ref:`ferm__rules_filter_icmp` and -:ref:`ferm__rules_filter_syn` which limits the packet rate for ICMP packets +This template is used in the default rules :envvar:`ferm__rules_filter_icmp` and +:envvar:`ferm__rules_filter_syn` which limits the packet rate for ICMP packets and new connection attempts. .. _iptables hashlimit: http://ipset.netfilter.org/iptables-extensions.man.html#lbAY @@ -519,7 +521,7 @@ The following template-specific YAML keys are supported: ``log_burst`` Optional. Burst limit of packets being logged. Defaults to - :ref:`ferm__log_burst`. + :envvar:`ferm__log_burst`. ``log_ip_options`` Optional. Log IP options of packet. Possible values: ``True`` or ``False``. @@ -532,7 +534,7 @@ The following template-specific YAML keys are supported: ``log_limit`` Optional. Rate limit of packets being logged. Defaults to - :ref:`ferm__log_limit`. + :envvar:`ferm__log_limit`. ``log_prefix`` Optional. Prefix (up to 29 characters) for firewall log messages. Defaults @@ -653,7 +655,7 @@ rules: * To clear the source address from the list again in case the connection restrictions are not met, add a second role using ``item.recent_remove``. -This template is used in the default role :ref:`ferm__rules_filter_recent_badguys` +This template is used in the default role :envvar:`ferm__rules_filter_recent_badguys` which will block IP addresses which are doing excessive connection attempts. .. _iptables recent: http://ipset.netfilter.org/iptables-extensions.man.html#lbBW @@ -682,9 +684,9 @@ Support for legacy rules is still enabled by default. However, they are stored in a separate ``iptables`` INPUT chain called ``debops-legacy-input-rules``. In case you haven't defined any legacy rules and none of the DebOps roles you are using are still depending -on it, disable support completely by setting :envvar:`ferm__include_legacy: False` -which will avoid the additional chain from being created. +on it, disable support completely by setting :envvar:`ferm__include_legacy` +to ``False`` which will avoid the additional chain from being created. If you're not sure if you still have legacy rules defined, look for variable names with only on '_' after the ``ferm`` prefix (e.g. -:ref:`ferm_input_list` and :ref:`ferm_input_dependent_list`). +:envvar:`ferm_input_list` and :envvar:`ferm_input_dependent_list`). From c28f16319a4a87ead6fde97b398c7bf53eb09008 Mon Sep 17 00:00:00 2001 From: Reto Gantenbein Date: Thu, 5 May 2016 19:19:05 +0200 Subject: [PATCH 6/8] Update some rules descriptions, fix invalid reference --- docs/rules.rst | 33 +++++++++++++++------------------ 1 file changed, 15 insertions(+), 18 deletions(-) diff --git a/docs/rules.rst b/docs/rules.rst index 3ff911c..51be34f 100644 --- a/docs/rules.rst +++ b/docs/rules.rst @@ -1,5 +1,5 @@ -Firewall Rule Definition -======================== +Firewall Rule Definitions +========================= Firewall configuration in ``debops.ferm`` is done through a flexible definition of rules. There are a number of variables which are used to @@ -67,6 +67,10 @@ the following keys: Optional. Set custom filename for ferm rule definition instead of generated one. +``name`` + Optional. Set rule name in ferm configuration file when ``item.filename`` is + not set and other places where a custom rule name might be useful. + ``role`` Optional. Custom name used in the generated ferm rule definition file. @@ -151,9 +155,6 @@ different chain. The following template-specific YAML keys are supported: Optional. Use ``iptables multiport`` extension. Possible values: ``True`` or ``False``. Defaults to ``False``. -``name`` - Optional. Set rule name in places where it is referenced. - ``outerface`` Optional. List of network interfaces for outgoing packets to which the rule is applied. @@ -245,9 +246,6 @@ template-specific YAML keys are supported: Optional. Use `iptables multiport`_ extension. Possible values: ``True`` or ``False``. Defaults to ``False``. -``name`` - Optional. Set rule name in places where it is referenced. - ``outerface`` Optional. List of network interfaces for outgoing packets to which the rule is applied. @@ -356,7 +354,7 @@ supported: defined in the given Ansible role. This template is used among others in the `debops.libvirtd`_ ferm rule -:envvar:`libvirtd__ferm__dependent_rules`. +:envvar:libvirtd__ferm__dependent_rules. .. _debops.libvirtd: http://docs.debops.org/en/latest/ansible/roles/ansible-libvirtd/docs/ @@ -443,7 +441,8 @@ The following template-specific YAML keys are supported: Optional. Expiration time of hash entries in seconds. Defaults to ``1.8``. ``hashlimit_target`` - Optional. ? Defaults to ``RETURN``. + Optional. Jump target used when packet matches the ``hashlimit`` rule which + means that the rate limit is not reached yet. Defaults to ``RETURN``. ``hashlimit_mode`` Optional. Options to take into consideration when associating packet @@ -458,9 +457,6 @@ The following template-specific YAML keys are supported: Optional. Write rate limit hits to syslog. Possible values: ``True`` and ``False``. Defaults to ``True``. -``name`` - Optional. Set rule name in places where it is referenced. - ``protocol`` Optional. Network protocol to which the rule is applied. @@ -586,9 +582,6 @@ supported: Optional. Use `iptables multiport`_ extension. Possible values: ``True`` or ``False``. Defaults to ``False``. -``name`` - Optional. Set rule name in places where it is referenced. - ``protocol`` Optional. Network protocol to which the rule is applied. @@ -603,7 +596,9 @@ supported: received so far. ``recent_log`` - Optional. Log packets hitting + Optional. Log packets matching the rule. Possible values: ``True`` or + ``False``. Defaults to :envvar:`ferm__log`. If this is set to ``True`` + :envvar:`ferm__log` must be enabled too for the packet to be logged. ``recent_name`` Optional. Name of the list. Defaults to ``DEFAULT``. @@ -619,7 +614,9 @@ supported: seconds. ``recent_set_name`` - Optional. ? + Optional. Add the source address of a matching packet to the given list. This + must correspond with ``item.recent_name`` of a second rule which would + potentially act on the packet, e.g. reject it. ``recent_target`` Optional. ``iptables`` jump target when packet has hit the recent list. From 5bf7287e47655789c7f229fada140979450f38c0 Mon Sep 17 00:00:00 2001 From: Reto Gantenbein Date: Thu, 5 May 2016 19:59:38 +0200 Subject: [PATCH 7/8] fix sphinx build error --- docs/rules.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/rules.rst b/docs/rules.rst index 51be34f..8478cd8 100644 --- a/docs/rules.rst +++ b/docs/rules.rst @@ -534,7 +534,7 @@ The following template-specific YAML keys are supported: ``log_prefix`` Optional. Prefix (up to 29 characters) for firewall log messages. Defaults - to ``iptables-log: `` + to ``iptables-log:`` ``log_target`` Optional. Select how ``iptables`` performs logging. Possible values: From cd7b51994bcf84c6292caaecf912a633c4850359 Mon Sep 17 00:00:00 2001 From: Reto Gantenbein Date: Thu, 5 May 2016 20:11:15 +0200 Subject: [PATCH 8/8] remove invalid reference to libvirtd ferm rule --- docs/rules.rst | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/rules.rst b/docs/rules.rst index 8478cd8..7936e69 100644 --- a/docs/rules.rst +++ b/docs/rules.rst @@ -353,8 +353,7 @@ supported: Optional. Add comment to generated ferm rule definition file that rule is defined in the given Ansible role. -This template is used among others in the `debops.libvirtd`_ ferm rule -:envvar:libvirtd__ferm__dependent_rules. +This template is used among others in a `debops.libvirtd`_ custom ferm rule. .. _debops.libvirtd: http://docs.debops.org/en/latest/ansible/roles/ansible-libvirtd/docs/