<?xml version="1.0" ?>
<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.1-Based Variant V1.0//EN" "dtd/kdex.dtd" [
<!ENTITY kappname "Guarddog">
<!ENTITY % addindex "IGNORE">
<!ENTITY % English "INCLUDE">
<!-- Do not define any other entities; instead, use the entities
from kde-genent.entities and $LANG/user.entities. -->
]>
<!-- kdoctemplate v0.8 October 1 1999
Minor update to "Credits and Licenses" section on August 24, 2000
Removed "Revision history" section on 22 January 2001 -->
<!-- ................................................................ -->
<!-- The language must NOT be changed here. -->
<book lang="&language;">
<!-- This header contains all of the meta-information for the document such
as Authors, publish date, the abstract, and Keywords -->
<bookinfo>
<title>The &kappname; Handbook</title>
<authorgroup>
<author>
<firstname>Simon</firstname>
<surname>Edwards</surname>
<affiliation>
<address><email>simon@simonzone.com</email></address>
</affiliation>
</author>
</authorgroup>
<copyright>
<year>2000</year>
<year>2001</year>
<year>2002</year>
<holder>Simon Edwards</holder>
</copyright>
<!-- Translators: put here the copyright notice of the translation -->
<!-- Put here the FDL notice. Read the explanation in fdl-notice.docbook
and in the FDL itself on how to use it. -->
<legalnotice>&FDLNotice;</legalnotice>
<date>1/3/2002</date>
<releaseinfo>1.9.12</releaseinfo>
<abstract>
<para>
&kappname; is user friendly firewall utility for KDE running on Linux. The
best way to get started is to read the short tutorials starting with
the first one.
</para>
</abstract>
<keywordset>
<keyword>KDE</keyword>
<keyword>&kappname;</keyword>
<keyword>firewall</keyword>
<keyword>linux</keyword>
<keyword>ipchains</keyword>
<keyword>iptables</keyword>
</keywordset>
</bookinfo>
<chapter id="introduction">
<title>Introduction</title>
<para>
&kappname; is user friendly firewall generation and management utility for KDE
on Linux. It allows you to simply specify which protocols should be allowed
between which groups of computers and requires no knowledge of port numbers
or packets. Built on top of <command>ipchains</command> and
<command>iptables</command>.
</para>
<sect1 id="introduction-what">
<title>What is a firewall and why do I need one?</title>
<para>
A firewall is a software and/or hardware tool for defending a computer or
network of computers, from attacks via the network performed by malicious or
curious computer users. It protects by restricting what hostile
computers are permitted to do to the protected computers.
It does this by filtering and blocking the network communication between the
protected computers and the Internet at large.
</para>
<para>
With the arrival of fast, permanent, 24 hour/7 day, internet connections for
home users, your computer is now exposed to constant attacks from anywhere in
the world. You may ask yourself "why would anyone want to break into my
computer? I don't have anything important". Actually you do, even a home
computer stores usernames and passwords for connecting to the internet,
personal email, possibly financial information and perhaps even credit card
information. Even without these things, your computer can be used as a
stepping stone by malicious users (often called 'crackers') to attack other
computers. The worst part of this is that these further attacks will look
like they are coming from you!
</para>
<para>
For more introductory material about firewalls try the
<ulink url="http://www.howstuffworks.com/firewall.htm">firewall</ulink> article
over at <ulink url="http://www.howstuffworks.com/">How Stuff Works</ulink>.
</para>
</sect1>
<sect1 id="introduction-silverbullet">
<title>A Warning: No Silver Bullet Here</title>
<para>[TODO: a firewall won't protect you from everything]</para>
<para>[TODO: Explain the importance of patching your system.]</para>
</sect1>
<sect1 id="introduction-why">
<title>Why use &kappname;</title>
<itemizedlist>
<listitem><para>Easy to use goal oriented GUI. You say what the firewall
should do without having to explain all the details of how it should do it.
</para></listitem>
<listitem><para>
Application protocol based. Unlike other tools, &kappname; does not require
you to understand the ins and outs of IP packets and ports. &kappname; takes
care of this for you. This also reduces the chances of configuration
mistakes being made which are a prime source of security flaws.
</para></listitem>
<listitem><para>
Doesn't just generate the firewall once and forgets it. &kappname; is used to
maintain and modify the firewall in place.
</para></listitem>
<listitem><para>
Can be used in workstation and router configurations.
</para></listitem>
<listitem><para>
Allows you to divide your network into groups of machines and control
what protocols are allowed between them.
</para></listitem>
<listitem><para>
Works on the older Linux kernel 2.2 series <command>ipchains</command>
firewall subsystem, and also on newer Linux kernel 2.4 netfilter/
<command>iptables</command> firewall subsystem.
</para></listitem>
<listitem><para>
Takes advantage of advanced Linux kernel 2.4 features such as connection
tracking and rate limited logging.
</para></listitem>
<listitem><para>
Licensed under the terms of the GPL. Is Free and will remain Free.
</para></listitem>
</itemizedlist>
</sect1>
</chapter>
<chapter id="using-guarddog">
<title>Using &kappname;</title>
<para>
</para>
<sect1 id="tutorial-basic">
<title>Tutorial: Basic Configuration</title>
<para>
In this tutorial I will explain basic networking concepts and how to quickly
setup &kappname; to protect a single workstation.
</para>
<sect2>
<title>Starting &kappname;</title>
<para>
First start up &kappname;. For recent Mandrake and Redhat systems there
should be a &kappname; menu entry on the K menu under Configuration/Networking.
You will then immediately be asked for the root password. This is needed
because &kappname; needs administrator access in order to modify the system's
networking sub-system.
</para>
<para>
Once &kappname; has opened it's window you will see that it the user interface
is divided across four tabs. For this tutorial we will ignore the the
<guilabel>Zone</guilabel>, <guilabel>Logging</guilabel> and
<guilabel>Advanced</guilabel> tabs and concentrate on the
<guilabel>Protocol</guilabel> tab.
</para>
</sect2>
<sect2>
<title>Basic Networking Concepts</title>
<para>
(Skip this section if you understand network protocols and the
"Client Server Model".)
</para>
<para>
Now I must explain what a protocol is. Networks are all about computers
talking to other computers. Like when talking to other person in the
Real World(tm) it helps if you both agree to speak the same language, be
it English, Dutch or Sign Language. Same thing for computers, they need
to agree on what language they are going to speak when talking to another
computer. The difference between computer protocols and my previous example
is that protocols are usually only intended for one particular task like
moving files (FTP), fetching web pages (HTTP) or chatting with other
computer users (IRC, ICQ).
</para>
<para>
Attacks against computer systems across the network are performed by using
and abusing protocols and the software used to implement them. All too often
the software used to implement a protocol contains flaws that can be
exploited by malicious people to gain access to a system or to disrupt it.
</para>
<para>
One more important concept to understand network protocols is the "Client
Server Model". All network protocols involve at least two different parties
communicating. Although each party is using the same protocol quite often
they will have different roles to play in that protocol. The most common
model is where one party acts as a "client" while the other acts as a
"server" who responds to requests from the "client". A very close analogy
in the real world would be buying fries down at the local fast food restaurant.
You and the person behind the counter would both be using English as the
protocol but you both have different roles. You would have the role of
"client" while the person serving you would be acting as the "server".
HTTP, the protocol used on the World Wide Web uses a the "Client Server Model".
Your web browser acts as the client while the big web server at Slashdot or
CNN acts as the server, delivering pages back to your browser when it asks for
them.
</para>
</sect2>
<sect2>
<title>Permitting DNS</title>
<para>
(Skip the next paragraph is you know what DNS is.)
</para>
<para>
The <guilabel>Protocol</guilabel> tab is where you specify which protocols
are permitted to be
used between your computer and the internet. The "Domain Name System"
protocol, commonly known as DNS, is a very important protocol. All machines
on the internet have what is known as an IP address which is just a number.
You may have some before. They are often written as a "dotted quad" like
"195.231.34.5" for example. An IP address is sort of like a telephone number,
except that it's for identifying computers on the internet and not
telephones. One problem with using IP addresses to identify machines is that
it's not very human friendly. This is why "Domain Names" were invented. A
"Domain Name" is just a human friendly name for a machine. Some examples of
domain names are www.simonzone.com, www.cnn.com and dot.kde.org. But to use
the internet your
computer still needs to know and use IP addresses. This is where DNS comes
in. It is a system for turning human friendly names like www.simonzone.com
into computer friendly IP addresses. Machines on the internet known as DNS
Servers do nothing except answer queries from other machine about what IP
address belong to which domain name. By using DNS servers your computer knows
what you are talking about when you ask for www.slashdot.org. Without DNS
your web browser won't know where www.cnn.com is, and ICQ chat client won't
be able to connect to the chat network at icq.com either. Without DNS most
other protocols won't work.
</para>
<para>
Lets go through the steps involved for permitting our computer to use the DNS
protocol to communicate with DNS servers on the internet.
</para>
<itemizedlist>
<listitem><para>
First make sure that <guilabel>Internet</guilabel> is selected in the
<guilabel>Defined Network Zones:</guilabel> list. (It's at the top left
corner on the window.) The listbox should have two entries,
<guilabel>Internet</guilabel> and <guilabel>Local</guilabel>.
</para></listitem>
<listitem><para>
Open the <guilabel>Network</guilabel> part of the list view widget in the
center of the window.
It should expand to show more options and checkboxes with entries like
<guilabel>ICMP Redirect</guilabel> and <guilabel>DNS - Domain Name Server
</guilabel>.
</para></listitem>
<listitem><para>
To the right of the list of protocols should be a black box in the
<guilabel>Local</guilabel> column. The box is just a checkbox and you should
click on it until it shows
a check mark (tick). The box has three states, unchecked, checked and crossed.
Just repetively click on it to cycle through the states.
</para></listitem>
</itemizedlist>
<para>
Done. That's all you need to do say that your local machine is permitted to
use DNS to access servers on the Internet. Your screen should look something
like the picture below.
</para>
<para>
<screenshot>
<screeninfo>Reading the protocol tab</screeninfo>
<mediaobject>
<imageobject>
<imagedata fileref="guarddog2_protocol.png" format="PNG"/>
</imageobject>
<textobject>
<phrase>Reading the protocol tab</phrase>
</textobject>
</mediaobject>
</screenshot>
</para>
<para>
This illustration also summarises how to read all of the information presented
on the <guilabel>Protocol</guilabel> tab. There is a lot of information
packed into this one tab, but it is vital that you understand what it means
so that you can avoid misconfiguration.
</para>
</sect2>
<sect2>
<title>Protocol Organisation</title>
<para>
Once we have DNS permitted we can move on to permitting other common protocols
that we might want to use.
</para>
<para>
&kappname; supports many different network protocols. To help organise them
all and make it easier to find what you want, they are divided into
categories. The different categories are:
</para>
<itemizedlist>
<listitem><para>
<guilabel>Chat</guilabel> - Protocols used by chat programs like IRC and ICQ.
</para></listitem>
<listitem><para>
<guilabel>Data Serve</guilabel> - Protocols used by databases and other data sources like time
servers.
</para></listitem>
<listitem><para>
<guilabel>File Transfer</guilabel> - Protocols used to transfers files like HTTP for the Web and FTP.
</para></listitem>
<listitem><para>
<guilabel>Game</guilabel> - Protocols used by games for online multiplayer gaming.
</para></listitem>
<listitem><para>
<guilabel>Interactive Session</guilabel> - Protocols used for working on or
performing actions on a remote system. SSH Secure Shell, telnet and also RPC
protocols are here.
</para></listitem>
<listitem><para>
<guilabel>Mail</guilabel> - Protocols associated with delivering and moving
email. SMTP and POP3 are here.
</para></listitem>
<listitem><para>
<guilabel>Media</guilabel> - Protocols used for delivering multimedia
across the internet in real time.
</para></listitem>
<listitem><para>
<guilabel>Miscellaneous</guilabel> - Other protocols that really didn't fit
under the other categories.
</para></listitem>
<listitem><para>
<guilabel>Network</guilabel> - Protocols related to the direct operation of the
network itself.
</para></listitem>
<listitem><para>
<guilabel>User Defined</guilabel> - Protocols defined by the user on the
<guilabel>Advanced</guilabel> tab appear here.
</para></listitem>
</itemizedlist>
<para>
Naturally there is some overlap and some protocols could easily also be
placed under a different category than the end they are currently in.
</para>
<tip><para>
To quickly get information about a protocol, click on its name. A description
of the protocol will appear in the area to the right side of the window.
</para></tip>
</sect2>
<sect2>
<title>Permitting Common Protocols</title>
<para>
Here is a quick list of the most common protocols that you will probably
want to permit.
</para>
<itemizedlist>
<listitem><para>
HTTP - Used on the World Wide Web to move web pages around. If want to browse
the web you will need this. It's in the <guilabel>File Transfer</guilabel>
category.
</para></listitem>
<listitem><para>
FTP - File Transfer Protocol. Used for uploading and downloading files. Also
commonly used on the web too. If you have seen something like "ftp://" in the
location bar on your web browser, then FTP is being used. FTP is in the
<guilabel>File Transfer</guilabel> category.
</para></listitem>
<listitem><para>
SMTP - Simple Mail Transport Protocol. Used for sending email around the
internet. It's in the <guilabel>Mail</guilabel> category.
</para></listitem>
<listitem><para>
POP3 - Post Office Protocol version 3. Commonly used for picking up and
downloading email from a mailbox located at an ISP. It's in the
<guilabel>Mail</guilabel> category.
</para></listitem>
</itemizedlist>
<warning><para>
Resist any temptation to permit all protocols. The more protocols you permit
the weaker your firewall will be. The idea is to only permit the protocols
you really need, and no more. Don't permit something just in case you might
need it in the future. If you need to permit another protocol in the future
then you can just come back to &kappname; and turn it on.
</para></warning>
</sect2>
<sect2>
<title>Applying your new Firewall</title>
<para>
Changes made in &kappname; don't take effect instantly. To start your new
firewall need to hit the <guibutton>Apply</guibutton> button or the
<guibutton>Ok</guibutton> button (which will also
exit the program once the firewall is in place). This will cause &kappname;
to set up the networking subsystem on your machine with your new firewall
rules. Once you click on the <guibutton>Ok</guibutton> or
<guibutton>Apply</guibutton> button a warning message will
appear to tell you that changing the system's firewall may disrupt existing
network connections. Basically, it not a good idea to be doing anything
important on your network, like an FTP download for example, when you go to
<guibutton>Apply</guibutton> the firewall. <guibutton>Ok</guibutton> the
warning and there will be a few seconds delay
and then you will see a konsole window appear. Once the firewall has been
put in place the message <guilabel>Press return to continue</guilabel> will
appear. If there were errors running the script they will be present in the
konsole window. Press the return key to close the konsole window.
</para>
<para>
Done! Your new firewall should now be in place and working. From now on
whenever your system boots it will automatically be set up to use your
firewall. &kappname; does not have to be constantly running to protect
your computer. As your firewall needs evolve you can just run &kappname;
again and tweak it's settings.
</para>
<tip><para>
To see if your firewall is doing its job you can put it too a bit of a test.
Go over to <ulink url="http://grc.com/">Gibson Research Corporation</ulink> and
head towards the "Shields Up!" area and ask it to "Test My Shields!" or "Probe
My Ports!". It will then scan your machine and give you a report on what it
found. Hopefully it should give you a very positive report.
</para>
</tip>
</sect2>
</sect1>
<sect1 id="tutorial-zones">
<title>Tutorial: Using Zones</title>
<para>
In this tutorial we will build on what we have learnt in the first tutorial
and introduce the concept of <guilabel>Zones</guilabel>.
<guilabel>Zones</guilabel> allow you to precisely control
which protocols are permitted between different groups of computers.
</para>
<sect2>
<title>Introducing Zones</title>
<para>
In &kappname; a zone is just a bunch of IP addresses.
You may recall that IP addresses are like telephone numbers for machines
on the internet. A zone is more or less specifies a group of computers.
Once a zone has been created we can use the <guilabel>Protocol</guilabel>
tab to specify which protocols computers in the zone may use.
</para>
<para>
For example. If know that the people at evil.com are evil and should not be
trusted, we can restrict thier access to our computer by first creating a
zone called "Bad Guys", entering evil.com into that zone and
then going to the <guilabel>Protocol</guilabel> tab and making sure that no
protocols are selected between the "Bad Guys" zone and the "Local" zone. (The
<guilabel>Local</guilabel> zone represents the local machine). This
way we can limit, or even completely block evil.com's access.
</para>
<para>
<screenshot>
<screeninfo>Placing the Bad Guys in a zone and firewalling them out</screeninfo>
<mediaobject>
<imageobject>
<imagedata fileref="guarddog2_zonedia.png" format="PNG"/>
</imageobject>
<textobject>
<phrase>Placing the Bad Guys in a zone and firewalling them out.</phrase>
</textobject>
</mediaobject>
</screenshot>
</para>
</sect2>
<sect2>
<title>Editing Zones</title>
<para>
Zones are specified and edited on the <guilabel>Zone</guilabel> tab.
To the left of the <guilabel>Zone</guilabel> tab is the list of
zones that have been defined.
&kappname; has two built in zones that you can't change. They are
<guilabel>Local</guilabel> and <guilabel>Internet</guilabel>.
<guilabel>Local</guilabel> is a zone simple containing the local machine,
the machine that &kappname; is running on. <guilabel>Internet</guilabel>
corresponds to any IP address that's not in another zone. Put simply, if a
IP address is not in another zone it is assumed to be in the
<guilabel>Internet</guilabel> zone.
</para>
<para>
The properties for the currently selected zone are displayed to the right of
the zone list. Each zone has a name. The zone's name is used on the
<guilabel>Protocol</guilabel> tab and should be kept short. A more
descriptive comment can also be given to a zone.
</para>
<para>
The list of IP addresses that make up the zone are in the
<guilabel>Zone Addresses</guilabel> list.
</para>
<para>
To the right of the window is the <guilabel>Connection</guilabel> list. Here
it is possible to specify which other zones the current zone should be able to
communicate with.
</para>
<para>
<screenshot>
<screeninfo>The Zone tab.</screeninfo>
<mediaobject>
<imageobject>
<imagedata fileref="guarddog2_zones.png" format="PNG"/>
</imageobject>
<textobject>
<phrase>The Zone tab.</phrase>
</textobject>
</mediaobject>
</screenshot>
</para>
<warning><para>
An IP address should only be in one zone at a time.
</para></warning>
</sect2>
<sect2>
<title>Creating a Demilitarised Zone</title>
<para>
Let's put zones to work.
</para>
<para>
A good use of zones is to harden our firewall by setting up a "Demilitarised
Zone" (DMZ). In network security a DMZ is a bunch of computers that are
located inbetween the internet and an organisation's internal computer
network. Computers in the DMZ are exposed to the internet and are usually
performing tasks like serving web pages to the internet or handling email.
Since these machines are exposed to the internet and constant attack from
outside, they are given limited access to the internal network. If an
attacker gains control of a machine in the DMZ they don't automatically gain
extra access to the internal network.
</para>
<para>
Even if you are not managing an internal network or a group of web servers
or mail servers, you probably do make use of a group of computers that could
be considered to be in a DMZ. For this tutorial we will set up a DMZ containing
the mail server you use for sending and receiving email from.
</para>
<para>
First go to the Zone tab and click on the <guibutton>New Zone</guibutton>
button to create a new zone. The new zone will be appear in the list of zones
and will, oddly enough, be called <guilabel>new zone</guilabel>. Go up to the
<guilabel>Name</guilabel> text box and change <guilabel>new zone</guilabel> to
say "DMZ". The name should be fairly short, but you can put a more
descriptive comment in the comment text box.
</para>
<para>
Over to the right is the <guilabel>Connection</guilabel> list. It is just a
group of checkboxes that let you specify which other zones the current zone
is connected to. Put a tick in <guilabel>Local</guilabel> checkbox to
indicate that the <guilabel>DMZ</guilabel> zone is connected to the
<guilabel>Local</guilabel> zone/machine. The combination of
<guilabel>DMZ</guilabel> and Local zone will only be available on the
<guilabel>Protocol</guilabel> tab when this checkbox is ticked.
</para>
<para>
Now move over to the <guilabel>Protocol</guilabel> tab and make sure that
<guilabel>Protocols Served from Zone:</guilabel> is set to
<guilabel>DMZ</guilabel>. In the protocol list below there should be a
column called <guilabel>Local</guilabel>. Open up the
<guilabel>Mail</guilabel> group of protocols and tick
<guilabel>POP2</guilabel>, <guilabel>POP3</guilabel>, and
<guilabel>SMTP</guilabel>. The first two are used by to fetch mail from a
mail box on a mail server. SMTP is used for sending mail. By turning these
on for <guilabel>Local</guilabel> we are saying that we want the local machine
to be allowed to use these mail protocols with the machines in the
<guilabel>DMZ</guilabel>.
</para>
<para>
If the machines in your DMZ are also web servers you may also want to turn on
HTTP, FTP and some other common protocols.
</para>
<para>
Once you have finished configuring Guarddog, <guibutton>Apply</guibutton>
your changes and test your email program to see if you can still send and
receive email.
</para>
</sect2>
</sect1>
<sect1 id="tutorial-router">
<title>Tutorial: Router Configuration</title>
<para>
So far we have only used &kappname; to protect a single workstation (i.e. the
one &kappname; is running on), but as many people know a Linux box can also
act as a fantastic router for connecting multiple networks. In this
tutorial we will go through how &kappname; can be used on a machine acting as a
gateway to protect a LAN placed behind the gateway from the internet.
</para>
<important><para>&kappname; only supports router configurations on machines
running Linux kernel series 2.4 with <command>iptables</command>.
</para></important>
<sect2>
<title>Anatomy of a typical LAN connected to the Internet</title>
<para>
<screenshot>
<screeninfo>A typical router or gateway configuration with &kappname; running on the router system.</screeninfo>
<mediaobject>
<imageobject>
<imagedata fileref="guarddog2_routerdia.png" format="PNG"/>
</imageobject>
<textobject>
<phrase>A typical router configuration with &kappname; running on the router system.</phrase>
</textobject>
</mediaobject>
</screenshot>
</para>
<para>
The diagram above shows the network configuration of a typical LAN connected
to the Internet via a Linux based system acting as a router.
On the left side of the diagram is our LAN that we wish to protect. The
Internet is shown on the right hand side. All communication between the LAN
and Internet passes through the gateway machine which is marked with the dog.
&kappname; runs on the gateway machine. The most important aspect of this
setup from a security point of view is that all of the traffic between the
LAN and the Internet passes through one machine: the gateway. This provides
us with an obvious "choke point" that we can use to place the firewall to
filter the traffic.
</para>
<para>
The diagram also shows the zones that we will implement in &kappname;.
</para>
</sect2>
<sect2>
<title>"Repeat after me: &kappname; is a firewall"</title>
<para>
There seems to be a bit of confusion surrounding the function of a firewall
versus the task of packet routing. Firewalls act as network traffic
<emphasis>filters</emphasis>. Filtering and blocking unwanted and dangerous
network traffic. They are security devices. Features such as routing and
IP masquerade are not primarily security devices. They are networking
features.
</para>
<note>
<para>
This misconception arised because in the past (before Linux kernel series 2.4)
on Linux the networking system was such that it wasn't possible to separate
advanced routing functionality from normal firewall functionality. This lead
to firewall programs that also included direct support for advanced routing
features such as IP masquerade, port forwarding etc.
</para>
</note>
<para>
&kappname; is a firewall and can not be used for configuring networking
features such as IP masquerade and routing. These networking features must
be configured outside of &kappname;.
</para>
<tip>
<para>
<ulink url="http://www.simonzone.com/software/guidedog/">Guidedog</ulink>
is a user friendly utility for configuring advanced networking features
and is designed to work along side &kappname;.
</para>
</tip>
</sect2>
<sect2>
<title>Configure Routing and Network Settings</title>
<para>
Before we continue you should go configure the routing setup for your machine
and confirm that it is routing/masquerading network traffic as expected.
To make the task of debugging your gateway configuration easier, you can
disable &kappname; by checking the <guilabel>Disable firewall</guilabel>
checkbox on the <guilabel>Advanced</guilabel> tab and then applying the
changes. This will allow you to test
your routing setup separately without &kappname; blocking any test traffic.
</para>
<warning>
<para>
I strongly recommend that you do not debug your network setup while connected
to a hostile network like the Internet. Attach a machine to the network card
that you plan to connect to the internet and give it an IP so that it can
act as a pretend Internet.
</para>
</warning>
</sect2>
<sect2>
<title>Teaching &kappname; to Allow Traffic to/from your LAN</title>
<para>
If your configured and tested your routing and network settings with
&kappname; disabled, go enable &kappname; again and apply the changes.
If all is going well then you should find that your LAN is once again
totally cut off from the internet. &kappname; has a fail-safe, "what is not
explicitly permitted is denied" design. What this means in this situation
is that since &kappname; hasn't been told to allow traffic from your LAN
out to the internet, or visa versa, it will assume that the traffic should
be blocked. This is intended to make it easy to get a secure configuration
(even if it is too secure) and difficult to have an insecure configuration.
</para>
<para>
The way we specify to &kappname; that computers on your LAN are allowed to
access computers on the Internet is done using zones. We simply create a zone
to hold the addresses of all of the computers on our LAN and then specify that
this zone is connected to the Internet and probably the Local, and then go to
the <guilabel>Protocols</guilabel> tab and tick on which protocols should be
allowed between the LAN and the Internet.
</para>
</sect2>
<sect2>
<title>Step by Step</title>
<para>
Go over to the <guilabel>Zone</guilabel> tab and create a new zone and call
it LAN. In the <guilabel>Zone Addresses</guilabel> list enter the IP
addresses of the computers on your LAN.
The address list understands several notations for addresses and can also
accept whole network blocks. If you are running an IP masqueraded network
with 192.168.1.0/255.255.255.0 private address space, you can enter the block
into a single address line in 192.168.1.0/255.255.255.0 format or the shorter
192.168.1.0/24 format.
</para>
<para>
Go to the <guilabel>Connection</guilabel> list and tick
<guilabel>Internet</guilabel> and <guilabel>Local</guilabel> to specify that
your LAN zone should be connected to the <guilabel>Internet</guilabel> and
<guilabel>Local</guilabel> zones.
</para>
<para>
Now, go to the <guilabel>Protocol</guilabel> tab and make sure that
<guilabel>Protocols Served from Zone:</guilabel> is set to
<guilabel>Internet</guilabel>. In the list of protocols below you should see
a column of checkbox for the <guilabel>Local</guilabel> zone and another row
for the <guilabel>LAN</guilabel> zone.
Just like when we were turning on protocols for the local zone in the first
tutorial, we can do the same for the LAN zone. Tick the protocols in the list
that machines in the LAN zone should be able to use with the Internet.
</para>
<para>
When you're ready, apply the changes and see if your LAN can access the
internet. That's all there is to it.
</para>
</sect2>
</sect1>
<sect1 id="specific-protocols">
<title>Important Notes</title>
<para>
Here are some important notes concerning the use of some protocols.
</para>
<sect2>
<title>Windows Networking (NETBIOS)</title>
<para>
[If you want to use NETBIOS on a zone (typically holding a LAN) make sure you
add the broadcast address to the zone address list.]
</para>
</sect2>
<sect2>
<title>Nmap and Nessus Scanning</title>
<para>
[doesn't/can't work. Can't really allow it without totally opening up your firewall and make ]
</para>
</sect2>
<sect2>
<title>Telstra BigPond Cable</title>
<para>
[Users in Australia connecting to the net via Telstra's BibPond cable.
the bloody heartbeat. Use the BigPond protocol, put the dce-server]
</para>
</sect2>
</sect1>
<!--
<sect1 id="guarddog-features">
<title>More Guarddog features</title>
<para>It slices! It dices! and it comes with a free toaster!</para>
<para>
The Squiggle Tool <guiicon><inlinemediaobject>
<imageobject>
<imagedata fileref="squiggle.png" format="PNG">
</imageobject>
<imageobject>
<imagedata fileref="squiggle.eps" format="EPS">
</imageobject>
<textobject>
<phrase>Squiggle</phrase>
</textobject>
</inlinemediaobject></guiicon> is used to draw squiggly lines all over
the &kappname; main window. It's not a bug, it's a feature!
</para>
</sect1>
-->
</chapter>
<!--
***************************************************************************
* Program Reference *******************************************************
***************************************************************************
-->
<chapter id="commands">
<title>Program Reference</title>
<sect1 id="guarddog-zonetab">
<title>The Zone Tab</title>
<para>
&kappname; is built around the concept of zones containing IP
addresses, and then managing which network protocols are permited
between the different zones. This tab is where zones and thier contents
are managed.
</para>
<para>
The list of currently defined zones is on the left side of the tab under
<guilabel>Defined Network Zones:</guilabel>. The properties of the currently
selected zone are shown in the <guilabel>Zone Properties</guilabel> area.
The <guibutton>New Zone</guibutton> and <guibutton>Delete Zone</guibutton>
buttons in the bottom left corner of the tab allow you to create new zones
or delete the currently selected zone.
</para>
<para>
There are two zones which are built-in and can not be modifed or
deleted. They are called the <guilabel>Internet</guilabel> and
<guilabel>Local</guilabel> zones. The <guilabel>Local</guilabel> zone
automatically contains the IP addresses of the network interfaces for the
machine that the firewall runs on. The <guilabel>Internet</guilabel> zone
automatically contains the IP addresses of anything that is not in another
zone. (i.e. it acts as the default zone holding addresses that are not in
any other zone).
</para>
<para>
Each zone has a name that can be edited in the <guilabel>Name:</guilabel>
text edit box. It is recommended that this be kept relatively brief. A longer
comment can be entered for each zone in the <guilabel>Comment:</guilabel>
text edit box.
</para>
<sect2>
<title>Addresses</title>
<para>
Each zone consists of a number of IP addresses. The <guilabel>Zone Addresses</guilabel>
list holds the list of IP addresses for the currently selected zone.
Addresses can be added to the list by using the <guibutton>New Address</guibutton>
button, or the currently selected address can be deleted using the <guibutton>Delete Address</guibutton>
button. The text edit box next to <guilabel>Address:</guilabel>, allows you
to edit the currently selected address.
</para>
<para>
Addresses and ranges of addresses can be specified in several ways:
</para>
<itemizedlist>
<listitem>
<para>Numeric IP address (dotted quad). Whole networks can be specified by
using a mask. Masks can be network masks (e.g. 255.255.255.0) or a plain number
(e.g. 24). Some examples would be: 123.34.56.78, 192.168.1.1/24 and
192.168.1.1/255.255.255.0</para>
</listitem>
<listitem>
<para>Domain name. Only Fully Qualitied Domain Names (FQDN) are allowed,
something like .simonzone.com will not work. A complete name is required,
like www.simonzone.com, for example.</para>
</listitem>
</itemizedlist>
</sect2>
<sect2>
<title>Connection</title>
<para>The <guilabel>Connection</guilabel> list allows you to specify which
other zones the currently selected zone is connected to. When a zone is
connected to another zone, that particular combination will appear on the
<guilabel>Protocol</guilabel> tab. If a combination is not selected here
then it won't appear on the <guilabel>Protocol</guilabel> tab, and no
communication will be permitted between the two zones.
</para>
</sect2>
<!--
<sect2>
<title>The File Menu</title>
<para>
<variablelist>
<varlistentry>
<term><menuchoice>
<shortcut>
<keycombo><keycap>Ctrl</keycap><keycap>n</keycap></keycombo>
</shortcut>
<guimenu>File</guimenu>
<guimenuitem>New</guimenuitem>
</menuchoice></term>
<listitem><para><action>Creates a new document</action></para></listitem>
</varlistentry>
<varlistentry>
<term><menuchoice>
<shortcut>
<keycombo><keycap>Ctrl</keycap><keycap>s</keycap></keycombo>
</shortcut>
<guimenu>File</guimenu>
<guimenuitem>Save</guimenuitem>
</menuchoice></term>
<listitem><para><action>Saves the document</action></para></listitem>
</varlistentry>
<varlistentry>
<term><menuchoice>
<shortcut>
<keycombo><keycap>Ctrl</keycap><keycap>q</keycap></keycombo>
</shortcut>
<guimenu>File</guimenu>
<guimenuitem>Quit</guimenuitem>
</menuchoice></term>
<listitem><para><action>Quits</action> &kappname;</para></listitem>
</varlistentry>
</variablelist>
</para>
</sect2>
-->
</sect1>
<sect1 id="guarddog-protocoltab">
<title>The Protocol Tab</title>
<para>
The <guilabel>Protocol</guilabel> tab is used to specify which protocols are
permitted between which combinations of zones.
</para>
<para>
To the left of the tab is the <guilabel>Defined Network Zones:</guilabel>
list holding every zone currently defined. The <guilabel>Zone Properties</guilabel>
area shows which protocols or services the currently selected zone is
permitted to serve and to whom. We will refer to the currently selected zone
as the serving zone.
</para>
<para>
The expandable list of protocols is organised into ten categories:
</para>
<itemizedlist>
<listitem><para>
Chat - Protocols used by chat programs like IRC and ICQ.
</para></listitem>
<listitem><para>
Data Serve - Protocols used by databases and other data sources like time
servers.
</para></listitem>
<listitem><para>
File Transfer - Protocols used to tranfers files like HTTP for the Web and FTP.
</para></listitem>
<listitem><para>
Game - Protocols used by games for online multiplayer gaming.
</para></listitem>
<listitem><para>
Interactive Session - Protocols used for working on or performing actions on
a remote system. SSH Secure Shell, telnet and also RPC protocols are here.
</para></listitem>
<listitem><para>
Mail - Protocols associated with delivering and moving email. SMTP and POP3
are here.
</para></listitem>
<listitem><para>
Media - Protocols used for delivering multimedia across the internet in real
time.
</para></listitem>
<listitem><para>
Miscellaneous - Other protocols that really didn't fit under the other
categories.
</para></listitem>
<listitem><para>
Network - Protocols related to the direct operation of the network inself.
</para></listitem>
<listitem><para>
User Defined - Protocols defined by the user on the "Advanced" tab show up
here.
</para></listitem>
</itemizedlist>
<para>
To the right of each protocol entry in the list may be one or more columns
of checkboxes. Each zone that the serving zone is connected to has a
column on checkboxes. The name of the zone is at the top of the column.
The zones/columns which appear here is determined by the <guilabel>Connection</guilabel>
list on the <guilabel>Zone</guilabel> tab for the currently selected zone.
</para>
<para>
The checkboxes have the following means:
</para>
<itemizedlist>
<listitem><para>Clear - The protocol is not permitted. Clients in this zone
may not start a connection to the serving zone using this protocol. For
example, if "Web Servers" is the currently selected serving zone, and the
HTTP (Web) protocol box is clear for the "Bad Guys" zone, then machines in
the "Bad Guys" zone will not be allowed to access a web server running on a
machine in the "Web Servers" zone. Any attempt will be completely ignored.
Any incoming packets will be dropped.
</para></listitem>
<listitem><para>Checked/Ticked - The protocol is permitted. Clients in this
zone may start a connection to the serving zone using this protocol. For
example, if "Web Servers" is the currently selected serving zone, and the
HTTP (Web) protocol box is ticked for the "Bad Guys" zone, then machines in
the "Bad Guys" zone will be allowed to access a web server running on a
machine in the "Web Servers" zone.</para></listitem>
<listitem><para>Crossed - The protocol is not permitted and packets will be
rejected instead of just dropped. When a packet is rejected an ICMP packet
is sent back to the source to inform it that the packets was rejected by the
firewall. For example, if "Web Servers" is the currently selected serving
zone, and the HTTP (Web) protocol box is crossed for the "Bad Guys" zone, then
machines in the "Bad Guys" zone will not be allowed to access a web server
running on a machine in the "Web Servers" zone. But unlike when the checkbox
is unticked and blank, any connection attempts will be rejected instead of
ignored.</para></listitem>
</itemizedlist>
<para>This information is summerised at the bottom of the tab in a concise
key or legend show each of the different checkbox states.</para>
<tip>
<para>
Rejecting a protocol is considered a more "friendly" way of blocking it's use,
because the sender is immediately informed about what has happened. When a
packet is quietly blocked by the firewall, the sender will not know and will
have to wait and "time out" before realising that communication has failed.
</para>
<para>
Generally there is little reason to reject protocols instead of just having
them dropped. If someone is trying to use a protocol that you didn't allow,
then for safety's sake we should assume that they are hostile and therefore
shouldn't be helped. In this situation, dropping packets is better because
it uses less network capacity and has the effect of making most port scanners
run very slowly.
</para>
<para>
The only situation that you are likely to run into where rejecting a protocol
is desirable, is with the "ident" protocol. When connecting to many mail
or IRC servers when connected to, use the "ident" protocol to try to find out
owner of the incoming connection, and don't respond to the incoming
connection until they have tried "ident". This problem shows up, for example,
as delays when connecting to mail servers. The connection will be made with
the mail server, but there will be a noticeable delay before any mail is
retrieved. This is because the server tries to make an "ident" connection
back, but has wait and time out before realising that it won't work. The
solution is to just make sure that "ident" is being rejected for connections
coming from the zone containing the mail server.
</para>
</tip>
<sect2>
<title>Protocol Information</title>
<para>
Information about a protocol is displayed on the botton left side of the tab.
You can get information about any of the protocols in the list just by
clicking on it's title.
</para>
<para>
The following information is available about each protocol:
</para>
<itemizedlist>
<listitem><para>Name - The name of the protocol. It's fully name and also any
acronym it may be known by.</para></listitem>
<listitem><para>Description - A short description of what the protocol is
used for.</para></listitem>
<listitem><para>Security Risk - An estimate of the security risk that use of
the protocol has. The risk ranges from low, medium, high or unknown.
</para></listitem>
<listitem><para>Network Usage - This is a description of how the protocol
uses the network. It describes which connections, IP protocols and port
ranges etc the protocol uses to operate. This field is only shown if the
<guilabel>Show Advanced Protocol Help</guilabel> checkbox is check on the
<guilabel>Advanced</guilabel> tab.
</para></listitem>
</itemizedlist>
</sect2>
</sect1>
<sect1 id="guarddog-loggingtab">
<title>The Logging Tab</title>
<para>The <guilabel>Logging</guilabel> tab holds many options for controlling
what things to log and how to log them.</para>
<para>The <guilabel>Log blocked packets</guilabel> checkbox controls whether
packets that are blocked by &kappname; are logged in the system log. A packet
that is not part of a permitted protocol is by blocked by default. When this
checkbox is ticked, blocked packets are logged.</para>
<para>The <guilabel>Log rejected packets</guilabel> checkbox controls whether
packets that are rejected by &kappname; are logged in the system log.
Protocols are marked to be rejected on the <guilabel>Protocol</guilabel>
tab by putting a cross checkbox in their checkbox. When this checkbox is
ticked, any rejected packets are logged.</para>
<para>The <guilabel>Log aborted TCP connections (half open scans)</guilabel>
checkbox controls whether TCP connections that are forcefully terminated using
a RST packet are logged. A port scanning technique know as "half-open"
scanning uses RST packets to quickly abort an half open TCP connection in
order to avoid being logged. This can be done using <command>nmap</command>'s
<option>-sS</option> option. By
turning this option on you can detect and log when this happens. Unfortunately
many web servers like to quickly terminate connections by using a RST packet.
This can produce quite a lot of unwanted noise in your system logs. Therefore
you may want to turn this option off. Also, this option only has effect when
the firewall is used on a Linux kernel 2.4 or higher machine.</para>
<tip>
<para>[Where is stuff logged to?]</para>
</tip>
<sect2>
<title>Rate Limiting</title>
<para>This group of options allow you to specify how &kappname; should limit
the rate at which messages are placed in the system log. Rate Limited logging
is intended to stop someone from performing a Denial of Service against your
machine by flooding it packets and trying to fill your log files and disk
space.</para>
<para>The <guilabel>Rate limit logging</guilabel> controls whether packet
logging should be rate limited at all. Turning this is off is not
recommended.</para>
<para>The <guilabel>Rate</guilabel> widget allows you to specify the average
maximum rate that packet log entries may be added to the system log. The rate
may be specified in terms of the number of entries per second, minute, hour or
day.</para>
<para>The <guilabel>Rate</guilabel> widget allows you to specify
<emphasis>average</emphasis> logging rate. Packets needing to be logged often
come as a burst of many packets in very quick succession. The <guilabel>Burst</guilabel>
widget allows you to specify how packets in a burst may be logged. Once the
burst limit has been reached, the average logging rate is enforced.</para>
<tip><para>For more information on exactly how this works, consult the
<command>iptables</command> documentation and the Linux kernel source
<filename>/net/ipv4/netfilter/ipt_limit.c</filename> file.
</para></tip>
<para>The <guilabel>Warn when limiting</guilabel> checkbox controls whether
&kappname; should put warning messages in the system log when it has been
forced to apply rate limiting to the packet log messages. When rate limiting
is applied to packet log messages, only a limited number of messages appear
in the log, while the rest are omitted. When you come to view the system log,
it useful to know if packet log messages have been omitted due to rate limiting.
</para>
<para>The <guilabel>Warning rate</guilabel> widget allows you to specify how
often warning messages should be placed in the system log when rate limiting
is being used.
</para>
<tip><para>The warning messages in the system log have the word
<literal>LIMITED</literal> at the start of the line.</para></tip>
</sect2>
<sect2>
<title>Logging Options</title>
<para>The <guilabel>Log IP Options</guilabel> checkbox controls whether the
options field in the IP header of a packet should be included in a packet log
message.</para>
<para>The <guilabel>Log TCP Options</guilabel> checkbox controls whether the
options field in the TCP header of a packet should be included in a packet
log message.</para>
<para>The <guilabel>Log TCP sequence numbers</guilabel> checkbox controls
whether the TCP sequence number for a packet should be included in a packet
log message.</para>
<para>The <guilabel>Logging Priority</guilabel> selector specifies the logging
priority used when sending log messages to the system log. See the
documentation for <filename>syslog.conf</filename> for more information.
</para>
</sect2>
</sect1>
<sect1 id="guarddog-advancedtab">
<title>The Advanced Tab</title>
<para>The <guilabel>Advanced</guilabel> tab holds many miscellaneous advanced
options. Here you can also set up your own simple protocols for opening a
small hole through your firewall to support an <emphasis>ad hoc</emphasis>
protocol. For example, accessing a remote administration web interface that
is served from a non-standard port number.</para>
<para>When the <guilabel>Show advanced protocol help</guilabel> checkbox is
ticked, extra information is given for the help text for protocols on the
<guilabel>protocol</guilabel> tab. The extra information includes the kinds
of network connections the protocols uses.</para>
<para>The <guilabel>Allow TCP timestamps</guilabel> checkbox lets you turn
TCP timestamps on or off. Leaving TCP timestamps turned on makes it possible
for outsiders to calculate how long your machine has been running since it
was last booted. <command>nmap</command> <option>-O</option> can do this.
Generally, unless you are connected to a high speed network connection chances
are you have no good reason to have TCP timestamps turned on.</para>
<para>The <guilabel>Restore to factory defaults</guilabel> clears the
firewall configuration and resets it back to how it was the first time
&kappname; was run.</para>
<sect2>
<title>Local Dynamic Port Range</title>
<para>The two input widgets next to <guilabel>Local Dynamic Port Range</guilabel>
allows you to specify the range of port numbers used by the operating system
for the source port of new out going connection. When a connection is made to
a port on an external machine, the source port of the connection is usually
specified by the application. It is left up to the operating system to choose
a suitable free source port number. The local dynamic port range is just range
of port numbers that the operating system will look in whether finding an
available source port.</para>
<para>Generally, there is little reason to change this. It might only become
important on machines that need to have an unusually high number of
connections active at the same time.</para>
</sect2>
<sect2>
<title>DHCP (Dynamic Host Configuration Protocol)</title>
<para>If you are using DHCP to configure an network interface, then you will
need to specify the name of the interface in the <guilabel>Enable DHCP on
interface:</guilabel> widget.</para>
<para>If you are running a DHCP server on an network interface, then you will
need to specify the name of the interface in the <guilabel>Enable DHCP server
on interface:</guilabel> widget.</para>
<para>Currently DHCP is limited to a single interface. This limitation will
be removed in a future version of &kappname;</para>
</sect2>
<sect2>
<title>Import/Export</title>
<para><guilabel>Import</guilabel> and <guilabel>Export</guilabel> allow you
to save the current configuration to a file, and read it back into &kappname;
again. When you click on either of these buttons, a file dialog appears where
you can choose the file to import from, or export to.</para>
<para>The <guilabel>Description</guilabel> text box allows you enter any short
notes about the current firewall configuration</para>
<tip><para><guilabel>Export</guilabel> doesn't just export the current
firewall configuration, it actually outputs an entire firewall script.
The firewall script can then be moved onto another machine and manually
installed. [Need more info here]</para></tip>
</sect2>
<sect2>
<title>User Defined Protocols</title>
<para>In addition to all the protocols that &kappname; supports, it is also
possible to specify your own custom protocols.</para>
<para>In the middle of the <guilabel>User Defined Protocols</guilabel>
group is the list of current user defined protocols. Use the <guilabel>New
Protocol</guilabel> button to create a new blank protocol. The <guilabel>Delete
Protocol</guilabel> button naturally deletes the currently selected user
defined protocol.</para>
<para>After creating a new protocol you can give it a name using the
<guilabel>Name</guilabel> text box. The <guilabel>Type</guilabel> widget lets
you specify what IP protocol your user defined protocol uses. You have the
choice between TCP and UDP. In the <guilabel>Port</guilabel> widget you
specify the TCP or UDP port on the server or remote machine that the
protocol must connect to. For UDP protocols use the
<guilabel>bidirectional</guilabel> checkbox to specify if the protocol is
bidirectional and requires packets to travel in both directions. Once a
user defined protocol has been specified here , it becomes available on the
<guilabel>Protocol</guilabel> tab under the <guilabel>User Defined</guilabel>
protocol category. There it can be turned on or off just like any other
built-in protocol.</para>
<tip><para>This feature is intended for simple protocols where a server is
just serving from a single TCP or UDP port. If you feel that you need to
specify a more complex protocol, consider contacting the author so that
direct support for it can be added in a future &kappname; release.</para></tip>
</sect2>
</sect1>
</chapter>
<!--
<chapter id="developers">
<title>Developer's Guide to Guarddog</title>
<para>
Programming &guarddog; plugins is a joy to behold. Just read through the next
66 pages of API's to learn how!
</para>
<refentry id="re-1007-unmanagechildren-1">
<refmeta>
<refentrytitle>XtUnmanageChildren</refentrytitle>
<refmiscinfo>Xt - Geometry Management</refmiscinfo>
</refmeta>
<refnamediv>
<refname>XtUnmanageChildren
</refname>
<refpurpose>remove a list of children from a parent widget's managed list.
</refpurpose>
<indexterm id="ix-1007-unmanagechildren-1"><primary>widgets</primary><secondary>removing</secondary></indexterm>
<indexterm id="ix-1007-unmanagechildren-2"><primary>XtUnmanageChildren</primary></indexterm>
</refnamediv>
<refsynopsisdiv>
<refsynopsisdivinfo>
<date>4 March 1996</date>
</refsynopsisdivinfo>
<synopsis>
void XtUnmanageChildren(<replaceable parameter>children</replaceable>, <replaceable parameter>num_children</replaceable>)
WidgetList <replaceable parameter>children</replaceable>;
Cardinal <replaceable parameter>num_children</replaceable>;
</synopsis>
<refsect2 id="r2-1007-unmanagechildren-1">
<title>Inputs</title>
<variablelist>
<varlistentry>
<term><replaceable parameter>children</replaceable>
</term>
<listitem>
<para>Specifies an array of child widgets. Each child must be of
class RectObj or any subclass thereof.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable parameter>num_children</replaceable>
</term>
<listitem>
<para>Specifies the number of elements in <replaceable parameter>children</replaceable>.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect2></refsynopsisdiv>
<refsect1 id="r1-1007-unmanagechildren-1">
<title>Description
</title>
<para><function>XtUnmanageChildren()</function> unmaps the specified widgets
and removes them from their parent's geometry management.
The widgets will disappear from the screen, and (depending
on its parent) may no longer have screen space allocated for
them.
</para>
<para>Each of the widgets in the <replaceable parameter>children</replaceable> array must have
the same parent.
</para>
<para>See the “Algorithm” section below for full details of the
widget unmanagement procedure.
</para>
</refsect1>
<refsect1 id="r1-1007-unmanagechildren-2">
<title>Usage</title>
<para>Unmanaging widgets is the usual method for temporarily
making them invisible. They can be re-managed with
<function>XtManageChildren()</function>.
</para>
<para>You can unmap a widget, but leave it under geometry
management by calling <function>XtUnmapWidget()</function>. You can
destroy a widget's window without destroying the widget by
calling <function>XtUnrealizeWidget()</function>. You can destroy a
widget completely with <function>XtDestroyWidget()</function>.
</para>
<para>If you are only going to unmanage a single widget, it is
more convenient to call <function>XtUnmanageChild()</function>. It is
often more convenient to call <function>XtUnmanageChild()</function>
several times than it is to declare and initialize an array
of widgets to pass to <function>XtUnmanageChildren()</function>. Calling
<function>XtUnmanageChildren()</function> is more efficient, however,
because it only calls the parent's <function>change_managed()</function>
method once.
</para>
</refsect1>
<refsect1 id="r1-1007-unmanagechildren-3">
<title>Algorithm
</title>
<para><function>XtUnmanageChildren()</function> performs the following:
</para>
<variablelist>
<varlistentry>
<term>-
</term>
<listitem>
<para>Ignores the child if it already is unmanaged or is being
destroyed.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>-
</term>
<listitem>
<para>Otherwise, if the child is realized, it makes it nonvisible
by unmapping it.
</para>
</listitem>
</varlistentry>
</variablelist>
<para>
</para>
</refsect1>
<refsect1 id="r1-1007-unmanagechildren-4">
<title>Structures</title>
<para>The <type>WidgetList</type> type is simply an array of widgets:
</para>
<screen id="sc-1007-unmanagechildren-1">typedef Widget *WidgetList;
</screen>
</refsect1>
</refentry>
</chapter>
-->
<chapter id="faq">
<title>Questions and Answers</title>
&reporting.bugs;
&updating.documentation;
<qandaset id="faqlist">
<qandaentry>
<question>
<para>Does &kappname; need to be running for it to protect my computer?</para>
</question>
<answer>
<para>&kappname; provides a user friendly way of configuring your computer's
built-in firewalling capabilities. &kappname; doesn't itself need to be
running continously per se.</para>
</answer>
</qandaentry>
</qandaset>
</chapter>
<chapter id="credits">
<title>Credits and License</title>
<para>
&kappname;
</para>
<para>
Program copyright 2000-2002 Simon Edwards <email>simon@simonzone.com</email>
</para>
<para>
Documentation copyright 2000-2002 Simon Edwards <email>simon@simonzone.com</email>
</para>
&underFDL; <!-- FDL: do not remove -->
<!-- Determine which license your application is licensed under,
and delete all the remaining licenses below:
(NOTE: All documentation are licensed under the FDL,
regardless of what license the application uses) -->
&underGPL; <!-- GPL License -->
</chapter>
<appendix id="installation">
<title>Installation</title>
<sect1 id="getting-guarddog">
<title>How to obtain Guarddog</title>
<para>
&kappname; can be found a
<ulink url="http://www.simonzone.com/software/guarddog/">http://www.simonzone.com/software/guarddog/</ulink>.</para>
</sect1>
<!--
<sect1 id="requirements">
<title>Requirements</title>
<para>
In order to successfully use &kappname;, you need KDE 2.0. Foobar.lib is required
in order to support the advanced &kappname; features. &kappname; uses about 5 megs of
memory to run, but this may vary depending on your platform and
configuration.
</para>
<para>
All required libraries as well as &guarddog; itself can be found
on <ulink url="ftp://ftp.guarddog.org">The &guarddog; home page</ulink>.
</para>
<para>
You can find a list of changes at <ulink
url="http://apps.kde.org/guarddog">http://apps.kde.org/guarddog</ulink>.
</para>
</sect1>
<sect1 id="compilation">
<title>Compilation and installation</title>
<para>
In order to compile and install KApp on your system, type the following in the base
directory of the Icon Editor distribution:
<screen width="40">
<prompt>%</prompt> <userinput>./configure</userinput>
<prompt>%</prompt> <userinput>make</userinput>
<prompt>%</prompt> <userinput>make install</userinput>
</screen>
</para>
<para>Since KApp uses autoconf and automake you should have not trouble compiling it.
Should you run into problems please report them to the KDE mailing lists.</para>
</sect1>
<sect1 id="configuration">
<title>Configuration</title>
<para>Don't forget to tell your system to start the <filename>dtd</filename>
dicer-toaster daemon first, or KApp won't work !</para>
</sect1>
-->
</appendix>
&documentation.index;
</book>
<!--
Local Variables:
mode: sgml
sgml-minimize-attributes: nil
sgml-general-insert-case: lower
End:
-->
