HOWTO for PCX Firewall 2.17+

1. download the software and install
it. The easiest is if you use the rpms. Read the README and INSTALL
files included with the distribution. If you installed via rpm, it
will be in /usr/share/doc/pcx_firewall-2.x.

2. peruse the man pages for the available modules. You
can either read them on-line or in the man directory (wherever the documentation
was installed).

3. install the pcx_firewall_rules
module.

4. edit the Rules.pm module or the
XML config file for the VeryTight or VeryTight2 rules modules. They
should be located at /usr/lib/pcx_firewall/PCXFireWall/.

5. run /usr/lib/pcx_firewall/generator
-r Rules -c ConfigFile. Where Rules is the rule module used and ConfigFile is the config file the rule
module needs, if it supports it. The resulting firewall script will be either in output or the name of the Rule module
- config file name. Ex: Rule module = VeryTight2 and config file
= test.xml, then output location would be VeryTight2-test.xml/firewall. Then
copy the generated firewall script to /etc/pcx_firewall. You can use
the install script to do this for you. Run /etc/pcx_firewall/firewall
start to start your firewall and test it.

Running generator -h will give all
the possible arguments for the generator script and a quick description of
them. It is now possible to generate a chkconfig compatible shell script
using the -s, -V and -d arguments.

Running install -h will give all
the possible arguments for the install script and a quick description of
them.

You can specify the Rules file to work with on the command line to
generator. If you do not specify anything, it defaults to Rules. The
file specified must exist in the PCXFireWall directory and must end in a
.pm extension. (Ex. test.pm would be usable as test.) There is
a Template.pm file in the doc directory. Copy it into PCXFireWall naming
it without any spaces in the name (perl modules can not have spaces in them)
and then edit the file and replace the word Template with The name
of the file minus the .pm extension. Then put your rules in the
same locations as you would if editing Rules.pm since this is a stripped
down version of Rules.pm. In the future, when new Table Modules are
added, to get access to those modules, you would just use the latest version
of Template.pm to put your rules in. It will have defined the variables
that will allow you to work with the new table modules. If you don't
upgrade your rules files, then you would only have access to the Filter,
Mangle and NAT modules.

When you specify a Rules file to work with the generated files are
now placed in a directory named after the Rules file you are using.
For Example if you used the rules file test.pm (generator
test) then the generated files would be placed in directory test.
To have the install script work with the files just generated you will
now have to specify the -s sourcedir option. In this
example you would install the files as follows: install -s test.
This would pull the firewall script from the test directory
and place it in /etc/pcx_firewall/. If you wanted the destination
directory to be under /usr for instance you could use the -r root
dir option to specify the root directory to prefix /etc/pcx_firewall
with. To complete this example you would have install -r /usr -s
test to pull the file from the test directory and put it in /usr/etc/pcx_firewall.
Note: If you do not specify either -r or -s options for the install
script, it will use the defaults of "" for -r and "output" for -s.

All /proc related manipulation is now done in the Proc module and is available
via $proc in the Rules.pm file. You should use the latest Template.pm module
and integrate your rules into it. See the Rules.pm file for examples of
setting ipForwarding, synCookies, etc.

The only file you should have to modify is Rules.pm. In it you will
find 3 methods defined (startingRules, stoppingRules and restartingRules).
These methods have passed into them the available modules we have defined.
These modules are (Config, Interfaces, Filter, NAT, Proc, Mangle and
Network).

Programming Note: Passing parameters to the defined methods is as
follows: parameter name => parameter value, parameter
name => parameter value, ...
If a parameter name has a - in it, wrap the parameter name in double
quotes (ex. "to-source" => "192.168.1.1").
If the parameter value is a string, then wrap it in double quotes. See
last example.
Parameter Names are CASE sensitive. If you change the case then
it will not be seen and the default will be used that the method provides.
Anything after a # is considered a comment to perl, as long as it
is outside a string.

In each of the above methods, you can use the available modules to define
what you want to happen in your firewall.

The perl program generator is responsible for instantiating each of
the above mentioned modules and for calling the methods provided by Rules
so as to generatethe firewall shell script which will actually do
your dirty work.

You must define all network interfaces you want to work with as they are
now being turned into shell variables and the shell variable is used in the
generated iptables command. You can classify your interfaces as internal,
external, firewall or dmz.
There are methods provided by the Interface module to get all interfaces
defined for a specified location (internal, external, firewall or dmz) and
to get the info you defined for a specific interface. You can create
IP Aliased interface entries (ex. eth0:0), but when it is used in the generated
rule, it will be referenced as the interface without the :X part (ex. eth0).
This is because iptables does not support aliased interfaces and in reality,
all that is different between the interfaces is the IP Address it responds
to.

Since the "Rules" are being programmed in perl, you have the ability to use
perl loops, conditional statements, etc. to help implement your firewall
ruleset. One possible use could be when you want to generate the same
rule, but have different interface and IP values assigned. You could
get the list of interfaces you defined that match your requirements (ex.
all internal interfaces) and then loop over them while defining your ACCEPT,
DROP, JUMP, etc. command.

If you want some comment or shell script to be output/executed before and/or
after the rule being generated, provide your text in the preComment and postComment
parameters to the method. So in the previous example, if you wanted
the following comment "# Accept ssh traffic to $interface." placed before
the accept rule you would add the following parameter to the accept method
call. preComment => "\n# Accept ssh traffic to $interface.\n". This
would cause $interface to be expanded on each loop through the foreach statement
so that you would get eth1 and then eth2 output (or however it comes out
of the hash).

Do not forget to place a \n at the end of your preComment or postComment
strings otherwise they will run into the generated rule which is not what
you want.

It is possible to specify what network related command should be used to
determine the dynamic IP address of a dynamic interface. You can specify
ifconfig or ip by setting $configObj->{networkCommand} =
"command" in your Rules.pm module. Make sure you have the required tool
installed if you use ip.

See the Rules Package for the Rules.pm module and any other Rules
modules being developed for the PCX Firewall Distribution.