<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
[
<!ENTITY authors SYSTEM "authors.xml">
<!ENTITY seealso SYSTEM "seealso.xml">
<!ENTITY notes SYSTEM "notes.xml">
]>

<!--
  SPDX-License-Identifier: GPL-2.0-or-later

  This file is part of firewalld.

  Copyright (C) 2010-2013 Red Hat, Inc.

  Authors:
  Thomas Woerner <twoerner@redhat.com>
-->

<refentry id="firewalld.richlanguage">

  <refentryinfo>
    <title>firewalld.richlanguage</title>
    <productname>firewalld</productname>
    &authors;
  </refentryinfo>

  <refmeta>
    <refentrytitle>firewalld.richlanguage</refentrytitle>
    <manvolnum>5</manvolnum>
  </refmeta>

  <refnamediv>
    <refname>firewalld.richlanguage</refname>
    <refpurpose>Rich Language Documentation</refpurpose>
  </refnamediv>

  <refsect1>
    <title>Description</title>

    <para>
      With the rich language more complex firewall rules can be created in an easy to understand way. The language uses keywords with values and is an abstract representation of ip*tables rules.
    </para>

    <para>
      The rich language extends the current zone elements (service, port, icmp-block, icmp-type, masquerade, forward-port and source-port) with additional source and destination addresses, logging, actions and limits for logs and actions.
    </para>

    <para>
      This page describes the rich language used in the command line client and D-Bus interface. For information about the rich language representation used in the zone configuration files, please have a look at <citerefentry><refentrytitle>firewalld.zone</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
    </para>

    <para>
      A rule is part of a zone. One zone can contain several rules. If some rules interact/contradict, the first rule that matches "wins".
    </para>

    <para>
      <emphasis role="bold">General rule structure</emphasis>
      <programlisting>
rule
  [source]
  [destination]
  service|port|protocol|icmp-block|icmp-type|masquerade|forward-port|source-port
  [log|nflog]
  [audit]
  [accept|reject|drop|mark]
      </programlisting>
      The complete rule is provided as a single line string. A destination is allowed here as long as it does not conflict with the destination of a service.
    </para>

    <para>
      <emphasis role="bold">Rule structure for source black or white listing</emphasis>
      <programlisting>
rule
  source
  [log|nflog]
  [audit]
  accept|reject|drop|mark
      </programlisting>
      This is used to grant or limit access from a source to this machine or machines that are reachable by this machine. A destination is not allowed here.
    </para>

    <para>
      <emphasis role="bold">Important information about element options:</emphasis>
	Options for elements in a rule need to be added exactly after the element. If the option is placed somewhere else it might be used for another element as far as it matches the options of the other element or will result in a rule error.
    </para>

    <refsect2>
      <title>Rule</title>
      <para>
	  <programlisting>
rule [family="ipv4|ipv6"] [priority="priority"]
	  </programlisting>
      </para>
      <para>
      If the rule family is provided, it can be either "ipv4" or "ipv6", which limits the rule to IPv4 or IPv6. If the rule family is not provided, the rule will be added for IPv4 and IPv6. If source or destination addresses are used in a rule, then the rule family need to be provided. This is also the case for port/packet forwarding.
      </para>
      <para>
      If the rule priority is provided, it can be in the range of -32768 to 32767 where lower values have higher precedence. Rich rules are sorted by priority. Ordering for rules with the same priority value is undefined. A negative priority value will be executed before other firewalld primitives. A positive priority value will be executed after other firewalld primitives. A priority value of 0 will place the rule in a chain based on the action as per the "Information about logging and actions" below.
      </para>
    </refsect2>

    <refsect2>
      <title>Source</title>
      <para>
	  <programlisting>
source [not] address="address[/mask]"|mac="mac-address"|ipset="ipset"
	  </programlisting>
	With the source address the origin of a connection attempt can be limited to the source address.
	An address is either a single IP address, or a network IP address, a MAC address or an IPSet.
	The address has to match the rule family (IPv4/IPv6).
	Subnet mask is expressed in either dot-decimal (/x.x.x.x) or prefix (/x) notations for IPv4, and in prefix notation (/x) for IPv6 network addresses.
	It is possible to invert the sense of an address by adding <option>not</option> before <option>address</option>.
	All but the specified address will match then.
      </para>
    </refsect2>

    <refsect2>
      <title>Destination</title>
      <para>
	<programlisting>
destination [not] address="address[/mask]"|ipset="ipset"
	</programlisting>
	With the destination address the target can be limited to the destination address. The destination address is using the same syntax as the source address.
      </para>
      <para>
	The use of source and destination addresses is optional and the use of a destination addresses is not possible with all elements. This depends on the use of destination addresses for example in service entries.
      </para>
    </refsect2>

    <refsect2>
      <title>Service</title>
      <para>
	<programlisting>
service name="service name"
	</programlisting>
      </para>
      <para>
	The service <replaceable>service name</replaceable> will be added to the rule. The service name is one of the firewalld provided services. To get a list of the supported services, use <command>firewall-cmd --get-services</command>.
      </para>
      <para>
	If a service provides a destination address, it will conflict with a destination address in the rule and will result in an error. The services using destination addresses internally are mostly services using multicast.
      </para>
    </refsect2>

    <refsect2>
      <title>Port</title>
      <para>
	<programlisting>
port port="port value" protocol="tcp|udp|sctp|dccp"
	</programlisting>
      </para>
      <para>
	The port <replaceable>port value</replaceable> can either be a single port number <replaceable>portid</replaceable> or a port range <replaceable>portid</replaceable>-<replaceable>portid</replaceable>.
      The protocol can either be <literal>tcp</literal>, <literal>udp</literal>, <literal>sctp</literal> or <literal>dccp</literal>.
      </para>
    </refsect2>

    <refsect2>
      <title>Protocol</title>
      <para>
	<programlisting>
protocol value="protocol value"
	</programlisting>
      </para>
      <para>
	The protocol value can be either a protocol id number or a protocol name. For allowed protocol entries, please have a look at <filename class="directory">/etc/protocols</filename>.
      </para>
    </refsect2>

    <refsect2>
      <title>Tcp-Mss-Clamp</title>
      <para>
        <programlisting>
tcp-mss-clamp="value=pmtu|value=number >= 536|None"
        </programlisting>
      </para>
      <para>
        The tcp-mss-clamp sets the maximum segment size in the rule.
      </para>
      <para>
        The tcp-mss-clamp has an optional attribute value can be either be set to "pmtu" or a number greater than or equal to 536. If attribute
	value is not present then the maximum segment size is automatically set to "pmtu".
      </para>
    </refsect2>

    <refsect2>
      <title>ICMP-Block</title>
      <para>
	<programlisting>
icmp-block name="icmptype name"
	</programlisting>
      </para>
      <para>
	The icmptype is the one of the icmp types firewalld supports. To get a listing of supported icmp types: <command>firewall-cmd --get-icmptypes</command>
      </para>
      <para>
	It is not allowed to specify an action here. icmp-block uses the action reject internally.
      </para>
    </refsect2>

    <refsect2>
      <title>Masquerade</title>
      <para>
	<programlisting>
masquerade
	</programlisting>
      </para>
      <para>
	Turn on masquerading in the rule. A source and also a destination address can be provided to limit masquerading to this area.
      </para>
      <para>
	It is not allowed to specify an action here.
      </para>
      <para>
        <emphasis>Note:</emphasis> IP forwarding will be implicitly enabled.
      </para>
    </refsect2>

    <refsect2>
      <title>ICMP-Type</title>
      <para>
	<programlisting>
icmp-type name="icmptype name"
	</programlisting>
      </para>
      <para>
	The icmptype is the one of the icmp types firewalld supports. To get a listing of supported icmp types: <command>firewall-cmd --get-icmptypes</command>
      </para>
    </refsect2>

    <refsect2>
      <title>Forward-Port</title>
      <para>
	<programlisting>
forward-port port="port value" protocol="tcp|udp|sctp|dccp" to-port="port value" to-addr="address"
	</programlisting>
      </para>
      <para>
	Forward port/packets from local port value with protocol "tcp" or "udp" to either another port locally or to another machine or to another port on another machine.
      </para>
      <para>
	The port value can either be a single port number or a port range <replaceable>portid-portid</replaceable>. The <option>to-addr</option> is an IP address.
      The protocol can either be <literal>tcp</literal>, <literal>udp</literal>, <literal>sctp</literal> or <literal>dccp</literal>.
      </para>
      <para>
	It is not allowed to specify an action here. forward-port uses the action accept internally.
      </para>
      <para>
        <emphasis>Note:</emphasis> IP forwarding will be implicitly enabled if <option>to-addr</option> is specified.
      </para>
    </refsect2>

    <refsect2>
      <title>Source-Port</title>
      <para>
	<programlisting>
source-port port="port value" protocol="tcp|udp|sctp|dccp"
	</programlisting>
      </para>
      <para>
	The source-port <replaceable>port value</replaceable> can either be a single port number <replaceable>portid</replaceable> or a port range <replaceable>portid</replaceable>-<replaceable>portid</replaceable>.
      The protocol can either be <literal>tcp</literal>, <literal>udp</literal>, <literal>sctp</literal> or <literal>dccp</literal>.
      </para>
    </refsect2>

    <refsect2>
      <title>Log</title>
      <para>
	<programlisting>
log [prefix="prefix text"] [level="log level"] [limit value="rate/duration"]
	</programlisting>
      </para>
      <para>
	Log new connection attempts to the rule with kernel logging for example in syslog.
	You can define a prefix text with a maximum length of 127 characters that will be added to the log message as a prefix.
	Log level can be one of "<option>emerg</option>", "<option>alert</option>", "<option>crit</option>", "<option>error</option>", "<option>warning</option>", "<option>notice</option>", "<option>info</option>" or "<option>debug</option>", where default (i.e. if there's no one specified) is "<option>warning</option>". See <citerefentry><refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum></citerefentry> for description of levels.
	See Limit section for description of <option>limit</option> tag.
      </para>
      <para>
        <emphasis>Note:</emphasis> The iptables backend truncates prefix to 29 characters.
      </para>
    </refsect2>

    <refsect2>
      <title>NFLog</title>
      <para>
	<programlisting>
nflog [group="group id"] [prefix="prefix text"] [queue-size="threshold"] [limit value="rate/duration"]
	</programlisting>
      </para>
      <para>
	Log new connection attempts to the rule using kernel logging to pass the packets through a 'netlink' socket to users or applications monitoring the multicast <option>group</option>.
      The minimum and default value for <option>group</option> is 0, maximum value is 65535.
	See NETLINK_NETFILTER in <citerefentry><refentrytitle>netlink</refentrytitle><manvolnum>7</manvolnum></citerefentry> man page and NFLOG in both <citerefentry><refentrytitle>iptables-extensions</refentrytitle><manvolnum>8</manvolnum></citerefentry> and <citerefentry><refentrytitle>nft</refentrytitle><manvolnum>8</manvolnum></citerefentry> man pages for a more detailed description.
      </para>
      <para>
      You can define a prefix text with a maximum length of 127 characters that will be added to the log message as a prefix.
      The <option>queue-size</option> option can be set to increase the queue threshold which can help limit context switching.
      The default value for <option>queue-size</option> is 1, maximum value is 65535.
	See <citerefentry><refentrytitle>iptables-extensions</refentrytitle><manvolnum>8</manvolnum></citerefentry> and <citerefentry><refentrytitle>nft</refentrytitle><manvolnum>8</manvolnum></citerefentry> for more details.
      </para>
      <para>
      See Limit section for description of <option>limit</option> tag.
      </para>
      <para>
        <emphasis>Note:</emphasis> The iptables backend truncates prefix to 63 characters.
      </para>
    </refsect2>

    <refsect2>
      <title>Audit</title>
      <para>
	<programlisting>
audit [limit value="rate/duration"]
	</programlisting>
      </para>
      <para>
	Audit provides an alternative way for logging using audit records sent to the service auditd.
	Audit type will be discovered from the rule action automatically. Use of audit is optional.
	See Limit section for description of <option>limit</option> tag.
      </para>
    </refsect2>

    <refsect2>
      <title>Action</title>
      <para>
	An action can be one of <option>accept</option>, <option>reject</option>, <option>drop</option> or <option>mark</option>.
      </para>
      <para>
	The rule can either contain an element or also a source only. If the rule contains an element, then new connection matching the element will be handled with the action. If the rule does not contain an element, then everything from the source address will be handled with the action.
      </para>
      <para>
	<programlisting>
accept [limit value="rate/duration"]
	</programlisting>
      </para>
      <para>
	<programlisting>
reject [type="reject type"] [limit value="rate/duration"]
	</programlisting>
      </para>
      <para>
	<programlisting>
drop [limit value="rate/duration"]
	</programlisting>
      </para>
      <para>
	<programlisting>
mark set="mark[/mask]" [limit value="rate/duration"]
	</programlisting>
      </para>
      <para>
	With <option>accept</option> all new connection attempts will be granted.
	With <option>reject</option> they will not be accepted and their source will get a reject ICMP(v6) message.
	The reject type can be set to specify appropriate ICMP(v6) error message.
	For valid reject types see <option>--reject-with type</option> in <citerefentry><refentrytitle>iptables-extensions</refentrytitle><manvolnum>8</manvolnum></citerefentry> man page.
	Because reject types are different for IPv4 and IPv6 you have to specify rule family when using reject type.
	With <option>drop</option> all packets will be dropped immediately, there is no information sent to the source.
	With <option>mark</option> all packets will be marked in the <option>PREROUTING</option> chain in the <option>mangle</option> table with the mark and mask combination.
	See Limit section for description of <option>limit</option> tag.
      </para>
    </refsect2>

    <refsect2>
       <title>Limit</title>
      <para>
	<programlisting>
limit value="rate/duration"
	</programlisting>
      </para>
       <para>
	 It is possible to limit Log, NFLog, Audit and Action.
	 A rule using this tag will match until this limit is reached.
	 The rate is a natural positive number [1, ..]
	 The duration is of "s", "m", "h", "d". "s" means seconds, "m" minutes, "h" hours and "d" days.
	 Maximum limit value is "2/d", which means at maximum two matches per day.
       </para>
    </refsect2>

    <refsect2>
      <title>Information about logging and actions</title>
      <para>
	Logging can be done with the log, nflog and audit actions. A new chain is added to all zones: zone_log. This will be jumped into before the deny chain to be able to have a proper ordering.
      </para>
      <para>
	The rules or parts of them are placed in separate chains according to the priority and action of the rule:
      </para>
      <para>
	<programlisting>
<replaceable>zone</replaceable>_pre
<replaceable>zone</replaceable>_log
<replaceable>zone</replaceable>_deny
<replaceable>zone</replaceable>_allow
<replaceable>zone</replaceable>_post
	</programlisting>
      </para>
      <para>
        When <emphasis>priority &lt; 0</emphasis>, the rich rule will be placed in the <replaceable>zone</replaceable>_pre chain.
      </para>
      <para>
        When <emphasis>priority == 0</emphasis> Then all logging rules will be placed in the <replaceable>zone</replaceable>_log chain. All reject and drop rules will be placed in the <replaceable>zone</replaceable>_deny chain, which will be walked after the log chain. All accept rules will be placed in the <replaceable>zone</replaceable>_allow chain, which will be walked after the deny chain. If a rule contains log and also deny or allow actions, the parts are placed in the matching chains.
      </para>
      <para>
        When <emphasis>priority &gt; 0</emphasis>, the rich rule will be placed in the <replaceable>zone</replaceable>_post chain.
      </para>
    </refsect2>
  </refsect1>

  <refsect1>
    <title>Examples</title>
      <para>
	These are examples of how to specify rich language rules.
	This format (i.e. one string that specifies whole rule) uses
	for example <option>firewall-cmd --add-rich-rule</option> (see
	<citerefentry><refentrytitle>firewall-cmd</refentrytitle><manvolnum>1</manvolnum></citerefentry>)
	as well as D-Bus interface.
      </para>

    <refsect2>
      <title>Example 1</title>
      <para>
	Enable new IPv4 and IPv6 connections for protocol 'ah'
      </para>
      <para>
	<programlisting>
rule protocol value="ah" accept
	</programlisting>
      </para>
    </refsect2>

    <refsect2>
      <title>Example 2</title>
      <para>
	Allow new IPv4 and IPv6 connections for service ftp and log 1 per minute using audit
      </para>
      <para>
	<programlisting>
rule service name="ftp" log limit value="1/m" audit accept
	</programlisting>
      </para>
    </refsect2>

    <refsect2>
      <title>Example 3</title>
      <para>
	Allow new IPv4 connections from address 192.168.0.0/24 for service tftp and log 1 per minutes using syslog
      </para>
      <para>
	<programlisting>
rule family="ipv4" source address="192.168.0.0/24" service name="tftp" log prefix="tftp" level="info" limit value="1/m" accept
	</programlisting>
      </para>
    </refsect2>

    <refsect2>
      <title>Example 4</title>
      <para>
	New IPv6 connections from 1:2:3:4:6:: to service radius are all rejected and logged at a rate of 3 per minute. New IPv6 connections from other sources are accepted.
      </para>
      <para>
	<programlisting>
rule family="ipv6" source address="1:2:3:4:6::" service name="radius" log prefix="dns" level="info" limit value="3/m" reject
rule family="ipv6" service name="radius" accept
	</programlisting>
      </para>
    </refsect2>

    <refsect2>
      <title>Example 5</title>
      <para>
	Forward IPv6 port/packets receiving from 1:2:3:4:6:: on port 4011 with protocol tcp to 1::2:3:4:7 on port 4012
      </para>
      <para>
	<programlisting>
rule family="ipv6" source address="1:2:3:4:6::" forward-port to-addr="1::2:3:4:7" to-port="4012" protocol="tcp" port="4011"
	</programlisting>
      </para>
    </refsect2>

    <refsect2>
      <title>Example 6</title>
      <para>
	White-list source address to allow all connections from 192.168.2.2
      </para>
      <para>
	<programlisting>
rule family="ipv4" source address="192.168.2.2" accept
	</programlisting>
      </para>
    </refsect2>

    <refsect2>
      <title>Example 7</title>
      <para>
	Black-list source address to reject all connections from 192.168.2.3
      </para>
      <para>
	<programlisting>
rule family="ipv4" source address="192.168.2.3" reject type="icmp-admin-prohibited"
	</programlisting>
      </para>
    </refsect2>

    <refsect2>
      <title>Example 8</title>
      <para>
	Black-list source address to drop all connections from 192.168.2.4
      </para>
      <para>
	<programlisting>
rule family="ipv4" source address="192.168.2.4" drop
	</programlisting>
      </para>
    </refsect2>

  </refsect1>

  &seealso;

  &notes;

</refentry>