Nupyf: administrator manual

Damien Boucard

This documentation is distributed under the GNU Free Documentation License. Before reading/copying/using this documentation, please make sure you have read and accepted the license. See http://www.gnu.org/licenses/licenses.html#FDL

Revision History
Revision 0.12005/06/15
Revision 0.1.12006/02/10

zones deletion, documented dftgateway attribute

Revision 0.22007/01/03

update document for NuPyF 1.2 (multiple addresses per interface, local_ipv4 type, layer7 filtering, Acl ID in logs, no same iface option, Acl descsort)


Table of Contents

General Introduction
Usage
Options
Configuration file
XML network description file (desc.xml)
Exemple
XML tags definition
Installation
Prerequisites
Installation

General Introduction

Nupyf is a tool working on an ACL XML file formatted for NuFW, and on an XML network description file, and generates a script suitable to load rules into Netfilter, as well as ACLs in an LDAP tree, usable by the nuauth server.

Usage

./nupyf.py [options] firewall_file.xml acls_file.xml

Options

Available options are:

  • -d, --dispatch dispatch.txt: writes dispatch and default reject rules into file dispatch.txt

  • -f, --forward fwd.txt: write forward rules into file fwd.txt

  • -i, --input in.txt: write rules for input into file in.txt

  • -o, --output out.txt: write output rules into file out.txt

  • -m, --mangle mangle.txt: write mangle rules into file mangle.txt

  • -v, --vpn vpn.txt: write vpn rules into file vpn.txt

  • -n, --nat nat.txt: write nat rules into file nat.txt

  • -r, --rescue: activate standard mode, ie, generated rules suit a non nufw firewall

  • --ulog: all netfilter logs will be sent to the ULOG target, instead of LOG. This is useful for SQL logging

  • --iptables: where to find iptables command, default is $ipt.

  • -s, --server: ldap server address

  • -u, --user: User for LDAP binding. Ex: 'cn=admin,dc=inl,dc=fr'

  • -p, --pwd: Password for LDAP binding

  • -b, --basedn: basedn where to store the NuFW ACLs

  • -a, --askpwd: request user to interactively type the LDAP password

  • -c, --config: path to nupyf config file (nupyf.conf)

  • --dumpldap ldap_obj: dumps ldap informations generated from the xml file into file obj_ldap

  • --loadldap ldap_obj: loads ldap informations from file obj_ldap

  • --auth_ext: generates netfilter rules to autenticate internet

  • --sortid: ACLs are ordered by the given ID

  • --no-same-iface: (recommended) optimizes bi-chain generation: chains which come from same interfaces are not considered for builting bi-chains

  • --ipv6: all IP adresses are manipulated as IPv6 adresses

  • --nulayer7: directory where to find nulayer7 modules ; if not set, disable Layer7 filtering.

  • -h, --help

The "-" value can be passed to the --dispatch, --input, --output, --forward and --nat options, and designates the standard output.

The --dumpldap and --loadldap options allow NOT to modify the LDAP tree while building the netfilter rules. It is hence possible to re-use the same informations without analysing the XML files again, and directly fill/update the LDAP tree from the dump file.

Rules in the LDAP tree are defined as such : <subject-name_resource-name_protocol-name_id_random>. ID value is the number of the rules coming from the correponding ACL in the XML file (one ACL can generate several rules). The random field is to make sure there will be no conflict between two ACLs while insertion (collision would occur if the same dn was used twice, not from the data in the rule).

Configuration file

The --config option specifies the nupyf configuration file. This file contains (for now) connection settings to the LDAP tree, and must respect this syntax:

{
'ldap_server': 'ldap.firm.com',
'ldap_password': 'secret',
'ldap_user': 'cn=ldap_user,dc=firm,dc=com',
'ldap_basedn': 'ou=Acls,dc=firm,dc=com',
}

Lines starting with # are ignored by the config file parser.

XML network description file (desc.xml)

Nupyf uses an XML file, that describes firewall's interfaces, and attached networks. Though nupyf doesn't support it yet, this file's syntax allows for configuring several firewalls.

The network description XML file uses the following XML tags:

Firewall interfaces description

address

address of an interface of the firewall.

interface

name of an interface of the firewall and encapsulates its address tags.

interfaces

encapsulates one or several interface tags.

fw

Describes type and name of a firewall.

fws

used to encapsulate one or several fw tags.

Network description

connection:

describes a relation between a firewall interface and a network.

net:

describes a network. Encapsulates connection tags.

nets

encapsulates both other tags.

The network tag encapsules all other named tags herein.

Exemple

This example shows a firewall with four interfaces, and linked to five networks:

  • The interface eth0 is linked to the INTERNET and INTERNETALIAS networks

  • The interface eth1 is linked to the DMZ network

  • The interface eth2 is linked to the INTRANET network

  • The interface tun0 is linked to the OPENVPN network

LAN_1 and DMZ are internal networks, in terms of routing. INTERNET is the firewall's external network, defined as such by dftgateway attribute of connection tag.

		
<?xml version="1.0"?>
<network>
    <fws>
        <fw id="1" type="nufw" name="fydelkass" queue="0">
            <interfaces>
                <interface id="1" name="eth0">
                    <address id="1" addr="172.16.6.116"/>
                    <address id="2" addr="84.255.101.237"/>
                </interface>
                <interface id="2" name="eth1">
                    <address id="1" addr="192.168.42.1"/>
                </interface>
                <interface id="3" name="eth2">
                    <address id="1" addr="192.168.42.129"/>
                </interface>
                <interface id="4" name="tun0">
                    <address id="1" addr="10.8.0.1"/>
                </interface>
            </interfaces>
        </fw>
    </fws>
    <nets>
        <net id="1" name="INTERNET" type="ipv4" addr="172.16.6.0/24">
            <connection direct="1" fwid="1" iface="1" dftgateway="172.16.6.1" snat="0"/>
        </net>
        <net id="2" name="INTERNETALIAS" type="ipv4" addr="84.255.101.232/29">
            <connection direct="1" fwid="1" iface="1" snat="0"/>
        </net>
        <net id="3" name="DMZ" type="ipv4" addr="192.168.42.0/255.255.255.128">
            <connection direct="1" fwid="1" iface="2" snat="1"/>
        </net>
        <net id="4" name="INTRANET" type="ipv4" addr="192.168.42.128/255.255.255.128">
            <connection direct="1" fwid="1" iface="3" snat="1"/>
        </net>
        <net id="5" name="LAN_1" type="ipv4" addr="192.168.100.0/24">
            <connection direct="0" fwid="1" iface="3" gateway="192.168.42.254" snat="1"/>
        </net>
        <net id="6" name="OPENVPN" type="ipv4" addr="10.8.0.0/24">
            <connection direct="1" fwid="1" iface="4" snat="1"/>
        </net>
    </nets>
</network>

		

XML tags definition

The fw tag

Attributes
idnumeric entry
type'nufw' value
namealphanumeric value, no space allowed.
queueNumeric value. Allow to use connexion tracking made by nufw for authenticated acls and to not generate netfilter rules that made this task. The value represents the queue used by NuFW to communicate with the kernel. Put 0 if you don't known which value to use. Using this parameter requires nufw >= 1.2, linux kernel >= 2.6.14, and libnfnetlink/libnetfilter_conntrack/libnetfilter_queue librairies.

The interface tag

Attributes
idnumeric entry
namealphanumeric value, no space allowed.

The address tag

Attributes
idnumeric entry
addrIP address

The net tag

Attributes
idnumeric entry
addrnetwork address
namealphanumeric value, no space allowed. The 'IF' value may not be used.
typeone amongst 'ipv4','mark'
remoteIP address. Describes the machine on the other side of a vpn. This MUST be set when zone is 'vpn', and is useless in other cases
markNumeric value. Must contains the mark used to tag packets coming from the VPN. MUST be set when type is 'vpn'.

The connection tag

Attributes
direct0 or 1.
fwidnumeric entry.
ifacenumeric entry
dftgatewayIP address. Describes the firewall's default gateway.
gatewayIP address. Describes the gateway in a direct network which can route connections to this remote network. (used with direct="0")
snatif set to 1, indicates connections from this network to Internet will use Source NAT (masquerading).

Setting 1 for the direct attribute means the firewall is directlty linked to the network. Setting 0 means a hop is needed to reach the network, or a VPN is used. Any given interface must be directly linked to at least one network.

The fwid attribute must be set to the ID attribute of the firewall connected to the given network.

The iface attribute must be set to the ID attribute of the interface connected to the given network.

Installation

Prerequisites

To use nupyf, one needs:

  • python 2.3

  • IPy 0.50: this python package manipulates IP objects, and is available at CheeseShop webpage. A (sarge) debian package is provided by INL, which now maintains the project.

Installation

This tools is composed of the main script : nupyf.py, and of python modules:

  • fw.py

  • ipt.py

  • nuacl.py

  • nubackend.py

  • nuldap.py

  • nunat.py

  • nuxml.py

If used with the Nuface interface, modules must stand in the same directory as the nupyf.py directory.