Provided by: cipux-storage-tools_3.4.0.2-6_all bug

NAME

       cipux_storage_client - Command line interface to CipUX storage abstraction layer

VERSION

       version 3.4.0.2

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

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

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>

DESCRIPTION OF OPTIONS

       -a  Same as option --add.

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

       --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>

       -D  Same as option --debug.

       -d  Same as option --del.

       --del
           This deletes the attribute from the object where possible.

       -e  Same as option --erase

       --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.

       -h  Same as option --help

       --help
           Prints brief help message.

       --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.

       -o  Same as option --object

       --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.

       -p  Same as option --pretty.

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

       -r  Same as option --replace.

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

       -s  Same as option --storage_type.

       --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

       --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.

       -t  Same as --storage_task.

       -V  Same as option --version.

       --version
           Prints the version and exits.

       --verbose
           Not implemented jet.

       -l  Same as option --list

       --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.

       -v  Same as option --verbose.

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

       -x  Same as option --mattrvalue.

       -y  Same as option --attrvalue.

DESCRIPTION

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

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

   cipux_storage_client -t get_value
       Retrieve one or more LDAP values for every given attribute of a given object.

   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.

   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.

   cipux_storage_client -t set_all_values
       Set all LDAP values of a given object and attribute.

   cipux_storage_client -t add_node
       Adds an LDAP node.

       SYNOPIS

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

       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.

   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.

   cipux_storage_client -t delete_node
       Deletes a given LDAP node.

DIAGNOSTICS

       TODO

EXIT STATUS

       TODO

CONFIGURATION

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

DEPENDENCIES

       CipUX::Storage::Client

INCOMPATIBILITIES

       Not known.

BUGS AND LIMITATIONS

       Not known.

SEE ALSO

       See the CipUX webpage 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) 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