README

   1
   2         README for ferm
   3
   4         Auke Kok <sofar@foo-projects.org>
   5         Max Kellermann <max@foo-projects.org>
   6
   7
   8 Contents:
   9
  10         - Description
  11         - Installing ferm
  12         - Uninstalling ferm
  13         - Basic use of ferm
  14         - Getting a firewall working with ferm on your system
  15         - Package contents
  16
  17
  18 Description
  19
  20         ferm is a frontend for iptables. It reads the rules from
  21         a structured configuration file and calls iptables(8) to
  22         insert them into the running kernel.
  23
  24         ferm's goal is to make firewall rules easy to write and
  25         easy to read. It tries to reduce the tedious task of writing
  26         down rules, thus enabling the firewall administrator to spend
  27         more time on developing good rules than the proper
  28         implementation of the rule.
  29
  30         To achieve this, ferm uses a simple but powerful configuration
  31         language, which allows variables, functions, arrays,
  32         blocks. It also allows you to include other files, allowing
  33         you to create libraries of commonly used structures and
  34         functions.
  35
  36         ferm, pronounced "firm", stands for "For Easy Rule Making".
  37
  38
  39 Installing ferm
  40
  41         # make install
  42
  43         The package does not need to be compiled, just make sure you
  44         have perl (which is present in any base linux system) and
  45         iptables (including iptables-save and iptables-restore), and
  46         the a kernel supporting netfilter.
  47
  48         Run the make install install script as root to install the
  49         package in it's best location, so it can be reached from
  50         the command line when called. The manual page will also
  51         be installed.
  52
  53         That's all!
  54
  55
  56 Uninstalling ferm
  57
  58         # make uninstall
  59
  60         Ferm can now be quickly removed from the system by issuing
  61         a "make uninstall" command (as root, of course). This
  62         will not remove any configuration files of course!
  63
  64
  65 Basic use of ferm
  66
  67         ferm is designed to parse structured firewall files,
  68         merely it's own language (quite C-like) to describe
  69         firewall-rules. Look at the examples for a good idea.
  70         To install a firewall, create an appropriate firewall
  71         file that suits your needs, store it into a good spot
  72         like /etc/ferm/ferm.conf and execute:
  73
  74                 ferm /etc/ferm/ferm.conf
  75
  76         ferm will read the file, translate it into netfilter rules,
  77         and install these into the kernel.  Read the manual and the
  78         examples to get the idea about the syntax of the firewall
  79         files.
  80
  81         Generally, ferm will be called in 2 ways:
  82
  83         - testing a firewall.conf file:
  84
  85                 ferm --lines --noexec /etc/ferm/ferm.conf
  86
  87         This way, the actual firewall is not implemented, but the
  88         resulting rules are printed so you may check them. Add
  89         -d or -v for even more information.
  90
  91         - implementing a ferm setup manually:
  92
  93                 ferm --lines --noexec /etc/ferm/ferm.conf
  94
  95         This way, you may check any iptables generated errors and
  96         check again rules are implemented correctly. It is
  97         advisable to carefully check the output.
  98
  99         When you are satisfied with the generated rules, feel free
 100         to insert ferm into an rc.d script or even an ip-up ppp
 101         script. Make sure you are satisfied with the setup because
 102         a wrong configuration may lead to terrible things. The
 103         line you need to insert will look like this:
 104
 105                 ferm /etc/ferm/ferm.conf
 106
 107
 108 Getting a firewall working with ferm on your system
 109
 110         First, get to know ferm, read the previous section and toy
 111         around with some examples. Ferm is really simple, but still
 112         people e-mail me questions that are answered in the man-page.
 113
 114         It is a requirement that you get some basic knowledge of
 115         networking before experimenting with ferm. I cannot stress
 116         that enough. There are many introductions available on
 117         the internet that explain the way the internet is constructed
 118         and what all those protocols are and how they work.
 119
 120         Also you should be comfortable as root modifying your system
 121         setup and editing some textfiles. Ferm may require you to
 122         use text-editors and plain old point and click do not work
 123         with ferm.
 124
 125         Okay, you've not ran away crying or screaming, good, now do
 126         this:
 127
 128         - make a ferm config file (or even more!)
 129
 130         Read the examples and compile a firewall that suits your needs,
 131         add or remove items at will and test it thoroughly
 132
 133         - test the ferm config file
 134
 135         Make sure the firewall behaves as you want it to! Be careful
 136         with this!!!
 137
 138         - install it on the system
 139
 140         Execute ferm manually or put it in an rc.d boot script, a ppp
 141         script or wherever you see fit. You might have more that one
 142         script (like the author).
 143
 144         That's it!
 145
 146
 147 Package Contents
 148
 149         * README        This file
 150         * AUTHORS       List of people who worked on the project
 151         * COPYING       Copy of the GPL
 152         * NEWS          A list of changes in the development of ferm
 153         * src/ferm      The program
 154         * doc/ferm.pod  The pod (perl doc format) file
 155         * doc/ferm.1    The man page
 156         * doc/ferm.txt  The man page as plain text
 157         * doc/ferm.html The man page as html file
 158         * examples/*    Some examples
 159         * Makefile      Installation Makefile
 160
 161
 162 --
 163 Auke Kok <sofar@foo-projects.org>