# $Id:
#=============================================================================
# Author:       Dr. Gareth S. Bestor, <bestorga@us.ibm.com>
# Contributors:
# Last Updated: April 28, 2005
# Description:
#    README for SBLIM sample CMPI authorization provider
#=============================================================================

-----------------------------------------------------------------------------
Description
-----------------------------------------------------------------------------
This SBLIM provider package contains a sample CMPI provider that performs
simple authorization checks by looking up authorization information saved in
a file. This information contains the name of a user and a classname, and
then a list of class operations and a flag indicating whether the user is
permitted to perform that operation on that class. e.g.

[darnok CIM_ManagedElement]
   enumerate : true
   get : true
   set : false
   create : false
   delete : false
   query : false
#
[bestorga CIM_OperatingSystem]
   enumerate: true
   get: true
   set: false
   create: false
   delete: false
   query: true

This provider is intended to serve as an example for how to write a CMPI
provider that exposes system data stored in a data file; it is NOT intended
for production use.

This provider instruments the following classes:
	CWS_Authorization:
		string Username		Name of user
		string Classname	Target classname
		boolean Enumerate	Enumeration permission (default=true)
		boolean Get		Get permission (default=true)
		boolean Set		Set permission (default=false)
		boolean Create		Create permission (default=false)
		boolean Delete		Delete permission (default=false)
		boolean Query		Query permission (default=true)

In addition, this provider supports one method:
	boolean IsAuthorized(string operation)
where
	operations = "Enumerate" | "Get" | "Set" | "Create" | "Delete" | "Query".
This method returns TRUE (1) or FALSE (0) if the user is/not authorized to
perform the desired operation on the class.
 

-----------------------------------------------------------------------------
File Description
-----------------------------------------------------------------------------
Files that will need to be changed when writing a new provider are:
	README					This file!
	configure.ac				Autoconf configuration input file
	Makefile.am				Makefile template containing build rules and targets
	sblim-cmpi-authorization.spec.in	RPM spec file template
	CWS_Authorization.c			Provider source code
	CWS_AuthorizationLexer.l		Data file parser (lex scanner input)
	CWS_AuthorizationParser.y		Data file parser (yacc grammar input)
	Enumeration.c				Functions to read/write/enumerate instances
	cmpiutil.c				CMPI utility functions
	authorization.sample			Sample authorization file
	schema/CWS_Authorization.mof		Provider class definition(s)
	schema/CWS_Authorization.registration	CIMOM registration info
	test/*					SBLIM Testsuite data files
	doc/*					Custom documentation (if any)

Please check each of these files for comments of how to change/adapt them
for writing new providers.

Files that do not need to be modified are:
	autoconfiscate.sh	Script to setup autoconf environment
	acinclude.m4		Autoconf macros to check for CMPI specific requirements
	provider-register.sh	Script to auto-register provider to various CIMOMs
	COPYING			CPL license
	NEWS			Optional
	AUTHORS			Optional
	CHANGELOG		Optional
	README.TEST		Instructions for how to test SBLIM providers
	README.RPM		Instructions for how to build SBLIM provider RPMs
	README.DEBUG		Instructions for how to debug SBLIM providers


-----------------------------------------------------------------------------
Prerequisites
-----------------------------------------------------------------------------
Build-Time:
- Linux or similar environment supported by autoconf-generated configure script
- CMPI Header files. Either the ones coming with a CIM server or a standalone
  development package like the following
  http://prdownloads.sourceforge.net/sblim/sblim-cmpi-devel-0.9.0.tar.bz2
                                                                                
Run-Time:
- Linux or similar environment (supporting the file system operations)
- A CIM Server supporting CMPI providers.


-----------------------------------------------------------------------------
Building SBLIM Provider
-----------------------------------------------------------------------------
This provider is fully integrated into the SBLIM autoconfiguration process,
meaning that minimal, if any, customization is necessary to get it to build,
compile and install on different Unix systems and different CIMOMs. At least
that is the hope....

This SBLIM provider package follows the standard build procedure for building
SBLIM packages. To perform a local build and install of this SBLIM provider
package do the following:
        cvs -z3 -d:pserver:anonymous:@cvs.sourceforge.net:/cvsroot/sblim -q co -P sblim-cmpi-authorization
        cd cmpi-authorization
        ./autoconfiscate.sh
        ./configure
        ./make

The generated configure script tries to determine where the CMPI header files
are located. For this purpose it searches a set of well-known locations.
The "canonical" location is /usr/include/cmpi or /usr/local/include/cmpi,
depending on how configure is invoked.
                                                                                                                  
Further, configure "determines" where providers are to be installed. Actually,
there's no detection logic. The provider directory will always be
/usr/lib/cmpi or /usr/local/lib/cmpi. If a CIM server requires a particular
directory this can be selected by specifying the PROVIDERDIR variable.
                                                                                                                  
And finally, configure tries to find out which CIM server type is being used.
This is necessary in order to select the appropriate schema and provider
registration technique. If the CIM server is not or incorrectly identified,
it is possible to specify it via the CIMSERVER variable.
Supported values are pegasus, sfcb, openwbem and sniacimom.
                                                                                                                  
For instance, in order to configure for a locally installed Pegasus you can
issue the following command:
./configure CIMSERVER=pegasus PROVIDERDIR=$PEGASUS_HOME/provider \
     --libdir=$PEGASUS_HOME/lib

Alternatively, instead of building and installing this provider locally, you
can also build and install an RPM package. See README.RPM for instructions on
how to build and install RPMs for SBLIM packages.


-----------------------------------------------------------------------------
Installing SBLIM Provider
-----------------------------------------------------------------------------
You must be root to install this SBLIM provider and run the required
postinstall steps to register the new provider to the existing CIMOM.

        su -c 'make install && make postinstall'


-----------------------------------------------------------------------------
Running SBLIM Provider Tests
-----------------------------------------------------------------------------
There is a sample authorization file included in this package containing
examples of authorization entries. Copy this file to
	/tmp/authorization

and then you can run CIM operations against the class.

TODO: SBLIM TEstsuite tests

