README

APF (Advanced Policy Firewall) - 0.9.6 [[email protected]]
 Copyright (C) 1999-2004, R-fx Networks <[email protected]>
 Copyright (C) 2004, Ryan MacDonald <[email protected]>

This program is free software; you can redistribute it and/or modify
 it under the terms of the GNU General Public License as published by
 the Free Software Foundation; either version 2 of the License, or
 (at your option) any later version.

This program is distributed in the hope that it will be useful,
 but WITHOUT ANY WARRANTY; without even the implied warranty of
 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
 GNU General Public License for more details.

You should have received a copy of the GNU General Public License
 along with this program; if not, write to the Free Software
 Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA

Contents:
1 ............. Introduction
2 ............. Configuration
2.1 ........... APF @ Boot
3 ............. Usage
4 ............. License
5 ............. Support

1) Introduction:
APF is a policy based iptables firewall system designed for ease of use and 
configuration. It employs a subset of features to satisfy the veteran
Linux user and the novice alike. Packaged in tar.gz and RPM formats, APF is
ideal for deployment in any linux server environment.

Summary of features:
- simple & well commented configuration files
- layered firewall with independent ingress and egress filtering system
- uid based egress filtering via simple configuration variables
- global tcp/udp ports & icmp types configurtion
- configurable policies for each ip on the system with convenience vars 
- prerouting rules for optimal network responce; TOS (type of service)
- icmp based rate limiting to prevent common icmp 'dos' abuses
- antidos subsystem to stop attacks before they become a significant threat
- dshield.org block list support to ban networks exhibiting suspicious activity
- advanced set of sysctl parameters for tcp/ip stack hardening
- advanced set of filter rules to remove undesired traffic
- advanced use of kernel features such as abort_on_overflow & tcp syncookies
- easy to use firewall managment script 
- trust based rule files (allow/deny); with advanced syntax support
- 3rd party addon projects that compliment APF features
- and much more...

2) Configuration:
The configuration file for APF is for the most part, simple. It contains
many comments and should not be hard to navigate.

APF uses a policy rules structure; the main ethernet adapter [e.g: eth0]
is configurable via /etc/apf/main.rules, where-as alias adapters are
configurable via /etc/apf/vnet/1.1.1.1.rules [1.1.1.1 being the ip]. The
policy files are all structured to give custom rules presidence to the
conf.apf configurable ports that are global to all server ip's/adapters.

Required iptable modules that must be compiled-in or module compiled:
ip_conntrack
ip_conntrack_ftp
ip_conntrack_irc
iptable_filter
iptable_mangle
ip_tables
ipt_limit
ipt_LOG
ipt_multiport
ipt_REJECT
ipt_state
ipt_TOS

APF's main configuration file is located at:
/etc/apf/conf.apf

You will need to go through it and configure options you feel meet your
environment settings. Below is a definition breakdown of each feature in
the conf.apf file (except misc. options), listed in the format of Option
(config option and default value) followed by definition.

Option: DEVM="1"
Definition: APF comes default in dev. mode; meaning the firewall rules
will be flushed every 5 minutes. This is intended to prevent you from
being locked out of your system in the event of undesired results from APF.
Set the DEVM="1" option to zero (0) once APF is operating as desired.
Do NOT! leave this option enabled on a permanet basis, or you defeat
the purpose of using a firewall.

Option: LGATE_MAC=""
Definition: Local gateway mac address [optional]; when a value is present, only traffic
from the local gateway will be permitted. It is quite trivial to forge a MAC address and 
as such this is provided as another layer of route verification.

Option: LGATE_LOG="0"
Definition: Log all forign gateway traffic. [0 = Disabled / 1 = Enabled]

Option: EN_VNET="0"
Definition: Enable virtual network subsystem; creats independent policy ruleset for each
ip on a system (pulls data from 'ip addr list') to /etc/apf/vnet/ip.rules; Template is
located in the vnet/ folder for rule files. This feature can reduce apf start/stop performance
and is not recommend for systems with more than 255 (/24) ip's. [0 = Disabled / 1 = Enabled]

Option: FWPATH="/etc/apf"
Definition: Absolute install path to APF; should not be changed usualy.

Option: IF="eth0"
Definition: Network interface visable too the Internet/Intranet.

Option: NET=`ifconfig $IF | grep inet | cut -d : -f 2 | cut -d \ -f 1`
Definition: IP Address that $IF holds; either define the IP in this value
or leave it as-is to autodetect.

Option: TIF=""
Definition: Trusted Network interface(s); all traffic on defined interface(s) will by-pass
ALL firewall rules (white space or comma seperated list; e.g: TIF="eth1 eth2").

Option: APF_LOG="/var/log/apf_log"
Definition: Location that APF should log status information to.

Option: DROP_LOG="1"
Definition: Control toggle to enable/disable netfilter kernel log chains.
These chains appear in the default syslog kernel log; /var/log/messages.

Option: LOG_RATE="60"
Definition: Limiting toggle to increase or decrease the max iptables
logging events per/minute. This should be left high but may be decreased
to preserve disk space and logging overhead.

Option: IG_TCP_CPORTS="22"
Definition: Common inbound ports; used to open TCP ports across all
ip addresses on an APF system. The values are comma seperated, port range
supported with underscore (_) seperator.
e.g: TCP_CPORTS="21,22,25,53,80,443,110,143,6000_7000"

Option: IG_UDP_CPORTS=""
Definition: Common inbound ports; used to open UDP ports across all
ip addresses on an APF system. The values are comma seperated, port range
supported with underscore (_) seperator.
e.g: UDP_CPORTS="53,1024_65535"

Option: EGF="0"
Definition: Toggle on or off the egress packet filtering; when off APF will
operate as traditional older versions did with just input filtering.
[0 = Disabled / 1 = Enabled]

Option: EG_TCP_CPORTS="22"
Definition: Common outbound ports; used to open TCP ports across all
ip addresses on an APF system. The values are comma seperated, port range
supported with underscore (_) seperator.
e.g: TCP_CPORTS="21,22,25,53,80,443,110,143,6000_7000"

Option: EG_UDP_CPORTS=""
Definition: Common outbound ports; used to open UDP ports across all
ip addresses on an APF system. The values are comma seperated, port range
supported with underscore (_) seperator.
e.g: UDP_CPORTS="53,1024_65535"

Option: USE_DS="0"
Definition: DShield.org's "block" list of top networks that have exhibited 
suspicious activity. [0 = Disabled / 1 = Enabled]

Option: USE_AD="0"
Definition: Enable the inclusion of antidos issued bans when APF starts. If
enabled, /etc/apf/ad/conf.antidos is parsed for further antidos specific
options. Check README.antidos for more information. 
[0 = Disabled / 1 = Enabled]

2.1) APF @ Boot:
To have APF start during boot you can do one of two options...
One either setup APF in the init system with chkconfig, as detailed
below:

chkconfig --add apf
chkconfig --level 345 apf on

Or, secondly you can add the following string too the bottom of the
/etc/rc.local file:

sh -c "/etc/apf/apf -s" &

It is not recommended that you use both of these startup methods together,
for most systems the init script via chkconfig should be fine.

3) Usage:
In all accounts APF is very simple to operate. The main 'apf' script has a few 
operations built in to ease the use of your firewall.

usage: /usr/local/sbin/apf
-start Load firewall policies
-restart Flsuh & Load firewall
-flush Flush firewall
-list List chain rules
-status Firewall status

APF can also be started from the init script located at /etc/init.d/apf,
standard start|stop|restart arguments are accepted by this script. APF does not
operate as a service, as some conclude if there is an init script.

- Other Features
APF comes packaged with two trust based files for the inclusion of IP's. These
files allow two trust levels that are, allow and deny.

The allow and deny trust files are located at:
/etc/apf/allow_hosts.rules
/etc/apf/deny_hosts.rules

The format of these files are line-seperated addresses, IP masking is supported.
Example:
24.202.16.11
24.202.11.0/24

Advanced trust usage; The trust rules can be made in advanced format with 4
options (proto:flow:port:ip);
 1) protocol: [packet protocol tcp/udp]
 2) flow in/out: [packet direction, inbound or outbound]
 3) s/d=port: [packet source or destination port]
 4) s/d=ip(/xx) [packet source or destination address, masking supported]

Flow assumed as Input if not defined. Protocol assumed as TCP if not defined.
When defining rules with protocol, flow is required.

Syntax:
 proto:flow:[s/d]=port:[s/d]=ip(/mask)
 s - source , d - destination , flow - packet flow in/out

Examples:
 inbound to destination port 22 from 24.202.16.11
 tcp:in:d=22:s=24.202.16.11

outbound to destination port 23 to destination host 24.2.11.9
 out:d=23:d=24.2.11.9

inbound to destination port 3306 from 24.202.11.0/24
 d=3306:s=24.202.11.0/24

4) License:
APF is developed and supported on a volunteer basis by Ryan MacDonald
[[email protected]]

APF (Advanced policy firewall) is distributed under the GNU General Public
License (GPL) without restrictions on usage or redistribution. The APF
copyright statement, and GNU GPL, "COPYING.GPL" are included in the top-level
directory of the distribution. Credit must be given for derivative works as
required under GNU GPL.

5) Support:
All inquiries relating to APF should be directed to [email protected] and/or check
the APF homepage at:
http://www.r-fx.org/apf.php