NuFW

<?xml version='1.0'?>

<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">

<book><title>NuFW Handbook</title>

  <bookinfo>

    <author>

      <firstname>Eric</firstname>

      <surname>Leblond</surname>

      <email>eric at inl dot fr</email>

    </author>

    <author>

      <firstname>Vincent</firstname>

      <surname>Deffontaines</surname>

      <email>gryzor at inl dot fr</email>

    </author>

    <author>

      <firstname>Pierre</firstname>

      <surname>Chifflier</surname>

      <email>chifflier at inl dot fr</email>

    </author>

    <copyright>

      <year>2005-2008</year>

      <holder>INL</holder>

    </copyright>

    <revhistory>

    <revision>

              <revnumber>1.0.3</revnumber>

        <date>2009/01/20</date>

        <revdescription>

        <para>Added a short note about OCSP support.</para>

        </revdescription>

    </revision>

    <revision>

              <revnumber>1.0.2</revnumber>

        <date>2008/12/10</date>

        <revdescription>

        <para>Updated the nuauth_command description. Synchronized nuauth and nufw output with current version in debug section.</para>

        </revdescription>

    </revision>

    <revision>

              <revnumber>1.0.1</revnumber>

        <date>2008/12/01</date>

        <revdescription>

        <para>Updated the recommended setup section, fixed image inclusions. Added a version choosing section. Better documentation for nuauth's user session disconnection.</para>

        </revdescription>

    </revision>

    <revision>

              <revnumber>1.0.0</revnumber>

        <date>2008/11/25</date>

        <revdescription>

        <para>This handbook is based on the original howto document, and has been dramatically enhanced (countless changes).</para>

        </revdescription>

    </revision>

    </revhistory>

  </bookinfo>

  <chapter><title>License</title>

  <para>

  This document is copyrighted by INL, and distributed under the Creative Commons <command>by-nc-sa</command> license. The full text of the license is available at  <ulink url="http://creativecommons.org/licenses/by-nc-sa/3.0/legalcode">http://creativecommons.org/licenses/by-nc-sa/3.0/legalcode</ulink>.

  </para>

  </chapter>

  <chapter><title>Introduction</title>

   <section><title>Presentation</title>

<para>

NuFW is an enterprise grade firewall that performs an authentication of every single connection passing through the IP filter, by transparently requesting user's credentials before any filtering decision is taken. Practically, this means security policies can integrate with the user directory, and bring the notion of user ID down to the IP layers.

NuFW lays on Netfilter, the state of the art IP filtering layer from the Linux kernel. It fully integrates with Netfilter and extends its capabilities.

The daemons currently run on Linux and software clients are available for Windows, Linux, FreeBSD et Mac OSX.

</para>

<para>

NuFW can:

<itemizedlist>

<listitem><para>

Authenticate any connection that goes through your gateway or only from/to a chosen subset or a specific protocol (iptables is used to select the connections to authenticate).</para></listitem>

<listitem><para>Perform accounting, routing and quality of service based on users and not simply on IP.</para></listitem>

<listitem><para> Filter packets with criteria such as application and OS used by remote users.</para></listitem>

<listitem><para> Be the key of a secure and simple Single Sign On system.</para></listitem>

</itemizedlist>

</para>

<para>

NuFW is composed of two daemons that can be put on different systems and the

main daemon nuauth is heavily multi-threaded.  nuauth uses loadable modules to

add features, like SQL logging, reporting alert to IDS using Prelude, etc.

</para>

   </section>

   <section><title>Architecture</title>

   <para>

    NuFW has very little needs in terms of architecture. It is a firewall, so it needs to be installed between the client and the server, concerning connections the admin wills to authenticate. In other words, if you look at the figure below, the requisite is that the firewall running NuFW is set between the client host (M) and the server (T). It doesn't matter whether you administrate the server (T) or whether it is a random host on the internet : NuFW authentication occurs at the time the firewall decision is taken for each connection.</para>

    <para>

    A very typical setup is to use NuFW on a central firewall, so that it can filter connections from LAN to DMZ, from LAN to Internet, from WAN to LAN, etc. Of course, this is no requisite and you can always chain NuFW with another implementation. Technically, NuFW has one requisite : no NAT should be applied on connections between the client and NuFW itself. If that occurs, NuFW authentication will not work. This can easily be turned around if you want to identify your users from the Internet, by setting up a VPN (road-warrior or network to network) tunnel.

    </para>

    <para>

    A typical architecture is as follows :

    <figure><title>NuFW Algorithm resume</title>

    <imageobject>

      <imagedata fileref="algorythm.png"/>

    </imageobject>

    </figure>

    <orderedlist>

      <listitem><para>A standard application sends a packet.</para></listitem>

      <listitem><para>The Nufw server queues the packet and sends an auth request packet to the Nuauth server.</para></listitem>

      <listitem><para>The Nuauth server sends to all nufw agents running on the client computer an authentication request.</para></listitem>

      <listitem><para>The Nufw client run by the user whose application sent traffic sees that a connection is being initiated and sends a user request packet. The Nuauth server sums the auth request and the user request packet and checks this against an authentication authority.</para></listitem>

      <listitem><para>The Nuauth server replies to the Nufw server accordingly.</para></listitem>

      <listitem><para>The Nufw server transmits the packet following the answer given to its request.</para></listitem>

      <listitem><para>The flow of the connection is handled by Netfilter's state table (the conntrack), like for any firewalling rule.</para></listitem>

    </orderedlist>

    </para>

    </section>

    <section><title>Requirements</title>

      <para>In this section, each invoked library will have to be installed and the

header files have to be in standard places (so <command>./configure</command> can

                find them).

</para>

      <section><title>General</title>

      <para>NuFW is an advanced network filtering solution. For logging, as well as for domain integrations, it is highly recommended that all servers hosting NuFW services (<command>nufw</command>, <command>nuauth</command>, <command>LDAP/Active Directory</command>, and <command>the logging server (SQLi/syslog/prelude)</command>) be time-synchronized with a protocol such as NTP. NuFW does not provide time synchronization per se.

      </para>

      </section>

      <section><title>Nuauth dependencies</title>

       <section><title>nuauth core daemon</title>

        <para>

nuauth dependencies are as follows:

<itemizedlist>

            <listitem><para><filename>libglib2.0</filename>: nuauth heavily uses this library which provides a set of very useful high level objects. It needs at least 2.4 release.</para></listitem>

            <listitem><para><filename>libgnutls</filename>: communications between components are encrypted using TLS v1</para></listitem>

            <listitem><para><filename>libsasl2</filename>: authentication is done via sasl</para></listitem>

            <listitem><para><filename>libtool</filename>: It's needed for the compilation of library and modules</para></listitem>

          </itemizedlist>

        <note><para>Be careful when choosing your GnuTLS version : old versions may contain security breaches. Check the <ulink url="http://www.gnu.org/software/gnutls/security.html">GnuTLS security advisories page</ulink> or make sure your distribution is reactive enough with updates.</para>

        </note>

</para>

      </section>

      <section><title>MySQL logging</title>

        <para>

The <filename>libmysqlclient</filename> library is required for compiling of this module.

</para>

      </section>

      <section><title>PostgreSQL logging</title>

        <para>

The <filename>libpq</filename> library is required for compiling this module.

</para>

      </section>

      <section><title>Prelude IDS alerts</title>

        <para>

The <filename>libprelude</filename> library is required for compiling this module.

Prelude allows for gathering security events at the scale of any organization, and NuFW can send Prelude the following events :

<itemizedlist>

<listitem><para>User authentication failures</para></listitem>

<listitem><para>User authentication successes</para></listitem>

<listitem><para>Start and end of user sessions</para></listitem>

<listitem><para>Start and end of authenticated connections</para></listitem>

<listitem><para>Rejected connections</para></listitem>

</itemizedlist>

NuFW is a native sensor for Prelude, allowing tight integration with any IDS based the IDMEF standard (RFC 4765).

All information about the Prelude project is available at <ulink url="http://prelude-ids.org/">http://prelude-ids.org</ulink>

        </para>

      </section>

      <section><title>LDAP authentication and acl check</title>

        <para>

<filename>libldap</filename> library is needed (version 2 or better).

</para>

      </section>

      </section>

      <section><title>nufw dependencies</title>

        <para>The nufw daemon only depends on:

<itemizedlist>

            <listitem><para><filename>iptables</filename>: <filename>libipq.a</filename> is necessary to compile the nufw server</para></listitem>

            <listitem><para><filename>libgnutls</filename>: nufw is connected to nuauth using a TLS encrypted channel</para></listitem>

          </itemizedlist>

</para>

      </section>

      <section><title>User marking requirement on old kernel</title>

        <para>

A system with a kernel prior to 2.6.14 needs a patched version of the ip_queue module and of

its "sibling" library libipq.

</para>

      </section>

      <section><title>Using nfnetlink and getting all latest NuFW features</title>

        <para>

On kernel superior to 2.6.14, ipq is now deprecated in favor of libnetfilter_queue which

uses the new nfnetlink system.

On top of that nfnetlink also provides libnetfilter_conntrack which is used by NuFW to implement

connection tracking, and strict time-based acls.

        </para>

        <para>To use this features, the following libraries are needed:

        <itemizedlist>

        <listitem><para>libnfnetlink</para></listitem>

        <listitem><para>libnetfilter_queue</para></listitem>

        <listitem><para>libnetfilter_conntrack</para></listitem>

        </itemizedlist>

        You can find working versions of these libraries at <ulink url="http://nufw.org/download/libs/index.html">http://nufw.org/download/libs/index.html</ulink>

        Debian packages are available at <ulink url="http://www.nufw.org/debian/">http://www.nufw.org/debian/</ulink>

        </para>

        <para>

If you plan to use NuFW time-based acls, it is best to use a kernel superior to 2.6.18 or

to apply patches provided on NuFW site.

        </para>

      </section>

    </section>

    <section><title>Recommended setup</title>

    <para>

    This section's aim is to provide the best practises to help admins start a NuFW installation.

    We recommend that you use :

    <itemizedlist>

     <listitem><para>A MySQL database for logs. Though nuauth as well as single sign on modules support PostgreSQL logging, NuLog PostgreSQL support should be considered experimental for now.</para></listitem>

     <listitem><para>A <command>NuLog</command> installation. This is not a formal requisite for setting up and using NuFW, but <ulink url="http://software.inl.fr/trac/wiki/EdenWall/NuLog">NuLog</ulink> is a great tool to keep track of what is going on on your firewall. It analyses data from a ulog SQL database.

    <figure><title>A Nulog screenshot</title>

    <imageobject>

      <imagedata fileref="nulog_scr.png"/>

    </imageobject>

    </figure>

     </para></listitem>

     <listitem><para>A <command>NuFace</command> installation. <ulink url="http://software.inl.fr/trac/wiki/EdenWall/NuFace">NuFace</ulink> is INL's tool to build consistent <command>Netfilter</command> + <command>nuauth</command> rules. You really should consider using <command>NuFace</command> unless you plan to write your own tool : dealing with filtering rules by hand can be tricky because you need to synchronise authenticating rules at <command>Netfilter</command> and <command>nuauth</command> levels.

    <figure><title>A NuFace screenshot</title>

    <imageobject>

      <imagedata fileref="nuface_scr.png"/>

    </imageobject>

    </figure>

     </para></listitem>

     <listitem><para>A <ulink url="http://www.netfilter.org/projects/ulogd/index.html">ulogd</ulink> daemon setup for Netfilter logging. Ulogd can log Netfilter flows into the same database as nuauth, in order to provide a consistent log for both authenticated and unauthenticated connections. For now we recommend you use ulogd in version 1.X. Ulogd should run on the same host as your <computeroutput>nufw</computeroutput> daemon, and log in the same MySQL database as nuauth. The <link linkend='mysql_log' endterm='mysql_log.title'/> section describes a MySQL installation.</para></listitem>

     <listitem><para>A user directory, supported by PAM. This means Active Directory, LDAP, Novell e-directory, and other directories are supported. This is actually a PAM matter, see section <link linkend='nuauth_auth' endterm="nuauth_auth.title"/> for details. A plaintext nuauth module exists for user authentication, but it should be used for quick testing only. We really advise you have nuauth lay on a user directory. For instance, adding/removing users from the plaintext file requires that you restart nuauth, while those changes are transparent if nuauth uses the <computeroutput>system</computeroutput> module.</para></listitem>

     <listitem><para>A LDAP (local) directory, to store nuauth ACLs. Again, user authentication can be setup on a plaintext file, but this means you will need to handle it by hand, with a text editor, and warranty that your nuauth rules are consistent with Netfilter rules. On the other hand, <ulink url="http://software.inl.fr/trac/wiki/EdenWall/NuFace">Nuface</ulink> can deal with both Netfilter and LDAP rules. Again, nuauth will need to be restarted if you make changes in the plaintext file, while the LDAP changes will apply on the fly. The LDAP ACL directory needs not formally be local, it can be hosted on any LDAP directory that <computeroutput>nuauth</computeroutput> can reach. See the <link linkend='LDAP_acls' endterm='LDAP_acls.title'/> section for details about how to setup your LDAP acl tree.</para></listitem>

    </itemizedlist>

    </para>

    </section>

    <section><title>How to choose your NuFW version</title>

      <section><title>Installing</title>

       <para>If you are installing NuFW from scratch, it is advised that you use the latest stable version. You should avoid distribution packages if they distribute old versions, especially if security upgrades have been notified in latest versions. NuFW security announces are always available at <ulink url="http://nufw.org/-Security-announces-.html">this URL</ulink>.

        <note><para>Up to date Debian packages are distributed by INL, and can be used on your Debian systems by setting :

         <screen>

          deb http://packages.inl.fr/ testing/

         </screen>

         or

         <screen>

          deb http://packages.inl.fr/ stable/

         </screen>

         to your <computeroutput>/etc/apt/sources.list</computeroutput> file. Also note that this URL makes the <computeroutput>inl-keyring</computeroutput> package available, for package GPG signatures.

        </para>

        </note>

       </para>

       <para>Unless you are a developer or a very advanced user, we recommend that you do not attempt to use the trunk version of NuFW.

       </para>

      </section>

      <section><title>Upgrading</title>

       <para>You should upgrade your installation at least when security announces are released in new versions. Security announces are always available at <ulink url="http://nufw.org/-Security-announces-.html">this URL</ulink>.</para>

      </section>

      <section><title>Finding out the installed version</title>

       <para>You can easily find out which version of the software you are using, with each NuFW component, by using the <computeroutput>-V</computeroutput> switch with any program that we distribute :

        <screen>

# nuauth -V

nuauth (version 2.2.18 ($Revision: 5020 $))

# nufw -V

NuFW (version 2.2.19)

# nutcpc -V

nutcpc (version 2.2.19 $Revision: 5350 $)

        </screen>

        As an alternative, you can also use your distribution's package manager to find out, for instance :

        <screen>

$ dpkg -l nutcpc

[...]

ii  nutcpc         2.2.19-1+inl1  The authentication firewall [client]

        </screen>

       </para>

      </section>

    </section>

  </chapter>

  <chapter><title>Compilation and installation</title>

    <section><title>Default distribution kernels</title>

      <para>

      The following distributions do NOT need a kernel recompilation to run NuFW <footnote><para>Please let us know if you find others ;)</para></footnote>:

      <itemizedlist>

        <listitem><para>Fedora Core 6 (kernel 2.6.18)</para></listitem>

        <listitem><para>Debian Etch (kernel 2.6.18)</para></listitem>

        <listitem><para>Debian Lenny</para></listitem>

      </itemizedlist>

      </para>

      <para>

      Please note that a Linux kernel recompilation will only be needed on the Firewall itself (the host running the nufw daemon). The nuauth daemon should run on any POSIX system, and clients are, by essence, multi-platform (meaning, NO kernel dependency).</para>

    </section>

    <section><title>Kernel preparation</title>

      <para>You only need to patch your kernel sources with patch-o-matic if you want to use userid marking (from Linux 2.6.14 there is no need to patch the kernel as this option is available in vanilla). This is necessary if you need to mark your network flows depending on the originating user ID, for instance, to perform per user Quality of Service. This is not needed to use NuFW. To do so, install patch-o-matic as usual and

      run <screen>$./runme ip_queue_vwmark</screen></para>

      <para>Important note : it seems 2.6.24 netfilter_netlink capabilities only work if they are compiled as modules. Always compile these options as modules :

      <itemizedlist>

        <listitem><para>CONFIG_NETFILTER_NETLINK</para></listitem>

        <listitem><para>CONFIG_NETFILTER_NETLINK_QUEUE</para></listitem>

        <listitem><para>CONFIG_NETFILTER_NETLINK_LOG</para></listitem>

        <listitem><para>CONFIG_NF_CT_NETLINK</para></listitem>

      </itemizedlist>

      Most distribution kernels come with these options compiled as modules.

      </para>

    </section>

    <section><title>Linux 2.6.14 and higher</title>

        <para>

        If you run a kernel higher than 2.6.14 (and you should!), you should set the following options:

<screen>

CONFIG_NETFILTER_XT_TARGET_NFQUEUE=Y or m

CONFIG_NETFILTER_NETLINK=Y or m

CONFIG_IP_NF_CONNTRACK=m (we advise you don't set this option statically)

CONFIG_IP_NF_CONNTRACK_EVENTS=Y

</screen>

        Setting these options will allow you to use the NFQUEUE target, and use very simple Netfilter rules.

        </para>

    </section>

    <section><title>NuFW compilation</title>

      <para>Extract the source to the directory of your choice and

go to the created directory.</para>

      <para>

NuFW uses autoconf and automake for compilation and a standard <command>configure</command> script

is provided.

Above standard options, the following flags (among other) are provided:

<itemizedlist>

          <listitem><para> <option>--with-mysql-log </option>   Support user activity logging in MySQL database</para></listitem>

          <listitem><para> <option>--with-pgsql-log </option>   Support user activity logging in PostgreSQL database</para></listitem>

          <listitem><para> <option>--with-system-auth </option>   Support PAM+NSS authentication</para></listitem>

          <listitem><para> <option>--with-ldap </option>   Support LDAP directory for users and acl lookups</para></listitem>

        </itemizedlist>

A detailed list of the options is available via

<screen>$./configure --help</screen>

Thus you can run <command>./configure</command> with the options you want and launch compilation and installation:

<screen linenumbering="numbered">$ ./configure --with-ldap --with-system-auth --with-mysql-log \\

                --sysconfdir=/etc/nufw/

$ make

$ sudo make install</screen>

If you want to install default configuration files :

<screen>sudo make install-conf</screen>

This will only copy new configuration files when an old version of the file does not already exist in your <command>$prefix/conf</command> directory

</para>

    </section>

    <section><title>Initial setup and tests</title>

      <section><title>Certificates and client installation</title>

        <para>This is about copying the default certificates. Don't do that unless on very early tests ; you probably want to generate your own certificates: see next section.</para>

        <para>For nufw

<screen>cp conf/certs/nufw-*.pem /etc/nufw/</screen>

                For nuauth:

<screen>cp conf/certs/nuauth*.pem /etc/nufw/

cp conf/certs/NuFW*.pem /etc/nufw/</screen>

</para>

      </section>

      <section><title>Creating your own certificates</title>

      <para>The management of certificates, or the use of a Public Key Infrastructure (PKI), is

      not covered in this howto. Using a dedicated software, like

      <ulink url="http://www.openca.org/">OpenCA</ulink> or

      <ulink url="http://ejbca.sourceforge.net/">EBJCA</ulink>,

      is suggested.

      </para>

      <para>See section <link linkend='hardening' endterm="hardening.title"/> for details on how

      certificates are used in NuFW.

      </para>

      <para>The following commands show how to quickly create a Certificate Authority, and some

      certificates for nufw and nuauth.

      </para>

      <para>Generating your own Certificate authority:

      <screen>mkdir private

chmod 700 private

openssl req -new -x509 -keyout private/CAkey.pem -out private/CAcert.pem</screen>

You have to set a strong password here and keep it secret.

      </para>

      <para>Generating nufw and nuauth private keys:

      <screen>openssl genrsa -out private/nufw-key.pem</screen>

      <screen>openssl genrsa -out private/nuauth-key.pem</screen>

      </para>

      <para>Generating Certificate Signing Requests for both nufw and nuauth

      keys:

      <screen>openssl req -new -key private/nufw-key.pem -out nufw.csr</screen>

      <screen>openssl req -new -key private/nuauth-key.pem -out nuauth.csr</screen>

      </para>

      <para>Having our keys signed by the certificate authority we created:

      <screen>openssl x509 -req -days 365 -in nufw.csr -CA private/CAcert.pem \

      -CAkey private/CAkey.pem -CAcreateserial -out nufw-cert.pem</screen>

      <screen>openssl x509 -req -days 365 -in nuauth.csr -CA private/CAcert.pem \

      -CAkey private/CAkey.pem -CAcreateserial -out nuauth-cert.pem</screen>

      </para>

      <para>Then, as in previous section, copy the files where needed:

      For nufw:

      <screen>cp private/nufw-key.pem /etc/nufw/</screen>

      <screen>cp nufw-cert.pem /etc/nufw/</screen>

      For nuauth:

      <screen>cp private/nuauth-key.pem /etc/nufw/</screen>

      <screen>cp nuauth-cert.pem /etc/nufw/</screen>

      And don't forget your key files (here, nufw-key.pem and nuauth-key.pem) should always remain private.

      </para>

      </section>

<section><title>Basic nuauth setup</title>

<para>NuFW sources provide a sample configuration file for nuauth <filename>nuauth.conf</filename>

which is available in the <filename>conf</filename> directory.

</para>

<para>The two most important configuration variables are:

<option>nuauth_client_listen_addr</option> which sets the address

where <command>nuauth</command> listens for client requests and <option>nuauth_nufw_listen_addr</option>

which sets the address where <command>nuauth</command> listens for nufw requests.

The list of <command>nufw</command> servers authorized to connect to server <command>nuauth</command> is the

 <varname>nufw_gw_addr</varname>.</para>

<para>

The next thing to do after setting this variable is to choose

your authentication and acl checking module.

Authentication modules for user have to be chosen in:

<itemizedlist>

<listitem><para>plaintext: user credentials are stored in a text file. It is advised not to use this module, except for quick testing :

you need to restart nuauth when updating the text file. Instead, on production, you should run the system module. This format supports both

plaintext and encrypted passwords, see the sample config file (named <command>users-plaintext.nufw</command>) for formatting and details.</para>

            </listitem>

<listitem><para>system: authentication is done against PAM and groups are system groups. This provides

 a convenient way to use nss features and/or pam-modules. This is the recommended way, as it lets you

 authenticate against your LDAP, Active Directory, or any directory.</para>

            </listitem>

          </itemizedlist>

This is set with the option <option>nuauth_user_check_module</option>

which default is <varname>libsystem</varname> (if not set in config file).

Further choice for the acl checking  module has to be done if you choose:

<itemizedlist><listitem><para>libldap : this is the recommended ACL checking module, as it is modular, and does not require a reload of the

nuauth server when updating rules. You can manage iptables and LDAP rules in a consistent way, by using <ulink url="http://software.inl.fr/trac/wiki/EdenWall/NuFace">NuFace</ulink></para>

            </listitem>

<listitem><para>plaintext : this module is intended to be used for quick testing only. It requires that you reload nuauth when modifying rules.</para>

            </listitem>

          </itemizedlist>

by setting the variable <option>nuauth_acl_check_module</option>.

</para>

      </section>

        </section>

     <section><title>Testing</title>

<para>To be able to proceed quickly to test, we will use the system

module for user and the plaintext module for acl.

A sample file for the plaintext acl check module is available

in the <filename>conf</filename> directory, <filename>acls.nufw</filename>.

Copy it to <filename>/etc/nufw</filename> and adjust the

group of the ssh acl to have it matching the group of a system

user you will use later to authenticate on the system.</para>

        <section><title>Setting up Netfilter rules before 2.6.14</title>

          <para>

We will test the setup by connecting from the local host ssh server. For this

we need to add filtering rules to ask for authentication:

<screen>iptables -A OUTPUT -s 192.168.75.0/24 -p tcp --dport 22 -m state --state NEW --syn -j QUEUE

iptables -A OUTPUT -m state --state ESTABLISHED,RELATED -j ACCEPT</screen>

<footnote><para>

Only SYN packets are sent to QUEUE. This is not enough to do advanced

user activities logging, but enough for traffic authentication.

</para></footnote>

</para>

        </section>

        <section><title>Setting up Netfilter rules from 2.6.14</title>

          <para>

We will test the setup by connecting from the local host ssh server. For this

we need to add filtering rules to ask for authentication:

<screen>iptables -A OUTPUT -s 192.168.75.0/24 -p tcp --dport 22 -m state --state NEW --syn -j NFQUEUE

iptables -A OUTPUT -m state --state ESTABLISHED,RELATED -j ACCEPT</screen>

<footnote><para>

Only SYN packets are sent to NFQUEUE. This is enough to do advanced

user activities logging, because events on the connections will be automatically sent to nufw by Netfilter.

This requires, in particular, that the CONFIG_IP_NF_CONNTRACK_EVENTS kernel option be set.

</para></footnote>

</para>

        </section>

        <section><title>Testing the authentication system</title>

          <para>First, the daemons need to be started. We start nuauth in a terminal

<screen>nuauth -vvvvvvvvv</screen>

then we start <screen>nufw -s -vvvvvvvvv</screen> in another terminal.

</para>

<note>

<para>When starting <command>nufw</command> or <command>nuauth</command> daemons without the <command>-D</command> switch,

they do not run as daemon : they remain attached to the console. In such conditions, both programs log to STDOUT/STDERR instead of

using syslog. On production, you should always start the daemons with the <command>-D</command> option.</para>

</note>

<para>

Next, we can try to connect a user. Under Linux it can be done with:

<screen>nutcpc -N -d -U [USERNAME] -H [NUAUTH IP]</screen>

Next step is to enter the user's password. Without the <command>-U</command> option, the current system user's name is used.</para>

<para>At nuauth level, we should see something like:

<screen>user bill@nufw uses OS Linux, 3.0.10, #1 Tue Oct 19 23:51:32 CEST 2008</screen>

If your PAM setup is based on shadow file, you will not be able to authenticate a user different from the one running nuauth. On this kind of setup, nuauth needs to be run as root to authenticate other users.

<footnote>

      <para> Never launch nutcpc against 'localhost' or '127.0.0.1',

even if nuauth is on the same computer.

Packets sent to nuauth by the firewall will hardly have the address of the loopback but rather have a

source address which is one of the network interface.

</para>

            </footnote>

</para>

        </section>

        <section><title>Initial tests and debug process</title>

          <para>

        Let's authenticate a ssh connection from the computer.

<itemizedlist>

              <listitem><para>nufw gets a packet from  Netfilter:

    <screen>[PID] Sending request for 12</screen>

12 is the ID of the packet inside the kernel.

</para>

              </listitem>

              <listitem><para>nuauth receives nufw's request:

    <screen>* Message: NuFW Packet: src=127.0.0.1 dst=127.0.0.1 proto=6 sport=48505 dport=22, IN=lo OUT=, packet_id=12, mark=0</screen></para>

              </listitem>

              <listitem><para>nuauth sends an authentication request to the clients

on IP source:

    <screen>** Message: Warn client(s) on IP 127.0.0.1</screen></para>

              </listitem>

              <listitem><para>nuauth receives packet from the client:

    <screen>** Message: User Packet: src=127.0.0.1 dst=127.0.0.1 proto=6 sport=48504 dport=22, mark=0, user=regit, \\

OS=Linux 2.6.26-1-amd64 #1 SMP Wed Sep 10 15:31:12 UTC 2008, app=/usr/bin/ssh</screen>

    </para>

              </listitem>

              <listitem><para>nuauth sends back response to nufw:

    <screen>** Message: Answ Packet: src=127.0.0.1 dst=127.0.0.1 proto=6 sport=48505 dport=22, decision=ACCEPT, IN=lo OUT=, \\

packet_id=12, mark=1000, user=regit, OS=Linux 2.6.26-1-amd64 #1 SMP Wed Sep 10 15:31:12 UTC 2008, app=/usr/bin/ssh</screen>

    </para>

              </listitem>

              <listitem><para>nufw pushes the packet back in the kernel:

    <screen>[PID] (*) Accepting packet with id=12</screen>

</para>

              </listitem>

            </itemizedlist>

                </para>

        </section>

      </section>

  </chapter>

  <chapter><title>Setting up NuFW</title>

    <section id='LDAP_acls'><title id='LDAP_acls.title'>Using the LDAP module for acl checking</title>

      <section><title>Installation of OpenLDAP server (slapd)</title>

        <para>OpenLDAP server installation is standard. Use your Linux distribution packages,

example with Debian:

<screen>apt-get install slapd</screen>

Read <ulink url="http://www.openldap.org/doc/admin/">OpenLDAP Software

Administrator's Guide</ulink>, section "Building and Installing OpenLDAP Software" to get more information.

        </para>

      </section>

      <section><title>Slapd configuration</title>

        <para>

The file <filename>acls.schema</filename> has to be put in <filename class="directory">/etc/ldap/schema</filename>

and a line

<screen>include         /etc/ldap/schema/acls.schema</screen>

has to be added at the beginning of the <filename>/etc/ldap/slapd.conf</filename>.

In the level of access setup in this file, one can add:

<screen>#INL access for acls

access to  dn="ou=acls,dc=nufw,dc=org"

       by dn="uid=nufw,ou=Users,dc=nufw,dc=org" write

       by dn="uid=nuauth,ou=Users,dc=nufw,dc=org" read

       by dn="cn=admin,dc=nufw,dc=org" write

       by * none</screen>

nufw user is able to modify the policy and the nuauth user

can only read the acls.

</para>

<para>

To speed up search request you can add the following index to your <filename>slapd.conf</filename>:

<screen>

index OsName,OsRelease,OsVersion,AppName pres,eq

index SrcIPStart,SrcIPEnd,DstIPStart,DstIPEnd pres,eq

index Proto,SrcPortStart,SrcPortEnd,DstPortStart,DstPortEnd pres,eq

index SrcPort,DstPort pres,eq

</screen>

</para>

<para>

You can start with a LDIF file such as:

<screen>dn: dc=nufw,dc=org

objectClass: top

objectClass: dcObject

objectClass: organization

o: nufw.org

dc: nufw

structuralObjectClass: organization

dn: ou=Users,dc=nufw,dc=org

objectClass: organizationalUnit

ou: Users

structuralObjectClass: organizationalUnit

dn: ou=acls,dc=nufw,dc=org

objectClass: organizationalUnit

ou: acls

structuralObjectClass: organizationalUnit

dn: uid=nuauth,ou=Users,dc=nufw,dc=org

objectClass: top

objectClass: simpleSecurityObject

uid: nuauth

userPassword: nuauth

dn: uid=nufw,ou=Users,dc=nufw,dc=org

objectClass: top

objectClass: simpleSecurityObject

uid: nufw

userPassword: nufw

</screen>

</para>

      </section>

     <section><title>nuauth configuration</title>

        <para>

To use LDAP support for acl checking, we need to modify the <filename>nuauth.conf</filename> file:

<screen>nuauth_acl_check_module="ldap"</screen>

and we have to setup the connection parameters:

<screen>ldap_bind_dn="uid=nuauth,ou=Users,dc=nufw,dc=org"

ldap_bind_password="secretpassword"

ldap_basedn="dc=nufw,dc=org"

ldap_acls_base_dn="ou=Acls,dc=nufw,dc=org"</screen>

</para>

      </section>

      <section><title>Using nuface, a web-based rules generator</title>

<para>

<ulink url="http://www.inl.fr">INL</ulink> has released a powerful Netfilter rules generator system for NuFW and Netfilter.

It is called Nuface and it is available at:

<ulink url="http://software.inl.fr/trac/wiki/EdenWall/NuFace">http://software.inl.fr/trac/wiki/EdenWall/NuFace</ulink>

It generates a set of rules for NuFW and Netfilter that can directly be applied from the web interface. All Netfilter rules generated by Netfilter use the stateful capabilities of Netfilter, without user intervention.

</para>

      </section>

      <section><title>nuaclgen configuration</title>

      <para>nuaclgen is a script that can help you maintain a simple

      set of acls in an LDAP tree.</para>

      <para>It is advised that you use Nuface rather than Nuaclgen, if possible, since it makes things simpler. In particular,

      be aware that when you use nuaclgen, you need to also modify by hand your Netfilter rules.</para>

        <para>

The file <filename>nuaclgen.conf</filename> contains the informations about LDAP

connections. It needs to be modified to suit your configuration, for example:

<screen>$ldap_host="localhost";

$username="uid=nufw,ou=Users,dc=nufw,dc=org";

$password="writepasswd";

$basedn="ou=Acls,dc=nufw,dc=org";</screen>

<footnote><para>The nuaclgen.conf file contains sensitive data

and thus must have limited rights.</para>

          </footnote>

</para>

        <para>To allow ssh for users

of group 513 if they use <filename>/usr/bin/ssh</filename> application, we can use:

<screen>nuaclgen --Aclname cn=ssh,ou=Acls,dc=nufw,dc=org -p 6 --dport 22 -AppName "/usr/bin/ssh" -j ACCEPT -g 513</screen>

</para>

        <para>Or for access directed to a web server:

<screen>

nuaclgen --Aclname cn=apt,ou=Acls,dc=nufw,dc=org -p 6 --dport 80 \

  -AppName "/usr/lib/apt/methods/http" -j ACCEPT -g 1042

</screen>

This ACL gives access to group 1042  which is used by root user of some server of ours.

Thus root user can only get file to update the computer, but other users can not access

the web.

</para>

      </section>

    </section>

    <section><title>Setting up NuFW authenticated connections tracking</title>

      <section><title>nuauth settings</title>

        <para>

 To achieve NuFW connection tracking it is necessary to have these options in <filename>nuauth.conf</filename>:

 <screen>nuauth_log_users_sync=1

nuauth_log_users=9</screen>

</para>

      </section>

<section id='mysql_log'><title id='mysql_log.title'>Installation of MySQL server</title>

        <para>MySQL server installation is standard. Use your Linux distribution packages,

example with Debian:

<screen>apt-get install mysql-server</screen>

Read <ulink url="http://dev.mysql.com/doc/">MySQL Documentation</ulink>, section

"2 Installing and Upgrading MySQL" to get more information.

        </para>

</section>

<section><title>Installation of PostgreSQL server</title>

        <para>PostgreSQL server installation is standard. Use your Linux distribution packages,

example with Debian (replace 8.2 by the latest server version):

<screen>apt-get install postgresql-8.2</screen>

Read <ulink url="http://www.postgresql.org/docs/">PostgreSQL Documentation</ulink>, section

"III. 14. Installation Instructions" to get more information.

        </para>

        <note>

        <para>Note that, even though nuauth PostgreSQL support is complete, you probably want to use

        a MySQL server for now, if you want to use <ulink url="http://software.inl.fr/trac/wiki/EdenWall/NuLog">Nulog</ulink>.

        Single Sign On modules (<ulink url="http://software.inl.fr/trac/wiki/EdenWall/mod_auth_nufw">apache</ulink>

        and <ulink url="http://software.inl.fr/trac/wiki/EdenWall/squid_nufw_helper">squid</ulink>) have

        PostgreSQL support.</para>

        </note>

</section>

<section><title>SQL configuration</title>

<para>The connection tracking system is really useful with SQL logging modules.

We will describe here the setup of the MySQL module.</para>

<para>

You have to create the SQL database from the dump file available in the conf/

subdir of the archive. Create a SQL account, which must have UPDATE,

INSERT privileges on the "conntrack_ulog" table. You will have to set the

credentials for that user in the nuauth.conf file.

</para>

<para>

You may choose between to schema an IPv4 only one and an IPv4/IPv6 one.

Recent tools like <ulink

url="http://software.inl.fr/trac/wiki/EdenWall/NuLog">Nulog2</ulink> are able to use

the IPv6 schema. If you have old script or older tools, you better use the IPv4 only schema.

To import the IPv4 schema into a newly created database, you can use:

</para>

<screen>mysqladmin create nufw

cat nulog.ipv4.mysql.dump | mysql nufw</screen>

<para>For the IPv6 schema, simply use:</para>

<screen>mysqladmin create nufw

cat nulog.ipv6.mysql.dump | mysql nufw</screen>

<para>

You may also want to rotate the "ulog" table, so that it doesn't grow to infinite

size with time. The ulog_rotate.py script is available in the

<ulink url="http://software.inl.fr/trac/wiki/EdenWall/NuLog">Nulog project</ulink>

tarball.

At the present time, it is assumed those scripts are run as the root SQL user,

as cronjobs. Of course the better way to go is to create a separate user for

this and grant it the needed privileges. Please provide updates for this

document if you implement this before we do.

</para>

      </section>

<section><title>Life of a connection in the SQL table</title>

<para>

If nuauth is configured to log network flow information in a SQL database, here is how the logging system works :

</para>

<itemizedlist><listitem><para>When the connexion opening datagram is authenticated (for TCP, that is the SYN datagram), nuauth creates an entry in database, with a request looking like this (for TCP) :

<screen>INSERT INTO conntrack_ulog (state, oob_time_sec, ip_protocol, ip_saddr, ip_daddr, oob_in, oob_out, oob_prefix, user_id,

username, client_os, client_app, tcp_sport, tcp_dport) VALUES (... our datagram values ...);</screen>

If nuauth decision for that datagram is to drop or reject it, log of the "connexion" stops here. The connexion will never be opened, and this database entry will no longer be manipulated by nuauth.

</para></listitem>

<listitem><para>At the time when connection changes state (For TCP, and for any accepted connection, state changes to ESTABLISHED as soon as the server answers the SYN datagram), this request is performed by nuauth, if the nufw daemon is run with "-C" :

<screen>

UPDATE conntrack_ulog SET state=ESTABLISHED, start_timestamp=FROM_UNIXTIME(timestamp)

WHERE (ip_daddr=%s AND ip_saddr=%s "AND tcp_dport='%hu' AND tcp_sport='%hu' AND state=OPEN)

</screen>

The only fields that are altered by this request are "state", which changes to "ESTABLISHED", and start_timestamp, which wasn't set before. It is important to note that no information is lost when this modification is performed. It is indeed obvious that the connection was previously in "OPEN" state, since that's a TCP preamble to the "ESTABLISHED" state, and the database keeps track of the timestamp when the connection was opened in the "oob_time_sec" field. The "start_timestamp" field simply marks the timestamp of switch to the "ESTABLISHED" state.

</para></listitem>

<listitem><para>When the connection expires, this request is executed by nuauth, if the nufw daemon is run with "-C" :

<screen>

UPDATE conntrack_ulog SET end_timestamp=FROM_UNIXTIME(timestamp), state=CLOSE, packets_in=%d , packets_out=%d , bytes_in=%d , bytes_out=%d

WHERE (ip_saddr=%s AND ip_daddr=%sAND tcp_sport='%hu' AND tcp_dport='%hu' AND (state=OPEN OR state=ESTABLISHED))

</screen>

State is updated, it becomes "CLOSE", and we set the end_timestamp field, which was empty before this, as well as packet number and byte number counters for the now dead connexion. Time of opening and time of establishment of the connection remain available in the oob_time_sec and start_timestamp fields.

</para></listitem></itemizedlist>

<para>

The SQL logging feature keeps track of the whole history of each connexion, and updates that nuauth performs on the database do never erase data that was previously logged. This log mode is the most powerful one that a firewall can achieve, because it is very synthetic : one single SQL entry is maintained for each connection ; and it keeps the whole history of all elements of connections.

</para>

</section>

      <section><title>Netfilter settings</title>

      <section><title>Settings on post 2.6.14 kernel</title>

      <para>

This is the good case compared to pre 2.6.14.

To enable authenticated connection tracking,

you only have to add the <option>-C</option> to nufw command line.

This flag asks nufw to send any ESTABLISHED and DESTROY message coming from Netfilter connections tracking to nuauth.

</para>

<para>

As an important number of events can be sent through this mean, nufw offers the capability to only send a subset.

It uses the fact that the initial mark can be put with CONNMARK

on every packets of the connection.

This mode is activated via the <option>-M</option> flag of nufw.

On Netfilter side, the following rules have to be added:

<screen>iptables -A PREROUTING -t mangle -j CONNMARK --restore-mark

iptables -A POSTROUTING -t mangle -m mark ! --mark 0 -j CONNMARK --save-mark

</screen>

</para>

<para>

In short, you should always use <option>-C</option> if you use libnetfilter_conntrack (this is available from linux 2.6.14), and you should use <option>-M</option> if you want all your connections marked per userID (please note that you need to apply <ulink url="http://nufw.org/download/patches/transmit_mark.patch">transmit_mark patch</ulink> on your kernel to use this). Library compatibility is better with a >=2.6.16 kernel.

      </para>

      </section>

      <section><title>Settings on pre 2.6.14 kernel</title>

        <para>

NuFW stores the following states in the life of a TCP connection:

    <itemizedlist><listitem><para>opening: bit SYN is set</para></listitem>

            <listitem><para>established: SYN ACK is sent</para></listitem>

            <listitem><para>closed: the tcp flags are FIN or FIN,ACK</para></listitem>

          </itemizedlist>

To match those packets we need to use the <option>--syn</option> and the

<option>--tcp-flags</option> options.

Let's use the following configuration as an example: our web servers are protected by a NuFW firewall. They are in the network $DMZ.

The following rules achieve to realize a user connection tracking on the web

server outgoing connections.

<screen>iptables -A FORWARD -p tcp -m state --state ESTABLISHED --tcp-flags ACK,FIN NONE -j ACCEPT

iptables -A FORWARD -d $DMZ -p tcp -m state --state ESTABLISHED --dport 80 --tcp-flags SYN,RST,ACK RST -j QUEUE

iptables -A FORWARD -d $DMZ -p tcp -m state --state ESTABLISHED --dport 80 --tcp-flags FIN FIN -j QUEUE

iptables -A FORWARD -s $DMZ -p tcp -m state --state ESTABLISHED --sport 80 --tcp-flags SYN,ACK SYN,ACK -j QUEUE

iptables -A FORWARD -p tcp -m state --state ESTABLISHED -j ACCEPT

iptables -A FORWARD -d $DMZ -p tcp --syn --dport 80 -m state --state NEW -j QUEUE</screen>

The first rule optimizes the filter by matching an important part of the ESTABLISHED traffic. The last rule with --state ESTABLISHED is the standard accepted established packets. It has to be put after NuFW flags matching rules.

</para>

</section>

      <section><title>Settings on >= 2.6.14 kernel</title>

        <para>

          No special complicated rule should be set, the kernel will automatically send new events on connections to NuFW.

          This is the reason why you don't want to use a pre-2.6.14 kernel ;)

        </para>

      </section>

      </section>

<section><title>Using the connection tracking</title>

<para>

<command>nutop</command> is a perl script provided with nufw sources. It is a

top like tool that displays the active and authenticated connections in real-time.

</para>

<para>The best way<footnote><para>as far as the author of this document knows at the time of the writing of

this document</para>

          </footnote> to use the logs generated by the connection tracking is to install

<command>nulog</command> which provides a convenient web interface.

<command>nulog</command> is available under GPL on this page:

<ulink url="http://software.inl.fr/trac/trac/wiki/EdenWall/NuLog">http://software.inl.fr/trac/wiki/EdenWall/NuLog</ulink>

</para>

        </section>

</section>

<section><title>Single Sign On setup</title>

<section><title>Apache</title>

<para>All you need to do is to setup a SQL user with SELECT permissions on the

"conntrack_ulog" table. Then setup mod_auth_nufw to use the configured SQL

user/database/table. The source code of the apache module is available at <ulink

url="http://software.inl.fr/trac/wiki/EdenWall/mod_auth_nufw">NuFW Apache SSO page</ulink></para>

        </section>

<section><title>Squid</title>

<para>All you need to do is to setup a SQL user with SELECT permissions on the

"conntrack_ulog" table. Then setup squid_nufw_helper to use the configured SQL

user/database/table. The source code of the squid helper is available at

<ulink url="http://software.inl.fr/trac/wiki/EdenWall/squid_nufw_helper">NuFW Squid SSO page</ulink></para>

        </section>

        <section><title>Troubleshooting single sign on problems</title>

         <section><title>General information</title>

          <para>If you experience problems with Single Sign On problems, one common way to find out where the problem lays is to check whether the SSO code performs SQL lookups correctly. You can check it out easily at the database level. On MySQL, check you have in <filename>my.cnf</filename> something like: <screen>log             = /var/log/mysql/mysql.log</screen> This ensures that MySQL logs request that it receives. Then all you need to do is test the module, while running <screen>tail -f /var/log/mysql/mysql.log</screen> If the Single Sign On module is doing its job, you should see lines such as : <screen>SELECT DISTINCT username FROM conntrack_ulog WHERE (tcp_sport=50423 AND ip_saddr=3232235761 AND tcp_dport=80 AND ip_daddr=3232235761 AND (state=1 OR state=2))</screen> in the log, revealing that the Single Sign On module actually requests the database. If you run a PostgreSQL database, you can do similar operations by setting <screen>log_min_duration_statement = 0</screen> in <filename>postgresql.conf</filename>. On Debian, the default PostgreSQL log file is probably located in <filename>/var/log/postgresql/postgresql-8.X-main.log</filename>.</para>

         </section>

         <section><title>Apache module troubleshooting</title>

          <para>Like any Apache module, the mod_auth[n]_nufw module dumps verbose/debug information in the Apache error log when you set :<screen>Loglevel debug</screen> in the Apache <filename>httpd.conf</filename> file.</para>

<!--          <note>This works on Apache 1.3, Apache 2.0 and Apache 2.2</note> -->

         </section>

        </section>

      </section>

<section><title>User based Quality of Service</title>

<section><title>Setting up Kernel on non libnetfilter_queue system</title>

<para>

Official Linux kernels are not able to mark packets

with ip_queue framework before 2.6.14 release.

It is thus necessary to patch the kernel (if pre 2.6.14), this has to be done by using

the <filename>ip_queue_vwmark</filename> patch available in the

patch-o-matic-ng from netfilter. This will generate a modified version of both

ip_queue module and libipq.a file.

</para>

<para>

Once the new libipq.a is installed, you can now compile nufw:

<screen>./configure --with-user-mark ${EXTRA_OPTIONS_YOU_LIKE}

make

make install</screen>

</para>

</section>

<section><title>Setting up nufw</title>

<para>

nufw can now be run with <option>-m</option> to use userid marking.

This option is compatible with <option>-M</option>.

</para>

    </section>

<section><title>Setting up Netfilter</title>

<para>

As nufw only works with initialization packets it can not pull the userid mark of each packet

of a connection. Thus, this is necessary to use

<application>CONNMARK<footnote><para>CONNMARK is only available in patch-o-matic

before 2.6.11, it is included in 2.6.12+ kernels</para>

            </footnote></application>

which is a target able to propagate marks across connections.

A basic setup is the following:

<screen>iptables -A PREROUTING -t mangle -j CONNMARK --restore-mark

iptables -A POSTROUTING -t mangle -j CONNMARK --save-mark</screen>

First line restores the existing mark when a packet arrives and second line

saves mark on the connection so it can be restored later.

</para>

      </section>

      <section><title>Using marking modules</title>

      <para>

The nuauth variable <option>nuauth_finalize_packet_module</option> lists module which attach a hook called just before

nuauth answer to nufw about a packet.

It is usually used to modify the mark of the packet following a given strategy.

By splitting the mark in different part, this is possible to define complex marking policy which can later be used

by Linux routing and QoS systems.

</para>

      <para>

      Extensive documentation can be found in the file <ulink url="http://software.inl.fr/trac/browser/mirror/edenwall/nufw/trunk/nufw/doc/README.mark">README.mark</ulink>

      </para>

      </section>

<section><title>Using NuFW mark</title>

<para>Netfilter mark can be use by the Quality of Service system and

the routing system of Linux.</para>

<para>

So it is possible to do differentiated routing between different users

by using command like:

<screen>ip rule add fwmark XXX lookup TABLE</screen>

</para>

<para>This is almost the same for QoS, by using <command>tc filter</command> one needs to put

user's flows in a specific class:

<screen>tc filter add dev IFACE  prio 5 protocol ip handle 102 fw flowid FLOWID</screen>

</para>

<para>For more information about routing and quality of service you can read

<ulink url="http://www.lartc.org">lartc</ulink>.

</para>

      </section>

    </section>

    <section><title>Controlling nuauth finely at runtime</title>

    <para>NuFW 2.2.0 introduced new nuauth control capabilities, thanks to <command>nuauth_command</command>. This command should

    be installed when you install nuauth, and it can be run by the administrator, on the same server as <command>nuauth</command>.

    <command>nuauth_command</command> connects to nuauth, and lets you do the following tasks :

    <itemizedlist>

    <listitem><para><option>help</option> display inline help with a summary of available subcommands</para></listitem>

    <listitem><para><option>version</option> display nuauth version</para></listitem>

    <listitem><para><option>users</option> list connected users</para></listitem>

    <listitem><para><option>firewalls</option> list connected nufw firewalls</para></listitem>

    <listitem><para><option>packets count</option> display number of decision waiting packets</para></listitem>

    <listitem><para><option>refresh cache</option> refresh all caches</para></listitem>

    <listitem><para><option>refresh crl</option> refresh the TLS crl file</para></listitem>

    <listitem><para><option>disconnect (ID|regexp)</option> disconnect a user with his session identifier or a regular expression apply on logging name.</para></listitem>

    <listitem><para><option>disconnect all</option> disconnect all users</para></listitem>

    <listitem><para><option>uptime</option> display nuauth starting time and uptime</para></listitem>

    <listitem><para><option>reload</option> reload the configuration and reload the modules</para></listitem>

    <listitem><para><option>reload periods</option> reload the time periods</para></listitem>

    <listitem><para><option>display debug_level</option></para></listitem>

    <listitem><para><option>display debug_areas</option></para></listitem>

    <listitem><para><option>debug_level <replaceable>LEVEL</replaceable></option></para></listitem>

    <listitem><para><option>debug_areas <replaceable>AREAS</replaceable></option></para></listitem>

    <listitem><para><option>help</option> display this help</para></listitem>

    <listitem><para><option>quit</option> disconnect</para></listitem>

    </itemizedlist>

    You can, for instance, use the <option>disconnect</option> task, in order to force a user reconnect, and have their groups reloaded.

    <note>

     <para>As a POSIX compliance, <command>nuauth</command> checks the user's authentication, as well as groups, at the time the user's NuFW agent connects. It is

     never refreshed, until the client disconnects, or the administrator forces a disconnect. Nuauth configuration file <computeroutput>nuauth.conf</computeroutput> can also force all users

     to reconnect regularly, by setting the <option>nuauth_session_duration</option> parameter.

     </para>

    </note>

    </para>

    </section>

    <section><title>Time-based ACLs</title>

    <section><title>Global configuration</title>

    <para>

NuFW can be used to implement strict time-based acls. When a period using time interval is defined (like say 08am-6pm)

a authenticated connection can only start in the interval and is destroyed at the end of the interval.

    </para>

    <para>Configuration is done by defining a set of periods and using them (by their name) in the acls backend.

    The <option>plaintext</option> acl backend uses the <option>period</option> key to defined the period

    to apply to the acl. The <option>LDAP</option> acls backend uses the <option>TimeRange</option> atttribute.

    </para>

    <para>

    Definition of periods is done by modules and the corresponding option is <option>nuauth_periods_module</option>.

    For now, the     only available module  is <filename>xml_defs</filename>.

    </para>

    </section>

    <section><title>XML period definition module</title>

    <para>

<filename>xml_defs</filename> is a period definition module. It uses a XML formatted file to store

the periods. The path to this file can be set by using the <option>xml_defs_periodfile</option>:

    </para>

<screen>

xml_defs_periodfile="/etc/nufw/periods.xml"

</screen>

<para>

The XML structure of the file is the following:

</para>

<screen>

<![CDATA[

<?xml version="1.0"?>

<periods>

<period name="5x8" desc="open hour">

    <perioditem>

        <days start="1" end="5"/>

        <hours start="8" end="18"/>

    </perioditem>

</period>

<period name="long" desc="date example">

    <perioditem>

        <dates start="1128282" end="323232323"/>

    </perioditem>

</period>

<period name="interval" desc="one hour interval">

    <perioditem>

        <!-- Duration in second (1 hour) -->

        <duration length="3600"/>

    </perioditem>

</period>

</periods>

]]>

</screen>

<para>

There are two major types of period definitions:

<itemizedlist>

<listitem><para><option>Time interval</option>: the period is defined by using specifying days, hours or dates interval. Days and hours can be combined to define more complex period.

</para></listitem>

<listitem><para><option>Duration</option>: the period is defined by a duration expressed in seconds.</para></listitem>

</itemizedlist>

</para>

<para>Multiple <option>perioditem</option> can be put in the same <option>period</option> to increase the flexibility of period definition.</para>

 </section>

 <note>

 <para>When using Nuface to manage filtering rules, time-based ACLs can be setup through the web interface, without editing any file by hand.</para>

 </note>

 </section>

    <section><title>Chaining modules in nuauth</title>

    <section><title>Syntax description</title>

    <para>

The syntax is the following: Each option that sets up the use of a hook is

a space separated list of modules.</para>

<para>For each module type, the syntax is as follows :

<option>name[:type[:config file]]</option>

If syntax is:

<itemizedlist>

<listitem><para><option>name</option>: loads module "name" with config file included in nuauth.conf</para></listitem>

<listitem><para><option>name:type</option>: loads module "type" with config file CONFIG_DIR/modules/name.conf</para></listitem>

<listitem><para><option>name:type:conf</option>: loads module "type" with config file "conf"</para></listitem>

</itemizedlist>

    </para>

    </section>

    <section><title>Some examples</title>

    <para>

 Let's analyze the following line:

<computeroutput>nuauth_user_logs_module="syslog dblocal:mysql maindb:mysql:/etc/nufw/mainmysql.conf"</computeroutput>

Packet will be logged multiple times:

<orderedlist>

<listitem><para>In syslog</para></listitem>

<listitem><para>In a MySQL database using configuration file /etc/nufw/modules/dblocal.conf</para></listitem>

<listitem><para>In a second MySQL database using configuration file /etc/nufw/mainmysql.conf</para></listitem>

</orderedlist>

    </para>

    </section>

    </section>

<section id='hardening'><title id='hardening.title'>Hardening NuFW</title>

<section><title>Nufw certificate verification</title>

<para>It is highly recommended to install nuauth and nufw on a dedicated server, hardened

for security. Other projects like GrSec <footnote><para>http://www.grsecurity.net/</para></footnote> or

SELinux <footnote><para>http://www.nsa.gov/selinux/</para></footnote> can be used to increase local (system)

security.

<note>

<para>Since NuFW 2.2.19, a SeLinux configuration is distributed in the <computeroutput>selinux/</computeroutput> directory of the archive. Read the <computeroutput>README.selinux</computeroutput>

file there if you want to implement SELinux policies to the NuFW daemons. However, this security policy set is not yet considered stable and

is distributed for testing purpose. You are welcome to send the NuFW team feedback about it!</para>

</note>

</para>

<para>To ensure confidentiality of communications between nufw, nuauth, and the clients,

all connections are encrypted using TLSv1.</para>

<para>

As the firewall policy is applied by nuauth, the trust relationship between nufw and nuauth

should be verified. The certificate provided by nuauth during the TLS negotiation

will be checked if a certificate authority is configured in nufw.

This is done by using the <option>-a</option> option at start

of nufw followed by the name of the certificate authority file.

With this option set, <varname>nufw</varname> will require a signed certificate

from nuauth, and verify it.</para>

<para>The CN (complete name) field from nufw certificate must contain the FQDN (fully

qualified domain name) of nufw server.

</para>

<para>

Since release 2.2.18, NuFW runs in TLS strict mode by default.

 It means nufw will not start if nuauth certificate is:

<orderedlist>

<listitem><para>Not verifiable against an authority</para></listitem>

<listitem><para>Invalid</para></listitem>

<listitem><para>Revoked</para></listitem>

<listitem><para>Without signer</para></listitem>

<listitem><para>Signed, but the signer is not a CA</para></listitem>

<listitem><para>With an insecure algorithm (if GnuTLS is compiled with its support)</para></listitem>

<listitem><para>Not yet activated</para></listitem>

<listitem><para>Expired</para></listitem>

</orderedlist>

See the <link linkend='FinerTLS' endterm="FinerTLS.title"/> section of this document for advanced TLS options of nufw and other components.

</para>

<warning>

<para>

Since release 2.2.18, this mode is now activated by default. You can disable it, at your own risks, using the <option>-s</option> option of nufw.

</para>

</warning>

<para>

To run nufw with strict TLS checking, you will have to specify the following option:

<itemizedlist>

<listitem><para><option>-a</option>: Specify the authority file to use.</para></listitem>

<listitem><para><option>-k</option>: Specify the key file to use.</para></listitem>

<listitem><para><option>-c</option>: Specify the certificate file to use.</para></listitem>

<listitem><para><option>-r</option>: Specify the certificate revocation list file to use (if available). A nufw restart  or a SIGHUP signal will be needed if you want change to the file to be taken into account.</para></listitem>

<listitem><para><option>-d</option>: Fully qualified domain name of the nuauth server.</para></listitem>

</itemizedlist>

Thus a typical nufw command line should look like:

</para>

<screen>nufw -d nuauth.nufw.org -a localCA-cacert.pem -k server.nufw.org-key.pem -c server.nufw.org-cert.pem -r localCA-crl.pem</screen>

<note><para><ulink

url="http://en.wikipedia.org/wiki/Online_Certificate_Status_Protocol">OCSP</ulink>

is currently not supported by NuFW 2.2.X. OCSP support is being worked on in the

trunk (currently unstable) branch of NuFW. Please contact NuFW developers if you need OCSP in 2.2.X,

maybe we can add it to the 2.2 TODO list.</para></note>

</section>

<section><title>Authentication server (nuauth)</title>

<para>The option <option>nuauth_tls_request_cert</option> defines if client

certificates are optional or not. Possible values are:

<itemizedlist>

<listitem><para><option>0</option>: nuauth will not ask client to provide a certificate, they won't send one

even if they have some to give.</para></listitem>

<listitem><para><option>1</option>: client is asked to send a certificate, but the server will not refuse connection if none is provided.</para></listitem>

<listitem><para><option>2</option>: client is asked to send a certificate, and the server will drop the connection if none is provided.</para></listitem>

</itemizedlist>

</para>

<para>The default setting (<option>nuauth_tls_request_cert=2</option>) is that nuauth will require and verify client certificates for all

connections (clients, and NuFW servers). Certificates are used to verify the identity

of all components of a NuFW installation (nufw, nuauth, and clients), and ensure that

no forgery or false representation has occurred.

</para>

<para>All components must share the same certificate authority (CA).

See the <link linkend='FinerTLS' endterm="FinerTLS.title"/> section of this document for advanced TLS options of nuauth and other components.

</para>

<para>The CN (complete name) field from nuauth certificate must contain the FQDN (fully

qualified domain name) of nuauth server. All clients and nufw servers will check that

the DNS name of nuauth server matches the name in the certificate.

</para>

<note>

<para>It is possible to generate a certificate with additional names, using the

<computeroutput>subjectAltName</computeroutput> extension (See

<ulink url="http://tools.ietf.org/html/rfc3280#section-4.2.1.7">Section 4.2.1.7 of RFC

3280</ulink>).

</para>

</note>

<para>

You have to:

<orderedlist>

  <listitem><para>Configure the certificate authority (<option>nuauth_tls_cacert</option>)</para></listitem>

  <listitem><para>Configure nuauth certificate (<option>nuauth_tls_cert</option>) and key (<option>nuauth_tls_key</option>) files.</para></listitem>

  <listitem>

    <para>Deploy client certificates. If you only want to verify server

identity, you can share a certificate between several clients. If you want to

use certificates for authentication, or if you will revoke certificates, you

have to deploy a certificate for each client.

    </para>

  </listitem>

</orderedlist>

Warning: since release 2.2.18, this mode is now activated by default. You can

disable it, at your own risks, by setting <option>nuauth_tls_request_cert=0</option> in nuauth

configuration file.

</para>

<para>nuauth will check that the CN (complete name) field from nufw certificate contains the FQDN (fully

qualified domain name) of the nufw server. You can disable it, at your own risks, by setting

<option>nuauth_tls_disable_nufw_fqdn_check=1</option> in nuauth configuration file.

</para>

<para>You should also configure a Certificate Revocation List (CRL), with the

<option>nuauth_tls_crl</option> parameter in nuauth configuration file. This file contains

the list of all revoked certificates, in standard CRL format. You have to create a

planified task (cron job) to update this file periodically, nuauth will check for

modifications every <option>nuauth_tls_crl_refresh</option> seconds and will reload the file

if necessary. You can use the HUP signal or the <command>refresh crl</command> command

to force an update of the CRL.

</para>

<note>

<para>Note that currently, private keys cannot be password protected : neither nufw nor nuauth support entering a passphrase.

The reference documentation mentions the <computeroutput>nuauth_tls_key_passwd</computeroutput> option, but it is not implemented for now.

</para>

</note>

</section>

<section><title>User authentication restrictions</title>

<para>You can restrict the number of simultaneous nuauth clients, per user or per IP address.

<orderedlist>