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.

Ex: (Define 3 interfaces. Drop and Log all traffic coming to the internal interfaces that isn't ssh.)
  $interfaces->defineInterface(name => "eth0", location => "external", type => "dynamic", alias => "external"); # location => "external" is assumed, so it could be left out.
  $interfaces->defineInterface(name => "eth1", location => "internal", type => "static", IP => "192.168.0.1", alias => "internal1"); # type => "static" is assumed, so it could be left out.
  $interfaces->defineInterface(name => "eth2", location => "internal", IP => "192.168.1.1", alias => "internal2");

  my %internalInterfaces = $interfaces->getInterfacesLocatedAt(location => "internal"); # get the hash of internal interfaces.
  foreach my $interface (keys %internalInterfaces)
  {
    $filter->drop(chain => "INPUT", i => $interface, d => "inInterfaceIP", dport => "! 22", log => 1, "log-prefix" => "Blocked Port");
    $filter->accept(chain => "INPUT", i => $interface, d => "inInterfaceIP", dport => "22"); # Accept ssh traffic to the internal interfaces of the firewall.
  }

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.