Skip to content
KMyFirewall
Release 1.1.1 Download

The KMyFirewall Handbook

Rule option plugins

The iptables command utility develops quickly and new options are added regularly. All rule option handling is therefore outsourced to small, easy to write plugins.

The underlying document format is flexible enough to implement any command option iptables knows, or will know. The rule creation engine can be extended by registering new option and target option types in small XML files that are parsed at startup. The editor GUI can embed the edit widgets needed to configure the option.

Parts of a rule option or target option plugin

  • An XML file, for example kmfruleoption_mac_option.xml.
  • A desktop file, for example kmfruleoptionedit_mac.desktop, that registers the plugin with the KDE services framework.
  • A KParts plugin component and class deriving from KMFRuleOptionEditInterface or KMFRuleTargetOptionEditInterface.
  • A class deriving from QWidget that can be loaded into the editor view when editing the option.

Most developers use Qt Designer to design the GUI. If you do, inherit from the generated class.

XML file describing the rule option

The XML file is loaded during application startup and registers the rule option in the engine. Other XML files installed in $KDE_PREFIX/share/apps/kmyfirewall/ruleoptions show more examples.

<!DOCTYPE kmyfirewall‑kmfruleoptiondefinition>
<ruleoptiondefinitionset>
  <ruleoptiondefinition name="mac_opt" guiName="MAC Address">
    <option guiName="" command="‑‑match mac" />
    <option guiName="MAC:" command="‑‑mac‑source" />
  </ruleoptiondefinition>
</ruleoptiondefinitionset>

The desktop file

This file is installed into the services directory and makes the plugin available to the KDE plugin framework. Set Type=Service and the right ServiceType. The application only searches for plugins with ServiceType=KMyFirewall/RuleOptionEdit or ServiceType=KMyFirewall/RuleTargetOptionEdit. The line X‑KDE‑Library=libkmfruleoptionedit_mac tells the framework which library defines the functionality.

[Desktop Entry]
Encoding=UTF‑8
Type=Service
Name=KMyFirewall MAC option edit
Name[da]=KMyFirewall MAC redigeringstilvalg
Comment=Plugin for edition MAC address based iptables rule options
Comment[da]=Plugin ril at redigere MAC adressebaserede regeltilvalg for iptables
X‑KDE‑Library=libkmfruleoptionedit_mac
ServiceTypes=KMyFirewall/RuleOptionEdit

The Makefile.am

Make sure you add the option ‑module $(KDE_PLUGIN) to the library LDFLAGS. Otherwise the plugin cannot be loaded at runtime.

INCLUDES = ‑I../kmfwidgets ‑I../../ipteditor ‑I$(srcdir)/../interfaces $(all_includes)
METASOURCES = AUTO
kde_module_LTLIBRARIES = libkmfruleoptionedit_mac.la
libkmfruleoptionedit_mac_la_LDFLAGS = ‑module $(KDE_PLUGIN) $(all_libraries)
libkmfruleoptionedit_mac_la_LIBADD = ../../core/libkmfcore.la ../../interfaces/libkmfinterfaces.la $(LIB_KPARTS)
noinst_HEADERS = kmfruleoptioneditmac.h kmfruleeditmac.h
libkmfruleoptionedit_mac_la_SOURCES = kmfruleoptioneditmac.cpp kmfruleeditmac.cpp kmyfirewallruleeditormac.ui
partdesktopdir = $(kde_servicesdir)
partdesktop_DATA = kmfruleoptionedit_mac.desktop
install‑data‑local:
  $(mkinstalldirs) $(DESTDIR)$(kde_datadir)/kmyfirewall/ruleoptions/
  $(INSTALL_DATA) $(srcdir)/kmfruleoption_mac_option.xml $(DESTDIR)$(kde_datadir)/kmyfirewall/ruleoptions/kmfruleoption_mac_option.xml
uninstall‑local:
  ‑rm ‑f $(DESTDIR)$(kde_datadir)/kmyfirewall/ruleoptions/kmfruleoption_mac_option.xml

KParts plugin component and class

This class defines the plugin that is loaded at application startup. The important public methods are loadRule, which receives the rule being edited, editWidget, which returns the widget for the editor view, and optionEditName and description, which describe the plugin to the GUI.

class KMFRuleOptionEditMAC : public KMFRuleOptionEditInterface {
  Q_OBJECT
public:
  KMFRuleOptionEditMAC(QObject *parent = 0, const char *name = 0);
  ~KMFRuleOptionEditMAC();
  void loadRule(IPTRule* rule);
  QWidget* editWidget();
  const QString& optionEditName() const;
  const QString& description() const;
private slots:
  void slotAddRuleOption(QString*, QPtrList<QString>*);
  void slotAddTargetOption(QString*, QPtrList<QString>*);
  void slotShowOverview();
private:
  KMFRuleEditMac *m_edit;
  IPTRule *m_rule;
};

The factory class derives from KLibFactory and exports an init_libkmfruleoptionedit_mac function that returns a new factory. The factory creates the plugin object and emits objectCreated.

The editor widget class

This class defines a widget that configures the specific rule option. It receives the rule with loadRule, reads the option values, validates the user input, and emits sigAddRuleOpt with the new option values. It also emits sigHideMe when the editor should close.

class KMFRuleEditMac : public KMyFirewallRuleEditorMac {
  Q_OBJECT
public:
  KMFRuleEditMac(QWidget* parent = 0, const char* name = 0, WFlags fl = 0);
  ~KMFRuleEditMac();
  void loadRule(IPTRule*);
public slots:
  void accept();
  void slotHelp();
  void reject();
signals:
  void sigAddRuleOpt(QString*, QPtrList<QString>*);
  void sigHideMe();
};

In the implementation, accept starts a transaction on the document, saves the rule state, builds the MAC address from the input fields, validates it with KMFCheckInput, emits the new option values, ends the transaction and hides the editor. slotHelp opens the handbook page for the option.

Reference

Background on the frameworks: KDE, KDevelop, and the project on SourceForge.

Back to top