###############################
                  |                             |
                  |  DOCUMENTATION FOR PROJECT  |
                  |                             |
                  |      NETFILTER-MANAGER      |
                  |                             |
                  |        VERSION 0.1          |
                  |                             |
                  ###############################


PURPOSE
#######

The purpose of this application is to manage the netfilter rules for a number of
remote hosts.

netfilter rules can be created by entering either classic iptables rules or by
entering Cisco firewall rules. This will be of convenience to those coming from
the Cisco world and having trouble adapting themselves to iptables syntax :-)

Rules are stored on the management node (most likely this host) until they are
"pushed" to the distant node.

LICENCE
#######

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 3 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.

FUNCTIONS
#########

Rule creation :
  - via translation of Cisco rules
  - via regular iptables rules

Rule management :
  - Create per-host iptables rules
  - Organize rules using "lines"
  - Batch add rule using templates

Host management :
  - Manage hosts via their name and their DNS name or IP

Rules export :
  - Push rules via SSH
  - Once pushed, execute rule script directly if root or via sudo if non-root


HOW TO USE
##########

Help
----

If you feel lost at any time, use the 'help' command which will give you extra
information.

You may also have to access to help for certain commands. This will be included
in the generic help for the mode you are currently in.


Exit
----
If you wish to exit the program, you can enter "quit" at any time.

If you wish to exit the mode you are currently in, you can enter "exit" at any
time.

Mode Selection
--------------

First, you need to select the mode that you will be using. You can choose
between 4 modes :

    - add
    - show
    - del
    - push

The mode you are currently in will be shown at the prompt as shown below.

    ex : (add) >

    1. Add mode
    -----------

    The add mode will enable to you to add configuration information. There are
two types of information you can add : host-specific and non-host-specific.

    host-specific information needs you to select a host before you can add
information. You can do this by using the "select" command as show below. If you
do not select a host, the command will return an error asking you to select one.

    ex : (add) > select test-host-1

    Commands requiring host selection are the following :

    - access-list
    - iptables
    - line
    - template

    Commands that do not require host selection are the following :

    - select
    - help
    - host

    We will now detail the use of the commands available in the add mode.

        1. a) access-list command
        =========================

    This command is host-specific therefore requires host selection before it
can be used. Optionnally, you can select a line on which to add the rule.

    This command allows you to add Cisco-style access lists to a host.

    Example uses :
        (add-host) > access-list input allow ip any any
        (add-host) > access-list input allow ip host 192.168.1.1 any
        (add-host) > access-list output allow ip 192.168.0.0 255.255.255.0 any

    The Cisco rules get translated into iptables rules and are added to the
host. They cannot be converted back from iptables to Cisco.

        1. b) iptables command
        ======================

    This command is host-specific therefore requires host selection before it
can be used. Optionnally, you can select a line on which to add the rule.

    This command allows you to add iptables rules directly. For now, no checks
are performed on iptables rules. Therefore, errors will not be displayed until
the script is executed.

    Examples uses :
        (add-host) > iptables -s 0/0 -d 192.168.1.0/24 -j ACCEPT
        (add-host) > iptables -A PREROUTING -o eth1 -j MASQUERADE

        1. c) line command
        ==================

    This command allows you to select the line on which you want to insert the
rule. Before selecting a line, you need to select a host.

    Example use :
        (add) > select host
        (add-host) > line 99
        (add-host:99) >

        1. d) select command
        ====================

    This command allows you to select a host for host-specific commands.

    Ex : (add) > select linux-host

        1. e) host command
        ==================

    This command allows you to create a host. In order to create a host, you
will need to give a name and an IP/hostname.

    ex : (add) > host linuxhost 192.168.1.1

        1. e) template command
        ======================

    This command is host-specific therefore requires host selection before it
can be used. Optionnally, you can select a line on which to add the rule.

    The name of the template used correspond to the name of the file found in
the templates directory.

    ex : cobalt for file cobalt.tpl

    Arguments are declared before the 'START-TEMPLATE' flag.

    ex : arguments = internalsubnet, externalsubnet, host

    The 'START-TEMPLATE' flag tells the script to start replacing variables with
the arguments given when adding the template.

    Variables need to be written in the following format.

    ex : {internalsubnet}, {externalsubnet}, {host}

    When creating the script, you need to input the arguments specified in the
template file.

    Example uses :
        - (add-linuxbox) > template cobalt 1.1.1.1 2.2.2.2 linuxbox
        - (add-linuxbox:100) > template cobalt 1.1.1.1 2.2.2.2 linuxbox


    2. show mode
    ------------

    The show mode will allow you to display information about objects used in
this program.

    None of the commands available in the show require host selection. The
following commands are available in this mode :

    - access-list
    - hosts
    - iptables
    - version
    - help

        2. a) access-list and iptables command
        ======================================

    These command allow you to display all the firewall rules associated to a
specific host.

    Example use :
        (show) > iptables linuxhost
        (show) > access-list linuxhost

        2. b) hosts command
        ===================

    This command displays all the host registered in the application and their
IP or hostname.

    Example use :
        (show) > hosts

        2. c) version
        =============

    This command displays the current version of the application.

    Example use :
        (show) > version

    3. del mode
    -----------

    The del mode will enable to you to delete configuration information. There
are two types of information you can delete : host-specific and non-host-specific.

    host-specific information needs you to select a host before you can delete
information. You can do this by using the "select" command as show below. If you
do not select a host, the command will return an error asking you to select one.

    Commands requiring host selection are the following :
    - line
    - iptables

    Commands that do not require host selection are the following :
    - host
    - help

        3. a) line command
        ==================

    The line command is host-specific therefore requires you to select a host
before you can delete the line.

    This command will delete all the rules on a line.

    Example use :
        (del) > line 50

        3. b) iptables command
        ======================

    The iptables command is host-specific therefore requires you to select a
host before you can delete the rule.

    This command will delete the rule on all lines.

    Example use :
        (del) > iptables -A INPUT -s 0/0 -d 0/0 -j DROP

        3. c) host command
        ==================

    The host command will delete a host and all the rules associated with it.

    Example use :
        (del) > host linuxbox

    4. push mode
    ------------

    The push mode will allow you to push the netfilter configuration to the
hosts managed by the application.

    Commands available under this mode are the following :

    - ssh

        4. a) ssh command
        =================

    The ssh command allows you to push the rules via SSH.

    First, a script is generated containing the start template available as
"start.tpl" in the templates folder. You can customize the start template as you
wish. The rules inserted and managed in the application are added after the
start template.

    Secondly, the script is copied via SCP onto the remote host.

    If you connect as root, the program can execute the script directly so that
the rules take effect. If you don't connect as root, the program can execute
the script via sudo.