+------------------------------------------------------------------------------+
| NAGIOS LOOKING GLASS - FILTER HOW-TO                                         |
|------------------------------------------------------------------------------|
| Author:           Andy Shellam <andy@networkmail.eu>                         |
| Last Updated:     4th August 2008                                            |
+------------------------------------------------------------------------------+

Filter authentication is the term used to describe the ability to provide
different sets of filters to different users.  This is controlled using the file
located at server/sync-files/s3_filter_auth.inc.php.

*********************************************************************************
** SECURITY WARNING                                                            **
** You must disable client-side caching (in s3_config.inc.php) when using this **
** feature, as caching could allow users to see data from filters other than   **
** their own.                                                                  **
*********************************************************************************

This is a temporary solution for organisations wishing to restrict the data
their users can see.  NLG v2 will have a security model built-in which will work
with caching enabled and provide a user/groups system to ease the burden of
manually updating the filter permissions file (s3_filter_auth.inc.php.)

In the meantime, there's no reason why this file cannot be generated from a
database if an organisation wants to.

This solution does not provide any access control.  It is easy for a user to
view the status of a server they don't have filter access to, if they try hard
enough.  NLG v2's security model will prevent this.

Example Case Study:

(This example assumes NLG 1.1.0b2 is set-up and configured with HTTP Basic
 authentication.)
 
A hosting company XYZ wants to provide a client ABC with a custom set of filters
for their servers :- server1 and server2.  This client logs in with the username
"Client-ABC".

They will also want to provide client DEF with a custom set of filters for their
servers :- server3 and server4.  This client logs in with the username
"Client-DEF".

The XYZ company will set up the following filters in addition to the standard
filters (in server/sync-files/s3_filter_auth.inc.php):

	$HostFilter[6] = new S3_NetworkFilter();
	$HostFilter[6]->Create("Client ABC - OK");
	$HostFilter[6]->SetType("both");
	$HostFilter[6]->AddHost("server1");
	$HostFilter[6]->AddHost("server2");
	$HostFilter[6]->AddStatus(0);
	
	$HostFilter[7] = new S3_NetworkFilter();
	$HostFilter[7]->Create("Client ABC - Problems");
	$HostFilter[7]->SetType("both");
	$HostFilter[7]->AddHost("server1");
	$HostFilter[7]->AddHost("server2");
	$HostFilter[7]->AddStatus(1);
	$HostFilter[7]->AddStatus(2);
	$HostFilter[7]->AddStatus(3);
	
	$HostFilter[8] = new S3_NetworkFilter();
	$HostFilter[8]->Create("Client DEF - OK");
	$HostFilter[8]->SetType("both");
	$HostFilter[8]->AddHost("server3");
	$HostFilter[8]->AddHost("server4");
	$HostFilter[8]->AddStatus(0);
	
	$HostFilter[9] = new S3_NetworkFilter();
	$HostFilter[9]->Create("Client DEF - Problems");
	$HostFilter[9]->SetType("both");
	$HostFilter[9]->AddHost("server3");
	$HostFilter[9]->AddHost("server4");
	$HostFilter[9]->AddStatus(1);
	$HostFilter[9]->AddStatus(2);
	$HostFilter[9]->AddStatus(3);
	
As the above stands, both clients can still see all of the standard filters as
well as the other client's filters and servers - not what XYZ wants.
This is where "Filter Authentication" comes in.

Company XYZ wants Client ABC to only see filters 6 and 7, which will result in
Client ABC only being able to see server1 and server2.  Client DEF, on the other
hand, should only see filters 8 and 9, which will result in Client DEF only
being able to see server3 and server4.

Everybody else (e.g. Company XYZ staff) should see everything.

The file server/sync-files/s3_filter_auth.inc.php contains a "lookup table" of
usernames to the filters they should be able to see, including a "default" user.
Any user not specifically listed in this file will see the "default" user's 
filters - which unless otherwise specified, is all filters configured.

This allows, for example, all normal users to be restricted to a set of filters,
while other users (e.g. super-users) can then specifically be defined to see the
extra filters.

It's dead easy - simply say which username should see which filters in each line
of the file - as below.  The ID numbers are the numbers of the filters defined
in server/sync-files/s3_filter.inc.php.  For the example above, this would be:

$FilterAuth['Client-ABC'] = Array(6, 7);
$FilterAuth['Client-DEF'] = Array(8, 9);

Now if a staff member "Staff-GHI" logs in, they will see all filters and
servers, because they will take the "default" user's permissions.

To restrict all users to a single filter, and create "user1" as a "power-user":

$FilterAuth['default'] = Array(0);                // Can only see filter ID 0
$FilterAuth['user1'] = Array(0, 1, 2, 3, 4, 5); // Can see filters 0-5
