source: trunk/LATMOS-Accounts/man/man8/latmos-accounts-base-sql.pod @ 2260

# $Id$

=head1 DESCRIPTION

=head1 SPECIFIC SETUP PARAMTERS

=head2 db_conn

The C<libpq> connection parameters, eg a semin colon separated paramaters
containing the server, the database name, user and password, etc...

=head2 no_pg_utf8

If set disable utf8 flags from postgresql. You can try this parameter if you
have issue with non ascii value from database

=head2 remove_old_dpmt

By default when the department is changed on a user account it remains in the
department group as a secondary department.

Setting C<remove_old_dpmt> to true in the config will force user removal from
the group when department is changed.
The user can still be added back later.

=head2 ASyncDynData

Don't compute dynamic attribute at commit but let syncManager do it
asynchronously.

=head2 monitored

Allow to specify monitored attributes. Monitored attributes will have their
value logued when changed.

Can be specified multiple times:

    monitored=user.loginShell
    monitored=nethost.ip

=head1 FEATURES

=head2 Object Aliases

It is possible to create object being simple alias to another, like symbolic on
UNIX filesystem or mail alias.

Thoses aliases objects are always resolved when propagating into other base.
The referenced object can be easilly change and all the data related will be
propagated.

Only alias for object type C<User> are supported at time.

=head3 Usage Example:

The typical exemple is for attribute C<manager> or attribute C<managedBy>.
Instead setting them to C<John> you can create an alias C<Director> and when
C<John> leave just change alias reference to C<Bill>.

=head2 Network managment

Link::Accounts can build automatically some part of your DNS or DHCP
configuration.

To do this you have to create a C<netzone> object. Such object need a type:

=over 4

=item dns: to build a DNS zone for classic domain

=item reverse: for reverse IP address (168.192.in-addr.arpa)

=item dhcp: ISC dscpd configuration for fixed address

=item puppet: puppet configuration

=back

The way it works is quite simple, each zone will make the code to write a file
you can include in your server configuration. The match is done by looking the
zone IP address masks and the host IPs.

For example someone having a zone named C<private.mydomain.com> having masks
C<192.168.5.0/24>, and having an host named C<foo> with IP C<192.168.5.3> and
another host C<bar> with IP C<192.168.13.78>. The zone built will look likes:

    foo IN A 192.168.5.3

As you can see this DNS zone is not valid: the goal of such feature is to make
the repetive work for us, not to manage the full zone (even such feature could
be possible). The repetitive work is declaring the hundred computers our users
have.

The output will be happend to a template have the name of the zone suffixed by
C<.in>. You can put in this template evering about the zone declaration (SOA,
NS, TXT...).

=head2 User endcircuit

The C<endcircuit> attribute contain the deadline for people to make
admnistrative task when starting to work.
If set this attribute take precedence to C<expire> attribute for computed
attributes (C<accountExpires> for Active Directory).

Setting C<endCircuitdontExpire> option to the database disable this behavior and
C<endcircuit> attribute become informationnal only.

=head2 User Employment

The employment object allow you to set time when you're user have a status. This
allow through 'Employment' module for la-sync-manager to automate changes.

The synchronized attributes are:

=over 4

=item C<company>

=item C<employer>

=item C<department>

=item C<contratType>

=item C<managerContact>

=item C<expire>

=item C<endcircuit>

=back

To avoid error when modifying user direclty when you're using employment those
attribute become on user's side become read-only once an employment exists.

You can change this beaviour using C<employment_lock_user> parameter:

By default it is impossible to modify or create past employment. This behavior
can be changed by settings C<allow_pasted_employment> parameter in base
configuration.

=over 4

=item any (default)

Any existing employment lock those attribute, you must
create another employment to change user status or delete all employements for
this user.

=item always

The user's attribute are always locked

=item never

The user's attribute are always locked

=item active

Thoses attributes are locked is any employment are still active (ie unfinished
or coming later).

=item attribute=value

Thoses attributes are read-only if the C<attribute> given contains C<value>,
C<*> allow to match any value.

=back

When active users become out of any employment all managed attribute are unset
(except the expire attribute).

A default value for each of this attribute can be set in configuration using
parameter in form C<unemployment.ATTRIBUTE>. For example
C<unemployment.contratType=external> will set any C<contratType> to C<external>
when no employment apply to user anymore.

Only active accounts are modified in this way.

=head3 User endEmployment

This attribute compute the next day the user will leave the company according
the employment object registered.

The parameter C<employment_delay> give the number of days to ignore when a hole
exists between two employment.

If no employment are found, if set the date given in C<unemployed_expire>
database parameter is returned.

=head3 User endStrictEmployment

This attribute compute the next day the user will leave the company according
the employment object registered.

It does not take C<employment_delay> parameter into account.

If no employment are found, if set the date given in C<unemployed_expire>
database parameter is returned.

=head3 User endLastEmployment

This attribute return the very last end of all registered employment fr this
user.

=head3 User endCurrentEmployment

The end of the employment matching current date.

=head3 Account Expiration

When using employment, account expiration are set to match employment. By
default the expiration is set to C<endEmployment> value.

This behaviour can be changed by setting C<expireOn> parameter into base
definition:

=over 4

=item any of endCurrentEmployment, endEmployment, endStrictEmployment, endLastEmployment

=item never

The expire date is left unchanged and must managed manually.

=back

=head2 Group AutoMemberFilter

Group objects contains users members by setting either C<members> or
C<memberUID> attributes.

Sometimes it can be usefull to have group automatically populated by arbitrary
rules.

This is possible by setting a filter in the C<autoMemberFilter> attribute,
The filter format is the same the one used by L<la-search>, the attribute is
multivaluable.

So for example one can create an account automatically a group containing people
having "Olivier" as first name:

    autoMemberFilter: givenBame=Olivier

A probably more usefull example is a group containing people from two others
groups:

    autoMemberFilter: memberOf=group1
    autoMemberFilter: memberOf=group2

The  C<members> or C<memberUID> attribute becomes read-only attribute once
C<autoMemberFilter> attribute is set.

=head2 Aliases AutoMemberFilter

This attribute allow to create automatics dynamics aliases according filter
rules exactly like L<Group AutoMemberFilter> works.

The C<forward> attributes is automatically set with email address of selected
user, user w/o email address are ignored.

=head2 Group AutoFromSutype

Group object can be tagged with the C<sutype> attribute.

When C<autoFromSutype> is set the group member will be computed from member of
all groups having C<sutype> set this value.

The goal of this attribute is to setup magic group like with the
C<autoMemberFilter> but working even a new group is created.

=head2 Aliases AutoFromSutype

This attribute allow to create automatics dynamics aliases according filter
rules exactly like L<Group AutoFromSutype> works.

The C<forward> attributes is automatically set with email address of selected
user, user w/o email address are ignored.

=head2 Statistics

The application provide some statitics tools but they are only based on the
current data inside the database and are unable to track delete data.

To keep some mesurement you must use C<stat> objects to describe the data you
want to track, and enable in L<la-sync-manager.ini> the C<Stats> module.

Each attribute of C<Stat> object describe how data must but compute before being
stored.

=head3 Stat object Attributes

=head4 description

A label about this statistics object

=head4 display

IF set the statistic appear in the menu of the web interface

=head4 otype

The object type this stat is tracking, must be a supported object type

=head4 filter

One or multiple filter to limit the objects taking into account

=head4 attribute

The attribute fetch to compute data

=head4 refFilter

When the attribute reference another type of object this setting allow to
filter to the matching referenced object.

=head4 refAll

When the attribute reference another type of object non exiting objects in
the results appear as 0, otherwise they are ignored.

=head4 aggregateFunction

An optionnal operation to do on the data:

=over 4

=item sum

Make the sum of the result per item

=item avg

Make the average of the result per item

=item count

Count the number of item return

=back

=head4 delay

The number of day between two run

=head4 retention

If set, the duration in days after which stats value must deleted