2.6 Using the Oracle VM CLI and Getting Help

Enter ? or help to display help on a token. You can also enter ? after a token to display the possible options based on context. For example, if you want to display information about an Oracle VM Server, you can work your way through the command options to find the commands to perform this action.

Note

To keep the output to a minimum in the examples in this book, we have set the output mode to sparse using the following command:

OVM> set OutputMode=Sparse

Your output may vary depending on which setting you use for this command; see Section A.165, “set” for more information.

To find the command to list Oracle VM Servers, start with the ? option and work your way through the commands:

OVM> ?
     add
     create
     delete
     edit
     embeddedcreate
     embeddeddelete
     embeddededit
     exit
     help
     list
     Perhaps this is the command? Let's drill down further.
     remove
     set
     show
     showallcustomcmds
     showclisession
     showcustomcmds
     showobjtypes
     showversion
OVM> list ?
          AccessGroup
          AntiAffinityGroup
          Assembly
          ...
          Port
          Repository
          RepositoryExport
          Server
     This looks like the command to use to list Oracle VM Servers
          ServerController
          ServerPool
          ServerPoolNetworkPolicy
          ...
          VmDiskMapping
          Vnic
          VolumeGroup
OVM> list Server
     No more options can be entered so the results are automatically displayed
  id:00:e0:81:4d:5f:2f:00:e0:81:4d:29:ee:00:e0:81:4d  name:MyServer1
  id:00:e0:81:4d:5e:16:00:e0:81:4d:5e:17:ff:ff:ff:ff  name:MyServer2
  id:00:e0:81:4d:40:16:00:e0:81:4d:40:17:ff:ff:ff:ff  name:MyServer3
OVM>

Now you have a list of the Oracle VM Servers, you can display information about them with another command. To find the command to display information about an Oracle VM Server, drill down again through the commands to find the most appropriate command using the ? option:

OVM> ?
     add
     create
     delete
     edit
     embeddedcreate
     embeddeddelete
     embeddededit
     exit
     help
     list
     remove
     set
     show
       This looks like the command to use to show information
     showallcustomcmds           commands available for all objects
     showclisession              
     showcustomcmds              commands specific to an object (requires object as argument)
     showobjtypes
     showversion
OVM> show ?
          AccessGroup
          AntiAffinityGroup
          Assembly
          ...
          Port
          Repository
          RepositoryExport
          Server
       This looks like the command to use to show information about an Oracle VM Server
          ServerController
          ServerPool
          ServerPoolNetworkPolicy
          ...
          VmDiskMapping
          Vnic
          VolumeGroup
OVM> show Server ?
                 id=<object identifier> OR
                 name=<object name>
OVM>

If you have forgotten the name of the Oracle VM Server, use the up arrow to scroll through the history until you see the list Server command and press Enter. Then use the show Server name= option to display information about an Oracle VM Server.

OVM> show Server name=MyServer1
  Status = Running
  Role 1 = Utility
  Role 2 = Vm
  Ip Address = 10.172.76.79
  ...  
  Name = MyServer1
  Locked = false
OVM>

The CLI is a self-learning tool; built in help and tab auto-completion guide you when working with the commands. The following commands assist you to use the CLI.

Table 2.1 Helpful CLI commands

Command/Feature

Description

?

Context sensitive help, for example, show ?, clone ?. If you do not know the format of a command, enter the command followed by ? to see the options for that command. Enter ? on its own to see a list of all the top level commands.

help

Displays the syntax to use for the top level commands.

showallcustomcmds

Displays a list of the all custom commands for all object types.

showclisession

Displays the CLI session settings. These settings are set using the set command.

showcustomcmds [object type]

Displays a list of the custom commands for a specific object type provided as a parameter.

showobjtypes

Displays a list of the object types.

tab completion

Press the Tab key to auto-complete the command.

history

Use the up or down arrow keys to step through the history of commands entered in the current session. Up to 50 commands are listed.

masking sensitive data

Append an asterisk (*) to an attribute name to mask the content following the equals sign (=) when setting the value of an attribute. See Masking Sensitive Data for more information on this.


You can configure the end of line characters used by your SSH client, for example, if your SSH client adds a line feed (double spacing) to the end of a line, you can set the endline characters to CR. Set the end of line characters using the set command.

You can configure the output mode to define how the CLI returns results, for example in plain text or in XML. Set the output mode using the set command.

Use the showclisession command to show the values for the options set with the Section A.165, “set” command.

The values you enter for parameters are case sensitive, unless explicitly stated in this Guide. For example, entering name=MyServer is not the same as entering name=myserver. The CLI treats these parameter strings as case sensitive, and are considered different.

Special characters are considered any of these: ", ', ?, \, /, <, >. You can escape special characters within a set of quotes to make sure they are treated as a literal string using a / (forward slash) before the character. For example:

OVM> create Tag name=MyTag description="HR/'s VMs from http:////example.com//vms// /<Delete/?/>"
  id:0004fb0000260000b351e52e3abbe192  name:MyTag
OVM> show Tag name=MyTag
  Name = MyTag
  Id = 0004fb0000260000b351e52e3abbe192
  description = HR's VMs from http://example.com/vms/ <Delete?>

Parameters are unique for each time you run a command. Providing more than one object of the same attribute type as a parameter always results in the last attribute value taking precedence. Therefore, a command similar to the following succeeds, but the values of these repeated parameters override each other:

OVM> discoverServer ipAddress=server1 ipAddress=server2 takeOwnership=No\
 takeOwnership=Yes password=** password=******
 Command: discoverServer ipAddress=server1 ipAddress=server2 takeOwnership=No
 takeOwnership=Yes password=** password=******
 Status: Success
 Time: 2013-12-23 00:34:38,398 PST
 JobId: 1387787665552

OVM> list server
 Command: list server
 Status: Success
 Time: 2013-12-23 00:34:43,602 PST
 Data: id:44:45:4c:4c:59:00:10:35:80:34:c7:c0:4f:57:48:31
       name:server2

In this example, only one Oracle VM Server is discovered. The second parameter in each instance of the command overrides the first. Therefore, server2 is discovered, and ownership is set to Yes, and the password in this instance is the second one specified.

If a command is issued, but no changes to an object are performed, a success message is displayed. For example, if you change the name of an object to the same name, Status: Success is returned and displayed.

2.6.1 Return Status Values

Operations that trigger job creation within Oracle VM Manager, such as create or modify operations, always return the status of the job. The status is referred to as the Return Status. If a job is successful, the status returned is set to Success. If a job fails, the status returned is set to Failure.

Job status is obtained by consistently polling Oracle VM Manager with the generated Job ID to query the job status. For operations that may take too long, the CLI may timeout the polling period. In this case, the status returned is set to Running to indicate that the job is still running. In this case, you may need to query the job status manually before continuing with any other operations.

Since all commands that result in some form of change within Oracle VM Manager trigger the creation of a job, these commands also return the job ID in the response output. The value for this appears in the JobId field. In the case where a command has returned a Running status, you can use this field to obtain the job ID for the task that you are performing, and then use the show job command to monitor its status.

The default job timeout value is 7200 seconds (120 minutes). The value can be set in the common configuration file, used by both the Oracle VM Manager CLI and the Oracle VM Manager Web Interface, at /u01/app/oracle/ovm-manager-3/ovm_cli/config/common_config.xml. The attribute to set is defaultCommandTimeout.

2.6.2 Masking Sensitive Data

In some scenarios you may need to mask sensitive data as it is entered into the CLI to avoid it displaying to screen. This functionality is applied by default on some known commands such as the discoverServer, where the password value is automatically substituted with a series of asterisk (*) characters on the screen as it is typed. However, in other situations, such as when sending messages to VMs, there are some additional values that you may wish to obscure on the screen that would not be hidden by default. Masking functionality has been built into the CLI to allow you to automatically mask the data for any attribute by simply appending the asterisk (*) character to the attribute name before entering its value. This is illustrated in the example below:

OVM> sendVmMessage Vm name=MyVM key=com.oracle.linux.root-password message*=******* log=No

In the example above, the message is purposefully masked and the actual value is substituted on screen with *******. For additional security, in this example, we also set the log parameter to No, to prevent the message from being logged.

The masking function can be applied to any attribute where a value is entered for a command, with the exception of the name or id attributes. For instance, it is possible to hide the description attribute as it is entered on screen:

OVM> edit Server name=MyServer description*=***********

The masking feature expects a single asterisk following the attribute name. Any attempt to enter multiple asterisks or other characters following the first asterisk causes the validation to fail and the attribute name is unrecognized.