Our main development OS is Linux, we also build and maintain FreeBSD ports

I do not update this list very often so it may be out of date.

These are listed in the file "Build" in the docs directory. It is fwbuilder/doc/Build if you unpack source tarball, or can be found online: Installation Guide

Binary packages and a source code for the recent release can be downloaded from the "Downloads" page on the project's web site http://www.fwbuilder.org/ or from Source Forge .

Nightly builds and experimental packages (source tar.gz and binary packages) are available on our web site http://www.fwbuilder.org/nightly_builds/. Nightly builds include latest bug fixes and are great way to test and see what is going to be included in the next release. At the same time nightly builds are certainly a cutting edge of the project and may break. Be sure to make backup copy of your data before you use it! We usually put the latest copy of the ChangeLog file in the same directory, remember to always check it before you download. See "Installation Guide" for more details and build instructions.

"Installation Guide"

Pre-built binary RPM and DEB packages define dependency packages they need, so the corresponding package manager tool will install dependencies automatically. Use your favorite package manager to do this ( yum, apt-get, aptitude, synaptic and so on). See here "Installation Guide" for more details.

Native packages for Windows and Mac OS X have no dependencies.

Although Firewall Builder GUI is based on QT, it works both with and without KDE.

Firewall Builder does not need Gnome; it may work both with and without Gnome.

See "Installation Guide" on our web site.

As of version 0.9.6 the code has been split into three major parts: API, GUI and policy compilers. You need to download, compile and install API for the rest to compile. The API comes in a separate source archive called libfwbuilder-0.10.0.tar.gz. Compile and install it as usual, using "./autogen.sh; make; make install" procedure.

You need to install prerequisite libraries. See the list of RPMs in the Installation Guide

Just type "fwbuilder" on the command line prompt (in xterm or gnome-terminal). If Firewall Builder was installed using pre-built binary RPM or DEB packages, it should appear in the system menu under "System / Administration".

Firewall Builder GUI is an X application, that is, it needs X server to display it on the screen. The program determines how to connect to the X server using environment variable DISPLAY; you probably do not have this environment variable if you get an error like that. The simplest way to avoid this problem is to start fwbuilder from the shell window in Gnome or KDE environment.

It may also be that the environment variable DISPLAY is set, but the program fwbuilder can not connect to the X server. In this situation you won't be able to run any application using X, check if that's the case by trying to start "xclock". This may be happening because of many different reasons, such as X server is not running, X authenitcation failure, or DISPLAY variable reassigned its value by the shell login script or many others. This problem falls outside the scope of this document, please search on the Internet for the answer. Here are few URLs to make troubleshooting easier:

Then the GUI binary (fwbuilder) can not find API library libfwbuilder. If you are using our binary packages, then make sure you download and install package called libfwbuilder. If you compiled from sources, then perhaps you installed libfwbuilder with default prefix /usr/local/, therefore library went to /usr/local/lib. Dynamic linker ldd can not find it there.

You have the following options:

You need to install a package that provides support for your firewall platform.

The problem is caused by SELinux security settings, to work around it try the following command:

chcon -t texrel_shlib_t /usr/lib/libfwbuilder.so*
          

Please file a bug on Sourceforge and provide information we might need to fix the problem. See the list on the Contact Us page.

Sometimes this happens when you skip several versions trying to upgrade the program. There used to be a bug in the upgrade procedure somewhere around version 1.0.4 which broke automatic upgrades from versions before 1.0.4 to versions after that. If this happens to you, upgrade your data file using script fwb-upgrade.sh that you can find in Contrib/Scripts area on our SourceForge site.

It looks something like this:

---------------------------------------
fwb_ipfw -f C:/Documents and Settings/User/data.fwb -d C:/Documents
and Settings/User -r C:\FWBuilder\resources fw

 Compiling policy for fw ...
  Detecting rule shadowing
 Begin processing
 Policy compiled successfully 
ios_base::failbit set
------------------------------------------
          

First of all, check available free disk space. Also check if the output file ( fw.fw ) is opened in another program while compiler is running. That is, if you looked at it after the previous compiler run and opened it in Notepad, it becomes locked and compiler won't be able to overwrite it with the new copy until you close Notepad.

Mainstream Linux distributions package fwbuilder as follows: they put libfwbuilder API library in the .deb or .rpm package "libfwbuilder", the GUI in the package "fwbuilder" and each policy compiler in its separate package, such as "fwbuilder-ipt", "fwbuilder-ipf", "fwbuilder-pf", "fwbuilder-cisco" and so on. Keep this in mind if you install from the distribution, because you need to install three packages: libfwbuilder, fwbuilder and a package with compiler, for example fwbuilder-ipt.

This is a known problem caused by new version of net-snmp library. I could not reproduce this, but a user suggested that the fix is to make sure that the value of "suffixprinting" in /usr/local/etc/snmp must not be set to 1

Run-time problems on Windows are hard to debug remotely. In order to make this little bit easier, fwbuilder GUI has built-in debugging capability. You need to download and run debugView program (you can download it here ).

Basically, you start debugView, then you start fwbuilder GUI from the MsDOS command line prompt like this:

c:\FWBuilder30\fwbuilder.exe -d
          

This will launch fwbuilder in debug mode and debugView will start printing bunch of lines in its window. Follow steps that lead to the crash all they way until it crashes. Then in debugView save the output to a file, make a zip archive with it and send it to support@netcitadel.com

Firewall Builder GUI has built-in policy importer that can import iptables policy saved with iptables-save script. It can also import Cisco IOS access lists configuration saved using "show run" command. You can access importer via main menu "File / Import Policy" Currently there is no way to import existing ipfilter, pf or ipfw firewall configuration into Firewall Builder.

Firewall Builder uses "stateful inspection" feature of underlying firewall platform. In case of iptables it loads module ip_conntrack which is tracking connections opened through the firewall and by the firewall itself. Since this module "remembers" each connection, there is no need in additional rule for "ACK" or "reply" packets. In fact, this module does lot more than keeping track of opened TCP sessions as it does similar thing to other protocols as well, where possible. Firewall Builder also loads some other modules to keep track of complex protocols, e.g. it loads module ip_nat_ftp to support FTP.

The option "Assume firewall is any" is needed for those firewalls where rules that control access to the firewall machine and rules that control access to machines behind the firewall use different syntax or different commands. Currently two plaforms require and use this option: iptables and Cisco PIX.

In iptables, rules controlling access to the firewall should go into INPUT chain (or rules controlling packets originated on the firewall should go to OUTPUT chain), while rules that control traffic going through the firewall go into the FORWARD chain. Generally, a rule may yield code for either chain depending on the addresses used in SRC and DST. If address used in DST matches one of the addresses of the firewall, then code goes into INPUT chain. There are two ways to interpret "any" though. We can say that "any" means anything, including the firewall. In this case this rule should put code into both INPUT and FORWARD chain. If we do not assume that firewall is part of any, then the generated code goes only into the FORWARD chain.

The algorithms used by the policy compiler are the same regardless of the network configuration, so this logic applies in the case when firewall protects local host, too.

We need them to be able to assign rules to an interface, but skip it in src or dst if firewall object is used in src/dst rule elements. This may be useful in configurations with VPN (imagine unnumbered VPN interface through which packets exit the tunnel).

I won't do this because I believe that currently the script does "The Right Thing". Here is why:

The script sets default policy in all chains to "DROP" before it clears all the rules. This is necessary because firewall and possibly machines behind it become wide open as soon as script clears the policy. Script needs to wipe out old rules before it installs new ones, so setting default policy to DROP is the only way to ensure there is no time window during which firewall does not offer any protection. One may argue that this window is really short, because script immediately loads new rules, but this is not always so. What if some rule contained an error and did not load? What if script has been interrupted and did not activate whole bunch of rules? In the end, it is always better to block access and thus prevent potential security problems, even if this comes at a price of some inconvenience.

Shadowing happens because a rule is a superset of a subsequent rule and any packets potentially matched by the subsequent rule have already been matched by the prior rule.

This happens when you are using an option "Create virtual addresses for NAT rules". The problem is that policy compiler needs to be able to determine interface of the firewall to assign virtual address to. In order to do that it scans all interfaces trying to find subnet requested NAT address is on. Sometimes firewall's interface has an address which belongs to a different network than NAT address specified in the rule; in this case compiler can not identify an interface and aborts.

The NAT rule still can be built without "-i" or "-o" option, but automatic assignment of virtual address is impossible. You need to turn off option "Create virtual addresses for NAT rules" in the tab "Firewall" of firewall dialog and configure this address manually.

If you install a firewall configuration on iptables from Firewall Builder, then save the configuration on the firewall using iptables-save, and then import that iptables-save configuration back into Firewall Builder you will not see the same configuration as what you used to create the configuration.

The reason is that Firewall Builder provides a lot of powerful abstractions that aren't available directly in iptables. For example you can create a rule in Firewall Builder with multiple sources or destinations defined. When Firewall Builder generates the iptables configuration it automatically splits the original rule into multiple rules, one for each source / destination pair.

Firewall Builder also tries to minimize the number of comparisons that need to be made, so it makes heavy use of the iptables user defined chains. For example if you have a rule with 10 source networks defined with the service set to HTTP, Firewall Builder will set a rule to match the HTTP protocol and then jump to a user defined chain that includes the source networks.

This yields better performance than creating 10 rules that need to be evaluated in the main chain. If the traffic is not HTTP it only needs to evaluate one rule, it's only if the traffic is HTTP that all 10 rules need to be evaluated.

So, why does this matter? When Firewall Builder generates the iptables configuration it does a lot of optimization and uses system generated names for things. If you import the resulting iptables configuration you aren't going to get the same configuration back in Firewall Builder since it doesn't know if a user defined chain was created as part of a single rule optimization by Firewall Builder or as part of a user created configuration. This is why imported configurations can look very different from the rules that were originally used to create them. Functionally they are the same, but the re-imported rules don't look as concise.

"Compile" only calls compiler, which produces a file called after the name of the firewall object, with ".fw" extension. This file contains a firewall sript which needs to be activated. There are three ways to activate it: 1) you can simply copy it to the firewall machine and then run it by hand; 2) you can use built-in installer and 3) you can use a shell script to copy this file to where it should be and then run it. Built-in installer uses ssh to communicate with the firewall, you can activate it by clicking menu Policy/Install (or corresponding toolbar icon). You can use your own installer script if you put the full directory path and file name for it in the "Policy Install Script" field in "Compile/Install" tab of the firewall's settings dialog. Then menu item "Rules/Install" will call your script.

You do not need to reboot your firewall to activate the new policy. Iptables script generated by Firewall Builder has a code to do a "clean up" job by removing all previous iptables settings, before it loads new ones.

The following HOWTO article describes the ways to use Built-in installer in fwbuilder: http://www.fwbuilder.org/4.0/docs/users_guide/compile-install-detail.shtml.

This option was added by popular request, it copies .fwb file over to the same directory on the firewall alongside with generated firewall script. Many people, it seems, use this as a simple way to create a backup copy of their data file so they can easily restore it if their management workstation crashes. This can also be useful if they want to quickly roll back to the version of the data file that was used to generate firewall script running on the firewall.

I would like to point out that this feature should be used carefully. This option (making a backup copy of fwb file on the firewall itself) makes sense when fwbuilder is used to manage only one firewall, and especially when the GUI runs on the firewall itself which means the fwb file is already present on the machine. However, this option may turn into potential problem if fwbuilder is used to manage multiple firewalls and all the objects and configurations are kept in the same fwb file residing on the remote workstation. If the fwb file was copied to every firewall as part of installation, each firewall would end up holding information about policy of every other firewall. This elevates risk in case of break-in into one of the firewall and should be avoided.

Fwbuilder is not really a backup tool, and copying the data file over to the firewall has its drawbacks. Please consider making regular backups of the data file using other means.

Built-in revision control system (RCS) in the Firewall Builder GUI allows administrator to maintain versioning of their data file. It is a good practice to check the file in (with appropriate log record) after every significant change is made to objects or rules. This provides a way for simple roll-back in the future if needed. Using RCS does not eliminate the need to make backups.

This only happens when Firewall Builder GUI runs on Windows and uses pscp.exe and plink.exe to transfer generated firewall script and activate it on the firewall machine. Utilities pscp.exe and plink.exe are part of the PuTTY package by Simon Tatham http://www.chiark.greenend.org.uk/~sgtatham/putty/.

Fwbuilder GUI launches plink.exe utility to log in to the firewall machine and activate firewall script there. It composes plink.exe command line using ip address of the firewall and adds command line option "-ssh" to force plink.exe to use ssh protocol. Plink.exe and GUI ssh client putty.exe share the same configuration stored in windows registry and if default settings configured in putty.exe set default protocol to "Serial" as shown in the screenshot below, plink.exe seems to ignore command line option "-ssh" and fails with an error 'Looking up host "" Connecting to 0.0.0.0 port 22'. Just set default protocol to "ssh" using putty configuration dialog.

Figure 1. 

You do not need to uninstall ipchains, but you need to deactivate it.

As root, run the following command:

	    # chkconfig --level 2345 ipchains off
	  

if you do not want to reboot at this point, run the following to stop and remove ipchains from the memory:

	    # /etc/rc.d/init.d/ipchains stop
	    # rmmod ipchains
	  

Now simply run iptables script created by fwbuilder to activate your firewall. This will immediately activate your new firewall policy; you can always check if your new rules are loaded using command "iptables -L -n".

There still is a problem of activating the policy at a boot time. Different OS deal with it using deifferent scripts that get installed in the directory /etc/rc.d/init.d (scripts in this directory are called in sequence when machine boots.) RedHat's standard iptables setup depends on their scripts iptables-save and iptables-restore. If you wish to stick with RedHat's standard scripts, simply run these commands:

	    # /etc/rc.d/init.d/iptables save
	    # chkconfig --level 2345 iptables on
	  

This will save your configuration to RedHat's standard file /etc/sysconfig/iptables in iptables-save format (which is different!) and then will restart it every time you reboot your firewall.

If you do not want to use their scripts, you can use script "firewall-initscript" available in the "Downloads" area on our web site. This script comes with a README file which describes its usage.

Iptables can either be compiled into the kernel or as a modules, it does not really matter. If some of the modules are missing, then respective feature won't work and you will get an error trying to load generates script. For example, if you compile everything into the kernel and leave ipt_LOG module out, then logging will stop working and you will get errors trying to load rules with logging turned on. Look into iptables HOWTO and Tutorial for more details as this problem is not really specific to Firewall Builder.

Here is (incomplete) list of modules taken from my firewall :

RedHat Linux comes with all iptables code compiled as modules.

You can turn debugging on (look for a checkbox in the tab "Firewall" in firewall dialog). This simple generates firewall script with shell option "-x" so it will print all commands while executing. This way you can see which command causes the error and trace it back to the policy rule.

This tool is part of the package 'iproute'; we use it to manage virtual IP addresses needed for some NAT rules.

You get this error because you used option "Log all dropped packets" (there is a checkbox in the 'Firewall' tab). This option requires "dropped" patch from patch-o-matic. You either need to turn this option off, or apply corresponding patch and recompile both ketnel modules and command-line utilities for iptables.

There are several conditions that may cause this error.

The script generated by fwbuilder uses tool /sbin/ip to verify configuration of the firewall interfaces and make sure that interfaces of the real firewall machine correspond to the interface objects created in the GUI. You may get this error if the tool /sbin/ip is not installed on your system. All modern Linux distributions come with the package iproute2 which includes /sbin/ip; check if iproute2 is installed and /sbin/ip exsits.

Another case when you may encounter this error is when firewall script is executed prematurely during the boot sequence and interface really does not exist at that time. For example, interface ppp0 is created only when the system is configured for PPP and daemon pppd is running. If firewall script is activated before the daemon started during the boot sequence, interface ppp0 is not there yet, which leads to this error. Make sure you start firewall script after all interfaces has been initialized.

eth0:1 is not a real interface on Linux, it is just a label for a second IP address of the interface eth0. One way to solve this is not to create it in the OS (remove file /etc/sysconfig/network-scripts/ifcfg-eth0:1 and restart networking), but rather add its IP address in the Firewall Builder GUI as a second address to interface eth0.

In any case you should not add interface "eth0:1" in fwbuilder because it really does not exist. Iptables will not recognize this interface either, so even if fwbuilder let you use it, you would get an error from iptables. You see "eth0:1" in the output of ifconfig only because ifconfig has been modified on Linux to show virtual IP addresses as pseudo-interfaces. The command "ip addr show" will reveal that the eth0:1 is really a label on the second IP address of eth0.

iptables:

Policy compiler for iptables generates a shell script that configures interfaces of the firewall using information entered in the GUI, adds virtual addresses if needed and activates firewall policy. Script checks pre-existing configuration of the interfaces and does not make any changes if all addresses are already configured. This means it won't break anything if you use standard configuration tools provided by your OS and then run this script.

ipfilter:

Policy compiler for ipfilter generates three files: "firewall.fw", "firewall-ipf.conf" and "firewall-nat.conf" (where 'firewall' is the name of the firewall opbject). The first file, "firewall.fw", is a shell script that configures interfaces and loads firewall policy from the other two files using /sbin/ipf and /sbin/ipnat. So, if you use this autogenerated shell script, then the answer is yes, interfaces will be configured. If you don't use this script and rely on the standard scripts provided by FreeBSD, then the answer is no.

pf:

Just like in case of ipfilter, policy compiler for pf creates initialization script in the file "firewall.fw" and a configuration file "firewall.conf". If you use generated script "firewall.fw", then it will configure interfaces of the firewall and load the policy. If you do not use it and simply copy "firewall.conf" file and rename it as "/etc/pf.conf", then you need to make all configuration using standard scripts available in OpenBSD (/etc/rc.conf).

This problem is specific to iptables. The asnwer below has been written in September 2006, most likely the situation and relevant recommendations are going to change in the future as module nf_conntrack matures and gets wider deployment.

Here is an example of an error message:

FATAL: Error inserting nf_conntrack_ipv4
(/lib/modules/2.6.13-15.11-default/kernel/net/ipv4/netfilter/nf_conntrack_ipv4.ko):
Device or resource busy
          

Here is the link to the nf_conntrack page in patch-o-matic catalog. Here is the link to the discussion on netfilter-devel mailing list.

It appears you can load either ip_conntrack or nf_conntrack but not both at the same time since nf_conntrack is a replacement for ip_conntrack. As of this writing, nf_conntrack does not support NAT just yet and is marked as having status "TESTING" on the patch-o-matic catalog page.

This actually represent a problem for fwbuilder. I would like to avoid having to write extensive GUI to let user choose which modules they want to load. One of the reasons is that the GUI may be working on one machine, while generated firewall script will be executed on another. In this situation the GUI can not determine which modules are available on the firewall. Currently generated script simply tries to load all modules but it aborts if it detects an error in the command that does it (modprobe).

Until better solution is found, you would probably need to remove module that conflicts with others or disable feature that makes generated script load modules and write your own script to load modules you need. You can for example add commands to load modules explicitly to the "prolog" section of the generated script.

RedHat Linux comes with syslog preconfigured to write all log messages with level "info" and higher to /var/log/messages, while iptables script generated by Firewall Builder by default logs everything as "debug". You need either to edit /etc/syslog.conf to make all "debug" messages to be logged, or change log level to "info" in iptables tab in firewall dialog

You can use our script logwatcher.pl available in Contrib area. It reads log file /var/log/messages and shows only the following fields from each log line:

Note though that this script drops some data logged by iptables to improve readability. You may miss some important information because of this, so in case of real problem always look in the original log!

Another, more elaborate version of the same script is logwatcher2.pl. It is also available in Contrib area.

You can use our script connwatcher.pl available in Contrib area. It prints the contents of the connections table every second, sort of like top shows processes active in the system.

You can use rule options dialog and add unique log prefix for this rule. Open rule options dialog by right mouse clicking on rule element in the "Options" column. This way you can make rules generate special lines in the log, which you can later process with automated script, to simply use while troubleshooting your policy.

Open Preferences dialog (under menu "Edit") and check checkbox "Automatically save data in dialogs while switching between objects" in the first tab of the dialog that appears.

A catastrophe (e.g. a system crash) can cause RCS to leave behind a semaphore file that causes later invocations of RCS to claim that the RCS file is in use. To fix this, remove the semaphore file. A semaphore file name typically begins with , or ends with _.

If not that, then it could be another manifestation of bug #1908351

See if there is a file with the name starting and ending with a comma in the RCS dirtectory (like ",file.fwb,"). The file should have length of zero bytes. This file is a lock file, it is created and deleted by RCS tools. Bug 1908351 caused this lock file to be left behind. When that happens, ci won't check file in because it thinks another copy of ci is already running. Likewise, co won't check the file out for the same reason. If such file exists (zero bytes in length and name starting or ending with a comma), just delete it and try to check your data file out again.

Such non-descriptive error message is ususally caused by hard unrecoverable errors experienced by RCS tools. Unfortunately these tools not always report errors in the best way possible and when this happens, Firewall Builder GUI can not provide any better diagnostics than it gets from the tool. Such poor diagnostics of errors happens more frequently on Windows than on other platforms.

Here are few things to check and try:

Use main menu item File/Add file to RCS

List of revisions and corresponding RCS log entries appear in the right panel of the Open File dialog when you highlight a file that has been added to RCS. Once the file has been opened, you can always see revision history and corresponding RCS log using main menu File/Properties

Branch is created automatically when you open one of the old versions of the file using list of versions that appears in the right panel of the Open File dialog

If you haven't checked changed file in to RCS, you can use main menu File/Discard. This deletes your current file (even if it was saved to disk) and replaces it with the head revision from RCS.

If you have checked changed file in to RCS, you can revert to the previous revision:

This operation will create a branch in RCS and you will continue working with your file from that point in its revision history

Open one file in the Firewall Builder GUI, then use main menu function "File/Import library" to import other files one at a time. Despite its name, this function can import both regular data files (.fwb) and library files (.fwl).

Note that the program identifies objects by their iternal unique IDs rather than by name. This means two objects can have the same name, which is probably inconvenient and should be avoided, but is not at problem per se. On the other hand, if you happen to have objects with the same ID in two data files, you can not import one such file into another. In fact, if you try to do that, the program will detect the conflict and present you with a dialog asking you to choose which object of the two you want to keep. This may be a problem if these two objects have different parameters (such as for example two network objects with the same ID but different IP address). Situation like this may happen if you make a copy of the data file and continue working with both the original and the copy, making changes to objects in both. With time, two files will probaly drift apart and at some point it will become impossible to merge them back. Such "forking" of the data files should be avoided.

As described in the previous question, the program identifies objects by their internal unique IDs. If you make a copy of the data file, you create copies of all objects it contains. Copies inherit IDs of the original objects, this means you now have two data files, each of which has objects with the same ID. If you now make any change to an object in one of these files, changing its parameter, you create potential conflict in case you want to merge these two files together in the future. It is not recommended to make such "forks" of the data files. You can create many firewall objects in the same file and manage multiple firewalls that way. There should be no reason to work with two distinct copies of the same data file.

However if this happened and you want to merge such conflicting files, use main menu function "Tools/Find Conflicting Objects in Two Data Files" to find all conflicts before you try to merge. This function lets you open two data files and finds all objects that have the same ID but different other attributes. It shows you such objects side by side and in the end can generate a report and save it in a text file. The procedure is as follows: