==========
Auth Mysql
==========

Introduction
============

auth_mysql can be used as:
 * nuauth_user_check_module
 * nuauth_get_user_id_module
 * nuauth_get_user_groups_module
 * nuauth_ip_authentication_module (use with caution)


Prerequisites
=============

Two different mysql schemas are provided in conf/auth_mysql:
- auth_mysql.ipv4.mysql.dump
- auth_mysql.ipv6.mysql.dump

import the one that matches with you setup.

If you use IPv6 mysql schema you need to uncomment the following line in nuauth.conf:

mysql_use_ipv4_schema=0

If you want to use netmask checking in ipauth module you must also import check_net.mysql, that contains 'check_net' function.
WARNING to import this file you must have the SUPER privilege or this variable must be declared:
-- SET GLOBAL log_bin_trust_function_creators = 1;

Then set this line in nuauth.conf:

mysql_ipauth_check_netmask=1

Module configuration
====================

mysql tables
~~~~~~~~~~~~

 * userinfo table contains users informations:

  * main columns are uid and username
  * password column is used for user authentication
  * other columns can be added to add user description (address, mail, phone, ...)

 * groups table contains group names and group id,
 * groupinfo table contains user-group associations:

  * Each user can be part of several groups, each line indicate that the uid is part of the gid,

 * ipauth_sessions table is used for ip based authentication.

  * 'netmask' column is used for authenticate a single ip or an entire subnet. Default value is 128
    for ipv6 mysql schema or 32 ipv4 schema (with int(10) ip_saddr) authenticating just one host,
    but you can change it to authenticate an entire subnet (i.e. 192.168.10.0/24
    or ::ffff:192.168.10.0/120). WARNING with ipv6 schema you'll need to declare 'check_mysql'
    function (see above)
  * 'no_logout' column is useful to tag the lines that should never be removed in order to add a
    'persistent' (never ending) connection. (values: 'y' or 'n')

nuauth.conf file
~~~~~~~~~~~~~~~~
  
In nuauth configuration file this parameters are supported:
 * mysql_ipauth_table_name (default: ipauth_sessions)
 * mysql_userinfo_table_name (default: userinfo)
 * mysql_groups_table_name (default: groups)
 * mysql_groupinfo_table_name (default: groupinfo)
 * some other mysql setting used by log_mysql module are used here too with the same meaning.
 * mysql_ipauth_check_netmask: wether or not use netmask in ip authentication. (default: 1)

IP authentication module configuration
======================================

iptables setup
~~~~~~~~~~~~~~

If you want to use ipauthentication module and want to redirect http/https traffic to a login
page you must declare following rules in iptables's nat table:

iptables -t nat -A PREROUTING -i eth0 -s 192.168.22.11 -m mark --mark 0 -p tcp --dport 80 -j REDIRECT
iptables -t nat -A PREROUTING -i eth0 -s 192.168.22.11 -m mark --mark 0 -p tcp --dport 443 -j REDIRECT

Notes:
   (1. we suppose eth0 being you lan interface)
   (2. if your login page is on a remote host you can use "DNAT --to-destination <remoteIP>" as target)

Moreover nufw's filtering rules must be declared in mangle table and not in forward or output:

iptables -t mangle -D PREROUTING -p tcp -i eth0 -m state --state NEW --syn -j NFQUEUE

This way every not authenticated connection is marked "guest" (by default uid=0,gid=99) and above rules
in nat table redirect it to login page

acl setup
~~~~~~~~~

In nuauth's acl you need to permit traffic from guest group (default 99 if not overridden in mysql tables)
to 80 and 443 ports. For example:

[web]
decision=1 
gid=99
proto=6
SrcIP=0.0.0.0/0
SrcPort=1024-65535
DstIP=0.0.0.0/0
DstPort=80

[web 2]
decision=1 
gid=99
proto=6
SrcIP=0.0.0.0/0
SrcPort=1024-65535
DstIP=0.0.0.0/0
DstPort=443

Using it
========

The PHP pages available in scripts/auth_mysql/mysqlauth/ provide an login and logout page.
You may need to edit the start of index.php to adjust the database configuration to your system.

logoff script in the directory scripts/auth_mysql/ can be used to end session after timeout.

You can also use the PHP script auth_mysql.php provided in scripts/auth_mysql as starting point
for a login banner. This script uses the userinfo table to verify user and password given at prompt.