<!-- The contents of the documentation begin here. Label
each chapter so with the id attribute. This is necessary for two reasons: it
allows you to easily reference the chapter from other chapters of your
document, and if there is no ID, the name of the generated HTML files will vary
from time to time making it hard to manage for maintainers and for the CVS
system. Any chapter labelled (OPTIONAL) may be left out at the author's
discretion. Other chapters should not be left out in order to maintain a
consistent documentation style across all KDE apps. -->
<chapter id="introduction">
<title>Introduction</title>
<!-- The introduction chapter contains a brief introduction for the
application that explains what it does and where to report
problems. Basically a long version of the abstract. Don't include a
revision history. (see installation appendix comment) -->
<sect1 id="about">
<title>About</title>
<para>
&kmyfirewall; attempts to make it easier to setup firewalls for your computer network without limitating your configuration options. If you don't have the time and/or the interest to spend hours in front of your operating system manual just to setup a simple firewall that keeps the "bad" people out, &kmyfirewall; will help you to configure your computer within a few clicks.
</para>
<para>
It will be the right tool if you like to have a so called "Personal Firewall" running on your worstation but it will also help you to setup complex rulesets for your network routers. Each of it's two different Graphical ruleset editors try to provide the right tool for each group of users.
</para>
<para>
Entire rule sets can be saved, so you only have to configure your rule set one time and then you can use it on several computers giving each of them a similar configuration (p.e. school networks, office, university etc.).
</para>
</sect1>
<sect1 id="note">
<title>Note</title>
<para>
Programs can't do any magic so you still will have to know what your firewall should do to setup your rule set.
</para>
<para>
KMyFirewall tries to provide well designed default settings so that there should not be much to do anymore to provide a secure setup. But there is no way &kmyfirewall; can prevent you from openeing security holes in your setup! Please allways test rulesets you created before you use them for a production system.
</para>
</sect1>
<!--
</chapter>
<chapter id="features">
<title>Features</title>
<para></para>
-->
<sect1 id="common">
<title>Features</title>
<sect2 id="main-features">
<title>Main Features</title>
<orderedlist>
<listitem>
<para>Easy setup of a small but efficient "Personal Firewall".</para>
</listitem>
<listitem>
<para>Nice overview of the configuration.</para>
</listitem>
<listitem>
<para>Import/Export of rule sets to ease the setup of large networks.</para>
</listitem>
<listitem>
<para>Easy-to-use GUI interface for most common setups.</para>
</listitem>
<listitem>
<para>An advanced interface for complex rule sets as needed by routers</para>
</listitem>
<listitem>
<para>Preconfigured rulesets for most common setups.</para>
</listitem>
<listitem>
<para>Integrated Install scripts for automatic execution during booting.</para>
</listitem>
<listitem>
<para>Plugin framowork that allows easy and fast development of new features.</para>
</listitem>
<listitem>
<para>Plugin framowork that allows easy and fast development of new features.</para>
</listitem>
</orderedlist>
</sect2>
<sect2 id="generic-interface-features">
<title>Generic Interface</title>
<para>
<orderedlist>
<listitem>
<para>Zone/Host based rule creation.</para>
</listitem>
<listitem>
<para>No portnumbers need to be known.</para>
</listitem>
<listitem>
<para>NAT and simple network router support.</para>
</listitem>
<listitem>
<para>Support for special hosts e.g. trusted banned etc.</para>
</listitem>
<listitem>
<para>Rule inheritance can be enabled/disabled for nested notwork zones.</para>
</listitem>
<listitem>
<para>Operating system and backend independet. (Currently only Linux is supported but OpenBSD should follow soon)</para>
</listitem>
</orderedlist>
</para>
</sect2>
<sect2 id="ipt-interface-features">
<title>IPTables Interface</title>
<para>
<orderedlist>
<listitem>
<para>XML based iptables command generation engine that allows to be extended by plugins providing a description about the new option.</para>
</listitem>
<listitem>
<para>State full packet filtering.</para>
</listitem>
<listitem>
<para>IP, MAC, Protocol, ROS and Interface based filtering</para>
</listitem>
<listitem>
<para>Limiting packet matches (avoids DoS attacks)</para>
As firewalling is a really complex topic I'd like to give you a briefly introduction about what firewalls are and how
IPTables firewalls work.
</para>
<para>
When you think of a firewall most people would say <quote>firewalls just restrict the network traffic</quote>,
but a modern firewall has more to do that just restricting the traffic which is of course it's main task.
</para>
<para>You can filter by having a look at the packet headers that store information about where the packet comes from,
which protocol is used etc.
</para>
<para>
The filtering possibilities provided by the IPTables are very powerful so it's even possible to
only let packets in that are know to belong to a connection you have made. This technology is called <quote>Connection Tracking</quote>
or <quote>Statefull Packet Filtering</quote>.
</para>
<para>
The second important feature a firewall has to provide is the possibility to log the network traffic.
This is a much more important part of it as you may think, because logfiles are give you a good view
about the activities in your network like who did what and when.
</para>
<para>
Logs are also really important when
the firewall got cracked and you want to know how. In that you would have a much harder life if you didn't
activeted the logging functions so that you can see what has happend and how the configuration be improved.
</para>
<para>
Most people think about firewalls just being used to block traffic from the Internet to your host, but you may also
configure your firewall to restrict the Internet access. Par example you may block some well known porn sites on your Children's PC
or you just want to allow e-mail and Web browsing in your office but you don't want your employees to be able to download files via FTP.
</para>
<para>
All the things described are really easy to implement with the IPTables once you have understood how they work. Please read
carefully through the next few chapters to learn how to efficiently use this Program to settup an firewall for your PC/Network.
</para>
</sect1>
<sect1 id="firewall-cant-do">
<title>A Note about Security in general</title>
<para>
A firewall can actually not guarantee 100% of security just because there may be bugs in the underlying software or the
configuration or even a hardware problem can be the <quote>open door</quote> for the bad guys.
</para>
<para>
It is also a common mistake to believe that a firewall is enough to provide security.
If you want to have a really high level of security you will need a whole <quote>Security Concept</quote> which
defined the basic rules for the network environment. This includes the used software, installing security updates to the running
software, a good documentation about how the security level is enforced in your network etc.
</para>
<para>
Here is an example what I mean by that.
</para>
<para>
Imagine you are running a public web server. To make it possible for the World to reach you you have to open the TCP port 80 for
incoming connections. By opening this port your computer is reachable through the Internet. You as the admin implemented a
really bomb save firewall configuration and you feel save because your firewall protects you. But certainly a securityhole in the webserver
application is found and made public in the Internet. If you didn't installed the security update because you forgot or it isn't available
yet a hacker may be able to use this securityhole (in the webserver not the firewall) to get access to your network. In this case the
firewall can't do anything against it because you allowed people to connect to your server.
</para>
<para>
I hope that this example makes it a little bit clearer what is meant when talking about a security concept.
To prevent these cases there are some basic rules to follow.
<orderedlist>
<listitem>
<para>Install updates to the software you are running.</para>
</listitem>
<listitem>
<para>Try to have a look at some security based websites to stay informed about whats going on out there.</para>
</listitem>
<listitem>
<para>Think about creating a security concept for your network.</para>
</listitem>
<listitem>
<para>Never ever trust your configuration blindly!</para>
</listitem>
<listitem>
<para>Watch your logfiles for strange activities.</para>
</listitem>
<listitem>
<para>Keep an eye on the legal users in your network, a lot of networks have been hacked because of users
that didn't follow the security concept and installed disallowed software, connect to the internet via modem or WLAN
so that your firewall is simply can't see those connections, or the installed software was a virus or hidden backdoor to the system.</para>
</listitem>
<listitem>
<para>Read books and all kind of documentation about this topic you can find.</para>
</listitem>
<listitem>
<para>Always remember there is no save host. Except it's offline...</para>
</listitem>
</orderedlist>
</para>
</sect1>
<sect1 id="iptables-concept">
<title>IPTables basics</title>
<para>
An IPTables based firewall is made of three different basic <quote>objects</quote>.
<orderedlist>
<listitem>
<para>Rules</para>
</listitem>
<listitem>
<para>Chains</para>
</listitem>
<listitem>
<para>Tables</para>
</listitem>
</orderedlist>
</para>
<para>
Please read through the next three chapters to get a short description about those
objects. Note that this is just a briefly introduction to the IPTables. For more detailed documentation have a look at the IPTables
Manpage or <ulink url="http://www.iptables.org">www.iptables.org</ulink>.
</para>
<sect2 id="rules">
<title>Rules</title>
<para>
The lowest level objects are the <quote>rules</quote> that are performing the packetfiltering or manipulation.
A rule is made of several parts.
<orderedlist>
<listitem>
<para>The Table to which this rule should be added. If no table is defined the rule will be added to the <quote>filter</quote> table.</para>
</listitem>
<listitem>
<para>The Chain to which this rule should be added p.e INPUT or FORWARD</para>
</listitem>
<listitem>
<para>The filtering or manipulation instructions.</para>
</listitem>
<listitem>
<para>The target of the rule. This target decides what should be done with the packet if it matches the rule.
The most Important targets are <quote>DROP</quote>, which drops the packet without any further action,
<quote>ACCEPT</quote>, which will let the packet pass the firewall and the data is sent to the receiver and
<quote>LOG</quote> that simply writes some information (src. IP, ports etc.) about the packet that matches to the Syslog.</para>
</listitem>
</orderedlist>
</para>
</sect2>
<sect2 id="chains">
<title>Chains</title>
<para>
Those rules are organized in <quote>chains</quote> which are simple ordered list of rules.
There are some built-in chains that are always available for the user like the INPUT or the OUTPUT chain in
the filter table.
Built-in chains do also have a so called <quote>Default Target</quote> which decides what to do with a packet that didn't
match any of the rules defined in that chain.
</para>
<para>
For large configurations it's often required to settup rules for packets that are common in some pieces of their attributes.
When you setup a firewall that also provides routing functionality you may want to have different kind of rules for packets coming
from the internal network than for packets coming from the evil Internet.
</para>
<para>
To make it more easy to manage such configurations you have the possibility to create your own chains.
Those user defined chains don't have a <quote>Default Target</quote>.
</para>
<para>
User defined chains must be fed by rules that have the name of the user defined chain as their target.
When a packet passes the whole user defined chain without matching any of its rules the packet will
be sent back to the chain that fed this chain just right after the rule that sent the packet to the user defined chain.
</para>
<para>
The packets will be compared to the rules in the order as they are defined in the chain. This means
that the packet will no longer be tested if a rule before matched. So please pay attention to the order of the rules
as a wrong ruleorder may end up in an very hard to find bug in the configuration.
</para>
</sect2>
<sect2>
<title>Tables</title>
<para>
Because of the lots of possibilities that IPTables rules give you to filter and/or mainpulate the packets
that are checked the chains themselves are organized in so called <quote>tables</quote>.
Each table has it's own set of built-in chains that are available for direct use.
</para>
<para>
There are three tables available <quote>filter</quote>, <quote>nat</quote> and <quote>mangle</quote>.
<orderedlist>
<listitem>
<para>The <quote>filter</quote> table that is used for packet filtering as we all think about when we are talking about firewalls</para>
</listitem>
<listitem>
<para>The <quote>nat</quote> table is made for all kind of <quote>Network Address Translation</quote> which is a technology
used to change the source and destination attributes of the packet. The well known <quote>IP Masquerading</quote> is the most common way to use this
feature.</para>
</listitem>
<listitem>
<para>The <quote>mangle</quote> table is designed to hold chains and rules that change other attributes of the packets or
sending them into the userspace to be processed by any other application. If you are not thinking about really complicated things
you shouldn't need to use this table.</para>
</listitem>
</orderedlist>
</para>
</sect2>
</sect1>
</chapter>
<chapter id="iptusage">
<title>IPTables usage</title>
<para>
Here is a short reference for the iptables commandline program. I'll try to explain most of the important
options the iptables command allows. For more details please have a look at <ulink url="man:/usr/share/man/man8/iptables.8.gz">man iptables</ulink>
</para>
<para>
Some (quiet a lot) of the descriptions are copy and paste from the iptables manpage, because the manpage is really good and I just added my own explanations where I thought this should be clearer. I'd like to say thanks to the iptables developers for this fabulous manpage.
</para>
<sect1 id="tableselection">
<title>Selecting the Table</title>
<para>
Each rule you like to add to your firewall needs to be inserted or appended into an existing chain in one of the three tables
<quote>filter</quote>, <quote>nat</quote> or <quote>mangle</quote>. Which of the tables are available depends on the configuration of your kernel.
</para>
<para>
Lets have a look at the following iptables commandline:
</para>
<para><command>iptables -t filter -A INPUT --source 192.168.0.1 -j DROP</command></para>
<para>
As you can see the command has several parts to set the behavior of the rule. Lets start with <command>iptables -t <tablename> ...</command>
The option <quote>-t</quote> tells iptables to add the rule to a chain in the table <tablename>. If no -t option is defined the rule will be inserted
into the <quote>filter</quote> table which is the default.
</para>
</sect1>
<sect1 id="append">
<title>Append, Insert and Delete</title>
<para><command>iptables -t filter -A INPUT ...</command></para>
<para>
The option <quote>-A INPUT</quote> tells the program to add the rule at the end of the<quote> INPUT</quote> chain. There are also the
options <quote>-I chain [rulenum] </quote> for inserting a rule, <quote>-R chain [rulenum]</quote> for replacing a rule and
<quote>-D chain rulenum</quote> for deleting a rule from a chain.
</para>
<para>&kapp; only uses the -A option in the generated script.</para>
</sect1>
<sect1 id="options">
<title>Defining Options</title>
<para>
For filtering and manipulation of packets you need to define which properties a packet must have
to be filtered/manipulated. This is done by passing one or more option names p.e. <quote> --source</quote>
and the value that should match <quote>192.168.0.1</quote> in that case.
</para>
<para>
IPTables define quiet a lot of different options you can check for. Some of them are directly implemented in the iptables
program like the --source option but there are also some more complex options that need to load the needed modules into the kernel to
be available. Those options are defined like <command>... --match state --state RELATED,ESTABLISHED ...</command> The <quote>--match state</quote>
options lets the program look for an available option called <quote>state</quote> which is in this case the connection tracking module.
</para>
<para>
The availability of those extended options depends on the configuration of your kernel and the available modules that can be loaded or are directly compiled into the kernel.
</para>
<para>
For a more detailed description of the options that can be used from within this program have a look at the chapter
<link linkend="rule_manupulation">Packet Filtering and Altering</link>.
The Target of a rule defines what to do if a packet matches the rule. The target is defined by the <command>-j <target> [target-options]</command> option
at the end of the filtering/manipulation options at the end of the rule. There are two different types of targets terminating and non-terminating.
If a target is terminating the packet will not be passed to rules after the matching one.
</para>
<para>A good example for a terminating target is <command>... -j DROP</command>.
The DROP target that tell the kernel to drop (delete) the matching packet which means that it will not reach it's destination. And it's quiet logical that
you don't want to check the packet against the other (later in the chain) defined rule as you already know what to do with it.
</para>
<para>
For a non-terminating target have a look at the code snip above. The here used LOG target lets the kernel log the packets matching this rule to
the syslog. It wouldn't be very useful if the packets would stop here therefore the packets continue the way through the kernel.
</para>
</sect1>
</chapter>
<chapter id="rule_manupulation">
<title>Filtering and Manipulation of Packets</title>
<para>
Packet filtering and altering is the main task iptables have to perform and they are really good in it. But a highly configurable and flexible packetfilter is nothing trivial so please read this carefully before you start you experiments.
</para>
<para>
This chapter will show you how the different filter modules of the iptables are used in detail. It may look shocking but it's not that hard to understand and once you've got it, it' really easy to settup highly complex rulesets for big network routers or simple personal firewalls.
Some of these advanced filtering options (connection tracking, mac) need extra modules to be either loaded as module or directly compiled into the kernel. Have a look at the Kernel Compiling HOWTO for details about building a custom kernel.
</para>
<sect1 id="src_dest_ip">
<title>Source and destination IP</title>
<para><command>iptables -A INPUT --source 12.168.120.15 -j ACCEPT</command></para>
<para>
Source specification. Address can be either a network name, a hostname (please note that specifying any name to be resolved with a remote query such as DNS is a really bad idea), a network IP address (with /mask), or a plain IP address. The mask can be either a network mask or a plain number, specifying the number of 1's at the left side of the network mask. Thus, a mask of 24 is equivalent to <command>255.255.255.</command>. A <command>!</command> argument before the address specification inverts the sense of the address. The flag <command>--src</command> is an alias for this option.
</para>
<para><command>iptables -A INPUT --destination ! 32.112.0.31/24 -j ACCEPT</command></para>
<para>
Destination specification is similar in usage to the source option.</para>
</sect1>
<sect1 id="protocol">
<title>Checking for the protocol</title>
<para><command>iptables -A INPUT --protocol tcp -j ACCEPT</command></para>
<para><command>iptables -A INPUT --protocol ! udp -j LOG</command></para>
<para>
The protocol of the rule or of the packet to check. The specified protocol can be one of <command>tcp</command>, <command>udp</command>, <command>icmp</command>, or all, or it can be a numeric value, representing one of these protocols or a different one. A protocol name from /etc/protocols is also allowed. A <command>!</command> argument before the protocol inverts the test. The number zero is equivalent to all. Protocol all will match with all protocols and is taken as default when this option is omitted.
</para>
<sect2 id="protocol_tcp">
<title>TCP specific options</title>
<para>
TCP specific are all filter options that have a deeper look into the TCP header of the packet. This includes checking for source-, destination port, real tcp connection tracking, tcp flags etc.
</para>
<sect3 id="protocol_tcp_ports">
<title>TCP Source and destination ports</title>
<para><command>iptables -A INPUT --protocol tcp --source-port 22:12 -j LOG</command></para>
<para><command>iptables -A POSTROUTING --protocol tcp --destination-port ! 21232 -j DROP</command></para>
<para>
Source/Destination port or port range specification. This can either be a service name or a port number. An inclusive range can also be specified, using the format <command>port:port</command>. If the first port is omitted, "0" is assumed; if the last is omitted, <command>65535</command> is assumed. If the second port greater then the first they will be swapped. The flag <command>--sport</command> is a convenient alias for this option.
Match when the TCP flags are as specified. The first argument is the flags which we should examine, written as a comma-separated list, and the second argument is a comma-separated list of flags which must be set. Flags are: <command>SYN ACK FIN RST URG PSH ALL NONE </command>. Hence the command:
</para>
<para>
<command>iptables -A FORWARD -p tcp --tcp-option SYN,ACK,FIN,RST SYN -j ACCEPT </command> will only match packets with the SYN flag set, and the ACK, FIN and RST flags unset.
</para>
</sect3>
<sect3 id="protocol_tcp_option">
<title>TCP Options</title>
<para><command>iptables -A INPUT --protocol tcp --tcp-option 0 -j LOG</command></para>
<para>
Match if the numeric TCP option is set in the tcp header. A <command>!</command> may be used to invert the match option.
</para>
</sect3>
</sect2>
<sect2 id="protocol_UDP">
<title>UDP specific options</title>
<para>
UDP is the second big protocol in the internet. The main difference to TCP is that it does not provide a stateful connection to the peer host. In other words UDP packets are anonymous and easy to fake. On the other hand is it extremely fast (no overhead of establishing connections) and therefore it's used by lots of protocols. Most important UDP protocols are <command>DNS</command> (hostname <---> ip address ) and <command>NFS</command> (Standard *NIX filesharing protocol).
</para>
<sect3 id="protocol_udp_ports">
<title>UDP Source and destination ports</title>
<para><command>iptables -A INPUT --protocol udp --source-port 22:12 -j LOG</command></para>
<para><command>iptables -A POSTROUTING --protocol udp --destination-port ! 21232 -j DROP</command></para>
<para>
Source/Destination port or port range specification. This can either be a service name or a port number. An inclusive range can also be specified, using the format <command>port:port</command>. If the first port is omitted, "0" is assumed; if the last is omitted, <command>65535</command> is assumed. If the second port greater then the first they will be swapped. The flag <command>--sport</command> is a convenient alias for this option.
</para>
</sect3>
</sect2>
<sect2 id="icmp">
<title>ICMP</title>
<para>
The Internet Control Message Protocol (ICMP) is the control and message protocol for the underlying IP protocol. Often needed messages and commands are defined in this protocol like <quote>host-unreachable</quote> when an ip address was not found,<quote>echo-request</quote> the normal ping and <quote>source-quench</quote> tells the receiver to slow down the traffic -> !!!Denial of Service!!!,
</para>
<sect3 id="icmp_type">
<title>ICMP type</title>
<para><command>iptables -A INPUT --protocol icmp --icmp-type echo-request -j LOG</command></para>
<para>
This allows specification of the ICMP type, which can be a numeric ICMP type, or one of the ICMP type names shown by the command: <command>iptables -p icmp -h </command>.
</para>
</sect3>
</sect2>
<sect2 id="multiport">
<title>Multiport Match Extension</title>
<para>
The Multiport match extension allows you to define a comma-separated list of up to 15 ports in an TCP or UDP specific rule. This is mostly useful to save some typing by specifying mor that one port per rule.
Match if the both the source and destination ports are equal to each other and to one of the given ports.
</para>
</sect3>
</sect2>
</sect1>
<sect1 id="interfaces">
<title>Incoming and Outgoing Interface</title>
<para><command>iptables -A INPUT --in-interface eth0 -j LOG</command></para>
<para>
Name of an interface via which a packet is going to be received (only for packets entering the <command>INPUT</command>, <command>FORWARD</command> and <command>PREROUTING</command> chains). When the "!" argument is used before the interface name, the sense is inverted. If the interface name ends in a "+", then any interface which begins with this name will match. If this option is omitted, any interface name will match.
</para>
<para><command>iptables -A OUTPUT --out-interface ! ippp1 -j DROP</command></para>
<para>
Name of an interface via which a packet is going to be sent (for packets entering the <command>FORWARD</command>, <command>OUTPUT</command> and <command>POSTROUTING</command> chains). When the "!" argument is used before the interface name, the sense is inverted. If the interface name ends in a "+", then any interface which begins with this name will match. If this option is omitted, any interface name will match.
</para>
</sect1>
<sect1 id="src_mac">
<title>Source MAC</title>
<para>
<command>iptables -A INPUT --match mac --mac-source 12:E4:86:FA:5C:54 -j ACCEPT</command>
</para>
<para>
Match source MAC address. It must be of the form XX:XX:XX:XX:XX:XX. Note that this only makes sense for packets coming from an Ethernet device and entering the <command>PREROUTING</command>, <command>FORWARD</command> or <command>INPUT</command> chains.
</para>
<para>
This options is very useful for protection against man-in-the-middle attacks, because it is possible to combine it
with the <command>--source</command> option and so protection against arp-spoofing may be provided.
</para>
</sect1>
<sect1 id="limit">
<title>Limit matches</title>
<para>
This module matches at a limited rate using a token bucket filter. A rule using this extension will match until this limit is reached (unless the `!' flag is used). It can be used in combination with the <command>LOG</command> target to give limited logging, for example.
<para><command>iptables -A INPUT --match state --state RELATED,ESTABLISHED -j ACCEPT</command></para>
<para>
Where state is a comma separated list of the connection states to match. Possible states are <command>INVALID</command> meaning that the packet is associated with no known connection, <command>ESTABLISHED</command> meaning that the packet is associated with a connection which has seen packets in both directions, <command>NEW</command> meaning that the packet has started a new connection, or otherwise associated with a connection which has not seen packets in both directions, and <command>RELATED</command> meaning that the packet is starting a new connection, but is associated with an existing connection, such as an FTP data transfer, or an ICMP error.
</para>
</sect1>
<sect1 id="tos">
<title>TOS - Type of Service</title>
<para>
This module matches the 8 bits of Type of Service field in the IP header (ie. including the precedence bits).
</para>
<para><command>iptables -A INPUT --match tos --tos Minimize-Delay -j ACCEPT</command></para>
<para>
The argument is either a standard name, or a numeric value to match. Run <command>iptables -m tos -h</command>
to see the list of allowed names).
</para>
</sect1>
</chapter>
<chapter id="using-kapp">
<title>Using &kapp;</title>
<!-- This chapter should tell the user how to use your app. You should use as
many sections (Chapter, Sect1, Sect3, etc...) as is necessary to fully document
your application. -->
<sect1 id="kapp-overview">
<title>Overview - GUI Interfaces</title>
<para>&kapp; ships with two different GUI interfaces.</para>
<sect2 id="kapp-interfaces-generic">
<title>Generic Interface</title>
<para>The Generic Interface is an abstract view on what kind of netwok traffic may or may not pass yout computer. The rules are generated by a compiler plugin so that it is possible to generate scripts for other plattforms p.e. OpenBSD/pf then GNU/Linux/iptables (well currently just the iptables compiler is implemented. Let me know if you are interrested in implementing that :)).</para>
</sect2>
<sect2 id="kapp-interfaces-ipt">
<title>IPTables Interface</title>
<para>The IPTables interfaces tries to represent a 1-1 look at the iptables rule set your configuration will create. Therefore it is ment to be used by experienced system administrators in order to setup very fine graduaded rulesets. Becaus of the tight relation this GUI has to the netfilter/iptables framework it can only be used on GNU/Linux workstations as the document can not be compiled into any other rule description language.</para>
</sect2>
</sect1>
<sect1 id="getting-started">
<title>Getting Started</title>
<para>
The easiest way to start is to create a new Document <keycombo><keycap>Ctrl</keycap><keycap>n</keycap></keycombo>
and use the Wizard to setup the basic rules for your new firewall.
For a simple <quote>Personal Firewall</quote> the default configuration should be quiet usable as it is designed to
let everything out of your Box (Table: Filter, Chain: OUTPUT, Target: ACCEPT) and only lets packets is that
are related with connections you established.
</para>
<para>
This configuration is a good starting point for your firewall if you don't need any kind of routing or packet mangling because
it deactivates the routing functionality in your kernel and only the filter table is used.
</para>
<para>
The Wizard can not be used to change an existing configuration it's simply made for setting up a basic ruleset that can be
changed by using the <quote>Rule Editor</quote> and the <quote>Chain Editor</quote>.
</para>
<para>
For more complex rulesets as needed by routes or firewalls that protect a whole network, you need to use the
<quote>Advanced Interface</quote> to setup the firewall.
The document generated by the <quote>Advanced Interface</quote> is an empty ruleset! In other words there
are no rules defined to filter any kind of packets.
As you can see this thing gets quiet big so every kind of help (coding,docs,translations)
is very welcome. Please don't hesitate to contact me <email>chubinger@gmail.com</email>
if you have some ideas, patches, wishes or whatever.
</para>
<sect1 id="developers-plugins">
<title>&kapp; Plugin framework</title>
<para>
&kapp; extensively uses KDE's KParts/XMLGUI technology to provide an easy to and robust plugin infrastructure. Allmost every function is performed by dynamicaly loaded plugins in order to make it easy manage the code and write extentions. Especially the IPTables interface uses plugins to embeed the different iptables rule options edit dialogs.
<para>As the iptables command utility is really fast developing and every few week new options are added, all ruleoption handling is outsourced to small easy to write plugins.</para>
<para>The underlieing document format is designed flexible enougth to allow the implementaiton of any command option iptables knows (or will know, if i didn't forget anything).</para>
<para>The rule creation engine can be extend by registering new option/targetoption types defined in small XML files that are parsed at startup. And the editor GUI can embeed the edit widgets needed to configure the ruleoption.</para>
<sect2 id="developers-plugins-ruleoptions-parts">
<title>Parts of an Ruleoption/targetoption Plugin</title>
<itemizedlist>
<listitem><para>A XML file named p.e. kmfruleoption_mac_option.xml</para></listitem>
<listitem><para>A desktop file p.e. kmfruleoptionedit_mac.desktop that registeres the plugin within the KDE services framework.</para></listitem>
<listitem><para>An KParts Plugin component/class that derives form either KMFRuleOptionEditInterface or KMFRuleTargetOptionEditInterface named p.e. KMFRuleOptionEditMAC </para></listitem>
<title>XML File describing the rule option</title>
<para>The xml file gets loaded during application startup and registers the specified rule option in the engine. Have a look at some of the other XML files installed in $KDE-PREFIX/share/apps/kmyfirewall/ruleoptions for some more example of how to define the needed options.</para>
<para>This file is installed into the services directory and makes the plugin available for the KDE plugin framework</para>
<para>The important thing here is that you set Type=Service and the right SeviceType. The application only searches for plugins with SeviceType=KMyFirewall/RuleOptionEdit or SeviceType=KMyFirewall/RuleTargetOptionEdit.</para>
<para>Make shure that you add the option -module $(KDE_PLUGIN) to the <library_name>_LDFLAGS. Otherwise the plugin can not be loaded at runtime.</para>
<programlisting>
INCLUDES = -I../kmfwidgets -I../../ipteditor -I$(srcdir)/../interfaces $(all_includes)
