Pegasus Enhancement Proposal (PEP)

PEP #: 257

PEP Type: Functional

Title: Indication Subscription Management

Version: 1.2

Created: 15 June 2006

Author: Carol Ann Krug Graves

Status: Approved

Version History:

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, or removing a subscription, display of selected subscription information, as well as removal and display of filters and handlers.

Definition of the Problem

Currently, there is no convenient way to query which indication subscriptions exist on the CIM Server, nor to 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.

Proposed Solution

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(1)

Name

cimsub - manage CIM indication subscriptions

Synopsis

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 -r s|f|h|a [-n namespace] [-F [fnamespace:]filtername] [-H [hnamespace:][hclassname.]handlername]
cimsub --help
cimsub --version


Description

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.

Options

The cimsub command recognizes the following options:

-l

List and display information about all or selected indication subscriptions ("s"), filters ("f"), or handlers ("h"). It is an error to specify the -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

Enable the specified subscription (set the SubscriptionState to Enabled).

-d

Disable the specified subscription (set the SubscriptionState to Disabled).

-r

Remove the specified subscription ("s"), filter ("f"), handler ("h"), or subscription and its referenced filter and handler ("a") (delete the instance(s) from the repository). The -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.

-v

Include verbose information (e.g. SubscriptionState value, filter query, handler destination) in the information displayed for each listed instance.

-n namespace

Specify the namespace. For the -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

Specify the Filter Name. Omission of the filter namespace specifies that it is the same as that of the subscription.

-H [hnamespace:][hclassname.]handlername

Specify the Handler Name. Omission of the handler namespace specifies that it is the same as that of the subscription. Omission of the handler classname specifies that it is CIM_ListenerDestinationCIMXML.

--help

Display the help message.

--version

Display the CIM Server version.

Exit Status

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

Usage Notes

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.

Examples

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

See Also

cimserver(1), cimconfig(1M).

Rationale

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:

• list all subscriptions
• list all subscriptions that reference a specific Filter and/or Handler
• list all subscriptions in a specific namespace

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.

Test Plan

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:

• user is not authorized to perform the operation
• instance not found
• namespace does not exist
• subscription already enabled
• no providers are capable of serving the subscription
• no providers accepted the subscription
• subscription expired
• subscription already disabled
• filter or handler referenced by a subscription cannot be deleted

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:

• privileged user, subscription creator, non-privileged non-creator
• enableSubscriptionsForNonprivilegedUsers=true, enableSubscriptionsForNonprivilegedUsers=false
• enableAuthentication=true, enableAuthentication=false

Schedule

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

Discussion

The possibility of supporting additional options and option argument values was discussed. These included:

• Option to list only enabled or only disabled subscriptions
  Resolution: an option to list only enabled subscriptions or only disabled subscriptions could be considered for the future, once users have had experience with the command, and the use model is better understood.
• Option to only count, rather than list instances
  Resolution: a count can be accomplished by other means (for example by redirecting the command output to "wc -l"), so a count option is not necessary.
• Support of regular expressions in specifying filter or handler names
  Resolution: support of regular expressions in specifying filter or handler names could be considered for the future.

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