Provided by: libcipux-storage-perl_3.4.0.2-6_all bug

NAME

       CipUX::Storage - Storage abstraction layer for CipUX

VERSION

       version 3.4.0.2

SYNOPSIS

         use CipUX::Storage;

DESCRIPTION

       The CipUX Storage abstraction layer is a generic abstract class, which can be used to
       access LDAP servers via Perl by issuing simple actions and via shell command line
       interface. It was tested with openLDAP version 3. The layer is capable of operating on
       different sets of LDAP nodes. A set of nodes might be defined by an LDAP objectClass or
       LDAP attribute. Example: cipuxAccount or posixAccount.  The number of objects inside a set
       might be ranged from one to many. The abstraction layer performs a method on a set of
       nodes. Valid methods are: 'get', 'set', 'get-all', 'set-all' on LDAP attribute values and
       'add', 'delete', 'rename' on LDAP nodes.

       It provides the functions get_value, set_value to modify LDAP attribute values.  The
       function add_node, delete_node and rename_node for adding, deleting and renaming LDAP
       objects.

SUBROUTINES/METHODS

       The following functions will be exported by CipUX::Storage.

   BUILD
       This is the constructor, see new.

         use CipUX::Storage;

         use base qw(CipUX::Storage);

         my $storage = CipUX::Storage->new();

   DEMOLISH
       This is the destructor.

   get_value
       The get_value queries the LDAP and returns one ore more values depending on the parameter
       'scope'.

       Syntax:

         eval {

             my $object    = 'ckuelker';
             my $attribute = 'cipuxFirstname';
             my $type      = 'all_user_node';
             $value_hr = $ldap->get_value({
                                              scope=>'one',
                                              type=>$type,
                                              obj=>$object,
                                              attr_ar=>[$attribute]
                                             });
         } or croak "ERROR: can't get value: $@!" if $@;

       returns one value:

           %$ret_hr = (
                     'ckuelker' => {
                                      'cipuxFirstname' => ['Christian'],
                                   }
                       );

         eval {

             my $object    = '';
             my $attribute = 'cipuxFirstname';
             my $type      = 'all_user_node';
             $value_hr = $ldap->get_value({
                                              scope=>'all',
                                              type=>$type,
                                              obj=>$object,
                                              attr_ar=>[$attribute]
                                             });
         } or croak "ERROR: can't get value: $@!" if $@;

         %$ret_hr = (
                     'ckuelker' => {
                                      'cipuxFirstname' => ['Christian'],
                                      'cipuxLastname' =>  ['Kuelker'],
                                   },
                     'xoswald' => {
                                      'cipuxFirstname' => ['Xavier'],
                                      'cipuxLastname' =>  ['Oswald'],
                                   },

                 );

       Return values

           %ret = (
                     'ckuelker' => {
                                      'cipuxFirstname' => ['Christian'],
                                      'cipuxLastname' =>  ['Kuelker'],
                                   }

   set_value
       Sets a value for a given object in the LDAP database.

        my $rslt = set_value( {
            obj=>$obj,
            attr_ar=>$attr_ar,
            changes=>$changes,
            scope=>$scope,
            escope=>$escope,
            type=>$type
        } ;

            obj:      object
            attr_ar:  reference to an array of LDAP attributes and values
            changes:
            scope:    'one|all'        set/modify value
            escope:   'one|all|none'   erase scope
            type:

       Modify Syntax

               my $msg = $ldap->modify( $dn,
                                          changes => [
                                              # add sn=Baggins
                                            add     => [ sn => 'Baggins' ],
                                              # delete all fax numbers
                                            delete  => [ faxNumber => []],
                                              # delete phone number 911
                                            delete  => [ telephoneNumber => ['911']],
                                              # change email address
                                            replace => [ mail => 'bilbo@baggins.org']
                                          ]
                                        );

   add_node
       Adds an LDAP node to the LDAP database.

        my $rslt = $cipux->add_node({obj=>$obj, type=>$type, attr_hr=>$attr_hr});

        obj :    The object to be added
        type:    kind of object to be added
        attr_hr: Hash reference with 'ldap_attribute=>value' structure

        $rslt:   is the reslult from Net::LDAP add

   delete_node
       Deletes an LDAP node from the LDAP database.

        my $rslt = $cipux->delete_node( { obj=>$obj, type=>$type } );

        obj :    The object to be added
        type:    kind of object to be added

        $rslt:   is the result from Net::LDAP delete

   rename_node
       Rename an LDAP node of the LDAP database.

        my $rslt = $cipux->rename_node({obj=>$obj, type=>$type, value=>$value });

        obj :    The object to be added
        type:    kind of object to be added
        value:   The new name

        $rslt:   is the result from Net::LDAP rename

   _ldap_start
       Binds to the LDAP server.

        my %access        = ();
        $access_cfg{ident $self}->{uri}      = 'ldap://localhost';
        $access_cfg{ident $self}->{bind_dn}  = 'cn=admin,dc=nodomain';
        $access_cfg{ident $self}->{password} = 'secret';
        my $ldap = $cipux->_ldap_start();

        $ldap:   is the LDAP Perl object returned from Net::LDAP.

   _ldap_start
       Unbinds from the LDAP server.

        my $msg = $cipux->_ldap_end( { ldap=>$ldap} );

        $msg:   is the message returned from Net::LDAP.

   list_storage_type
       Lists all CipUX LDAP nodes entities, sorted.

        my $list_ar = $cipux->list_type( { ldap=>$ldap} );

        $list_ar:   reference to an array of sorted CipUX LDAP entities.

   _ldap_struct
       Parses cipux-storage.perl with for object, type, filter of a given scope. It also performs
       some simple validation of that file.

        my $ldap_structure_hr = $cipux->_ldap_struct( {
            obj=>$obj,
            type=>$type,
            scope=>$scope,
            filter=>$filter
        });

        $ldap_structure_hr: returns a structure hash reference

   oid_number_supremum
       Searches the storage database for uidNumber and gidNumber. It returns the one number above
       the largest number or the minimum number in the number range for users and groups.

       To perform the search it uses get_value (the storage layer itself).

   get_sid
       Retrieve sambaSID and return it if successful

Configuration files

   cipux-access.ini
       The CipUX access configuration has the following entries:

        [ldap]
        uri      = ldaps://ldap
        bind_dn  = cn=cipuxroot,dc=nodomain
        base_dn  = ou=CipUX,dc=nodomain
        password = secret
        system   = debian
        customer =

   cipux_storage.perl
       The storage structure configuration might look like this:

           $cfg = {
               'structure' => {
                       all_group_node => {
                           desc         => 'access to all CN group objects',
                           struc_rdn    => 'ou=Group',
                           dn_attr      => 'cn',
                           filter       => '(cn=?)',
                       },
                       all_user_node => {
                           desc         => 'access to all system UID objects',
                           struc_rdn    => 'ou=User',
                           dn_attr      => 'uid',
                           filter       => '(uid=?)',
                       },
                       course_group_node => {
                           desc         => 'access to all system GID objects',
                           struc_rdn    => 'ou=Group',
                           dn_attr      => 'cn',
                           filter       => '&(cn=?)(groupType=public)',
                       },
                   },
       }

DIAGNOSTICS

       TODO

CONFIGURATION AND ENVIRONMENT

       See cipux-access.ini and cipux-storage.perl man page for details on configuration.
       CipUX::Storage do not use the environment for configuration.

DEPENDENCIES

        Carp
        Class::Std
        CipUX
        Data::Dumper
        English
        Net::LDAP
        Log::Log4perl
        Readonly
        utf8
        version

INCOMPATIBILITIES

       Not known.

BUGS AND LIMITATIONS

       Not known.

SEE ALSO

       See the CipUX web page and the manual at <http://www.cipux.org>

       See the mailing list http://sympa.cipworx.org/wws/info/cipux-devel
       <http://sympa.cipworx.org/wws/info/cipux-devel>

AUTHOR

       Christian Kuelker  <christian.kuelker@cipworx.org>

LICENSE AND COPYRIGHT

       Copyright (C) 2007 - 2009 by Christian Kuelker

       This program is free software; you can redistribute it and/or modify it under the terms of
       the GNU General Public License as published by the Free Software Foundation; either
       version 2, or (at your option) any later version.

       This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY;
       without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
       See the GNU General Public License for more details.

       You should have received a copy of the GNU General Public License along with this program;
       if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston,
       MA 02111-1307 USA