===============================================================================
$Id: README 137 2006-01-04 08:31:23Z trappist $
===============================================================================


                                IPKungFu version 0.6.0

Notes and configuration information on IPKungFu
Please see the FAQ for troubleshooting.

IPKungFu man page available after installation

	man ipkungfu

WHAT IS IPKUNGFU?

 Ipkungfu is an iptables-based Linux firewall. The primary design goals are
 security, ease of use, and performance, in that order.  It takes advantage of
 advanced features of iptables and the Linux kernel. Ipkungfu can handle a 
 wide array of configurations, and supports Internet connection sharing, 
 multiple virtual hosts, IP forwarding, IP masquerading, configurable logging, 
 string matching and much more. It is designed with both the novice and the 
 expert in mind with its simple configuration interface.

WHO SHOULD USE IPKUNGFU?

 Anyone who wishes to simplify the creation of an iptables-based firewall.
 Additionally, anyone who would like a simple method of configuring a Linux
 machine to share its Internet connection.

HOW DOES IT WORK?

 It takes configuration directives from the files in /etc/ipkungfu and uses
 them, along with some information gathered from your system, to build a
 firewall using iptables and sysctl.  It is primarily an interface to iptables.
 which in turn is an interface to the Linux kernel's netfilter code.

WHERE CAN I GET THE LATEST VERSION?

 IPKungFu can be obtained from http://freshmeat.net/ipkungfu 
 Please send bug reports to bugreport@linuxkungfu.org
 Or, submit them to ipkungfu's development site:
 http://ipkungfu.ufsoft.org

I HAVE A QUESTION THAT IS NOT ANSWERED IN THIS DOCUMENT.

 First read the FAQ, your question may be answered there.
 You may post questions at http://freshmeat.net/ipkungfu, you may be
 able to find me on IRC at: irc.freenode.net channel: #ipkungfu, or
 you can subscribe to our users mailing list:
	To subscribe to the list, send a message to:
		ipkungfu-users-subscribe@ufsoft.org

	To remove your address from the list, just send a message to the address in
	the "List-Unsubscribe" header of any list message.
	If you haven't changed addresses since subscribing, you can also send a
	message to:
		ipkungfu-users-unsubscribe@ufsoft.org

HOW DO I RUN IPKUNGFU?

 Running ipkungfu is done in a few simple steps. (as root)
  1) Download and unpack the source.
  2) Install per the installation instructions (./configure && make && sudo make install)
  3) Edit configuration files in /etc/ipkungfu to taste.
  4) Execute ipkungfu.

WHAT COMMAND LINE OPTIONS ARE AVAILABLE?

	-t or --test
		Test the configuration, listing some of the optional kernel
		support installed, the interfaces in use, IP addresses,
		whether or not you have chosen IP forwarding, IP masquerading,
		subnet and ports you have chosen to allow.

	-d or --disable
		Disables the firewall and sets the default policies back to
		ACCEPT. Internet connection sharing is not disabled.

	-h or --help
		Displays all options available to ipkungfu.

	-v or --version
		Displays the version number of ipkungfu and exits.

	-l or --list
		Displays the iptables rule sets and exits.

	-c or --check
		Check to see if ipkungfu is loaded and display if it is in
		disable mode or panic mode if either.

	-f or --flush
		Flush all iptables rules and delete custom chains.  This
		completely takes down the firewall, and will also disable
		Internet connection sharing.

	--panic
		Panic mode. All internal and external access is denied. Nothing
		is allowed, in or out.

	--quiet
		Runs ipkungfu with no standard output.

	--show-vars
		Shows main configuration options (whether specified or
		auto detected) and exits.

	--failsafe
        	If ipkungfu fails, default policy for all builtin chains will
		revert to ACCEPT.  This essentially means the firewall will be
		disabled if it fails.  This is useful for working with ipkungfu
		remotely, to prevent loss of access to the machine.

	--no-caching
		As of version 0.6.0, ipkungfu now supports rules caching support
		which in case rules haven't changed, will make ipkungfu load way
		faster. Passing this argument disables this feature.
		
WHAT DO I NEED TO RUN IPKUNGFU?

 ipkungfu requires a Linux kernel of 2.4.x or higher.
 The following should be compiled into your kernel or as a module.
 Note that most Linux distributions already have much of this already,
 especially the required section. If you have other firewalls running, you
 should disable or uninstall them first to avoid conflict.

 Required:

 connection tracking
 IP tables support
 connection state match support
 REJECT target support
 full NAT
 MASQUERADE target support
 packet mangling
 TOS target support
 LOG (and/or ULOG) target support
 multiple port match support

 Highly recommended:

 FTP protocol support
 IRC protocol support
 limit match support
 REDIRECT target support
 NAT of local connections

 Optional:
 
 ULOG target support
 MIRROR target support
 string match support
 iplimit support
 recent match support
 psd match support
 nth match support
 tcp syncookie support

 Currently IPKungFu does not support IPv6

INSTALLING IPKUNGFU

 Installation of ipkungfu is designed to be as simple as possible.  Unlike
 previous (and future) versions, ipkungfu does not ship with a configurator,
 and no configuration is done automatically at install time.

 To install, download the ipkungfu-<version>.tgz file and run:

 	tar zxvf ipkungfu-<version>.tgz

 Or if you have the ipkungfu-<version>.tar.bz2 file:

 	tar jxvf ipkungfu-<version>.tar.bz2
	
 This will unpack and extract the files to a subdirectory named
 
    ipkungfu-<version>

 Then change into that directory:
 
	cd ipkungfu-<version>

 And then do:
 
	./configure && make
	 
 And then su to root. (You must be root to be able to install) Then do:
     
	make install

 If this is the first time you install ipkungfu on your system also do:

	make install-config

 This will install the default configuration files. You MUST edit these files
 before you run ipkungfu.
 DO NOT run the above command if you have installed ipkungfu before and you
 want you current configuration files, if you do, your old configuration files
 will be overrriden.

CONFIGURATION FILES

 There are several configuration files, each one corresponding to a specific
 function or set of functions.
 Advanced users or those with more complex networks will want to edit most or
 all of these files. They are located in /etc/ipkungfu/ and are:

   accept_hosts.conf : IP addresses of hosts or nets to always ACCEPT and
   optionally the ports they are allowed to access

   advanced.conf : Configuration settings for advanced users.

   custom.conf : Here you will find sample rules several sample rules already
   predefined.  This is where you would add any custom rules you want applied
   to your firewall.  This file is parsed first, before any other rules are
   added by ipkungfu, to ensure that none of ipkungfu's rules override the
   rules in this file.

   deny_hosts.conf : You can list IP addresses/subnets:ports:protocols you wish
   to block completely.  This file is parsed before accept_hosts.conf and takes
   precedence over it.

   ipkungfu.conf : This is the main configuration file.  Edit this file, if
   nothing else.  For most people, this is the only file that needs to be
   edited to set up a decent firewall, with or without Internet connection
   sharing.
   WARNING: ALLOW_TCP_IN and ALLOW_UDP_IN are now deprecated and mantained only
   for backward compatability. Now use services.conf.

   log.conf : This file specifies what the firewall will log and the rate at
   which it is logged. By default, nearly all dropped packets are logged.
   To turn logging off on a particular item, change the 1 (log) to a
   0 (don't log). The default location of the log on most systems is
   /var/log/syslog.  Consult your syslogd configuration to find out where
   kernel logs are stored.

   redirect.conf : Use this file to specify where certain traffic should be
   routed on the SAME machine. If you want to redirect ports that come in on
   one port, and should go to another, set them up here. There is a single
   entry here that is commented out by default- tcp:443:10000 which
   redirects incoming https traffic on port 443 to webmin on port 10000.
   Please see the file for more information.

   vhosts.conf : If you have virtual hosts, (servers on machines behind your
   gateway), define the routing rules here.  This file makes it possible to
   have servers behind the firewall, with private IP addresses, accessible
   from the Internet.

   pre.conf : This is parsed and executed as a bash script prior to running
   ipkungfu.

   post.conf : This is parsed and executed as a bash script after ipkungfu
   has completed execution.

   services.conf : Here you keep all of your rules previously defined in
   ipkungfu.conf as ALLOW_TCP_IN and ALLOW_UDP_IN, plus more. Edit the file,
   it's self explanatory.

MANUALLY EDITING FILES

 Most people, especially those with very simple configurations, will only
 need to edit /etc/ipkungfu/ipkungfu.conf if anything at all.  As of 0.5.1
 ipkungfu does a lot of detecting and guessing for the main configuration
 parameters unless you specify their values in ipkungfu.conf.  This should
 work for most people.  To go over the list of variables as ipkungfu
 knows them, run ipkungfu --show-vars.  If anything looks wrong, edit the
 appropriate configuration file accordingly.

 A "#" is a comment. When a line begins with #, the whole line is ignored. If
 you want enable an option in a configuration file that is commented out,
 simply remove the leading #. If you wish to remove an option, place a #
 in front of that line.

 Note that anytime you edit a configuration file, you MUST rerun the script
 as outlined below in order for changes to take effect.

RUNNING THE SCRIPT

 Now that you have ipkungfu configured, you must run the ipkungfu script as
 root to enable the firewall.

  	/usr/local/sbin/ipkungfu
	
	or, if /usr/local/sbin is in your PATH, simply

	ipkungfu

	or, if your system is chkconfig-compatible, try

	/etc/init.d/ipkungfu start

	or

	/etc/rc.d/init.d/ipkungfu start

	
 You should see several lines explaining what is being done,
 unless you started ipkungfu using the init script.

 If you would like ipkungfu to start at boot time, and your system is
 chkconfig compatable, then do (as root)

        chkconfig --level 2345 ipkungfu on

  This turns ipkungfu on for runlevels 2, 3, 4 and 5. Put whatever levels you
  like, with the obvious exceptions of levels 0, 1 or 6.

 
 That's it! You can check to verify that the firewall is loaded:

 	ipkungfu -c or --check

 You can also check to see if the firewall is running by

 	ipkungfu -l or --list
	
 You should see several lines or pages of chains and rules.
 If you only see a few lines, or an error message, then the firewall
 is probably not enabled.

 Any time you make a change to any of your configuration files, you MUST run
 ipkungfu again for your changes to take effect.

TROUBLESHOOTING

 Most problems can be resolved by checking your settings in your configuration 
 files.
 Many users overlook certain settings, so you may want to double-check them to 
 be sure.
 Remember to run ipkungfu again (/usr/local/sbin/ipkungfu) after making any 
 changes to the configuration files (located in /etc/ipkungfu/).
 Please see the FAQ for more troubleshooting issues and resolutions. If all 
 else fails, you can ask for help via IRC at: irc.freenode.net channel
 #ipkungfu, or use the users mailing list show on the top of this document.

UNINSTALLING IPKUNGFU

 Although uninstalling IPKungFu is not recommended, you may safely uninstall
 it.
 Run:
	ipkungfu --disable

 Your iptables rules will be flushed and reset to the default ACCEPT policy.
	
 Go to the directory where you unpacked ipkungfu and run:

	make uninstall

 If an error is outputed, do:

 	./configure && make uninstall