#!/usr/bin/perl -w -T
# +=========================================================================+
# || cipux_rbac_client                                                     ||
# ||                                                                       ||
# || Example client for command line interface for CipUX RBAC class.       ||
# ||                                                                       ||
# ||                                                                       ||
# ||                                                                       ||
# ||                                                                       ||
# || (C) Copyright 2008 by Christian Kuelker. All rights reserved!         ||
# ||                                                                       ||
# || License: GPLv2 or later                                               ||
# ||                                                                       ||
# +=========================================================================+
#
# ID:       $Id$
# Revision: $Revision$
# Head URL: $HeadURL$
# Date:     $Date$
# Source:   $Source$

package cipux_rbac_client;

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

# +=============================================================================+
# || MAIN                                                                      ||
# +=============================================================================+
my $client = CipUX::RBAC::Client->new();

$client->run( { name => 'cipux_rbac_client' } );

exit 0;

=pod

=head1 NAME

Command line interface to CipUX RBAC 

=head1 VERSION

3.4.0

=head1 SYNOPSIS

 (1) Version:
     cipux_rbac_client -V

 (2) Help (will you gove more information):
     cipux_rbac_client --help|-h

 (3) List RBAC scopes:
     cipux_rbac_client [OPT] --list|-l

 (4) Check access, reading ACL data from the database: 
     cipux_rbac_client [OPT] --[rpc|task] -a -s <SCOPE> -f <OBJ> -t <OBJ>

     Check access, reading ACL all data from a XML file:
     cipux_rbac_client [OPT] --[rpc|task] -a -s <SCOPE> -r <FILE>
  
     Check access, reading ACL data from object to object from a XML file:
     cipux_rbac_client [OPT] --[rpc|task] -a -s <SCOPE> -f <OBJ> -t <OBJ> -r <FILE>

 (5) Reading all data from database and write ACL XML file: 
     cipux_rbac_client [OPT] --[rpc|task] -s <SCOPE> -w <FILE>

     Reading data from object to object and write XML file:
     cipux_rbac_client [OPT] --[rpc|task] -s <SCOPE> -f <OBJ> -t <OBJ> -w <FILE>

     Reading all data from database and write dot file:
     cipux_rbac_client [OPT] --[rpc|task] -s <SCOPE> -d <FILE>

     Reading all data from XML file and write to dot file:
     cipux_rbac_client [OPT] --[rpc|task] -s <SCOPE> -r <FILE> -d <FILE>

 abbreviations: OBJ = OBJECT, OPT = OPTIONS (see section)

=head1 OPTIONS

        Options [OPT] for all commands:

        -c | --cfg             : cipux-rbac.conf
        -D | --debug [<LEVEL>] : print debug messages for developers
             --verbose         : print more messages

        Most important options: 

        -h | --help            : print help (this message + options)
	-V                     : prints version     

        Brief explanation:

        -a | --access         : read access
	-d | --write_dot      : writes graph to dot file
	-f | --from           : from obejct, as starting point
        -l | --list           : lists configuration scopes, 
	                        can be used for --scope
	     --rpc            : use RPC call to get access info			
        -s | --scope          : CipUX::RBAC command
	     --task           : use CipUX task to get access info
	-t | --to             : to obejct, as ending point
	-r | --read_xml       : read graph from XML file
	-w | --write_xml      : writes graph to XML file


=head1 REQUIRED ARGUMENTS

TODO

=head1 ARGUMENTS

=over 4

=item B<-a>

Same as option --access.

=item B<--access>

Test the access --from an object --to an other object against the ACL database.
If no --read_xml is given the LDAP server will be queried. If the option
--pretty is given the answer will be "NO" or "YES" otherwise it will be exit
code 0 for success and 1 for failure and 255 for program exception. If --pretty
is given, then also --write-[xml|dot] maybe specified to write the database to
the file system. The --write-[xml|dot] can be used without --access. The
--access option has no influence on the content of --write-[xml|dot} operation.

=item B<-c>

Same as option --cfg.

=item B<--cfg>

To specify the configuration file, if any. The default location for the
configuration file is:

 (1) ~/.cipux/cipux-rbac.conf

or

 (2) /etc/cipux/cipux-rbac.conf

If you do not like to use the default location you may specify an other
configuration file by providing the --cfg option.

=item B<-d>

Same as option --write_dot.

=item B<-D>

Same as option --debug.

=item B<--debug>

To see more output, what the internals are doing, you can enable the --debug
and see more message printed to STDOUT.

=item B<-h>

Same as option --help

=item B<--help>

Prints brief help message.

=item B<-l>

Same as option --list

=item B<--list>

Lists all rbac scopes. The rbac scopes are red from the configuration file.
(See --cfg option for details.) The output from the --list option can be used
to feed the --scope option. But only one rbac scope name is needed for the
--scope option.

=item B<-p>

Same as option --pretty.

=item B<--pretty>

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

=item B<-s>

Same as option --scope.

=item B<--scope>

This option defines the "rbac scope name" the cipux_rbac_client is operating
on. A "rbac scope name" is a certain range inside the CipUX RBAC Class. For
example "task" is a valid "rbac scope name". The rbac scope name is the target
or teh RBAC request.  Whereas the UID (user ID or login) is the source. You can
easily define new rbacs scopes in the configuration file. For more information
about configuration files see --cfg option.  /etc/cipux/cipux-rbac.conf.

=item B<-V>

Same as option --version.

=item B<--version>

Prints the version and exits.

=item B<--verbose>

Not implemented jet.

=item B<-v>

Same as option --verbose.

=item B<-w>

Same as option --write_xml.

=item B<--write_dot>

Writes the ACL database to an dot file. This can be used by dotty and other
tools to display the ACL as a directed graph.

=item B<--write_xml>

Writes the ACL database to an XML file.


=back


=head1 USAGE

 cipux_rbac_client

 TODO

=head1 DESCRIPTION

The cipux_rbac_client is an example implementation for a client program to
make use of CipUX::RBAC module. This client can be used for 

 (1) list RBAC scopes
 (2) reading ACL data from the database (LDAP, file)
 (3) writing ACL data to the file system
 (4) converting ACL data from LDAP to XML|dot and from XML to dot
 (5) query data for access 

=head2 cipux_rbac_client

Executes a given CipUX rbac.

=head2 _list_rbac

Prints a list of CipUX RBAC Library command names to STDOUT. No object will be
changed.  This is useful if (1) you would like to see what kind of rbac this
the CipUX RBAC Library can handle and (2) if you would like to test the default
or an other rbac library configuration file. You can use this with all other
options, they will be ignored except -p | -pretty or -D | --debug.

=head1 EXAMPLES

(1)

 cipux_rbac_client  -lp
 +------+
 | rbac |
 +======+
 | cat  |
 | task |
 +------+

(2)

 cipux_rbac_client  -l
 cat
 task

(3) realtime query access test

 cipux_rbac_client  -pa -s cat -f frodo -t teacher.cgi
 NO

(4) realtime query access test

 cipux_rbac_client  -pa -s cat -f bilbo -t teacher.cgi
 YES

(5) storing ACL to file

 cipux_rbac_client  -s task --write_xml rbac.xml

(6) using stored ACL data for access test

 cipux_rbac_client  -pa -s task -f frodo -t teacher.cgi --read_xml rbac.xml
 NO

(7) writing graphical representation for ACL from realtime query

 cipux_rbac_client  -s task --write_dot rbac.dot

(8) writing graphical representation for ACL from XML file

 cipux_rbac_client  -s task --read_xml rbac.xml --write_dot rbac.dot

=head1 DIAGNOSTICS

TODO

=head1 EXIT STATUS

TODO

=head1 CONFIGURATION

/etc/cipux/cipux-rbac.conf

TODO

=head1 DEPENDENCIES

Carp
CipUX
CipUX::RBAC
Getopt::Long
Pod::Usage
List::MoreUtils
Fatal
English
version

=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://www.cipux.org/mailman/listinfo/>

=head1 AUTHOR

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

=head1 LICENSE AND COPYRIGHT 

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

