Pegasus Enhancement Proposal (PEP)
PEP #: 257
PEP Type: Functional
Title: Indication Subscription Management
Version: 1.3
Created: 23rd April 2012
Author: Ajay N Rao
Status: Draft
Version History:
Version | Date | Author | Change Description |
---|---|---|---|
1.0 | 5 June 2006 | Carol Ann Krug Graves | Initial Submittal |
1.1 | 14 June 2006 | Carol Ann Krug Graves | Updates based on version 1.0 comments (Updates in Purple) |
1.2 | 15 June 2006 | Carol Ann Krug Graves | Clarify namespace option precedence (Updates in Maroon) |
1.3 |
12
April 2012 |
Ajay N
Rao |
Added for two features of
creation of Filter, Handler, Subscription and Batch
file Execution.(Updates
in blue) |
Abstract:
A command line utility is proposed to provide a command line
interface to manage CIM indication subscriptions on the local CIM
Server. The new command would support enabling, disabling,
Creating, or removing a subscription, display of selected
subscription information, as
well as Creation, removal and display of filters and
handlers.The Command would
also Support the execution of these commands in the Batch file.
Currently, there is no convenient way to query which indication subscriptions exist on the CIM Server, nor to Create or remove a subscription, filter or handler. There is no convenient way to query the SubscriptionState, to see which subscriptions are active, nor to modify the SubscriptionState, in order to enable or disable a subscription. A utility is needed to assist in managing indication subscriptions, filters, and handlers.
The cimsub command line utility is proposed to provide a command line interface to manage CIM indication subscriptions on the local CIM Server. The cimsub command line interface is proposed as an external interface, to be managed for compatibility across releases, and added to the Command Line Interfaces section of the OpenPegasus 2.6 External Interface Definition PEP.
Proposed cimsub man page:
cimsub - manage CIM indication subscriptions
cimsub -l s|f|h [-v] [-n namespace]
[-F [fnamespace:]filtername]
[-H [hnamespace:][hclassname.]handlername]
cimsub -e [-n namespace] -F [fnamespace:]filtername
-H [hnamespace:][hclassname.]handlername
cimsub -d [-n namespace] -F [fnamespace:]filtername
-H [hnamespace:][hclassname.]handlername
cimsub
-c f [fnamespace:]filtername -Q query [-L querylanguage] [-N
sourcenamespace]
cimsub -c h
[hnamespace:][hclassname.]handlername [-D destination]|
[-T mailto [-C mailcc] -S mailsubject]|
[-T snmptargethost [-P snmpportnumber] -V
snmpversion] [-S snmpsecurityname] [-E snmpengineid]]
cimsub -c s [-n
namespace] -F [fnamespace:]filtername -H
[hnamespace:][hclassname.]handlername
cimsub -r s|f|h|a [-n namespace] [-F
[fnamespace:]filtername] [-H
[hnamespace:][hclassname.]handlername]
cimsub -b batchfile [-n namespace]
cimsub --help
cimsub --version
The cimsub
command provides a command line
interface to manage CIM indication subscriptions on the local CIM
Server.
The first form of the cimsub
command lists
all or selected indication subscriptions, filters, or handlers,
and displays the requested information about the instance(s).
The second form of the cimsub
command
enables the specified subscription, i.e. the subscription instance
is modified to set the value of the SubscriptionState property to
Enabled. When a subscription is enabled, the CIM Server attempts
to process the subscription if at least one provider is available
to serve the subscription.
The third form of the cimsub
command
disables the specified subscription, i.e. the subscription
instance is modified to set the value of the SubscriptionState
property to Disabled. When a subscription is disabled, the CIM
Server does not attempt to process the subscription, regardless of
whether any providers are available to serve the subscription.
The fourth form of the cimsub
command
removes the specified subscription, filter, handler, or
subscription and its referenced filter and handler, i.e. each
instance is deleted from the repository, and the CIM Server will
no longer have any information about the instance(s). A filter or
handler may not be removed if it is referenced by any other
subscription.
The fifth form of the cimsub
command creates the specified Subscription, filter, or handler.
i.e each instance is created into the repository and CIM Server
will get the new information about the created Instance(s).
The sixth form of the cimsub
command executes the batch file
of cimsub commands.
The cimsub
command recognizes the following
options:
-c
Create specified
subscription, filter,
handler(CIM_ListenerDestinationCIMXML,
if not specified hclassname).
-l
-F
option with -lh
.
It is an error to specify the -H
option with -lf
.
With the -lf
or -lh
option, fnamespace or hnamespace takes
precedence over the -n namespace
option
if both are specified. -e
-d
-r
-F
and -H
options are required with -rs
or -ra
. It is an error to specify the -F
option with -rh
. It is an error to specify the -H
option with -rf
. With the -rf
or -rh
option, fnamespace or hnamespace
takes precedence over the -n namespace
option if both are specified. -b
Executes the batch file of cimsub commands.
-v
-l
forms of the
command, if no namespace is specified, instances in all
namespaces are listed. For all other forms of the command, if no
namespace is specified, the command operates on an instance in
the namespace root/PG_InterOp. -F [fnamespace:]filtername
-H [hnamespace:][hclassname.]handlername
L
N
-D
Specify Destination of a
CIM_IndicationHandlerCIMXML Handler. Required option for
CIM_IndicationHandlerCIMXML or CIM_ListenerDestinationCIMXML
Handler.
-M
Specify Mailto of a
PG_ListenerDestinationEmail Handler.
C
S
T
U
P
V
E
--help
--version
When an error occurs, an error message is written to stderr, and an error value is returned. The following values are returned:
0 | Success |
1 | General error |
2 | Connection failed |
3 | Connection timed out |
4 | Access was denied |
5 | Namespace does not exist |
6 | Object could not be found |
7 | Operation is not supported |
The cimsub
command requires the cimserver
to be running.
If the enableSubscriptionsForNonprivilegedUsers configuration property is set to false, only a privileged user may list, enable, disable, or remove a subscription, filter, or handler. If the enableSubscriptionsForNonprivilegedUsers configuration property is set to true, only a privileged user or the instance creator may enable, disable, or remove a subscription, filter or handler.
Caution should be used when specifying
the -r
option, since subscriptions, filters or
handlers removed may not be easily re-created, and may not be
re-created using this command.
List all indication subscriptions in all namespaces on the local CIM Server:
cimsub -ls
List all indication subscriptions referencing the Filter with Name 'TestFilter' in all namespaces on the local CIM Server:
cimsub -ls -F TestFilter
List all indication subscriptions referencing the CIM_ListenerDestinationCIMXML Handler with Name 'TestHandler' in all namespaces on the local CIM Server:
cimsub -ls -H TestHandler
List all indication subscriptions in the root/cimv2 namespace on the local CIM Server, including subscription state, filter query and handler destination (verbose listing output):
cimsub -ls -v -n root/cimv2
Display information about the subscription referencing Filter with Name 'TestFilter' and referencing CIM_ListenerDestinationCIMXML Handler with Name 'TestHandler' (all in namespace root/PG_InterOp), including subscription state, filter query and handler destination (verbose listing output):
cimsub -ls -v -n root/PG_InterOp -F TestFilter -H
TestHandler
Display information about the Filter with Name 'TestFilter' in the root/cimv2 namespace (verbose listing output):
cimsub -lf -v -F root/cimv2:TestFilter
List all handlers in all namespaces on the local CIM Server:
cimsub -lh
Enable the subscription referencing Filter with Name 'TestFilter' and referencing CIM_ListenerDestinationCIMXML Handler with Name 'TestHandler' (all in namespace root/PG_InterOp):
cimsub -e -F TestFilter -H TestHandler
Disable the subscription in namespace root/cimv2, referencing Filter with Name 'TestFilter' in namespace test1/cimv2, and referencing PG_ListenerDestinationSystemLog Handler with Name 'TestHandler' in namespace test2/cimv2:
cimsub -d -n root/cimv2 -F test1/cimv2:TestFilter -H
test2/cimv2:PG_ListenerDestinationSystemLog.TestHandler
Remove the subscription referencing Filter with Name 'TestFilter', and referencing CIM_ListenerDestinationCIMXML Handler with Name 'TestHandler' (all in namespace root/cimv2), also removing the filter and handler instances (if not referenced by any other subscription):
cimsub -ra -n root/cimv2 -F TestFilter -H TestHandler
Create filter with Name 'filteraa' with the Query 'select * from IndicationStressTestClass' with SourceNamespaces test/TestProvider and test/testIndSrcNS1.
cimsub -c f filteraa -Q "select * from IndicationStressTestClass" -N test/TestProvider,test/testIndSrcNS1
Create handler with Name 'handler01' and Destination '/Pegasus_IndicationStressTestConsumer'.
cimsub -c h handler01 -D /Pegasus_IndicationStressTestConsumer
Create Subscription with referencing Filter with Name 'TestFilter', and referencing CIM_ListenerDestinationCIMXML Handler with Name 'TestHandler'
cimsub -c s -F filteraa -H handler01
Execute the batch file in the patch'../testbatchfile/batchfile.batch'
cimsub -b ../testbatchfile/batchfile.batch
Execute the batch file in the patch'../testbatchfile/batchnamespace.batch with namespace 'root/PG_InterOp'
cimsub -b ../testbatchfile/batchnamespace.batch -n root/PG_InterOp
cimserver(1), cimconfig(1M)
.
The cimsub command line utility will provide users a more convenient way to get information about and operate on indication subscriptions on the local CIM Server. For example, the list form of the command may be used to:
It is not proposed that the cimsub command support subscription creation, since that is a complex operation, and it is already possible to create subscriptions using the cimmof command.
The cimsub command will be tested in the automated test suite. A test provider will be added to respond to createSubscription requests (but will not actually generate indications). All forms and options for the command will be tested, and the correctness of the command output and the result will be verified.
Each set of tests will include appropriate error test cases, such as the following:
Each set of tests will also include appropriate tests of privilege requirements, including testing combinations of the following types of users and configuration property settings:
Action | Planned | Actual | Comment |
PEP Submitted | 5 June 2006 | 5 June 2006 | |
PEP Reviewed | 16 June 2006 | 13 June 2006 | |
PEP Approved | 30 June 2006 | 16 June 2006 | |
Code Committed | Pegasus 2.6 | 20 October 2006 |
The possibility of supporting additional options and option argument values was discussed. These included:
The rationale for not supporting
subscription creation with the command was also discussed. It
was reported that complaints had been received about the
cimprovider command, because it supports removal but not
creation. A note has been added to the Usage Notes section of
the proposed cimsub man page, to advise caution in use of the -r
option. It was agreed that subscription creation is not
generally an administrator function, and not easily done on a
command line. It was also noted that keeping a command that
supported creation in sync and up to date (e.g. with new
ListenerDestination classes, etc.) would be a maintenance issue.
Copyright (c) 2006 Hewlett-Packard Development Company, L.P.; IBM
Corp.;
EMC Corporation; Symantec Corporation; The Open Group.
Permission is hereby granted, free of charge, to any person
obtaining a copy
of this software and associated documentation files (the
"Software"), to
deal in the Software without restriction, including without
limitation the
rights to use, copy, modify, merge, publish, distribute,
sublicense, and/or
sell copies of the Software, and to permit persons to whom the
Software is
furnished to do so, subject to the following conditions:
THE ABOVE COPYRIGHT NOTICE AND THIS PERMISSION NOTICE SHALL BE
INCLUDED IN
ALL COPIES OR SUBSTANTIAL PORTIONS OF THE SOFTWARE. THE SOFTWARE
IS PROVIDED
"AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
INCLUDING BUT NOT
LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
PARTICULAR
PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
COPYRIGHT
HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
WHETHER IN AN
ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
CONNECTION
WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
Template last modified: March 26th 2006 by Martin
Kirk
Template version: 1.11