cipux-storage-tools 3.4.0.2-6 / usr / bin / cipux_storage_client

#!/usr/bin/perl -w -T

eval 'exec /usr/bin/perl -w -T -S $0 ${1+"$@"}'
    if 0; # not running under some shell
# +=======================================================================+
# || cipux_storage_client                                                ||
# ||                                                                     ||
# || Command line interface for CipUX Storage abstraction layer.         ||
# ||                                                                     ||
# || Copyright (C) 2008 - 2009 by Christian Kuelker.                     ||
# ||                                                                     ||
# || GNU GPL version 2 or any later version.                             ||
# ||                                                                     ||
# +=======================================================================+
#  ID:       $Id$
#  Revision: $Revision$
#  Head URL: $HeadURL$
#  Date:     $Date$
#  Source:   $Source$

package cipux_storage_client; ## no critic (Capitalization)

use 5.008001;
use strict;
use warnings;
use CipUX::Storage::Client;
use version; our $VERSION = qv('3.4.0.2');
delete @ENV{qw(PATH IFS CDPATH ENV BASH_ENV)};    # Make %ENV safer

# +=============================================================================+
# || MAIN                                                                      ||
# +=============================================================================+
my $client = CipUX::Storage::Client->new( { name => 'cipux_storage_client' } );

$client->run();

exit 0;

__END__


=pod

=head1 NAME

cipux_storage_client - Command line interface to CipUX storage abstraction layer

=head1 VERSION

version 3.4.0.2

=head1 USAGE

 (1) cipux_storage_client -h
 (2) cipux_storage_client [OPT] -t get_value      -s <TYPE> -o <OBJ> -y <ATTR> [-y <ATTR>]
 (3) cipux_storage_client [OPT] -t get_all_values -s <TYPE>          -y <ATTR> [-y <ATTR>]
 (4) cipux_storage_client [OPT] -t set_value [-r] -s <TYPE> -o <OBJ> -y <ATTR> -v <VAL>
     cipux_storage_client [OPT] -t set_value  -a  -s <TYPE> -o <OBJ> -y <ATTR> -v <VAL>
     cipux_storage_client [OPT] -t set_value [-r] -s <TYPE> -o <OBJ> -y <ATTR=VAL> [-y <ATTR=VAL>]
     cipux_storage_client [OPT] -t set_value  -a  -s <TYPE> -o <OBJ> -y <ATTR=VAL> [-y <ATTR=VAL>]
     cipux_storage_client [OPT] -t set_value  -d  -s <TYPE> -o <OBJ> -y <ATTR> [-y <ATTR>]
     cipux_storage_client [OPT] -t set_value  -e  -s <TYPE> -o <OBJ> -y <ATTR>
 (5) cipux_storage_client [OPT] -t set_all_values [-r] -s <TYPE> -y <ATTR> -v <VAL>
     cipux_storage_client [OPT] -t set_all_values  -a  -s <TYPE> -y <ATTR> -v <VAL>
     cipux_storage_client [OPT] -t set_all_values [-r] -s <TYPE> -y <ATTR=VAL> [-y <ATTR=VAL>]
     cipux_storage_client [OPT] -t set_all_values  -a  -s <TYPE> -y <ATTR=VAL> [-y <ATTR=VAL>]
     cipux_storage_client [OPT] -t set_all_values  -d  -s <TYPE> -y <ATTR> [-y <ATTR>]
 (6) cipux_storage_client [OPT] -t add_node -s <TYPE> -o <OBJ> -x <ATTR=VAL> [-x <ATTR=VAL>]
 (7) cipux_storage_client [OPT] -t delete_node -s <TYPE> -o <OBJ>
 (8) cipux_storage_client [OPT] -t rename_node -s <TYPE> -o <OBJ> -v <VAL>
 abbreviations: OBJ = OBJECT, ATTR = ATTRIBUTE, VAL = VALUE, OPT = OPTIONS

=head1 OPTIONS

        Options for all commands:

        -c | --cfg             : cipux-storage-access.conf
        -D | --debug [<LEVEL>] : print debug messages for developers
        -h | --help            : print help (this message + options)
        -p | --pretty          : nice boxed output
        -V | --version         : print only version
             --verbose         : print more messages

        Options for some commands:

        -a | --add            : rather add then replace a value
        -d | --del            : delete the value of the attribute
        -e | --erase          : delete the attribute
        -l | --list           : lists configuration scopes, can be used for --type
        -o | --object         : LDAP object leaf
        -r | --replace        : replace a value, default behaviour
        -s | --storage_type   : configuration type
        -t | --storage_task   : action to perform
        -v | --value          : value to be set
        -x | --mattrvalue     : multiple LDAP attributes, please see description
        -y | --attrvalue      : LDAP attribute, please see description

=head1 REQUIRED ARGUMENTS

cipux_storage_client

  -t or -h

cipux_storage_client -t get_value

 -s <TYPE>
 -o <OBJ>
 -y <ATTR>

cipux_storage_client -t get_all_values

 -s <TYPE>
 -y <ATTR>

cipux_storage_client -t set_value

 -s <TYPE>
 -o <OBJ>
 -y <ATTR>

cipux_storage_client -t set_all_values

 -s <TYPE>
 -y <ATTR>
 -v <VAL>

cipux_storage_client -t add_node

 -s <TYPE>
 -o <OBJ>
 -x <ATTR=VAL>

cipux_storage_client -t delete_node

 -s <TYPE>
 -o <OBJ>

cipux_storage_client -t rename_node

 -s <TYPE>
 -o <OBJ>
 -v <VAL>


=head1 DESCRIPTION OF OPTIONS

=over 4

=item I<-a>

Same as option --add.

=item I<--add>

This adds a value where possible rather then replace a value.

=item I<--attrvalue>

This can be used to specify the attribute by

 --attrvalue <ATTRIBUTE>

Or it can be used to specify the attribute and the value

 --attrvalue <ATTRIBUTE>=<VALUE>

Of course it can also be use together with --value option
to specify the attribute and the value like this:

 --attrvalue <ATTRIBUTE> --value <VALUE>

=item I<-D>

Same as option --debug.

=item I<-d>

Same as option --del.

=item I<--del>

This deletes the attribute from the object where possible.

=item I<-e>

Same as option --erase

=item I<--erase>

Deletes the LDAP attribute of a given object. This will delete also all content
of this attribute. If the an object has multible values for that attribute all
values will be removed. If this is option is set, it will trigger --delete
command line option automatically.

=item I<-h>

Same as option --help

=item I<--help>

Prints brief help message.

=item I<--mattrvalue>

This is option have to be use if a LDAP object has to be created. Unlike
--attrvalue this option requires always an attribute and a value. Therefore
only this syntax is possible:

  --mattrvalue <ATTRIBUTE>=<VALUE>

The reason for this is to be able to gave the user exact hints when he try to
create a object but forget the value.

The 'm' stands for multiple. So it is possible to give the option several
times.

=item I<-o>

Same as option --object

=item I<--object>

This option is used to specify the object on which the command is operating.
Make sure you choose the right object. Of course this will also fail when the
object is not fetchable with (in the objects list of) --storage_type.

=item I<-p>

Same as option --pretty.

=item I<--pretty>

On command which produce an output, this option can be used to draw a fancy box
around the output.

=item I<-r>

Same as option --replace.

=item I<--replace>

For some command this is the default option. It replace the value of a given
attribute with a new value.

=item I<-s>

Same as option --storage_type.

=item I<--storage_task>

Name fo the action that can be performed. Valid actions are:

 get_all_values
 set_all_values
 add_node
 get_value
 set_value
 list
 delete_node
 rename_node

=item I<--storage_type>

This option defines the 'type of the object' the command is operating with. A
'type of object' is a certain set of objects with common attributes. For
example all POSIX account objects. You can easily define new types of objects
in the configuration file. The default location of this file is
/etc/cipux/cipux-storage-structure.conf.

=item I<-t>

Same as --storage_task.

=item I<-V>

Same as option --version.

=item I<--version>

Prints the version and exits.

=item I<--verbose>

Not implemented jet.

=item I<-l>

Same as option --list

=item I<--list>

Lists all object scopes. The object scopes are red from the configuration file.
The default location of the configuration file is
/usr/share/cipux/etc/cipux-storage.perl. One object type is needed for the
--storage_type option.

=item I<-v>

Same as option --verbose.

=item I<--value>

On some commands this is use to provide a value for an object or an attribute.

=item I<-x>

Same as option --mattrvalue.

=item I<-y>

Same as option --attrvalue.

=back

=head1 DESCRIPTION

This is the command line client for CipUX::Storage. It can be used to get
modify or delete CipUX storage objects.


=head1 COMMANDS

  cipux_storage_client -t get_value
  cipux_storage_client -t set_value
  cipux_storage_client -t get_all_values
  cipux_storage_client -t set_all_values
  cipux_storage_client -t add_node
  cipux_storage_client -t rename_node
  cipux_storage_client -t delete_node

=head2 cipux_storage_client -t get_value

Retrieve one or more LDAP values for every given attribute of a given object.

=head2 cipux_storage_client -t get_all_values

Retrieve one or more LDAP values for every given attribute of all objects in a
given object type.

=head2 cipux_storage_client -t set_value

(1) You can add values with cipux_storage_client -t set_value.

 cipux_storage_client -t set_value -s all_group_node -e memberUid -o testgroup -v login -a

But this make only a difference for LDAP attributes which can be there more
then one time.

  cipux_storage_client -t set_value -s all_group_node -e memberUid -o testgroup -v login1 -a
  cipux_storage_client -t set_value -s all_group_node -e memberUid -o testgroup -v login2 -a

This will result:

   memberUid: login1
   memberUid: login2

Where as the following lines have a different result:

 cipux_storage_client -t set_value -s all_group_node -e groupType -o testgruppe -v public -a

The resulting exception:

  attribute 'groupType' cannot have multiple values at ./cipux_storage_client -t set_value line 369

In this case you have to remove the -a option from your line or use -r.


(2) The default behavior is to replace values. Values can be replaces with:


 cipux_storage_client -t set_value -s all_group_node -e groupType -o testgruppe -v private

or

 cipux_storage_client -t set_value -s all_group_node -e groupType -o testgruppe -v private -r


This will replace the existing value with the new one.

But be aware (!), if you have 3 members in a group, for example:

   memberUid: login1
   memberUid: login2
   memberUid: login3

after command the command:

 cipux_storage_client -t set_value -s all_group_node -e memberUid -o testgroup -v login4

you will have only one member!

   memberUid: login4

Therefor the default behavior is to replace all but one value. The replace and
not the add is the default behavior, because it there are more single
attributes in LDAP and therefor the probability of failure will be less if
replace is the default behavior.

(3) Also LDAP attributes can be deleted. If you have 2 memberUid's for example
the delete operation will led to an exception:

 modify/delete: memberUid: no such value at ./cipux_storage_client -t set_value line 369

So to delete all (!) member you have to do two LDAP operations:

 cipux_storage_client -t set_value -s all_group_node -e memberUid -o testgroup -v login -r
 cipux_storage_client -t set_value -s all_group_node -e memberUid -o testgroup -v login -d

Where as the value from -v is not important.

=head2 cipux_storage_client -t set_all_values

Set all LDAP values of a given object and attribute.

=head2 cipux_storage_client -t add_node

Adds an LDAP node.

=head3 SYNOPIS

 cipux_storage_client -t add_node -s <TYPE> -o <NAME> -x <ATTR>=<VALUE> [-x <ATTR>=<VALUE> ...]

=head3 Usage example

 cipux_storage_client -t add_node -s cipux_room -o test1 -x objectClass=room -x objectClass=cipuxRoom -x cn=test1

If you do not provide cn=NAME for example, you will get the following exception:

 EXCEPTION mandatory attr [cn] is missing!
           Please provide -x or --mattrvalue command line option!
           Example: -x cn=<VALUE>

To add a user node (not a complete user account!) this will create a half
user account named testuser:

 cipux_storage_client -t add_node -s cipux_account.user -o testuser -x cipuxFirstname=test -x cipuxLastname=user -x objectClass=cipuxAccount -x objectClass=posixAccount -x objectClass=shadowAccount -x uid=testuser -x cn=testuser -x cipuxCreationDate=2007-10-26 -x uidNumber=20000 -x gidNumber=20000 -x homeDirectory=/home/testuser -x objectClass=imapUser -x mailMessageStore=/tmp -D 129

Of course this is just an example. It is not a good idea to give /tmp as mail
storage directory or use a static uidNumber. But this or a similar command can
be user to test the LDAP layer.

=head2 cipux_storage_client -t rename_node

The rename command sets upon the Net::LDAP command modrdn. And due to the fact
that simply rename a LDAP dn is not hole task of renaming an LDAP leaf the
command can rename only certain LDAP objects.

It can for example rename a cipuxConfiguration LDAP leaf. Before renaming it
looks basically like this:

 dn: cn=testconfig,ou=Configuration,ou=CipUX,dc=nodomain
 cipuxVariable: testvalue
 cn: testconfig
 objectClass: top
 objectClass: cipuxConfiguration

If you now issue the command:

 cipux_storage_client -t rename_node -s cipux_configuration -o testconfig -v myconfig

You will get

 dn: cn=myconfig,ou=Configuration,ou=CipUX,dc=nodomain
 cipuxVariable: testvalue
 cn: testconfig
 cn: myconfig
 objectClass: top
 objectClass: cipuxConfiguration

You noticed the 'cn' has doubled, since LDAP expect a corresponding 'cn' in
this LDAP object? There for this configuration has now two names. It should be
difficult to crate now a new 'testconfig'. You have to delete 'cn: testconfig'
attribute and value before you can create a new 'testconfig'.  Because this is
rather confusing, you should avoid renaming where possible.  Deleting an object
and recreate it is a safer way.


=head2 cipux_storage_client -t delete_node

Deletes a given LDAP node.

=head1 DIAGNOSTICS

TODO

=head1 EXIT STATUS

TODO

=head1 CONFIGURATION


 /usr/share/cipux/etc/cipux_storage.perl

=head1 DEPENDENCIES

CipUX::Storage::Client

=head1 INCOMPATIBILITIES

Not known.

=head1 BUGS AND LIMITATIONS

Not known.

=head1 SEE ALSO

See the CipUX webpage and the manual at L<http://www.cipux.org>

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

=head1 AUTHOR

Christian Kuelker  E<lt>christian.kuelker@cipworx.orgE<gt>

=head1 LICENSE AND COPYRIGHT

Copyright (C) 2008 - 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

=cut