sailfish-connman-plugin-iptables

Connman plugin that provides D-Bus API for controlling iptables rules.

API description

The detailed API description is provided as D-Bus introspect XML file (in spec/sailfish_iptables_dbus_interface_description.xml) from which a docbook XML is generated for the docs-package (run make -C doc).

File contains descriptions for all the methods and parameters for each method.

Generating documentation HTML

A html page can be generated from the introspect XML with the script at doc/docbook_html. The script requires xsltproc, docbook, docbook-xsl, docbook-xsl-ns, and docbook5-xml in order to generate the file from docbook XML.

Loading the plugin

Plugin is loaded by Connection Manager at startup.

When loaded plugin registers its interface "org.sailfishos.connman.mdm.iptables" under "net.connman" with path "/org/sailfishos/connman/mdm/iptables". Plugin uses Connection Manager D-Bus functions to register itself to D-Bus.

After the plugin is loaded signal "Initialize" is sent over D-Bus indicating that the plugin is running. Then iptables filter table content is loaded from the default save path of connman iptables module for IPv4 rules. All previously created custom chains (prefixed with sfos_) are loaded at plugin startup (using iptables content returned by connman) into plugin's internal database.

When unloaded (by Connman at exit) iptables filter table is saved to connman's default save path, iptables content is cleared, custom chains are removed from the filter table and finally signal "Shutdown" is sent over D-Bus. Custom chains are saved by connman's sailfish iptables extension.

Plugin iptables operations

This plugin allows to:

Add a rule to iptables filter table
Remove a rule from iptables filter table
Change policy of a filter table chain INPUT and OUTPUT
Add a custom chain to filter table
Clear iptables rules
Clear iptables custom chains
Get iptables filter table content
Get version of plugin interface
Register (and unregister) to listen for API change signals

Rules can be added to any chains found iptables filter table. Each rule can be added with any iptables target: ACCEPT, DENY, REJECT, QUEUE, LOG and custom chains can be used as targets too. Custom chains must be used with the name they are added, e.g., adding chain CUSTOM1 is added as sfos_CUSTOM1 and it has to be used without the prefix "sfos_" as CUSTOM1.

Following parameters are supported:

Ip address or network
Ip address or network with port
Ip address or network with port range
Ip address or network with service name
Port with any address 0.0.0.0
Port range with any address 0.0.0.0
Service name with any address 0.0.0.0

Additionally ICMP rule adding is also supported. Parameters for this are:

ICMP type and code
IP address (optional, can be left as empty strings if not required)

Both source and destination parameters are supported for all. Either or both parameters (source or destination) must be set. They are added to iptables accordingly.

For more information refer to xml documentation of the D-Bus interface of this plugin (sailfish_iptables_dbus_interface_description.xml).

Plugin D-Bus interface access

Access control prevents regular users from changing iptables content or to listen for signals emitted by API. Default configuration is provided by the installation and installed to /etc/connman/iptables_policy.conf. Configuration is loaded from this file, which follows libdbusaccess policy format (see https://git.merproject.org/mer-core/libdbusaccess/).

If a client wishes to get the signals (detailed later) client has to call method Register() successfully. Method use does not require use of Register() method. On each function call (except GetVersion()) the access is checked from D-Bus access policy (via libdbusaccess).

Three different properties are supported in the policy configuration file: full, manage and listen.

full()

Allow everything, no restrictions on access. All signals can be received.

manage()

Make changes to iptables content (add/remove rules and custom chains). Clearing of iptables table with ClearIptablesTable() method is not allowed. All signals can be received.

listen()

Can only listen for D-Bus signals emitted by API after calling method Register().

Signals

The API emits following signals (further described in the D-Bus introspect XML/ HTML documentation):

Initialize

Plugin is initialized and ready to be used.

Signal is sent to all.

Shutdown

Plugin is unloaded.

Signal is sent to all.