Lemonldap::NG::Handler manpage update

modules/lemonldap-ng-handler/lib/Lemonldap/NG/Handler.pm

@@ -12,7 +12,8 @@ __END__
 
 =head1 NAME
 
-Lemonldap::NG::Handler - The Apache module part of Lemonldap::NG Web-SSO system.
+Lemonldap::NG::Handler - The Apache protection module part of
+Lemonldap::NG Web-SSO system.
 
 =head1 SYNOPSIS
 
@@ -35,7 +36,6 @@ Create your own package (example using a central configuration database):
         dbiUser             => "lemonldap",
         dbiPassword          => "password",
     }
-    # Maximum time to load a local stored configuration
   } );
 
 =head2 Configure Apache
@@ -71,10 +71,10 @@ It manages both authentication and authorization and provides headers for
 accounting. So you can have a full AAA protection for your web space as
 described below.
 
-The Apache module part works both with Apache 1 and 2 ie mod_perl 1 and 2
+The Apache module part works both with Apache 1.3.x and 2.x ie mod_perl 1 and 2
 but B<not with mod_perl 1.99>.
 
-=head2 Authentication, Autorization, Accounting
+=head2 Authentication, Authorization, Accounting
 
 =head3 B<Authentication>
 
@@ -88,10 +88,10 @@ Lemonldap use session cookies generated by L<Apache::Session> so as secure as a
 128-bit random cookie. You may use the C<securedCookie> options of
 L<Lemonldap::NG::Portal> to avoid session hijacking.
 
-You have to manage life of sessions by yourself since Lemonldap knows nothing
-about the L<Apache::Session> module you've choosed, but it's very easy using a
-simple cron script because L<Lemonldap::NG::Portal> stores the start time in the
-C<_utime> field.
+You have to manage life of sessions by yourself since Lemonldap::NG knows
+nothing about the L<Apache::Session> module you've choosed, but it's very easy
+using a simple cron script because L<Lemonldap::NG::Portal> stores the start
+time in the C<_utime> field.
 By default, a session stay 10 minutes in the local storage, so in the worth
 case, a user is authorized 10 minutes after he lost his rights.
 
@@ -106,7 +106,7 @@ about the way the user will choose. When configuring your Web-SSO, you have to:
 authorization (see C<exportedHeaders> parameter in L<Lemonldap::NG::Portal>
 documentation).
 
-=item * create Perl expression to define user groups (using ldap attributes)
+=item * create Perl expressions to define user groups (using ldap attributes)
 
 =item * create an array foreach virtual host associating URI regular
 expressions and Perl expressions to use to grant access.
@@ -116,8 +116,8 @@ expressions and Perl expressions to use to grant access.
 =head4 Example (See L<Lemonldap::NG::Manager> to see how configuration is
 stored)
 
-Exported variables (in Lemonldap::NG::Portal, will be stored in
-configuration database):
+Exported variables (values will be stored in session database by
+L<Lemonldap::NG::Portal>):
 
   exportedVars => {
       cn            => "cn",
@@ -125,15 +125,15 @@ configuration database):
       login         => "uid",
   },
 
-User groups (stored in configuration database with L<Lemonldap::NG::Manager>):
+User groups (values will be stored in session database by
+L<Lemonldap::NG::Portal>):
 
   groups => {
       group1 => '{ $departmentUID eq "unit1" or $login = "xavier.guimard" }',
       ...
   },
 
-Area protection (stored in configuration database with
-L<Lemonldap::NG::Manager>):
+Area protection:
 
   locationRules => {
       www1.domain.com => {
@@ -150,17 +150,19 @@ L<Lemonldap::NG::Manager>):
 =head4 Performance
 
 You can use Perl expressions as complicated as you want and you can use all
-the exported LDAP attributes (and create your own attributes: see examples in
-L<Lemonldap::NG::Portal> distribution) both in groups evaluations and area
-protections (you just have to call them with a "$").
+the exported LDAP attributes (and create your own attributes: with 'macros'
+mechanism. See L<Lemonldap::NG::Manager>) in groups evaluations, area
+protections or custom HTTP headers (you just have to call them with a "$").
 
 You have to be careful when choosing your expressions:
 
 =over
 
-=item * C<groups> are evaluated each time a user is redirected to the portal,
+=item * C<groups> and C<macros> are evaluated each time a user is redirected to
+the portal,
 
-=item * C<locationRules> are evaluated for each request.
+=item * C<locationRules> and C<exportedheaders> are evaluated for each request
+on a protected area.
 
 =back
 
@@ -173,8 +175,8 @@ evaluate a long expression at each HTTP request:
       },
   },
 
-You can also use ldap filters in C<groups> parameter, or Perl expression or
-mixed expressions. Perl expressions has to be enclosed with C<{}>:
+You can also use LDAP filters, or Perl expression or mixed expressions in
+C<groups> parameter. Perl expressions has to be enclosed with C<{}>:
 
 =over
 
@@ -200,23 +202,24 @@ was wrong if C<process> method has failed.
 =head4 I<Logging application access>
 
 Because an handler knows nothing about the protected application, it can't do
-more than logging URL. As Apache does this fine, L<Lemonldap::NG::Handler> gives it
-the name to used in logs. The C<whatToTrace> parameters indicates which
-variable Apache has to use (C<$uid> by default).
+more than logging URL. As Apache does this fine, L<Lemonldap::NG::Handler>
+gives it the name to used in logs. The C<whatToTrace> parameters indicates
+which variable Apache has to use (C<$uid> by default).
 
 The real accounting has to be done by the application itself which knows the
 result of SQL transaction for example.
 
-Lemonldap can export http headers either using a proxy or protecting directly
-the application. By default, the C<User-Auth> field is used but you can change
-it using the C<exportedHeaders> parameters (stored in the configuration
-database). This parameters contains an associative array:
+Lemonldap::NG can export HTTP headers either using a proxy or protecting
+directly the application. By default, the C<Auth-User> field is used but you
+can change it using the C<exportedHeaders> parameters (stored in the
+configuration database). This parameters contains an associative array per
+virtual host:
 
 =over
 
 =item * B<keys> are the names of the choosen headers
 
-=item * B<values> are perl expressions where you can use user datas stored in
+=item * B<values> are Perl expressions where you can use user datas stored in
 the global store by calling them C<$E<lt>varnameE<gt>>.
 
 =back
@@ -230,10 +233,11 @@ Example:
       },
       www2.domain.com => {
           'Authorization' => '"Basic ".encode_base64($employeeNumber.":dummy")',
+          'Remote-IP'     => '$ip',
       },
   }
 
-=head2 Storage systems
+=head2 Session storage systems
 
 Lemonldap::NG use 3 levels of cache for authenticated users:
 
@@ -244,17 +248,17 @@ parameter (completed with C<globalStorageOptions>) and used by
 L<lemonldap::NG::Portal> to store authenticated user parameters,
 
 =item * a L<Cache::Cache> module choosed with the C<localStorage> parameter
-(completed with C<localStorageOptions> and used to share authenticated users
+(completed with C<localStorageOptions>) and used to share authenticated users
 between Apache's threads or processus and of course between virtual hosts,
 
-=item * Lemonldap::NG variables: if the same user use the same thread or
-processus a second time, no request are needed to grant or refuse access. This
-is very efficient with HTTP/1.1 Keep-Alive system.
+=item * Lemonldap::NG::Handler variables: if the same user use the same thread
+or processus a second time, no request are needed to grant or refuse access.
+This is very efficient with HTTP/1.1 Keep-Alive system.
 
 =back
 
-So the number of request to the central storage is limited to 1 per user each
-10 minutes.
+So the number of request to the central storage is limited to 1 per active
+user each 10 minutes.
 
 Lemonldap::NG is very fast, but you can increase performance using a
 L<Cache::Cache> module that does not use disk access.

modules/lemonldap-ng-handler/lib/Lemonldap/NG/Handler/SharedConf/DBI.pm

@@ -2,7 +2,6 @@ package Lemonldap::NG::Handler::SharedConf::DBI;
 
 use strict;
 
-use UNIVERSAL qw(can);
 use Lemonldap::NG::Handler::SharedConf qw(:all);
 use DBI;
 use Storable qw(thaw);