Sanewall - making sense of firewalling
                  **************************************
                       http://www.sanewall.org/
                       ************************

Sanewall is a firewall builder for Linux which uses an elegant language,
abstracted to just the right level. This makes it powerful as well as easy
to use, audit, and understand. It allows you to create very readable
configurations even for complex stateful firewalls.

Simple but useful firewalls need only a few lines of configuration. Very
complex setups with flow control and external commands can be created by
using bash (http://www.gnu.org/software/bash/) commands in-line with the
standard configuration language.

Sanewall can be used to produce local firewalls or router-based firewalls
on any system that bash and iptables are available including full GNU/Linux
servers and embedded routers such as OpenWRT (http://www.openwrt.org/).


Known Issues
============
This is a development release of Sanewall. Below is a list of issues you
should consider before using it. Note that the list is probably not
exhaustive.

You should also read the "IPv6 Support" section of this README.

If you do choose to use this version, please take the time to audit
the output and ensure it meets your expectations.

If you encounter any bugs or unexpected behaviour please report them
to the mailing list or bug tracker.

1. There are a variety of ICMPv6 packet types without helpers and
   not described here yet which are needed for full handling of IPv6.

   The ipv6error packet rules have not been thoroughly tested.

   A full set of ICMPv6 recommendations that ought to be implemented are
   here:
     http://tools.ietf.org/html/rfc4890

   The recommendations, and how to achieve them (and where there is
   still work to do) are documented in the "RFC 4890 Recommendations"
   section of sanewall-manual.pdf and the online documentation.

2. There is no Linux kernel NAT support for IPv6, you will get errors
   if you try to use it.

   The masquerade command automatically defaults to  only.

3. No way to successfully mark a whole interface or router as ipv4/ipv6 only

   There hopefully aren't too many situations where one would want
   to do this but support will be added in due course.

4. Private / Unroutable IPv6 lists may be incomplete.

5. Creating a rule which applies only to one ip type will lead to
   empty chains. For example:
      server ssh accept src "10.0.0.0/8"

   will create two chains, one using iptables and the other using
   ip6tables; only the iptables chain has any rules added to it. This
   should not cause any problems, but can look odd when inspecting
   the tables directly.


Goals
=====
The main goals of the Sanewall project are:
  - Allow experts and non-experts alike to produce secure firewalls
  - Simple configuration should be simple
  - Complex configuration should be possible (and as easy as possible)
  - Maintain compatibility with old FireHOL configurations
  - Eliminate distinctions between IPv4 and IPv6 wherever possible
  - Keep to a minimal set of dependencies

This is achieved by providing an expressive, easy-to-read, write and
understand configuration language geared specifically to firewalls
(a Domain Specific Language).

The language is sufficiently brief, well-structured and meaningful that
a human can manage the firewall rules without the need for additional tools.
The use of a simple text-file for configuration allows for optimal use
with version control and file-comparison tools.


Getting Started
===============
If you want to install the package from the source tar-files found here:
   http://download.sanewall.org/releases
please read the file INSTALL first. Sanewall uses the GNU Autotools so
you can get away with:
  ./configure && make && make install

When you first install the program a very basic sanewall.conf.example
is installed, which if you rename it to sanewall.conf will allow connections
out but not in. To get something more complete you have three choices:

  1. If you are replacing FireHOL you should just be able to create the
     Sanewall configuration by copying firehol.conf over sanewall.conf
     and renaming any FIREHOL_ variables to SANEWALL_ instead.

     Rename the files (if you have them, they are optional):
        RESERVED_IPS   ->   RESERVED_IPV4
        PRIVATE_IPS    ->   PRIVATE_IPV4
        MULTICAST_IPS  ->   MULTICAST_IPV4

     There are new (optional) files for IPv6 addresses:
        RESERVED_IPV6, PRIVATE_IPV6 and MULTICAST_IPV6

     If you have any custom services in /etc/firehol/services then you
     will need to update those, too.

     If you made use of "firehol save" you need to verify that the
     SANEWALL_AUTOSAVE and SANEWALL_AUTOSAVE6 variables are correctly
     specified.

     If you made use of "firehol condrestart" you should be aware that
     sanewall implements the behaviour documented here:
       http://fedoraproject.org/wiki/Packaging:SysVInitScript#Required_Actions
     whereas firehol started only if it was not already running.

  2. Start from an example configuration:
       client-all.conf
       lan-gateway.conf
       server-dmz.conf
       office.conf
       ipv6.conf

  3. Have Sanewall try to generate a configuration tailored to the machine
     automatically by running:
       sanewall wizard

You should review the variables that can be configured and decide if you
want to change any. The variables are documented in the "control variables"
reference section of sanewall-manual.pdf and the online documentation. You
can also read the man-page:
  man sanewall-variables

If you are running a service which is not pre-defined for you it is simple
to define your own. This is documented in the "Adding Services" part of
the "sanewall configuration" reference section of sanewall-manual.pdf and
the online documentation. You can also read the man-page:
  man sanewall.conf

Finally, you will also want to ensure that Sanewall runs at boot-time. If you
installed from an official package this will be configured in the usual way.
For a source installation, the binary can be linked directly into /etc/init.d
on many systems. In addition, some example init scripts are available here:
  http://bugs.sanewall.org/wiki/Init_Scripts


IPv6 support
============
Versions of Sanewall above 1.1.0 contain IPv6 support.

Sanewall will attempt to load both iptables and ip6tables entries for
all rules, except as follows:

1. When invoked with -4 or -6 on the command line:

     sanewall -4 ...
       IPv4 only

     sanewall -6 ...
       IPv6 only

2. Explicitly stated version in the configuration e.g.:

   interface wlan0 internet
      ipv4 masquerade
      ipv6 server ssh allow

   Will only enable masquerading on IPv4 and ssh access via IPv6.

2. Implicit protocol or address in the configuration e.g.:

   interface eth0 lan
      server telnet accept src "192.168.0.0/24"
      server ftp accept src "fe80::/64"
      server ssh accept src "fe80::/64 192.168.0.0/24"

   Will should do the "right thing" and allow mix and match of addresses.
   Note that creating a rule with e.g. "src not" will negate fully. For
   example:
      server ssh accept src not "10.0.0.0/8"

   Will accept any address that is not 10.0.0.0/8, including any IPv6.
   If you mean not 10.0.0.0/8 and no IPv6 addresses you should restrict
   the rule explicitly:
      ipv4 server ssh accept src not "10.0.0.0/8"

   The same applies if you negate only IPv6 addresses.

3. ICMP and ICMPv6 are not identical. You will get warnings and/or errors
   if you try to include rules for an ICMP packet type for ICMPv6 and
   vice-versa e.g.:

   interface eth0 lan
      client timestamp accept

   will issue a warning, but:

   interface eth0 lan
      ipv4 timestamp client accept

   will not, the reason being that the ICMP packets timestamp-request and
   timestamp-reply have no equivalent in ICMPv6.

   New ipv6-only marked protocols (e.g. ipv6router, ipv6neigh) will not
   warn in "both" mode, only in "ipv4" mode.

4. Network neighbour solicitation/advertisement messages (IPv6 replacement
   for ARP) should be enabled on each interface. In most contexts,
   router solicitation/advertisement messages should also be enabled
   to allow router auto-configuration.

   See the documentation (sanewall-manual.pdf or man sanewall-services)
   on ipv6neigh and ipv6router for details. See also the ipv6.conf example.

5. Various ICMPv6 error messages need to be allowed for correct operation
   of IPv6.

   See the documentation (sanewall-manual.pdf or man sanewall-services)
   on the ipv6error complex rule for details. See also the ipv6.conf example.


Support and documentation
=========================
The main website is here:
   http://www.sanewall.org/

To ask questions please sign up to the list:
   http://lists.sanewall.org/mailman/listinfo/sanewall-users

Man pages, PDF and HTML documentation are provided as part of the package
and can be found in the tarball or in your distribution's standard locations
(e.g. /usr/share/doc). The latest manual is always available as PDF and
online HTML here:
   http://download.sanewall.org/releases/latest/sanewall-manual.pdf
   http://download.sanewall.org/releases/latest/sanewall-manual.html

along with a list of all services supported "out of the box":
   http://download.sanewall.org/releases/latest/sanewall-services.html

For further help and advice the sanewall-users mailing list archive is
fully searchable:
   http://lists.sanewall.org/pipermail/sanewall-users/


Contributing
============
The wiki page for contributors and potential contributors is here:
   http://bugs.sanewall.org/wiki/Getting_Involved

The official bug tracker is here:
   http://bugs.sanewall.org/sanewall

The official git trees are here:
   http://git.sanewall.org/

If you would like to get involved, please consider subscribing to the
development mailing list:
   http://lists.sanewall.org/mailman/listinfo/sanewall-dev


History
=======
Sanewall is a fork of FireHOL (http://firehol.sourceforge.net/) which was
made when development of that project stalled. A great deal is owed to that
project and Costa Tsaousis for originating it. All existing FireHOL
definitions should be compatible with Sanewall.


License
=======
Copyright (C) 2012,2013 Phil Whineray <phil@sanewall.org>
Copyright (C) 2003-2013 Costa Tsaousis <costa@tsaousis.gr>

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