<?xml version="1.0" encoding="iso-8859-1"?>
<!--<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
    "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">-->
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
  "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
<article>
    <title>Nupyf: administrator manual</title>
    <articleinfo>
	<author>
	    <firstname>Jean</firstname>
	    <surname>Gillaux</surname>
	    <email>jgillaux@inl.NOSPAM.fr</email>
	</author>
        <author>
            <firstname>Damien</firstname>
            <surname>Boucard</surname>
            <email>dboucard@inl.NOSPAN.fr</email>
        </author>
	<copyright>
	    <year>2005-2007</year>
	    <holder>INL</holder>
	</copyright>
	<revhistory>
	    <revision>
		<revnumber>0.1</revnumber>
		<date>2005/06/15</date>
	    </revision>
            <revision>
		<revnumber>0.1.1</revnumber>
		<date>2006/02/10</date>
                <revdescription>
                <para>zones deletion, documented dftgateway attribute</para>
                </revdescription>
	    </revision>
            <revision>
                <revnumber>0.2</revnumber>
                <date>2007/01/03</date>
                <revdescription>
                  <para>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)</para>
                </revdescription>
            </revision>
	</revhistory>
	<legalnotice>
	<para>
	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
	<ulink url="http://www.gnu.org/licenses/licenses.html#FDL"><citetitle>http://www.gnu.org/licenses/licenses.html#FDL</citetitle></ulink>
	</para>
	</legalnotice>
    </articleinfo>
     <section><!-- ddd-->
	<title>General Introduction</title>
	<para>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.</para>
    </section>
    <section><title>Usage</title>
	<para>
	    <informalexample>
		<programlisting>./nupyf.py [options] firewall_file.xml acls_file.xml</programlisting>
	    </informalexample>
	</para>
	<section><title>Options</title>
	    <para>Available options are:
	    <itemizedlist>
	    <listitem><para>-d, --dispatch dispatch.txt: writes dispatch and default reject rules into file dispatch.txt</para></listitem>
	    <listitem><para>-f, --forward fwd.txt: write forward rules into file fwd.txt</para></listitem>
	    <listitem><para>-i, --input in.txt: write rules for input into file in.txt</para></listitem>
	    <listitem><para>-o, --output out.txt: write output rules into file out.txt</para></listitem>
            <listitem><para>-m, --mangle mangle.txt: write mangle rules into file mangle.txt</para></listitem>
            <listitem><para>-v, --vpn vpn.txt: write vpn rules into file vpn.txt</para></listitem>
	    <listitem><para>-n, --nat nat.txt: write nat rules into file nat.txt</para></listitem>
	    <listitem><para>-r, --rescue: activate standard mode, ie, generated rules suit a non nufw firewall</para></listitem>
	    <listitem><para>--ulog: all netfilter logs will be sent to the ULOG target, instead of LOG. This is useful for SQL logging</para></listitem>
            <listitem><para>--iptables: where to find iptables command, default is $ipt.</para></listitem>
	    <listitem><para>-s, --server: ldap server address</para></listitem>
	    <listitem><para>-u, --user: User for LDAP binding. Ex: 'cn=admin,dc=inl,dc=fr'</para></listitem>
	    <listitem><para>-p, --pwd: Password for LDAP binding</para></listitem>
            <listitem><para>-b, --basedn: basedn where to store the NuFW ACLs</para></listitem>
	    <listitem><para>-a, --askpwd: request user to interactively type the LDAP password</para></listitem>
            <listitem><para>-c, --config: path to nupyf config file (nupyf.conf)</para></listitem>
	    <listitem><para>--dumpldap ldap_obj: dumps ldap informations generated from the xml file into file obj_ldap</para></listitem>
	    <listitem><para>--loadldap ldap_obj: loads ldap informations from file obj_ldap</para></listitem>
            <listitem><para>--auth_ext: generates netfilter rules to autenticate internet</para></listitem>
            <listitem><para>--sortid: ACLs are ordered by the given ID</para></listitem>
            <listitem><para>--no-same-iface: (recommended) optimizes bi-chain generation: chains which come from same interfaces are not considered for builting bi-chains</para></listitem>
            <listitem><para>--ipv6: all IP adresses are manipulated as IPv6 adresses</para></listitem>
            <listitem><para>--nulayer7: directory where to find nulayer7 modules ; if not set, disable Layer7 filtering.</para></listitem>
	    <listitem><para>-h, --help</para></listitem>
	    </itemizedlist>
	    </para>
	    <para>
            The "-" value can be passed to the --dispatch, --input, --output, --forward and --nat options, and
            designates the standard output.
	    </para>
	    <para>
            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.
	    </para>
	    <para>
            Rules in the LDAP tree are defined as such : &lt;subject-name_resource-name_protocol-name_id_random&gt;.
            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).
	    </para>
	</section>
	<section><title>Configuration file</title>
        <para>
        The --config option specifies the nupyf configuration file. This file
        contains (for now) connection settings to the LDAP tree, and must
        respect this syntax:
	<programlisting>
{
'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',
}</programlisting>
Lines starting with # are ignored by the config file parser.
        </para>
	</section> <!-- fichier de conf-->
    </section><!-- utilisation -->
    <section>
	<title>XML network description file (desc.xml)</title>
	<para>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.</para>
	<para>The network description XML file uses the following XML tags:</para>
	<variablelist>
	    <title>Firewall interfaces description</title>
            <varlistentry><term>address</term>
		<listitem>
		<para>address of an interface of the firewall.</para>
		</listitem>
	    </varlistentry>

	    <varlistentry><term>interface</term>
		<listitem>
		<para>name of an interface of the firewall and encapsulates its address tags.</para>
		</listitem>
	    </varlistentry>

	    <varlistentry><term>interfaces</term>
		<listitem>
		<para>encapsulates one or several interface tags.</para>
		</listitem>
	    </varlistentry>

	    <varlistentry><term>fw</term>
		<listitem><para>Describes type and name of a firewall.</para></listitem>
	    </varlistentry>
	    <varlistentry><term>fws</term>
		<listitem><para>used to encapsulate one or several fw tags.</para></listitem>
	    </varlistentry>

	</variablelist>

	<variablelist>
	    <title>Network description</title>
	    <varlistentry><term>connection: </term>
		<listitem><para>describes a relation between a firewall interface and a network.</para></listitem>
	    </varlistentry>
	    <varlistentry><term>net:</term>
		<listitem><para>describes a network. Encapsulates connection tags.</para></listitem>
	    </varlistentry>
	    <varlistentry><term>nets</term>
		<listitem><para>encapsulates both other tags.</para></listitem>
	    </varlistentry>

	</variablelist>
	<para>The network tag encapsules all other named tags herein.</para>
	<section><title>Exemple</title>
	    <para>
        This example shows a firewall with four interfaces, and linked to five networks:
	    <itemizedlist>
<listitem><para>The interface eth0 is linked to the INTERNET and INTERNETALIAS networks</para></listitem>
<listitem><para>The interface eth1 is linked to the DMZ network</para></listitem>
<listitem><para>The interface eth2 is linked to the INTRANET network</para></listitem>
<listitem><para>The interface tun0 is linked to the OPENVPN network</para></listitem>
	    </itemizedlist>
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.
	    </para>
	    <informalexample>
		<programlisting>
		<![CDATA[
<?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>
]]>
		</programlisting>

	    </informalexample>
	</section>
	<section><title>XML tags definition</title>

	    <section><title>The fw tag</title>
		<informaltable frame="all">
		    <tgroup cols="2" colsep='1' rowsep='1'>
		    <colspec colname="c1"/>
		    <colspec colname="c2"/>
		    <thead>
		    <row>
		    <entry namest="c1" nameend="c2" align="center">Attributes</entry>
		    </row>
		    </thead>
		    <tbody>
		    <row>
			<entry>id</entry>
			<entry>numeric entry</entry>
		    </row>
		    <row>
			<entry>type</entry><entry>'nufw' value</entry>
		    </row>
		    <row>
			<entry>name</entry><entry>alphanumeric value, no space allowed.</entry>
		    </row>
		    <row>
			<entry>queue</entry><entry>Numeric 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.
                        </entry>
		    </row>
		    </tbody>
		    </tgroup>
		</informaltable>
	    </section> <!--tag fw -->

	    <section><title>The interface tag</title>
		<informaltable frame="all">
		    <tgroup cols="2" colsep='1' rowsep='1'>
		    <colspec colname="c1"/>
		    <colspec colname="c2"/>
		    <thead>
		    <row>
		    <entry namest="c1" nameend="c2" align="center">Attributes</entry>
		    </row>
		    </thead>
		    <tbody>
		    <row>
			<entry>id</entry>
			<entry>numeric entry</entry>
		    </row>
		    <row>
			<entry>name</entry><entry>alphanumeric value, no space allowed.</entry>
		    </row>
		    </tbody>
		    </tgroup>
		</informaltable>
	    </section> <!--tag interface -->

            <section><title>The address tag</title>
		<informaltable frame="all">
		    <tgroup cols="2" colsep='1' rowsep='1'>
		    <colspec colname="c1"/>
		    <colspec colname="c2"/>
		    <thead>
		    <row>
		    <entry namest="c1" nameend="c2" align="center">Attributes</entry>
		    </row>
		    </thead>
		    <tbody>
		    <row>
			<entry>id</entry>
			<entry>numeric entry</entry>
		    </row>
                    <row>
			<entry>addr</entry><entry>IP address</entry>
		    </row>
                    </tbody>
		    </tgroup>
		</informaltable>
	    </section> <!--tag address -->

	    <section><title>The net tag</title>
		<informaltable frame="all">
		    <tgroup cols="2" colsep='1' rowsep='1'>
		    <colspec colname="c1"/>
		    <colspec colname="c2"/>
		    <thead>
		    <row>
		    <entry namest="c1" nameend="c2" align="center">Attributes</entry>
		    </row>
		    </thead>
		    <tbody>
		    <row>
			<entry>id</entry>
			<entry>numeric entry</entry>
		    </row>
		    <row>
			<entry>addr</entry><entry>network address</entry>
		    </row>
		    <row>
			<entry>name</entry><entry>alphanumeric value, no space allowed. The 'IF' value may not be used.</entry>
		    </row>
		    <row><entry>type</entry><entry>one amongst 'ipv4','mark'</entry>
		    </row>
		    <!--<row><entry>zone</entry><entry>one amongst 'internal', 'external', 'vpn'.</entry>-
		    </row>-->
		    <row><entry>remote</entry><entry>IP 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</entry>
		    </row>
		    <row><entry>mark</entry><entry>Numeric value. Must contains the mark used to tag packets coming from the VPN. MUST be set when type is 'vpn'.</entry>
		    </row>
		    </tbody>
		    </tgroup>
		</informaltable>
	    </section> <!-- tag net -->

	    <section><title>The connection tag</title>
		<informaltable frame="all">
		    <tgroup cols="2" colsep='1' rowsep='1'>
		    <colspec colname="c1"/>
		    <colspec colname="c2"/>
		    <thead>
		    <row>
		    <entry namest="c1" nameend="c2" align="center">Attributes</entry>
		    </row>
		    </thead>
		    <tbody>
			<row><entry>direct</entry><entry>0 or 1.</entry>
			</row>
			<row><entry>fwid</entry><entry>numeric entry.</entry>
			</row>
			<row><entry>iface</entry><entry>numeric entry</entry>
			</row>
			<row><entry>dftgateway</entry><entry>IP address. Describes the firewall's default gateway.</entry>
			</row>
                        <row><entry>gateway</entry><entry>IP address. Describes the gateway in a direct network which can route connections to this remote network. (used with direct="0")</entry>
			</row>
                        <row><entry>snat</entry><entry>if set to 1, indicates connections from this network to Internet will use Source NAT (masquerading).</entry></row>
		    </tbody>
		    </tgroup>
		</informaltable>
                <para>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.</para>
                <para>The fwid attribute must be set to the ID attribute of the
                firewall connected to the given network.</para>
                <para>The iface attribute must be set to the ID attribute of the
                interface connected to the given network.</para>
	    </section> <!-- tag connection -->
	</section>
    </section>
    <section>
	<title>Installation</title>
	<section><title>Prerequisites</title>
	<para>To use nupyf, one needs:
	    <itemizedlist>
	    <listitem><para>python 2.3</para></listitem>
	    <listitem><para>IPy 0.50: this python package manipulates IP objects, and is
            available at <ulink
            url="http://cheeseshop.python.org/pypi/IPy/"><citetitle>CheeseShop webpage</citetitle></ulink>.
            A (sarge) debian package is provided by INL, which now maintains the project.</para></listitem>
	    </itemizedlist>
	</para>
        </section>
	<section><title>Installation</title>
	<para>
        This tools is composed of the main script : nupyf.py, and of python
        modules:
	<itemizedlist>
	<listitem><para>fw.py</para></listitem>
	<listitem><para>ipt.py</para></listitem>
	<listitem><para>nuacl.py</para></listitem>
	<listitem><para>nubackend.py</para></listitem>
	<listitem><para>nuldap.py</para></listitem>
	<listitem><para>nunat.py</para></listitem>
        <listitem><para>nuxml.py</para></listitem>
	</itemizedlist>
        If used with the Nuface interface, modules must stand in the same
        directory as the nupyf.py directory.
	</para>
	</section>
    </section>

</article>