source: trunk/LATMOS-Accounts/man/man8/latmos-accounts.pod

# $Id$

=head1 NAME

    Link::Accounts - A multiple accounts base management and synchronisation
    system

=head1 GENERALITY

=head2 HISTORY

Link::Accounts is born with the need to have same set of groups and users in
multiples accounts bases:

=over 4

=item OpenLDAP

Standard ldap base w/o any change on basis schema

=item Active Directory

The domain management system for windows. Active Directory is a solution
including LDAP, Kerberos, Smb protocol and a graphic interface to configure it.

=item Unix file

Standard users base under Unix system, also used for C<NIS>/C<YP> system.

=item Kerberos/Heimdal

Remote access to Kerberos base.

=back

=head2 WORKFLOW

C<Link::Accounts> is made of three components:

=over 4

=item L</Bases>

=item L</Objects>

=item L</Attributes>

=back

=head3 Bases

A base module provide the common way to access a set of data. Usually a base is
accessed remotely trought a network connection but always.

In an ideal world, all base can be synchronised over another one.

Each data inside a base is represented as objects of differents type. The most
common type are for sure C<user> and C<group>.

=head3 Objects

Inside a base the objects is the unbreakble subset of data.

Each object are identified uniquely by both a type and an identifier on the
C<LATMOS::Accounts> side. This mean two object of different type can have the
same id.

On the other hand the identifier must allow to identify uniquelly the object
inside the base.

For example in C</Unix file> base each line of F<passwd> is a C<user> object and
the login is the uniq identifier.

The couple object type/identifier must also allow to find common objects through
differents bases.

=head3 Attributes

The attributes is the basic data storage for an object.

Each attribute have a name and normally a specific usage, even through base.

Attributes may have different behavior, depending their definition and base
constraint:

=over 4

=item single or multiple value

=item limited possible values

=item reference to others objects

=back

=head1 CONFIGURATION

All configuration files listed bellow must be stored in the same directory.

By default this directory is F</etc/latmos-accounts>.

It can be overload by setting envirronment variable C<LA_CONFIG>.

=head2 Configuration files list

=over 4

=item latmos-accounts.ini

Bases and synchronisations definitions.

See L<latmos-accounts.ini>

=item la-allowed-values.ini

Attributes values allowed.

See L<la-allowed-values.ini>

=item la-sync-manager.ini

The setup of L<la-sync-manager>, the daemon in charge of pushing values from
primary base to others.

See L<la-sync-manager.ini>

=item la-acls.ini

Access list configuration, used by Web application

See L<la-acls.ini>

=item la-sync-list.ini

Configuration of mailing synchronisation module

See L<la-sync-list.ini>

=back

=head1 INPUT FILE

The input file is a list of attribute and value separate by a semi-colon.
Multi-values attributes must be repeated for each value.
Attributes not listed are left untouched.

Example:

    sn: Myname
    givenName: Myfirstname

Some object have related objects, for example C<user> have multiple C<address>
and C<employment>. It can be usefull to create those object in same time the
main object.

At creation the related object attributes can given using attribute in form
C<OTYPE.ATTRIBUTE>.

Example:

    sn: Myname
    givenName: Myfirstname
    address.streetAddress: 5th Avenue, 123

Multiple objects of same type can be given a key between C<[]>, this key may
use any letter C<a-z>, C<A-Z> or number C<0-9>.

    sn: Myname
    givenName: Myfirstname
    address[0].streetAddress: 5th Avenue, 123
    address[aa].streetAddress: 5th Avenue, 123

=head1 TOOLS LIST

The tools listed bellow are availlable to administrate the C<Link::Accounts>
system.

They are low level tools and are designed to be used system administrator, not
end user (unlike the web interface).

=head2 Configuration Tools

=over 4

=item la-config

Display configuration information.

L<la-config>

=item la-attributes

Display supported object and attributes.

L<la-attributes>

=item la-log-test

Send message using log functions (for testing purpose)

L<la-log-test>

=item la-acls

Check validity of ACL file (eg L<la-acls.ini>).

See: L<la-acls>

=item la-qacls

Test ACLs permission for given user over given object.

See: L<la-qacls>

=back

=head2 Base Content Tools

=over 4

=item la-cli

Interactive command line interface, include online help, completion, etc...

See L<la-cli>

=item la-create

Create an object into main base.

See L<la-create>

=item la-delete

Delete an object from main base

See L<la-delete>

=item la-edit

Modify object into main base.

See L<la-edit>

=item L<la-expired-reminder>


=item L<la-graph.pl>

=item L<la-group>

=item L<la-guser>

=item L<la-passwd>

Change the password of users.

=item L<la-query>

The basic tools to query any database

=item L<la-rename>

Allow to rename an object in all configured base simultaneously, then avoiding
a deletion  and a creation potentially destructive in some base.

To use carrefully

=item L<la-search>

Search object into base.

=item L<la-sync>

=item L<la-sync-manager>

=item L<la-sync-process>

=item L<la-warn-expire>

=item L<la-test-mail>

=back

=head2 SQL Base Tools

=head3 Common tools

=over 4

=item L<la-sql-freeip>

Return an unallocated IP address from the given DHCP zone.

=back

=head3 Maintenance tools

=over 4

=item L<la-sql-rev>

Give the latest internal revision of the base. The revision is a counter
increase when database is changed.

=item L<la-sql-upgrade>

Upgrade the schema of the SQL database

=item L<la-sql-crypt-passwd>

Tools to managed the reversible encryptage of passaword.

=item L<la-rename-host>

Rename an network host

=item L<la-sql-exchange-hostname>

Exchange the name between two hosts.

=item L<la-sql-exchange-ip>

Exchange two ip address between different hosts.

=item L<la-sql-find-expired>

=item L<la-sql-edit-form>

=item L<la-sql-list-request>

=item L<la-sql-valid-request>

=back

=head1 ENVIRONMENT VARIABLES

=head2 LA_DEBUG

When set print a lot of debug message

=head2 LA_ACL_DEBUG

Print debug message about ACL processing. LA_DEBUG must be set to see
ACL messages

=head2 LA_USERNAME

The user UID set into this variable will be used as logged user.
If set ACL will always be used.

=head2 LA_NO_COMMIT

If set no commit will be done in the database.

=head1 BUGS

=head1 AUTHOR

Olivier Thauvin <olivier.thauvin@latmos.ipsl.fr>