Features/FirewalldRichLanguage

In other languages: English (en) 中文（中国大陆） (zh-cn) [edit]

firewalld Rich Language

Summary

This feature adds a rich (high level) language to firewalld, that allows easily creating complex firewall rules without the knowledge of iptables syntax.

Owner

• Name: Thomas Woerner
• Email: twoerner@redhat.com

Current status

• Targeted release: Fedora 19
• Last updated: 2013-06-12
• Percentage of completion: 100%
• The feature is limited to milestone 1 (base): configuration with files, no cli and no D-Bus interface
• Milestone 2 (D-BUS, command line client) has been added to Fedora 19 with version 0.3.3.
• Milestone 3 (GUI) has been added to Fedora 19 with version 0.3.4 (as an update)
• Firewalld milestones for rich language and lockdown features, the milestones 1 is part of Fedora 19, milestone 2 (base and cli) will be provided as an update for F-19. Milestone 3 (gui) is planned for F-20.
  • Milestone 1: Rich config language via config files; minimal lockdown ~ end of March
  • Milestone 2: New config language via D-BUS interfaces with command line client ~ end of May
  • Milestone 3: GUI ~ mid July

Detailed Description

Currently, complex firewall rules can only be added using the direct interface of firewalld. But this requires to know the syntax of iptables and the rules are not permanent.

With the rich language more complex firewall rules can be created in an easy to understand way. The language will use keywords with values and will be an abstract representation of ip*tables rules. Zones can be configured using this language, the current configuration will still be supported.

The configuration with files will be available for Fedora 19. The D-BUS interface with the command line client should be finished, but this depends on Fedora 19 schedule. UI work will most likely be available later (depends on Fedora 19 schedule also).

Benefit to Fedora

More powerful and easier firewall configuration.

Scope

Only needs changes in firewalld and it's components.

How To Test

Create firewall rules using the rich language in services and zones. More to come.

User Experience

Users will be able to easily create more powerful and also permanent firewall configurations.

Dependencies

None.

Contingency Plan

Disabling or reverting of the feature should be easy as it will be created as an addition to the current configuration. Only users of the new language will be affected.

Documentation

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

Handle rich rules with the command line client

firewall-cmd [--zone=<zone>] --add-rich-rule='<rule>' [--timeout=<seconds>]

Add rich language rule '<rule>' for zone <zone>. This option can be specified multiple times. If zone is omitted, the default zone will be used. To get the default zone use --get-default-zone. If a timeout is supplied, the <rule>(s) will be active for the amount of seconds and will be removed automatically afterwards.

firewall-cmd [--zone=<zone>] --remove-rich-rule='<rule>'

Remove rich language rule '<rule>' for zone <zone>. This option can be specified multiple times. If zone is omitted, the default zone will be used. To get the default zone use --get-default-zone.

firewall-cmd [--zone=<zone>] --query-rich-rule='<rule>'

Return whether a rich language rule '<rule>' has been added for the zone <zone>. If zone is omitted, the default zone will be used. There is no output. Returns 0 if true, 1 otherwise.

General rich rule structure

rule [family="<rule family>"]
  [ source address="<address>" [invert="True"] ]
  [ destination address="<address>" [invert="True"] ]
  [ <element> ]
  [ log [prefix="<prefix text>"] [level="<log level>"] ]
  [ audit type="<audit type>" ]
  <action>

A rule is part of a zone. A zone can contain several rules. If some rules interact/contradict, the first rule that matches the packet "wins". 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.

Source

With the source address the origin of a connection attempt can be limited to the source address. A source address or address range is either an IP address or a network IP address with a mask for IPv4 or IPv6. The network family (IPv4/IPv6) will be automatically discovered. For IPv4, the mask can be a network mask or a plain number. For IPv6 the mask is a plain number. The use of host names is not supported. It is possible to invert the sense of an address by adding invert="true" or invert="yes". All but the used address with match.

Destination

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.

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.

The element can be exactly one of the element types service, port, protocol, masquerade, icmp-block and forward-port.

Service

service name="<service name>"

The service <service name> 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 firewall-cmd --get-services.

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.

Port

port port="<port value>" protocol="tcp|udp"

The port <value> can either be a single port number or a port range <id>-<id>. The protocol can either be "tcp" or "udp".

Protocol

protocol value="<protocol value>"

The protocol value can be either a protocol id number or a protocol name. For allowed protocol entries, please have a look at /etc/protocols.

ICMP-Block

icmp-block name="<icmptype name>"

The icmptype is the one of the icmp types firewalld supports. To get a listing of supported icmp types: firewall-cmd --get-icmptypes

It is not allowed to specify an action here. icmp-block uses the action reject internally.

Masquerade

masquerade

Turn on masquerading in the rule. A source address can be provided to limit masquerading to this area, but not a destination address.

It is not allowed to specify an action here.

Forward-Port

forward-port port="<port value>" protocol="tcp|udp" to-port="<port value>" to-addr="<address>"

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.

The port <value> can either be a single port number or a port range <id>-<id>. The destination address is a simple ip address.

It is not allowed to specify an action here. forward-port uses the action accept internally.

Log

Log new connection attempts to the rule with kernel logging for example in syslog. You can define a prefix text that will be added to the log message as a prefix. Log level can be one of "emerg", "alert", "crit", "err", "warn", "notice", "info" or "debug". The use of log is optional.

It is possible to limit logging:

log [prefix="<prefix text>"] [level="<log level>"] limit value="<rate/duration>"

The rate is a natural positive number [1, ..], the duration of of "s", "m", "h", "d". "s" means seconds, "m" minutes, "h" hours and "d" days. The maximum limit value is "1/d" which means at maximum one log entry per day.

Audit

Audit provides an alternative way for logging using audit records sent to the service auditd. The audit type can be one of "ACCEPT", "REJECT" or "DROP". The use of audit is optional.

Also audit can be limited using the limit tag.

Actions

An action can be one of accept, reject or drop.

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 (requires firewalld version 0.3.1).

accept | reject [type="<reject type>"] | drop

With accept all new connection attempts will be granted. With reject they will not be accepted and their source will get a reject message. The reject type can be set to use another value. With drop all packets will be dropped immediately and no information is sent to the source.

Information about logging and actions

Logging can be done with the LOG and also with audit. 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.

The rules or parts of them are placed in separate chains according to the action of the rule:

<zone>_log
<zone>_deny
<zone>_allow

Then all logging rules will be placed in the <zone>_log chain, which will be walked first. All reject and drop rules will be placed in the <zone>_deny chain, which will be walked after the log chain. All accept rules will be placed in the <zone>_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.

Examples

Example 1: Enable new IPv4 and IPv6 connections for protocol 'ah'

firewall-cmd --add-rich-rule='rule protocol value="ah" accept'

Example 2: Allow new IPv4 and IPv6 connections for service ftp and log 1 per minute using audit

firewall-cmd --add-rich-rule='rule service name="ftp" audit type="ACCEPT" limit value="1/m" audit accept'

Example 3: Allow new IPv4 connections from address 192.168.0.0/24 for service tftp and log 1 per minutes using syslog

firewall-cmd --add-rich-rule='rule family="ipv4" source address="192.168.0.0/24" service name="tftp" log prefix="tftp" level="info" limit value="1/m" accept'

Example 4: 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.

firewall-cmd --add-rich-rule='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'

Example 5: 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

firewall-cmd --add-rich-rule='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"'

Example 6: White-list source address to allow all connections from 192.168.2.2

firewall-cmd --add-rich-rule='rule family="ipv4" source address="192.168.2.2" accept'

Example 7: Black-list source address to reject all connections from 192.168.2.3

firewall-cmd --add-rich-rule='rule family="ipv4" source address="192.168.2.3" reject'

Example 8: Black-list source address to drop all connections from 192.168.2.4

firewall-cmd --add-rich-rule='rule family="ipv4" source address="192.168.2.4" drop'

With zone configuration file

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

General rule structure

<rule [family="<rule family>"]>
  [ <source address="<address>" [invert="True"]/> ]
  [ <destination address="<address>" [invert="True"]/> ]
  element
  [ <log [prefix="<prefix text>"] [level="<log level>"]/> ]
  [ <audit type="<audit type>"/> ]
  action
</rule>

This <rule> element is part of <zone> element in a zone configuration file. There can be more rules (<rule> elements) in one zone. If some rules interact/contradict, the first rule that matches the packet "wins". 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 addresses are used in the rule, then the rule family need to be provided. This is the case if source or destination is used and also for port/packet forwarding.

Source and destination addresses

<source address="<address>" [invert="True"]>
<destination address="<address>" [invert="True"]>

If source address is specified, the rule from element (see Elements section further down) is further restricted only to packets coming from this address. The same with destination address, i.e. if specified, it restricts the element only to packets with this destination address.

The address can be an ip address or an ip address with a mask, where mask can be either a plain number or for ipv4 also a network mask. The use of host names is not supported. The use of source and destination addresses is optional.

The use of destination addresses is not possible with all elements. This depends on the use of destination addresses for example in services.

It is also possible to invert the sense of an address by adding invert="True" or invert="yes". All but the used address with match.

Elements

The element can be exactly one of the element types service, port, protocol, masquerade, icmp-block and forward-port

Service

<service name="<service name>"/>

The service <service name> 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 firewall-cmd --get-services.

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.

Port

<port port="<port value>" protocol="tcp|udp"/>

The port <value> can either be a single port number or a port range <id>-<id>. The protocol can either be "tcp" or "udp".

Protocol

<protocol value="<protocol value>"/>

The protocol value can be either a protocol id number or a protocol name. For allowed protocol entries, please have a look at /etc/protocols.

ICMP-Block

<icmp-block name="<icmtype name>"/>

The icmptype is the one of the icmp types firewalld supports. To get a listing of supported icmp types: firewall-cmd --get-icmptypes

It is not allowed to specify an action here. icmp-block uses the action reject internally.

Masquerade

<masquerade/>

Turn on masquerading in the rule. A source address can be provided to limit masquerading to this area, but not a destination address.

It is not allowed to specify an action here.

Forward-Port

<forward-port port="<port value>" protocol="tcp|udp" to-port="<port value>" to-addr="<address>"/>

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.

The port <value> can either be a single port number or a port range <id>-<id>. The destination address is a simple ip address.

It is not allowed to specify an action here. forward-port uses the action accept internally.

Log

Log new connection attempts to the rule with kernel logging for example in syslog. You can define a prefix text that will be added to the log message as a prefix. Log level can be one of "emerg", "alert", "crit", "err", "warn", "notice", "info" or "debug". The use of log is optional.

It is also possible to limit logging:

<log [prefix="<prefix text>"] [level="<log level>"]/>
  <limit value="<rate/duration>"/>
</log>

The rate is a natural positive number [1, ..], the duration of of "s", "m", "h", "d". "s" means seconds, "m" minutes, "h" hours and "d" days. The maximum limit value is "1/d" which means at maximum one log entry per day.

Audit

Audit provides an alternative way for logging using audit records sent to the service auditd. The audit type can be one of "ACCEPT", "REJECT" or "DROP". The use of audit is optional.

Also audit can be limited using the limit tag.

Actions

An action can be one of accept, reject or drop.

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 (requires firewalld version 0.3.1).

<accept/> 
<reject [type="<reject type>"]/>
<drop>

With accept all new connection attempts will be granted. With reject they will not be accepted and there source will get a reject message. The reject type can be set to use an other value. With drop all packets will be dropped immediately, there is no information sent to the source.

Information about logging and actions

Logging can be done with the LOG and also with audit. 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.

The rules or parts of them are placed in separate chains according to the action of the rule:

 <zone>_log
 <zone>_deny
 <zone>_allow

Then all logging rules will be placed in the <zone>_log chain, which will be walked first. All reject and drop rules will be placed in the <zone>_deny chain, which will be walked after the log chain. All accept rules will be placed in the <zone>_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.

Examples

Example 1: Enable new IPv4 and IPv6 connections for protocol 'ah'

<rule>
  <protocol value="ah"/>
  <accept/>
</rule>

Example 2: Allow new IPv4 and IPv6 connections for service ftp and log 1 per minute using audit

<rule>
  <service name="ftp"/>
  <audit type="ACCEPT">
    <limit value="1/m"/>
  </audit>
  <accept/>
</rule>

Example 3: Allow new IPv4 connections from address 192.168.0.0/24 for service tftp and log 1 per minutes using syslog

<rule family="ipv4">
  <source address="192.168.0.0/24"/>
  <service name="tftp"/>
  <log prefix="tftp" level="info">
    <limit value="1/m"/>
  </log>
  <accept/>
</rule>

Example 4: 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.

<rule family="ipv6">
  <source address="1:2:3:4:6::"/>
  <service name="radius"/>
  <log prefix="dns" level="info">
    <limit value="3/m"/>
  </log>
  <reject/>
</rule>
<rule family="ipv6">
  <service name="radius"/>
  <accept/>
</rule>

Example 5: 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

<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"/>
</rule>

Example 6: White-list source address to allow all connections from this source

 <rule family="ipv4">
   <source address="192.168.2.2"/>
   <accept/>
 </rule>

Release Notes

Fedora 19 includes the latest firewalld version that supports a rich language to be able to create more complex firewalls in a easy way.

Comments and Discussion

• See Talk:Features/FirewalldRichLanguage