cli.txt

Pegasus is an open-source implementationof the DMTF CIM and WBEM standards. It is designed to be por

cimcli(1)							     cimcli(1)



NAME
       cimcli - command line WBEM Client

SYNOPSIS
       cimcli [operation] [object] [options] [extra-parameters] ...

       cimcli is available for all platforms that support the 
              Pegasus CIM Server.


DESCRIPTION
       cimcli is a command line test tool for executing CIM client operations.
       It implements all of the DMTF CIM operations except for the modify and
       create class/instance operations and includes several other  operations
       that are useful in testing including getting all namespaces and enumer-
       ating all instances in a namespace.

       Each execution of cimcli invokes a CIM Operation with the corresponding
       command  parameters  equivalent  to  he  CIM Operations  defined in the
       CIM Operations over HTTP specification.

       In addition to the basic CIM Operations defined in  the	specification,
       this tool implements a number of other specific operations that support
       testing and querying CIM servers including   a  command	to  query  for
       namespaces and to get all instances in a namespace.


       1.     Enumerate	 namespaces  (ns)  -  Returns a list of the namespaces
	      available from the CIMOM.

       2.     Enumerate all instance names (niall) - Returns  a	 list  of  all
	      instance names in the defined namespace.

       2.     Turn CIMServer statistics on and off (At least for the OpenPega-
	      sus server

	      The format of this command is generally:

       cimcli [Operation] [objectname] [options] [extra parameters]


       [Operation]
	      defines the operation to be executed. cimcli executes all of the
	      DMTF  CIM Operations (ex. getclass) and a set of compound opera-
	      tion (enumeratenamespaces). There are two forms for each	Opera-
	      tion definition, a short form typically two characters (i.e. gc)
	      and the long form which is the full name of the operation	 (i.e.
	      getclass).

       [objectname]
	      The name of the object input with the command. This parameter is
	      operation dependent.  For example, with the  getClass  operation
	      the  object  is  a class name.  With the getinstance command the
	      object is an object name. Note that some of the commands do  not
	      require an object.   Thus, for example, the [object] is optional
	      with the enumerateClasses operation as it is with the equivalent
	      enumerateClassNames  CIM	operation.  Normally  this is either a
	      classname or an instancename (classname  plus  keybindings).  In
	      some  operations	one or the other is required.  In other opera-
	      tions, the behavior of the operation  is	dependent  on  whether
	      classname or instancename is supplied.

       [options...]
	      Options  are  identified	on  the	 command line with the - or --
	      notation.	 There are three types of options:


       1.      A set of options that are universal and modify  or  define  the
	       execution  of  the  command  or	the  form of the return.  This
	       includes options like setting  the  output  format  for	object
	       responses or requesting only summary operation.

       2.      A  set  of options that represent the optional input parameters
	       for selected operation. The command defines the	CIM  Operation
	       that will be executed and the options define the optional char-
	       acteristics.  Typical context options  might  be	 -n  namespace
	       (used on most but not all operations)or -niq which sets includ-
	       equalifiers to false for operations that use the	 includeQuali-
	       fiers optional parameter.

       3       A  set  of  options  to display help (-h, --help, --ho to get a
	       list of all options, and -hc to get a  list  of	all  commands.
	       When these options are requested, no operation is executed.

       [extra-parameters]
	       Some of the operations allow or require extra parameters. these
	       are typically keywords or keyword/value pairs and  are  defined
	       as part of the particular options that might use them.

	       Any  extra  parameters  entities on the command line that occur
	       after the [Operation] and are not preceeded by "-" to  indicate
	       an  option  are	considered extra paramters.  These are used in
	       some  of	 the  operations  to  provide  additional  information
	       required	 or  optionally	 desired  by  the operation.  See each
	       operation definition  to	 determine  if	extra  parameters  are
	       required	 or  allowed.  These may be either keyname-value pairs
	       in some cases or simply strings depending on the operation.


	       NOTE: cimcli does not protect the  user against inputting extra
	       options or parameters.  Since the options are heavily dependent
	       on the operation	 to  be	 executed,  it	simply	ignores	 those
	       options	that  are not used with a particular operation.	 Thus,
	       entering the -r option (role)  with  a  getClass	 operation  is
	       syntatically allowed but cimcli ignores the parameter.


UNIVERSAL OPTIONS
       There  is  a  set of options which are general to all of the CIM Opera-
       tions and most of the compound operations and which provide  parameters
       for the initiation or execution of the command.	These include:

       -n [namespace]
	      Namespace	 name  for  this  operation (ex. -n root). The default
	      namespace is root/cimv2.

       -l [location]
	      Host name or IP address and optionally port for this  operation.
	      The default for this command if the the -n option is not used is
	      to use the Pegasus connectLocal() function  to  connect  to  the
	      server. Note that  this  means  that  a  command  like cimcli gc
	      CIM_Door may not work when trying to connect to a	 server	 other
	      than Pegasus on the same system. If cimcli is to be used to con-
              nect to a CIM Server  other than Pegasus  on the same system use
              -l localhost or -l 127.0.0.1  or	the actual name or IP address.
	      This will force cimcli to make the connection in the normal way,
	      not using connectLocal()

       -u [user-name]
	      The  user name to be used in in the connection to the CIM server
	      for the command

       -p [password]
	      The password to be used in the connection to the CIM server  for
	      the command

	      In  addition  there is a set of options that modifies the manner
	      in which the command is executed or the display  of  information
	      on response including the following:


       --t    Measure  time  for  the  operation to be completed and report it
	      upon command completion. If this option is set, the time for the
	      operation	 is  recorded  upon  completion	 of the operation.  In
	      addition, the client infrastructure is qeieried to determine  if
	      the operation execution times optionally measured in the infras-
	      tructure and at the server are available. If they are, they  are
	      displayed	 also.	This would allow the user to see a) time spent
	      in the server, b) round trip time for the operation, c) applica-
	      tion  round trip time for the operation. Note that when combined
	      with the repeat option, the output  includes  maximum,  minimum,
	      and average times for the operation.  There are a specific oper-
	      ations in cimcli to turn control statistics generation (See son 
              and soff operations)

       --r [repeat_count]
	      Repeat the operation repeat_count times. This repeats the opera-
	      tion without disconnecting. This option is useful for setting up
	      tests that load the server with repeated calls and also for get-
	      ting average times for an operation by taking the average	 of  a
	      number  of calls ( when used with the summary information option
	      and the measure time option).

       -delay [seconds]
	      Delay count seconds between connect and operation.

       --sum  Present only summary information, not full output.  Generally it
	      presents	counts of objects returned and response times in place
	      of the names or objects themselves.

       --count [object_count]
	      Defines an expected count of objects expected on	the  response.
	      An  error	 exit  is  generated  if this number of objects is not
	      received.	 This test can be used in batch files to test for num-
	      ber of objects returned by an operation.

       --timeout [seconds]
	      Set  the	connect	 timeout  to  some time other than the default
	      timeout.

       -o [ xml | mof ]
	      Output type for commands that output objects. Used with commands
	      that present CIM objects in their response.

       -verbose
	      Displays details on the options for the CIM Operation and execu-
	      tion.



       OPERATIONS
	      This section defines  the  individual  operations  supported  by
              cimcli.
	      Note  that  the  either the names (ex EnumerateInstances) or the
	      shortcut (ei) may be used in inputting  an  operation  defintion
	      and they they are case independent.


       ci CreateInstance
	      NOTE: This command is not implemented in the current version and
	      return a fixed "NOT IMPLEMENTED" response.  This command	issues
	      the  CIM operation create instance with the parameters provided.
	      It requires the [object] parameter defining the class for	 which
	      the  instance  is	 to be created and also allows for an optional
	      set of parameters that defined properties to be provided in  the
	      following format

		[propertyName]=value

	      If  the  propertyName  parameter	is provided with no value, the
	      default is inserted.  Note that the CIM operation is issued even
	      if the property name is illegal since this is considered to be a
	      test program.

	      The command actually reads the CIM_Class, inserts the properties
	      that  have been defined on the command line using the value type
	      from the class.

	      The command will be rejected if the class does not exist in  the
	      namespace.

	      Example:

		   cimcli ci CIM_door name=abc size=zyx

	      Returns  the  object path of the created instance if the call to
	      the cim server was executed.  Otherwise it returns the exception
	      received.


       ec EnumerateClasses
	      Issues  the  enumerateClasses CIM operation which enumerates the
	      class hiearchy starting at the level defined by <classname>.

	      The format is: cimcli ec [classname] [options]

	      where classname is not required. If it's omitted, cimcli inserts
	      an  empty	 classname  into the CIM operation which tells the CIM
	      Server to start at the top of the class inheritance  tree.   The
	      possible options that represent the parameters of the enumerate-
	      Classes operation are:


	      -niq Boolean (not_include_Qualifiers) that  sets	the  operation
	      parameter for include_quailifers to false.

	      -nlo  Boolean  that defines whether properties from superclasses
	      are included in the response. the -nlo option turns this parame-
	      ter off

	      -cl  Boolean  parameter sets the operation parameter classOrigin
	      in the operation request. the CIMServer is  expected  to	return
	      classOrigin information as part of the response.

	      -pl [propertyList] Optional property list for the operation.

	      Examples	    TBD


       nc EnumerateClassNames
	      Enumerate Class Names.  The format is:

		   cimcli[ <classname> ] [options] where the used options are:

	      The options specific to this operation include;

	      -niq do not include qualifiers

	      -nlo not localOnly

	      -cl class origin

	      -pl [propertyList] optional property list for the operation.

	      On this operation the classname parameter is optional similar to
	      the way the CIM operation is defined.

	      Examples	    TBD


       ni EnumerateInstanceNames
	      Execute the enumerateInstanceNames CIM Operation. The syntax for
	      this operation is:

	      cimcli ni [classname] [options]

	      This  operation  takes as input options specific to this command
	      the following:

		  object - classname for which instancenames are to be enumer-
	      ated.

	      It  displays  the	 instances names that were returned by the CIM
	      server in response to the enumerateInstances CIM operation  with
	      the defined input parameters. if the -s option is set it returns
	      only the count of names returned.

	      In order to provide all of the options allowed for the CIM oper-
	      ation  EnumerateInstances it uses the following options specific
	      to the command:

	      -B -nlo not local only operation parameter to false.  Note  that
	      this  negative  form for the option is used becaused the default
	      for local only parameter	is  true.  Thus,  not  including  this
	      parameter means that the parameter is not set.

	      Example:

		  cimcli ni CIM_ManagedElement -n root/PG_Interop

              	  Execute the enumerateInstanceNames operation on 
                  CIM_ManagedElement class in the root/PG_Interopnamespace.


       ei EnumerateInstances
	      Execute the CIM operation enumerateInstances. The format of this
	      operation is:

	      cimcli ei <className> [options]

	      In order to provide all of the options allowed for the CIM oper-
	      ation EnumerateInstances it uses the following options  specific
	      to the command

	      -nlo not local only operation parameter to false. Note that this
	      negative form for the option is used becaused  the  default  for
	      local only parameter is true. Thus, not including this parameter
	      means that the parameter is not set.

	      -niq Boolean (not_include_Qualifiers) that  sets	the  operation