.\" Automatically generated by Pod::Man 2.23 (Pod::Simple 3.14)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.ie \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.el \{\
.    de IX
..
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "CipUX::Storage 3pm"
.TH CipUX::Storage 3pm "2011-05-05" "perl v5.12.3" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
CipUX::Storage \- Storage abstraction layer for CipUX
.SH "VERSION"
.IX Header "VERSION"
version 3.4.0.2
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  use CipUX::Storage;
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
The CipUX Storage abstraction layer is a generic abstract class, which can be
used to access \s-1LDAP\s0 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 \s-1LDAP\s0 nodes. A set of nodes might be
defined by an \s-1LDAP\s0 objectClass or \s-1LDAP\s0 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 \s-1LDAP\s0 attribute values and  'add',
\&'delete', 'rename' on \s-1LDAP\s0 nodes.
.PP
It provides the functions get_value, set_value to modify \s-1LDAP\s0 attribute values.
The function add_node, delete_node and rename_node for adding, deleting and
renaming \s-1LDAP\s0 objects.
.SH "SUBROUTINES/METHODS"
.IX Header "SUBROUTINES/METHODS"
The following functions will be exported by CipUX::Storage.
.SS "\s-1BUILD\s0"
.IX Subsection "BUILD"
This is the constructor, see new.
.PP
.Vb 1
\&  use CipUX::Storage;
\&
\&  use base qw(CipUX::Storage);
\&
\&  my $storage = CipUX::Storage\->new();
.Ve
.SS "\s-1DEMOLISH\s0"
.IX Subsection "DEMOLISH"
This is the destructor.
.SS "get_value"
.IX Subsection "get_value"
The get_value queries the \s-1LDAP\s0 and returns one ore more values depending
on the parameter 'scope'.
.PP
\&\fBSyntax:\fR
.PP
.Vb 1
\&  eval {
\&
\&      my $object    = \*(Aqckuelker\*(Aq;
\&      my $attribute = \*(AqcipuxFirstname\*(Aq;
\&      my $type      = \*(Aqall_user_node\*(Aq;
\&      $value_hr = $ldap\->get_value({
\&                                       scope=>\*(Aqone\*(Aq,
\&                                       type=>$type,
\&                                       obj=>$object,
\&                                       attr_ar=>[$attribute]
\&                                      });
\&  } or croak "ERROR: can\*(Aqt get value: $@!" if $@;
.Ve
.PP
returns one value:
.PP
.Vb 5
\&    %$ret_hr = (
\&              \*(Aqckuelker\*(Aq => {
\&                               \*(AqcipuxFirstname\*(Aq => [\*(AqChristian\*(Aq],
\&                            }
\&                );
\&
\&
\&  eval {
\&
\&      my $object    = \*(Aq\*(Aq;
\&      my $attribute = \*(AqcipuxFirstname\*(Aq;
\&      my $type      = \*(Aqall_user_node\*(Aq;
\&      $value_hr = $ldap\->get_value({
\&                                       scope=>\*(Aqall\*(Aq,
\&                                       type=>$type,
\&                                       obj=>$object,
\&                                       attr_ar=>[$attribute]
\&                                      });
\&  } or croak "ERROR: can\*(Aqt get value: $@!" if $@;
\&
\&
\&  %$ret_hr = (
\&              \*(Aqckuelker\*(Aq => {
\&                               \*(AqcipuxFirstname\*(Aq => [\*(AqChristian\*(Aq],
\&                               \*(AqcipuxLastname\*(Aq =>  [\*(AqKuelker\*(Aq],
\&                            },
\&              \*(Aqxoswald\*(Aq => {
\&                               \*(AqcipuxFirstname\*(Aq => [\*(AqXavier\*(Aq],
\&                               \*(AqcipuxLastname\*(Aq =>  [\*(AqOswald\*(Aq],
\&                            },
\&
\&          );
.Ve
.PP
\fIReturn values\fR
.IX Subsection "Return values"
.PP
.Vb 5
\&    %ret = (
\&              \*(Aqckuelker\*(Aq => {
\&                               \*(AqcipuxFirstname\*(Aq => [\*(AqChristian\*(Aq],
\&                               \*(AqcipuxLastname\*(Aq =>  [\*(AqKuelker\*(Aq],
\&                            }
.Ve
.SS "set_value"
.IX Subsection "set_value"
Sets a value for a given object in the \s-1LDAP\s0 database.
.PP
.Vb 8
\& 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:    \*(Aqone|all\*(Aq        set/modify value
\&     escope:   \*(Aqone|all|none\*(Aq   erase scope
\&     type:
.Ve
.PP
\fIModify Syntax\fR
.IX Subsection "Modify Syntax"
.PP
.Vb 12
\&        my $msg = $ldap\->modify( $dn,
\&                                   changes => [
\&                                       # add sn=Baggins
\&                                     add     => [ sn => \*(AqBaggins\*(Aq ],
\&                                       # delete all fax numbers
\&                                     delete  => [ faxNumber => []],
\&                                       # delete phone number 911
\&                                     delete  => [ telephoneNumber => [\*(Aq911\*(Aq]],
\&                                       # change email address
\&                                     replace => [ mail => \*(Aqbilbo@baggins.org\*(Aq]
\&                                   ]
\&                                 );
.Ve
.SS "add_node"
.IX Subsection "add_node"
Adds an \s-1LDAP\s0 node to the \s-1LDAP\s0 database.
.PP
.Vb 1
\& 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 \*(Aqldap_attribute=>value\*(Aq structure
\&
\& $rslt:   is the reslult from Net::LDAP add
.Ve
.SS "delete_node"
.IX Subsection "delete_node"
Deletes an \s-1LDAP\s0 node from the \s-1LDAP\s0 database.
.PP
.Vb 1
\& 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
.Ve
.SS "rename_node"
.IX Subsection "rename_node"
Rename an \s-1LDAP\s0 node of the \s-1LDAP\s0 database.
.PP
.Vb 1
\& 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
.Ve
.SS "_ldap_start"
.IX Subsection "_ldap_start"
Binds to the \s-1LDAP\s0 server.
.PP
.Vb 5
\& my %access        = ();
\& $access_cfg{ident $self}\->{uri}      = \*(Aqldap://localhost\*(Aq;
\& $access_cfg{ident $self}\->{bind_dn}  = \*(Aqcn=admin,dc=nodomain\*(Aq;
\& $access_cfg{ident $self}\->{password} = \*(Aqsecret\*(Aq;
\& my $ldap = $cipux\->_ldap_start();
\&
\& $ldap:   is the LDAP Perl object returned from Net::LDAP.
.Ve
.SS "_ldap_start"
.IX Subsection "_ldap_start"
Unbinds from the \s-1LDAP\s0 server.
.PP
.Vb 1
\& my $msg = $cipux\->_ldap_end( { ldap=>$ldap} );
\&
\& $msg:   is the message returned from Net::LDAP.
.Ve
.SS "list_storage_type"
.IX Subsection "list_storage_type"
Lists all CipUX \s-1LDAP\s0 nodes entities, sorted.
.PP
.Vb 1
\& my $list_ar = $cipux\->list_type( { ldap=>$ldap} );
\&
\& $list_ar:   reference to an array of sorted CipUX LDAP entities.
.Ve
.SS "_ldap_struct"
.IX Subsection "_ldap_struct"
Parses cipux\-storage.perl with for object,
type, filter of a given scope. It also performs some
simple validation of that file.
.PP
.Vb 6
\& my $ldap_structure_hr = $cipux\->_ldap_struct( {
\&     obj=>$obj,
\&     type=>$type,
\&     scope=>$scope,
\&     filter=>$filter
\& });
\&
\& $ldap_structure_hr: returns a structure hash reference
.Ve
.SS "oid_number_supremum"
.IX Subsection "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.
.PP
To perform the search it uses get_value (the storage layer itself).
.SS "get_sid"
.IX Subsection "get_sid"
Retrieve sambaSID and return it if successful
.SH "Configuration files"
.IX Header "Configuration files"
.SS "cipux\-access.ini"
.IX Subsection "cipux-access.ini"
The CipUX access configuration has the following entries:
.PP
.Vb 7
\& [ldap]
\& uri      = ldaps://ldap
\& bind_dn  = cn=cipuxroot,dc=nodomain
\& base_dn  = ou=CipUX,dc=nodomain
\& password = secret
\& system   = debian
\& customer =
.Ve
.SS "cipux_storage.perl"
.IX Subsection "cipux_storage.perl"
The storage structure configuration might look like this:
.PP
.Vb 10
\&    $cfg = {
\&        \*(Aqstructure\*(Aq => {
\&                all_group_node => {
\&                    desc         => \*(Aqaccess to all CN group objects\*(Aq,
\&                    struc_rdn    => \*(Aqou=Group\*(Aq,
\&                    dn_attr      => \*(Aqcn\*(Aq,
\&                    filter       => \*(Aq(cn=?)\*(Aq,
\&                },
\&                all_user_node => {
\&                    desc         => \*(Aqaccess to all system UID objects\*(Aq,
\&                    struc_rdn    => \*(Aqou=User\*(Aq,
\&                    dn_attr      => \*(Aquid\*(Aq,
\&                    filter       => \*(Aq(uid=?)\*(Aq,
\&                },
\&                course_group_node => {
\&                    desc         => \*(Aqaccess to all system GID objects\*(Aq,
\&                    struc_rdn    => \*(Aqou=Group\*(Aq,
\&                    dn_attr      => \*(Aqcn\*(Aq,
\&                    filter       => \*(Aq&(cn=?)(groupType=public)\*(Aq,
\&                },
\&            },
\&}
.Ve
.SH "DIAGNOSTICS"
.IX Header "DIAGNOSTICS"
\&\s-1TODO\s0
.SH "CONFIGURATION AND ENVIRONMENT"
.IX Header "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.
.SH "DEPENDENCIES"
.IX Header "DEPENDENCIES"
.Vb 10
\& Carp
\& Class::Std
\& CipUX
\& Data::Dumper
\& English
\& Net::LDAP
\& Log::Log4perl
\& Readonly
\& utf8
\& version
.Ve
.SH "INCOMPATIBILITIES"
.IX Header "INCOMPATIBILITIES"
Not known.
.SH "BUGS AND LIMITATIONS"
.IX Header "BUGS AND LIMITATIONS"
Not known.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
See the CipUX web page and the manual at <http://www.cipux.org>
.PP
See the mailing list http://sympa.cipworx.org/wws/info/cipux\-devel <http://sympa.cipworx.org/wws/info/cipux-devel>
.SH "AUTHOR"
.IX Header "AUTHOR"
Christian Kuelker  <christian.kuelker@cipworx.org>
.SH "LICENSE AND COPYRIGHT"
.IX Header "LICENSE AND COPYRIGHT"
Copyright (C) 2007 \- 2009 by Christian Kuelker
.PP
This program is free software; you can redistribute it and/or
modify it under the terms of the \s-1GNU\s0 General Public License as
published by the Free Software Foundation; either version 2, or (at
your option) any later version.
.PP
This program is distributed in the hope that it will be useful, but
\&\s-1WITHOUT\s0 \s-1ANY\s0 \s-1WARRANTY\s0; without even the implied warranty of
\&\s-1MERCHANTABILITY\s0 or \s-1FITNESS\s0 \s-1FOR\s0 A \s-1PARTICULAR\s0 \s-1PURPOSE\s0.  See the \s-1GNU\s0
General Public License for more details.
.PP
You should have received a copy of the \s-1GNU\s0 General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 59 Temple Place, Suite 330, Boston, \s-1MA\s0
02111\-1307 \s-1USA\s0