Oracle® VM Manager Command Line Interface User's Guide for Release 3.4

2.1 Starting and Stopping the CLI

The CLI is automatically started when you first install Oracle VM Manager. You can also stop and start it separately to Oracle VM Manager as required. To use the CLI, the Oracle VM Manager service should first be started. See Starting and Stopping Oracle VM Manager for information on starting and stopping Oracle VM Manager.

When the CLI is installed (as part of Oracle VM Manager), it is set to automatically start when the operating system starts. If you want to disable this, enter:

# chkconfig ovmcli off

To manually start or stop the CLI, and to verify its status, log in as the root user, and use the syntax:

/sbin/service ovmcli [start|stop|status|restart]

For example, to start the CLI:

# /sbin/service ovmcli start

To stop the CLI:

# /sbin/service ovmcli stop

To restart the CLI:

# /sbin/service ovmcli restart

To check the status of the CLI:

# /sbin/service ovmcli status

The status option returns whether the CLI service is running or stopped.

If the Oracle VM Manager host computer runs a full graphical desktop environment, you can also use the Services dialog to start and stop the CLI. From the Applications menu, select System Settings > Server Settings > Services. Or by running the following command in a terminal to display the Services dialog:

# /usr/bin/system-config-services

In the Service Configuration dialog, select ovmcli to check the status, and start or stop it.

2.2 Connecting to the CLI

Multiple CLI connections can be made to a single instance of Oracle VM Manager at any time. The connection to the CLI is an SSH connection. To connect to the CLI, use an SSH client or command line interface and connect to the Oracle VM Manager host using the syntax:

ssh -l manager_username { manager_IP | manager_hostname } -p port

The default port for the CLI is 10000.

For example:

$ ssh -l admin 10.172.76.146 -p 10000

To connect to the CLI from the Oracle VM Manager host, enter:

$ ssh -l admin localhost -p 10000

You can also use the abbreviated connection syntax (without the -l option), for example:

$ ssh admin@localhost -p 10000

Tip

To keep your ssh session from disconnecting due to inactivity, you can use the ssh ServerAliveInterval option to send a null packet to the CLI to keep the connection alive. You can use this option, either on the command line when you enter the ssh command, or in the ~/.ssh/config file, for example to use this on the command line, enter:

$ ssh admin@localhost -p 10000 -o ServerAliveInterval=40

The interval length is in seconds, so this example will keep the connection alive for 40 seconds. Setting this value to 0 disables the feature. The syntax to use when adding this to the ~/.ssh/config file is:

Host *manager_hostname
 ServerAliveInterval 40

When you establish a connection to the CLI, you are prompted to enter a password for the Oracle VM Manager admin user. Enter the password and the CLI prompt is displayed, ready for you to begin entering Oracle VM CLI commands.

Using username "admin".
admin@10.172.76.146's password: password
OVM>

To exit the CLI, enter exit, or end the SSH session.

2.3 SSH Host Keys

On some operating systems, when you first log in to the CLI, you may be prompted to add the key fingerprint of the Oracle VM Manager host to the ~/.ssh/known_hosts file, for example:

$ ssh -l admin hostname -p 10000
The authenticity of host 'hostname (IP_address)' can't be established.
DSA key fingerprint is fingerprint.
Are you sure you want to continue connecting (yes/no)? yes
Warning: Permanently added 'hostname' (DSA) to the list of known hosts.
admin@hostname's password:

If you want to avoid this message and have host keys automatically added to the known_hosts file, you can turn off strict checking of SSH host keys using the following command:

$ ssh -o 'StrictHostKeyChecking no' admin@hostname

If you have upgraded or reinstalled Oracle VM Manager, you may be prompted that the host identification has changed when connecting to the CLI, for example:

$ ssh -l admin hostname -p 10000
@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
@    WARNING: REMOTE HOST IDENTIFICATION HAS CHANGED!     @
@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
IT IS POSSIBLE THAT SOMEONE IS DOING SOMETHING NASTY!
Someone could be eavesdropping on you right now (man-in-the-middle attack)!
It is also possible that the DSA host key has just been changed.
The fingerprint for the DSA key sent by the remote host is
fingerprint.
Please contact your system administrator.
Add correct host key in /root/.ssh/known_hosts to get rid of this message.
Offending key in ~/.ssh/known_hosts:1
DSA host key for localhost has changed and you have requested strict checking.
Host key verification failed.

To clear this message and allow connections to the CLI, use the ssh-keygen utility to remove the entry for the Oracle VM Manager host, for example:

$ ssh-keygen -R hostname:10000

You may need to add braces around the hostname if the previous command does not remove the entry, for example:

$ ssh-keygen -R [localhost]:10000

Alternatively, edit the ~/.ssh/known_hosts file and remove the entry for the Oracle VM Manager host.

Connect to the CLI again and you are prompted to add the new fingerprint if strict checking of SSH host keys is enabled.

2.4 Key-Based Authentication

You can use public key-based SSH authentication to connect to the CLI. When you set up key-based authentication, you can log in to the CLI without being prompted for a password. Using key-based authentication does not effect the existing authentication mechanism using a username and password.

Keys are set up between a local system and the Oracle VM Manager host. After the keys are set up, you log in for the first time with the CLI admin password, as you normally would, then a connection is established using public key authentication and the channel is identified to the CLI Server by the client IP address and user name. Subsequent log ins do not require the password, for as long as the channel remains open. If the channel is closed, or the admin user's password is changed, key-based authentication is terminated and you are required to enter the admin user's password again. To reestablish the connection using key-based authentication, log in again using the standard SSH connection, enter the admin user's password, and the channel is opened again.

To set up key-based authentication:

Make sure the ssh-agent is running on your local host:
```
$ eval `ssh-agent`
Agent pid number
```
If the ssh-agent is not running, you may encounter the following error when you perform the next step:
```
Could not open a connection to your authentication agent.
```

On your local host, generate a public/private key pair to log in to the CLI. Make sure you remember the passphrase that you enter.

$ ssh-keygen -t rsa -f ~/.ssh/admin
Generating public/private rsa key pair.
Enter passphrase (empty for no passphrase): passphrase
Enter same passphrase again: passphrase
Your identification has been saved in /user/.ssh/admin.
Your public key has been saved in /user/.ssh/admin.pub.
The key fingerprint is:
fingerprintuser@hostname

The two keys are generated in ~/.ssh/: admin (the private key) and admin.pub (the public key).

Add the private key to the authentication agent, using the same passphrase you used to create the key pair, for example:

$ ssh-add ~/.ssh/admin 
Enter passphrase for /home/user/.ssh/admin: passphrase
Identity added: /home/user/.ssh/admin (/home/user/.ssh/admin)

Copy the public key to the Oracle VM Manager host, for example:
```
$ scp ~/.ssh/admin.pub oracle@hostname:/home/oracle/.ssh/
```
Where hostname is the hostname of the Oracle VM Manager host. Make sure you do the copy as the oracle user.
Log into the Oracle VM Manager host as the oracle user and append the admin.pub public key to the CLI authorized file (ovmcli_authorized_keys).
```
$ ssh oracle@hostname
$ cd /home/oracle/.ssh/
$ cat admin.pub >> ovmcli_authorized_keys
$ exit
```
Where hostname is the hostname of the Oracle VM Manager host.
From the local machine, log in to the CLI using the command:
```
$ ssh -l admin hostname -p 10000
```
You are requested to enter the admin user's password. Enter it.
```
admin@hostname's password: password
OVM>
```
Subsequent log ins use the newly established channel and do not require a password.

For security reasons, the channel for public key authentication expires after a designated period of time. See Section 2.10, “Configuring the Oracle VM CLI” for information on how to change the public key authentication expiry time.

2.5 Using SSH to Run Background Processes

If you choose to run CLI commands in the background via the standard SSH interface, it is possible that keyboard breaks interrupt running processes. This is a standard behaviour if the TTY setting has been set to sane, and is remedied by providing the SSH command with the -n option to automatically send keyboard input to /dev/null. This type of command can only be used with key-based authentication, since at the point that it is run, the command is run in the background so you can no longer interact with it.

$ ssh -l admin localhost -p 10000 -n "importVirtualAppliance Repository name=MyRepository
url=http://example.com/myappliance.ova" &

Note that using the -n flag does not make sense if you intend to maintain an interactive session within the CLI.

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.

2.7 Passing in a CLI Command at the Command Line

If you want to run the CLI and pass in a simple command, append the command in quotes after the SSH login credentials, for example:

# ssh admin@hostname -p 10000 "list Server"

You can submit multiple commands using a semicolon (;) as the command delimiter, for example:

# ssh admin@hostname -p 10000 "list Server; show Server name=MyServer"

If you have enabled key-based authentication, you are not prompted for the password to access the CLI, and the results are displayed. If you have not, you must enter the CLI password before the results are returned. See Section 2.4, “Key-Based Authentication” for information on setting up key-based authentication. You can also use any other programming language to write scripts using the CLI as discussed in Section 2.9, “Integrating the CLI into Your Applications”.

2.8 Sample Scripts

There are a number of shell scripts provided with Oracle VM to help you use the CLI. If a password is required for any of these scripts, you are prompted at the command line to enter it. The shell scripts use key-based authentication, which is available after the first log in to the CLI.

These scripts are located in:

/u01/app/oracle/ovm-manager-3/ovm_cli/scripts

Table 2.2 Sample scripts

Script Name	Purpose
`ackAllEvents`	A shell script that acknowledges all events that a user can acknowledge. This script does not acknowledge system events. This script uses localhost as the default host. If you run this script from another host, you can specify the Oracle VM Manager location using the syntax: ackAllEvents -l `user`@`host`
`inventory`	A shell script that displays an inventory of all objects managed by Oracle VM Manager.

Script Name

Purpose

ackAllEvents

A shell script that acknowledges all events that a user can acknowledge. This script does not acknowledge system events.

This script uses localhost as the default host. If you run this script from another host, you can specify the Oracle VM Manager location using the syntax:

ackAllEvents -l user@host

inventory

A shell script that displays an inventory of all objects managed by Oracle VM Manager.

There are a also a set of shell scripts provided to get you started scripting in the CLI. These scripts are located in:

/u01/app/oracle/ovm-manager-3/ovm_cli/scripts/createdeletescripts

To use any of these scripts, you should first overwrite the default values in the associated *.properties file with values that match those of your environment. Each parameter within the associated properties file is commented to provide guidelines on the information that must be provided within these files. Additional information on how to run the scripts are contained as comments at the start of each script.

Table 2.3 Sample create/delete scripts

Script Name	Purpose
`create-fc-based-VM.sh`	A shell script that sets up a complete Oracle VM environment, including storage, server pool, networking, virtual machine resources and a virtual machine, using fibre channel-based storage. To use this script, edit the `fc-based-VM.properties` file in the same directory and change the parameters to suit your environment.
`delete-fc-based-VM.sh`	A shell script that deletes the set up created using the `create-fc-based-VM.sh` script. To use this script, edit the `fc-based-VM.properties` file in the same directory and change the parameters to suit your environment.
`create-iscsi-based-VM.sh`	A shell script that sets up a complete Oracle VM environment, including storage, server pool, networking, virtual machine resources and a virtual machine, using ISCSI-based storage. This script uses a fibre channel LUN for the server pool's clustered file system. The Oracle VM Server must have access to an unmanaged fibre channel storage array. This script creates a storage array using the Oracle NetApp Filer plug-in. To use this script, edit the `iscsi-based-VM.properties` file in the same directory and change the parameters to suit your environment.
`delete-iscsi-based-VM.sh`	A shell script that deletes the set up created using the `create-iscsi-based-VM.sh` script. To use this script, edit the `iscsi-based-VM.properties` file in the same directory and change the parameters to suit your environment.
`create-nfs-based-VM.sh`	A shell script that sets up a complete Oracle VM environment, including storage, server pool, networking, virtual machine resources and a virtual machine, using NFS-based storage. To use this script, edit the `nfs-based-VM.properties` file in the same directory and change the parameters to suit your environment.
`delete-nfs-based-VM.sh`	A shell script that deletes the set up created using the `create-nfs-based-VM.sh` script. To use this script, edit the `nfs-based-VM.properties` file in the same directory and change the parameters to suit your environment.
`common.sh`	A shell script that contains the common functions used by other scripts in this directory. Do not run this script directly, instead call it from other scripts. You can see a list of the common functions in this script in Table 2.4, “Sample scripts common functions”.

To customize any of these scripts for your environment, copy them to a directory outside of the Oracle VM Manager installation tree, edit the script with a text editor and change the variables to suit your environment, or extend further to provide additional functionality.

When you run any of these scripts, the output is displayed to the screen; spool it to a file or other process or script as required.

The common.sh file provides some common functions used by the sample scripts. The functions available in this script are listed in Table 2.4, “Sample scripts common functions”.

Table 2.4 Sample scripts common functions

Function	Description
getPass	Prompts for a password. You may want to prompt for an Oracle VM Server, or storage server pasword. When prompted, the input is not echoed on screen. The password can then be securely used with other CLI commands, such as discoverServer. No password is required for authentication with Oracle VM Manager as this uses certificate authentication.
validateCLI `command`	Script continues if the CLI command returns success, and terminates if the command returns a failure.
runCLI `command`	Script continues, regardless of the outcome of the CLI command.
deleteRepo `repository`	Deletes a storage repository and all of its contents.
deleteServerpool `serverpool`	Remove all Oracle VM Servers from a server pool, and deletes the server pool.
addVnicFromClonedVmToNetwork `vm network`	Use this command when cloning a virtual machine that includes a VNIC. This command associates the VNIC with a network, so enables the virtual machine to be started.

Performance Monitoring, Script Logging and Debugging

Optional timer functionality is built into the validateCLI and runCLI functions, which are used by all of the sample scripts to initiate connections to the CLI. This allows you to gather useful performance data, when running any of the sample scripts, by accurately timing and logging how long each of the commands within the scripts take to run. This tool also provides a useful log of every single command run for any of the scripts, providing debugging information that can be used to determine script failure or to understand the sequence of commands being issued by the script.

By default, the timer functionality is disabled, however it can be enabled by using the command line switch: -tfilename.txt. For instance:

./create-nfs-based-VM.sh -t report.txt

Output generated within the specified file for a script where the timer functionality has been enabled may look similar to the following:

TIME(Seconds) Command
18.621        discoverServer ipAddress='10.172.76.80' password=******** takeOwnership=yes
5.587         create serverpool virtualIP='0.0.0.0' clusterEnable=no name='MyServerPool' \ 
              description='this is nfs pool MyServerPool'
...

It is worth noting that output logged for the timer functionality is appended to the file specified. This means that if you re-use the same filename, the file is not overwritten with the new data. Instead, the output is simply appended to the bottom of the file.

If no filename is specified for the timer switch, the output is dumped to STDOUT.

2.9 Integrating the CLI into Your Applications

CLI-based integration is a popular and inexpensive way to integrate Oracle VM into your own applications. It is far easier and faster than using the Web Services API, and for smaller integrations is a very good option.

Since it is possible to configure the CLI to return information in XML format, it is easy to develop applications that are capable of parsing the results of any command issued to the CLI. Set the output mode using the set command.

The connection information is cached on the Oracle VM Manager host for 15 minutes, so subsequent calls with the same login credentials are faster than the initial connection.

You can write your own CLI scripts and take advantage of all the rich constructs that the operating system shell provides: variables, looping, conditional execution, parsing, and so on.

An easy way to integrate with Java is to use the exec method within the Runtime class, then parse the XML output with an XML parser such as SAX.

Equally, scripts may be written using Python along with an XML parser such as LXML. An SSH library such as Paramiko may assist in the development of tools that can be used remotely.

The CLI does not support regular expressions. If you want to use regular expressions, you should use them in your script that calls the CLI.

2.10 Configuring the Oracle VM CLI

When Oracle VM Manager starts, it reads the CLI configuration file. The configuration file is located at:

/u01/app/oracle/ovm-manager-3/ovm_cli/config/CLIConfigParams.xml

You can change a number of options in the configuration file. These options are listed in this section.

Before you change any options in the configuration file, you should back up the original and change the permissions of the file to make it writeable:

# chmod +w /u01/app/oracle/ovm-manager-3/ovm_cli/config/CLIConfigParams.xml

Any changes to this configuration file require a restart of the CLI. See Section 2.1, “Starting and Stopping the CLI” for information on restarting the CLI.

2.10.1 SSH Port

By default, SSH connections to the CLI are allowed on port 10000. To change the port on which the CLI accepts connections, edit the sshPort="10000" line in the configuration file and change it to the port number you require.

2.10.2 Timeout

By default, connections to the CLI time out after 45 minutes. To change the timeout period for connections to the CLI client, edit the clientInactivityTimeout="45" line in the configuration file. Set the time out to be between 1-1440 minutes. For security reasons, there is no option to disable the timeout period. Setting the value to less than 1 or greater than 1440 (1 day) causes the timeout value to revert to the default of 45 minutes.

In addition to this timeout option, you can use the ssh ServerAliveInterval option to stop an ssh client from timing out before the set timeout period. See the Tip in Section 2.2, “Connecting to the CLI” for more information on using this option.

2.10.3 Case Sensitivity

CLI commands are not case sensitive, so you can enter list vm, List VM, or any other variation in case.

Data values you use for objects in the CLI are case sensitive, so if a virtual machine has a name of MyVM, then you must use the same case when identifying it in the CLI and cannot use variations such as myvm.

2.10.4 Public Key Authentication Expiry

The connection channel for public key authentication expires after a designated period of time, or if Oracle VM Manager is restarted. The default for keeping the channel open is 1 week (10080 minutes). You can modify this setting by editing the publicKeyAuthChannelTimeout="10080" option in the configuration file. A value of -1 keeps the channel open indefinitely.

2.10.5 Lock Exceptions

When executing multiple concurrent CLI scripts, you may experience lock exceptions around shared resources such as file systems and storage repositories. By default, connections to the CLI time out after 20 seconds if an object that is being requested by the CLI command is locked. If a command fails due to a lock exception, the command is resubmitted 12 times to see if the lock has become free and the command can be executed. To help you tune the CLI to reduce lock exceptions, you can configure the amount of time a command waits for the lock to become free, and the number of times the command is resubmitted with the following options in the configuration file:

The lock time out period is defined by the lockExceptionRetryInterval="20" option. This option must be a value between 6 and 119 seconds, with the default being 20.
The number of retry attempts is defined by the lockExceptionRetryCount="12" option. This option must be greater than 0.

2.11 CLI Logs

A log of the CLI application is available in:

/u01/app/oracle/ovm-manager-3/domains/ovm_domain/servers/AdminServer/logs/CLI.log

A log of commands submitted to the CLI is available in:

/u01/app/oracle/ovm-manager-3/domains/ovm_domain/servers/AdminServer/logs/CLIAudit.log

This log contains the following information about the command submitted to the CLI:

Timestamp
Client IP Address
Username
Command

The log files are rotated when the file size reaches 5 MB with up to 10 rotations, in the same way as the other Oracle VM log files.