---------------------------------------------------------------------------
   README for fireflier
   Author: Martin Maurer, Klaus Triendl

   We are searching for someone, that is willing to improve the 
   documentation of this project. We use our limited time mostly 
   for improving and extending the features of fireflier, so anyone who 
   wants to step in and do some improvements to the documentation, 
   create additional documentation, ... (web page, man pages,
   this README, ...) please send us an email.
---------------------------------------------------------------------------

0.) Get source code
  http://sourceforge.net

1.) Quick install guide
1.1) fireflier-server
 - change to fireflier-xxxx/server
 - ./configure
 - make
 - make install
 - prepare your kernel for fireflier. 
   You will need the following kernel options: 
       - Code maturity level options -> 
           -> Prompt for development and/or incomplete code/drivers 
	      (CONFIG_EXPERIMENTAL)
           This options is needed for CONFIG_IP_NF_QUEUE (see below).
           Please notice, that the ip_queue module (which is needed by
           fireflier) is marked as experimental, and so it may happen,
           that it does not work.
	 
       - Network options -> Network packet filtering (CONFIG_NETFILTER)
       - Network options -> IP: Netfilter configuration -> 
           -> Userspace queueing via netlink (CONFIG_IP_NF_QUEUE)
       - Network options -> IP: Netfilter configuration -> 
           -> IP Tables support (CONFIG_IP_NF_IPTABLES)
       - Network options -> IP: Netfilter configuration -> 
           -> Connection state match support (CONFIG_IP_NF_MATCH_STATE)
       - Network options -> IP: Netfilter configuration -> 
 	   -> Packet filtering (CONFIG_IP_NF_FILTER)
       
     verify that ip_queue kernel module is loaded (or ip_queue is compiled 
     into the kernel)
 - start server: /usr/local/sbin/fireflier

1.2) fireflier-client-qt
 - change to fireflier-xxxx/qtclient
 - ./configure
 - make
 - make install

1.3) fireflier-client-kde
 - change to fireflier-xxxx/qtclient
 - copy Makefile.in.kde to Makefile.in
 - edit "build" file (adapt configure line)
 - source build
 - make
 - make install
 
1.4) fireflier-client-java
 - change to fireflier-xxxx/javaclient
 - make run
 
1.5) fireflier-client-java applet
 - copy Client.html, *.class, the "de" subdirectory to
   a directory on your webserver (you may wanr to edit Client.html)
 - use your webbrowser to load Client.html

1.6) fireflier-client-gtk
 - change to fireflier-xxxx/gnomeclient
 - autogen --disable-gnome
 - make
 - make install
 
1.7) fireflier-client-gnome
 - change to fireflier-xxxx/gnomeclient
 - autogen
 - make
 - make install

 We do not recommend to use the gnomeclient at the moment, as there are 
 still problems with gconf support.
 
2.) What is all this about
   I wrote this program to provide an easy way to configure the firewall
   rules for my desktop machine. I am too lazy to use existing tools to
   configure the rules manually, thinking which port I would have to open, 
   and which one to close. So I thought it would be useful to have a tool
   which does what all those personal windows firewalls do: At the beginning 
   everything is denied. When someone wants to connect in or out, the tool 
   asks the user, providing information about the corresponding packet, 
   if it should <accept> or <deny> this packet. Besides you can create rules 
   based on the packets. As I didn't find anything achieving this need, 
   I finally decided to write it myself. This is what later became fireflier.
   
3.) Architecture and functionality
   To provide the possibility to administer remote machines, I designed 
   fireflier as a client/server system. 
   The iptables rules implemented in 2.4.x kernels provide the possibility
   to pass rules from kernel space to a userspace program via netlink sockets.
   So the fireflier server waits for these packets, organizes them into a 
   queue and passes them on to the client (if one is available).
   The client displays the information and sends back commands (accept/deny 
   current packet, accept/deny packets in queue, create rule to accept 
   packets)
   If the queue of the server gets larger than 50 packets, further incoming
   packets will immediately be dropped.
   If the client creates a rule to accept packets matched by some criteria,
   this rule is inserted to the iptables rules. The rules are inserted 
   at the end of the firewall rules (but before the queue rules).
   The other possibility to create rules are rules based on the program,
   which is listening on the corresponding local port or sending via
   the local port. These rules are managed and filtered in userspace by
   the server.
   So when the server is shut down, the iptables rule continue to work, but
   the userspace rules won't.
   One of my goals was to keep the possibility to use other firewall
   configuration tools at the same time. To achieve this, I do not store
   any information about the iptables rules. So it is only important,
   that the other tool refreshes its information whenever a rule is
   inserted via fireflier. 
   One limitation of this is that you should not manage the rules from
   another application, as long as the fireflier iptables rules window is open.
   Deleting of rules is done using the rule number and so there would be
   problems if you had inserted a rule before the one you are deleting.
   
4.) Compiling and installing fireflier
4.1) fireflier-server
   To compile fireflier-server you should have the following libraries/includes:
      - iptables development libraries (libipq). 
          In debian use iptables-dev
      - pam libraries
          In debian use libpam0g-dev
      - openssl libraries
          With debian use libssl-dev
	  
   - "./configure [--prefix=your_destination_dir]" verifies the dependencies and creates the Makefile
   - "make" compiles the server
   - "make install" installs the necessary files:
     - fireflierd binary to /usr/local/sbin/
     - fireflier.pem, fireflier.users, fireflier.conf to /etc/fireflier
          you may want to edit fireflier.conf
	  these files won't be overwritten if already existing (=upgrading)
     - make directory /var/lib/fireflier
          here the userspace rules will be stored
     - fireflier pam file to /etc/pam.d
          edit this if you want. It is configured to let all
	  users log in which are in /etc/fireflier/fireflier.users
	  Every user who is able to log in to fireflier is able to 
	  modify/delete/insert firewall rules.

4.2) fireflier QT client
   To compile fireflier-client-qt you should have the following 
   libraries/includes:
      - openssl libraries
      - qt3 libraries 
          With debian use libqt3-dev
      - qt3: moc, uic
          With debian use qt3-tools
   - "autoconf" generates the configure file
   - "./configure [--prefix=your_destination_dir]" creates the Makefile
   - "make" compiles the qtclient
   - "make install" installs fireflier-client-qt to /usr/local/bin/
   
   To use the KDE version install the kde libraries, copy Makefile.in.kde
   to Makefile.in and rerun the "build" file (which runs the autoconf stuff)
   The KDE version has a dock icon, which changes as packets are pending,
   and supports autopopup (-r command line option).

4.3) fireflier-client-java
   I do only know the fireflier-client-java to work with java1.3 and java1.4.
   I hadn't got the time to try others at the moment.
   (If you get it to work on other versions simply tell me what you had 
   to do and I'll include it into the documentation/source code)

   To compile the javaclient just do
     - (maybe edit fireflier.java)
     - make
     there is no make install. You should decide yourself where you would want
     the .class files to put. (if in doubt copy the whole client directory
     to some directory and do make run from inside)
     Notice that since version 0.9.3 I no longer use the sun-jsse
     because it had various disadvantages (inconvenient for applets,
     bad license model). So I switched to miniSSL by Stefan Franke (BebboSoft)
     This software is free as long as it is used only in free projects.
     webpage: http://www.bebbosoft.de
     Official disclaimer as required by the license:

     This product includes software developed by BebboSoft,
     written by Stefan Bebbo Franke. (http://www.bebbosoft.de)

     For further details look at the license.txt file which is redistributed
     in minisslV1_3.zip
     Because of the licence I decided to not include the java clients into
     the debian packages. Using them should be no problem, as fireflier
     is entirely free, but I am not sure about the redistribution issue
     (on debian-cds and such)
   
4.4) fireflier-client-java (applet)
   To compile the javaclient as an applet
     - change to javaclient/
     - execute "patch -p0 < applet.patch.xxx"
     - run "make"

4.5) fireflier-client-gtk
   To compile fireflier-client-gtk you should have the following libraries/includes:
      - openssl libraries
          With debian use libssl-dev
      - gtkmm2 libraries version 2.0.x (or higher)
      	  you can surely use version 2.1.x, too
      	  (available at http://www.gtkmm.org)
      	  debian-package: libgtkmm2.0-dev
      - make sure that ``pkg-config" is installed and the 
	``PKG_CONFIG_PATH" environment variable is set to the directories where 
	the pkgconfig-files reside
   - "./configure --disable-gnome [--prefix=your_destination_dir]" creates the Makefile
   - "make" compiles the gtk client
   - "make install" installs the necessary files:
     - fireflier-client-gtk to /usr/local/bin
     - pixmaps to /usr/local/share/fireflier-client-gtk/pixmaps
     
4.6) fireflier-client-gnome

   We do not recommend to use the gnomeclient at the moment, as there are still problems with gconf support.
  
   To compile fireflier-client-gnome you should have the following libraries/includes:
      - openssl libraries
	  With debian use libssl-dev
      - gtkmm2 libraries version 2.0.x (or higher)
	  you can surely use version 2.1.x, too
	  (available at http://www.gtkmm.org)
	  debian-package: libgtkmm2.0-dev
      - make sure that ``pkg-config" is installed and the 
	``PKG_CONFIG_PATH" environment variable is set to the directories where 
	the pkgconfig-files reside
      - libgnomeuimm2 libraries version 1.3.x (or higher)
	(available at http://www.gtkmm.org)
	debian-package: libgnomeuimm1.3-dev
   - "./configure [--prefix=your_destination_dir]" creates the Makefile
   - "make" compiles the gtk client
   - "make install" installs the necessary files:
     - fireflier-client-gtk to /usr/local/bin
     - pixmaps to /usr/local/share/fireflier-client-gtk/pixmaps
     

5.) Uninstalling fireflier
5.1) fireflier-server
   - change to fireflier-xxxx/server
   - "make uninstall"
   - "rm -r /etc/fireflier"
   
5.2) fireflier-client-gtk
   - change to fireflier-xxxx/gnomeclient (yes gnomeclient !!!)
   - "make uninstall"
   
5.3) fireflier-client-gnome
   If you want to be able to uninstall the flierflier-client-gnome, 
   be sure to keep the build-directory.
   If you built the fireflier-client-gnome, then the gconf-directories 
   have to be removed, too (This doesn't apply to fireflier-client-gtk). 
   The Makefile does this task only for the system 
   directories; you have to do it on your own for the directories in your 
   home path where the actual values of gconf are stored.
   They probably are in ~/.gconf/;
   To find out where else directories could be, look into the path-config file 
   of gconf (probably /etc/gconf/2/path).


   These steps should lead you to a clean deinstallation:

   - "make uninstall"
   for every user who used the gnomeclient:
   - "rm -r ~/.gconf/schemas/apps/fireflier-client-gnome"
   - "rm -r ~/.gconf/apps/fireflier-client-gnome"
   
6.) Running fireflier server
6.1) fireflier-server
   Ensure that the ip_queue module is inserted into the kernel (via modprobe
   or compiled in). The ip_queue module is responsible for passing packets
   to userspace. 
   When the server starts up, it inserts automatically the ip_queue rules
   to the INPUT, FORWARD and OUTPUT chains. These are the only supported ones
   at the moment. The ip_queue rules are needed for passing packets
   to userspace. They have the form "iptables -A INPUT/FORWARD/OUTPUT -j QUEUE).
   You could maybe copy the startup/fireflier script to your runlevel
   scripts and create the corresponding links to start up the server
   automatically. This one works very well for me so far.
   
   Notice that you would need to store the iptables rules yourself.
   The userspace rules (=rules relating to some programs) will be
   stored by the server.
   In debian the iptables package provides a means of storing and loading
   the rues on startup. (although you would have to enable it. 
   cf /etc/defaults/iptables)
   
6.2) fireflier-client-qt/gtk/java/gnome
   - fireflier-client-xxxx IP-address IP-port
   connects to fireflier server at IP-address with port IP-port
 
6.3) Running fireflier javaclient
   start up the client using
     make run
   or java fireflier Server_ip server_port
         you need to ensure that the three .jar are in the classpath
   
   Usually after a few seconds a small login window should appear. Here you 
   have to enter a username and password for users who are allowed 
   to connect to the firewall. (cf /etc/fireflier/fireflier.users)
   By default root and your unix root password should work. 
   Any user who is allowed to connect to fireflier has full access to 
   ALL firewall rules.
   Otherwise the first packet (if any available) will appear. 
   If you want to create a rule, simply click onto the checkboxes,
   which should match for the rule to take effect. If you select the
   checkbox, where the progamname is displayed (at the bottom of the interface)
   the rule will be a userspace rule automatically. Notice that userspace
   rules will only be available as long as the server is running.
   The other rules will still be matched by iptables (the server is not neededfor 
   them).
   Via the menu you get to the rules windows where you can inspect and 
   delete the current iptables or userspace rules. Editing is not
   possible but planned for the 2.1 release. You might want to use another tool
   to modify the inserted iptables rules. Just don't delete the
   last rule, which has the target "QUEUE". This one is needed by fireflier.
   
   
7.) Differences between the gtk- and the gnome-version
   The both clients are very similar of course. One minor difference is 
   the about-dialog.

   The major difference by now is that the gnome client uses gconf to store 
   the position and size of the main window, the source dialog, 
   the IPTables rules dialog and the Userspace rules dialog. This means that 
   you can place the windows where you want them to be and they will be there 
   the next time you start fireflier (you can turn this option off in the 
   gconf-editor, key ``/apps/fireflier-client-gnome/ui").
   It also stores the font used for displaying the source, the IPTables rules 
   and the Userspace rules.
   I recommend to use a fixed width font.

8.) Documentation
   There is no nice documentation available yet. See the TODO file for details.
   However, here is a short description how to use the fireflier-client-gtk/gnome.
   Although there are some differences to the other clients they are not relevant.

   the user interface:

   On startup, the main window and a authentication dialog is displayed. You 
   can type in any user name which is written into the fireflier-server 
   config-file (/etc/fireflier/fireflier.users).
   This dialog is displayed as long as the authentication is not successful or 
   as long as you don't cancel the dialog. If you cancel it you could display 
   it again with ``log in" found in the ``File" menu.


8.1) the main window
8.1.1) the menu:
   - File:
     	log in:	displays the authentication dialog
       		shortcut: <control>l

      	quit:	quits the fireflier-client-gnome
       		shortcut: <control>q


   - View:
      	Source:		 shows the source of the packet
     			 shortcut: <control>s

      	IPTables rules:	 management of IPTables rules
			 shortcut: <control>i

      	Userspace rules: management of Userspace rules
			 shortcut: <control>u


   - Help:
      	About:	displays some information about the application
      		shortcut: <control>a


8.1.2) the toolbar:
   There is a toolbar with image-buttons as a shortcut for the 
   menu items found under the ``View" menu.

8.1.3) the rest of the user interface
	- three radio buttons
		to tell the server what to do with the packet.
		
		- this packet
		  you can allow or deny the packet currently displayed.

		- queued packets
		  allow or deny all packets already in the server queue.

		- create rule from this packet
		  creates a rule with the information specified in 2), 3) and 4).

	- general characteristics of packet
		- Chain
			The term ``Chain" is used together with the IPTables. Basically it 
			means whether a packet is incoming, outgoing or forwarded. There 
			is the possibility to create other chains with the IPTables tools, 
			note however that they are not supported by fireflier at the moment!

		- Length
			length of the packet

		- MAC
			MAC address

		- Program
			process from which the packet is sent or received.
			If you toggle this check box, you create a Userspace rule.

		- Timestamp
			date and time the packet arrived.

		- TCP Flags

		- ICMP Type

		- Protocol
			the protocol over which this packet is sent, e.g. TCP or UDP


	- source and destination of packet
		- IP
			address of the source or destination machine in the form a.b.c.d; 
			e.g. 127.0.0.1

		- Hostname
			the fireflier-client tries to resolve the IP to hostnames if possible.

		- Port
			every packet has not only an ip-address coming from and going to but 
			also a port - together they are called a ``socket", 
			e.g.: 127.0.0.1:80

		- Interface
			every packet is sent over an interface. Often this will be the name 
			of your network card or ``lo" for the loop back device.


	- options
		- connection tracking
			Choose this option if you want to connect to a server because e.g. you 
			want to download a file, but you don't allow this server to connect to 
			you.
			
		- timeout
			the timeout of the rule i.e. how long this rule should 
			be valid (the server will delete the rule after the timeout)


	- Source dialog
		The source of the packet is displayed. Every letter represents a byte in 
		the packet. On the left is the hexadecimal, on the right the ascii 
		representation.


	- iptables rules dialog
		The rules for the chains INPUT, FORWARD and OUTPUT are displayed (note 
		other chains are not supported by fireflier at the moment) in a tree. 
		A node is created for each chain. You can click on the node to hide rules 
		belonging to that chain.
		You can delete rules by selecting one or more and activating the 
		delete button. The chain node and description are not selectable of 
		course.
		Be careful with the ``queue all" rule (probably the last rule 
		if you did not play around with another iptables tool) because it is a rule 
		needed by the fireflier-server to receive those packets which do not 
		match against an existing rule; if you delete it then you won't get any 
		packets anymore concerning the chain this rule belonged to.


	- Userspace rules dialog
		You can manage the Userspace Rules.
		The userspace rules (created if you toggle the ``Program" checkbox 
		when creating a rule) are displayed in a simple list.
		You can delete them by selecting one or more rules and activating the 
		delete button.


	To make the handling of the dialogs even easier, buttons, check buttons and 
	radio buttons are enabled with so-called ``mnemonics". You recognize them 
	on the underlined letter of a label; Mnemonics work just like shortcuts - 
	you can use this mnemonic by pressing <alt>letter. 
	e.g. the ``allow" button has the `a' underlined, so you would 
	press <alt>a to activate this button. This has the same effect as you would 
	click on that button with the mouse.



9.) Glossary
   - iptables:
      Iptables is the linux firewall backend which has been introduced with 
      the linux kernel version 2.4.0
      Fireflier is a utility built on top of the iptables framework.
      For further documentation please consult the iptables manual pages.

   - userspace:
      Userspace is a term referring to all the applications which are not part
      of the operating system kernel.

   - userspace rules:
      This is a feature of the fireflier.			
      The iptables framework of the kernel only supports creating rules 
      concerning the header of packets.
      But fireflier offers the possibility to filter packets based on the program
      which is receiving them on the local machine.

   
10.) Hacking source code
   If you make any modifications which might be useful to public, it would
   be nice to inform me about them and/or send me a sourcecode patch.
   
   server:
     ports.*: this file resolves Local Port+Local ip to a corresponding
              program
     queue.*: a simple queue implementation by myself supporting one passive
              iterator and a maximum queue size (per element)
     rules.*: interaction with iptables. Inserting/retrieving/deleting rules
     pam.*: authentication via pam
            I got most of this code from Rene Mayrhofer (rmayr@debian.org)
     backend.*: the server itself. the main part of this tool.
     
   Maybe look at the sourcecode itself. It is a little bit documented.
   
   javaclient:
     fireflier.java: the javaclient source.
     *.class: the javaclient "binaries". 
     miniSSL: small but working library for SSL-encrypted connections
              developped by BebboSoft (see above)
  
11.) Contact
	If you have questions, suggestions, wishes or bugs, send an email to me/us 
	or the mailing list. If you are sure that you detected a bug, use the bug 
	tracking system at sourceforge.net or at gnome.org (only for gnomeclient). 
	Note that the bug tracking system at sourceforge.net is preferred.

	To subscribe to the mailing list, go to 
		http://lists.sourceforge.net/lists/listinfo/fireflier-users

	project website:
		http://fireflier.sourceforge.net

	emails:
		mailing list: <fireflier-users@lists.sourceforge.net>
		Klaus Triendl <fireflier@gibraltar.at>
		Martin Maurer <fireflier@gibraltar.at>

	(bug) tracking systems:
		http://sourceforge.net/tracker/?group_id=53081
			(there are also other trackers available like feature requests)

		http://bugzilla.gnome.org

12.) Acknowledgements

   Rene Mayrhofer (rmayr@debian.org): 
     support on developing the structural+optical design
     many improvements and ideas
     support on making the .deb archives and uploading them to the main debian
       archives
     code for pam authentication
     
   Markus Loeberbauer (markus.loeberbauer@students.jku.at):
     support on developing optical design
     testing
     inventing name "fireflier"
   
   Dipl-Ing Dr. Dieter Kranzlmueller: 
     the idea of "timeouting rules"
   
   the netfilter development team:
     providing a powerful firewall tool
   
   the gtkmm2 team:
     Thanks goes also to the maintainers of the gtkmm2 and gnomemm2 libraries - 
     a c++-language binding for the gtk2 and gnome2 libraries.
     They made these libraries happen and are always kind in answering questions 
     on the mailing list.


  
13.) License
   This program is released under the GPL with the additional 
   exemption that compiling, linking, and/or using OpenSSL and miniSSL
   is allowed.
