Avance Documentation » Avance Command Line Interface Reference

AVCLI has been enhanced to add support for the – -remap-volumes feature to the vm-import command. When specified, the vm-import operation will first attempt to remap all volumes to the shared-mirrors as defined in the archive. After that the rules for ––volumes and ––shared-storages will be in effect.

Version 4.0.0.0

Added R4.0.0 to the list of supported releases the CLI will run against.

Version 3.1.1.0

Added R3.1.1 to the list of supported releases the CLI will run against.

Version 3.1.0.0

Added R3.1.0 to the list of supported releases the CLI will run against.

Version 3.0.0.0

As of version 3.0.0.0 the vm-migrate command is no longer supported. This functionality was deprecated in favor of the preferredNode mechanism feature. This operation is not currently available in AVCLI and must be set through the User Interface.

AVCLI has been enhanced to incorporates enhancements to support snapshots, as well as enhanced exports.

vm-snapshot-info

shows information about current snapshots that are on the Avance Unit

vm-snapshot-create

used to create a snapshot.

vm-snapshot-delete

used to delete a snapshot

vm-export

enhanced to allow the export of a snapshot, supports config only exports, as well as ability to selectively omit data volumes.

vm-import

extended to allow selective volumes to restore, and control on where to place allocate storage for imported volumes.

vm-restore

extended to allow selective volumes to restore, and control on where to place allocate storage for imported volumes.

Version 2.1.3.1

This version adds support for Avance R2.1.3.10 release and is fully backwards compatible with the previous Avance releases. In addition, the following new commands have been added in this release:

avance-set-dom0-memory – Allows the user to set dom0 memory size from 1G to 2G and vice-versa. This command must be followed by a rolling reboot of each node.

Version 2.1.3

The following new commands have been added in the R2.1.3 release:

node-shutdown

Shutdown the node specified in the command line.

node-reboot

Reboot the node specified in the command line.

vm-import

Changed to use HTTP as the default transport protocol.

vm-export

Changed to use HTTP as the default transport protocol and does not compress the volume data.

Version 2.1.2

The following new commands have been added in the R2.1.2 release:

vm-boot-attributes

Set the boot attributes for the specified virtual machines.

audit-export

Exports all of the audit logs

Installing the AVCLI Client

Verifying the Java Runtime Library version

The client computer must have Java Runtime Environment version 1.6 update 14 or later.

To verify, type this on a command line:

java –version

Typical results:

java version "1.6.0_16"
Java(TM) SE Runtime Environment (build 1.6.0_16-b01)
Java HotSpot(TM) Server VM (build 14.2-b01, mixed mode)

If needed, upgrade at http://www.java.com/en/download/manual.jsp.

Installing for Windows

Download AVCLI Client for Windows

AVCLI for Windows

This is latest compatible version of Windows AVCLI client
Double-click avcli.msi. Follow the onscreen instructions.
Click Run. Accept the EULA.
If prompted to remove a previous version: click Start > All Programs > Avance > Uninstall Avance CLI. Then repeat steps 1- 3.

Installing the RHEL Client

Download the AVCLI client.

AVCLI for RHEL

This is latest compatible version of RHEL AVCLI client
Log in as the root user.
Add the directory /usr/bin if not present.
Install the new version. Type: $ rpm -i avcli*.rpm
Note that the avcli RPM will only allow a single copy of avcli to be installed on your Linux system at once. If a previous version is installed you will get an error message that looks something like:
```
file /usr/bin/avcli.bat from install of avcli-4.0.0-2 conflicts with file from package avcli-4.0.0-1
file /usr/lib/ImportExportLibs.jar from install of avcli-4.0.0-2 conflicts with file from package avcli-4.0.0-1
```
if this occurs, remove the previous version $ rpm -e avcli-4.0.0-1 And repeat step 6.

Installing the Ubuntu 12.04 Client

Download the AVCLI client.

AVCLI for Ubuntu 12.04

This is latest compatible version of Ubuntu 12.04 AVCLI client
Log in as the root user.
Add the directory /usr/bin if not present.
Install the new version. Type: $ dpkg -i avcli*.deb
Note that the avcli deb will only allow a single copy of avcli to be installed on your linux system at once. If a previous version is installed you will get an error message similar to.
```
file /usr/bin/avcli.bat from install of avcli-4.0.0-2 conflicts with file from package avcli-4.0.0-1
file /usr/lib/ImportExportLibs.jar from install of avcli-4.0.0-2 conflicts with file from package avcli-4.0.0-1
```
If this occurs, remove the previous version $ dpkg -r avcli-4.0.0-1 And repeat step 6.

Quick Start

Windows only: to launch AVCLI, click Start Menu > All Programs > Avance > Command Prompt.
Display a list of AVCLI commands by typing:$ avcli help

AVCLI Command Overview

Getting Help

To list all commands, type:

$ avcli help

This is then output:

[root@node1.avance~]# avcli help
Usage: avcli [OPTION]… [COMMAND]
-u, ––username username to log in with
-p, ––password password to log in with
-H, ––hostname hostname to log in to
-x, ––xml format output in XML
-h, ––help display this message and exit

For help with a command, type:

$ avcli help command_name

Authentication and Security

Executing AVCLI commands requires a valid username and password. The default username is admin, and the default password is admin.

AVCLI scripts embed the username/password. Use Access Control Lists (ACLs) to safeguard these credentials.
AVCLI commands are encrypted using SSL.

Basic Command Syntax

Commands must include the DNS name or IPV4 address of the Avance unit.

If you use incorrect syntax, a message displays the correct syntax.

AVCLI Output

AVCLI output is formatted for easy readability.

The output format of these commands may vary between releases.

$ avance -u admin -p admin -H avance –x node-info

node:
-> name : node0
-> id : host:o14
-> state: running
-> sub-state : nil
-> standing-state : maintenance
-> mode : maintenance
-> primary : false
-> manufacturer : Dell
-> model : Dell PowerEdge 2950
-> maintenance-allowed : true
-> maintenance-guest-shutdown : false
-> cpus : 8
-> memory : 4,288,675,840
virtual machines:
node:
-> name : node1
-> id : host:o406
-> state : running
-> sub-state : nil
-> standing-state : warning
-> mode : normal
-> primary : true
-> manufacturer : Dell
-> model : Dell PowerEdge 2950
-> maintenance-allowed : true
-> maintenance-guest-shutdown : true
-> cpus : 8
-> memory : 4,288,675,840
virtual machines:
virtual machine:
-> name : eagles1
-> id : vm:o1836

Program Friendly – XML Output

Scripts work with XML output. The schema definition will be maintained between releases.

Force XML output using the global options -x or –-xml, as shown:

$ avance -u admin -p admin -H avance –x node-info
node0
host:o14
running
nil
maintenance
maintenance
false
Dell
Dell PowerEdge 2950
true
false
8
4288675840
node1
host:o406
running
nil
warning
normal
true
Dell
Dell PowerEdge 2950
true
true
8
4288675840
eagles1
vm:o1836

AVCLI Error Status

AVCLI does not follow the Linux convention of returning 0 on successful execution and 1 for an error.

Usage Errors – Command Syntax

Command syntax errors return a Usage: error. Unrecognized commands display the AVCLI help:

$ cli -H foo -x node-infoasdasd
Usage: avcli [OPTION]… [COMMAND]
-u, ––username username to login with
-p, ––password password to login with
-H, ––hostname hostname to login to
––log log file to capture debug information in
-x, ––xml format output in XML
-V, ––version display the version and exit
-h, ––help display this message and exit
Commands:
ad-disable
ad-enable
ad-info
ad-join
ad-remove
alert-delete
alert-info

Valid commands with invalid arguments return the same error message as requesting command help. For example:

$ cli -H eagles -x vm-create

Usage: avcli vm-create[––interfaces] [––shared-storage]

Create a new VM.

––name Name of the VM.
––cpu Number of virtual CPUs to assign to the VM.
––memory Memory ( MB) to assign the VM.
––cdrom CD-ROM to boot the VM from, this option

Examples:

Create a VM named vm001 with a CPU, 512 MB of memory, attached to network0, and a 1,024 MB

volume.

   $ avcli vm-create ––name vm001 ––cpu 1 ––memory 512 ––cdrom linux.iso ––interfaces network0 ––volumes 1024

Create a VM named vm001 with a CPU, 512 MB of memory, attached to network0, a 1,024 MB volume and allocate storage from shared-mirror-0001 for the volume.

AVCLI Exceptions

Commands resulting in an error without –X or –XML specified as the output option return a verbose command line message. XML output is recommended.

$ cli -H eagles vm-delete eagles23
%Error: Cannot find a resource that matches the identifier eagles23.
com.avance.yak.cli.exceptions.CommandLineException: Cannot find a resource that matches the identifier eagles23.

at com.avance.yak.cli.ResourceDisambiguateServiceProvider.throwNonExistentResource(ResourceDisambiguateServiceProvider.java:56)
at com.avance.yak.cli.ResourceDisambiguateServiceProvider.getResourceId(ResourceDisambiguateServiceProvider.java:81)
at com.avance.yak.cli.Command.findResourceId(Command.java:80)
at com.avance.yak.cli.CommandWithUnparsedAmbiguousResourcesInvokeEach.execute(CommandWithUnparsedAmbiguousResourcesInvokeEach.java:65)
at com.avance.yak.cli.Command.execute(Command.java:194)
at com.avance.yak.cli.CommandLine.execute(CommandLine.java:649)
at com.avance.yak.cli.Program.main(Program.java:94)

XML Encapsulated Errors

Specify -x on the command line to display all errors as encapsulated XML suitable for processing with an XML parser. Examples:

Bad username/password

$ avcli -x -H eagles -u admin -p foo node-info

Bad host address for Avance unit

$ avcli -x -H foo -u admin -p foo node-info

foo

Operation using nonexistent VM

$ avcli -H eagles -x vm-delete eagles23

Cannot find a resource that matches the identifier eagles23.

Catching errors programmatically

To cleanly catch all errors while developing scripts, always specify output in XML format. This returns an error with any reply that does not return valid XML or any XML document with an error attribute.

This example is from a Perl subroutine _cli that provides a shell for executing AVCLI commands. The code that checks for errors does a simple pattern match on $stdout.

my $error = 0
$error = 1 unless ($stdout =~ /xml version/);
$error = 1 if ($stdout =~ /\/);

If there is no error, then $stdout is cast into a Perl hash using the standard PERL XML::Simple Library. Otherwise, an error is displayed:

unless ($error) {
     my $xs = XML::Simple->new();
     $stdout_hash = $xs->XMLin($stdout,forceArray=>0);
     return 0;
}
return 1;

Pausing for Asynchronous Commands

Commands that invoke an action on the Avance unit are said to be asynchronous because the command completes before the action completes. This allows complex scripting.

You will often want a simple script to wait for a command to complete inline before proceeding to the next. To do this, use the —wait option. For example:

 $ cli -x -H eagles node-workon ––wait node0

In this, cli does not complete until VMs and the management port are failed over from node0 to node1, and node0 is in maintenance mode. Without the —wait option, the command completes when acknowledged but before the resources are migrated.

Creating login shortcuts

Use shortcuts to simplify using the command line interface.

Linux

Create an alias in your login .cshrc file. For example:

alias avcli='/usr/bin/avcli -u admin -p admin –H avance'

where avcli is the alias name, admin/admin is the username/password, and avance is the Avance unit’s domain name.

You can then use this alias to log in. From the above example, the avance‑info command would be this:

$ avcli avance-info

Windows

In Windows, the avcli command executes the batch file avcli.bat in %Program Files%\Avance. You can add login credentials to this file:

Open avcli.bat with a text editor.
Search for this string:
```
-jar "%AVCLI_HOME%\avcli.jar"
```
Append login info. For example:

-jar "%AVCLI_HOME%\avcli.jar" –u admin –p admin –H avance

If you manage several Avance units with the same username and password, specify the domain names of the individual units in the command line:

$ avcli –H avance1 node-info node0
-or-
$ avcli –H avance2 node-info node0

Basic System Information/Commands

All command usage examples that follow assume you have setup a shortcut to execute the command, otherwise you must prefix all commands with the hostname, username, and password. For example:

avcli –H -u -p avance-info

avance-eula-accept

This command allows the user to accept the EULA agreement.

Usage: avcli avance-eula-accept [––deny]
This command allows the EULA to be programmatically accepted

avance-eula-reset

This command allows the user to reset the EULA agreement.

avcli avance-eula-reset

This command resets the EULA acceptance so that the next time a user opens the Avance Management Console they will be prompted to accept the EULA prior to logging in. After clicking “accept EULA” they will be stepped through all 6 steps associated with the first install wizard. If the configuration in each step is correct the user can simply click “next” for each step until they reach the final page. Note that the user will be prompted to login with the default credentials of admin/admin regardless of whether that user account has been changed as part of the installation procedure prior to resetting the EULA.

avance-set-dom0-memory

Changes the size of dom0 to 1GB or 2GB for more optimal system performance. Refer to the support article How to Increase the Size of the Avance Footprint found on the Avance Customer or Partner Portal for details on the proper procedure for this command. Note that a check is performed to see if there is adequate memory available before allowing dom0 to grow from 1G to 2G. If there is not enough memory then an error exception is returned. Both nodes must be rebooted after executing this command for the new memory size to take effect. This can be done either via AVCLI or the Avance Management Console. The procedure is to place the secondary node in maintenance, reboot, finalize; and then repeat the same procedure for the primary node.
Usage: avcli avance-set-dom0-memory [––size]
Example:

$ avcli avance-set-dom0-memory ––size 1
$ avcli avance-set-dom0-memory ––size 2

audit-export

Exports all of the audit logs.

Usage: avcli audit-export
Examples:

$ avcli audit-export

avance-info

Display information about the specified Avance unit.
Usage:

 avcli avance-info

avance-shutdown

Shut down an Avance unit. The VMs are cleanly shut down, then both PMs.
This command is asynchronous, but has —wait option. Monitor shutdown state with the avance-shutdown-state command.
Usage:

avcli avance-shutdown-state

avance-shutdown-cancel

Cancel a pending shutdown command. Some combinations of VMs and PMs will shut down and must be restarted.
Usage:

avcli avance-shutdown-cancel

avance-shutdown-state

Display the shutdown state of an Avance unit.
Usage:

avcli avance-shutdown-state

Example Output

$ avcli -H eagles avance-shutdown-state
shutdown-state : false

audit-info

Display the specified number of audit logs (default: 50).
Usage:

avcli audit-info [50]

Examples:

$ avcli audit-info
$ avcli audit-info 20

System Configuration

callhome-disable

Disable call home messages.
Usage:

avcli callhome-disable

callhome-enable

Enable call home, sent when the Avance server detects an alert condition. Recommended for L2/L3 support.
Usage:

avcli callhome-enable

callhome-info

Display call-home setup information.
Usage:

avcli callhome-info

dialin-disable

Disable dial-in access.
Usage:

 avcli callhome-disable

dialin-enable

Enable dial-in access. Recommended for L2/L3 support.
Usage:

 avcli dialin-enable

dialin-info

Display dial-in setup information.
Usage:

avcli dialin-info

ealert-config

Configure e-alert support. If no username is specified, AVCLI assumes no authentication is required to access the server. If a username is specified but no password, users are prompted for the password.
Usage:
avcli ealert-config [––ssl] [––username] [––password]
––username name to authenticate against the SMTP host
––password password to authenticate against the SMTP host
––host DNS or IP address of the SMTP server
––ssl use SSL when communicating with the SMTP server

Examples:

$ avcli ealert-config ––host mail.my-domain.com admin@my-domain.com
$ avcli ealert-config ––host mail.my-domain.com admin@my-domain.com bob@my-domain.com
$ avcli ealert-config ––host mail.my-domain.com ––username admin ––password secret ––ssl bob@my-domain.com
$ avcli ealert-config ––host mail.my-domain.com ––username admin ––ssl bob@my-domain.com

ealert-disable

Disable e-alert messages.
Usage:

avcli callhome-disable

ealert-enable

Enable e-alert messages when an alert condition is detected.
Usage:
avcli ealert-enable

ealert-info

Display e-alert setup information.
Usage:
avcli ealert-info

license-info

Display license information.
Usage: avcli license-info
Examples
avcli -H eagles license-info

license:

-> name : av_v_335

-> id : license:o928

-> type : volume

-> install-date : Thu May 06 18:26:22 EDT 2010

-> expire-date : Sat Jun 05 18:26:22 EDT 2010

-> allow-features : true

-> activated : true

-> expires : true

-> installed : true

license-file

Install a license file
Usage: avcli license-install

Examples
$ avcli license-install avance.key

ntp-config

Enable and configure NTP support for specified servers.Usage: avcli ntp-config

Examples: $ avcli ntp-config 1.2.3.4

$ avcli ntp-config 1.2.3.4 2.4.6.8

ntp-disable

Disable NTP.
Usage: avcli ntp-disable

datetime-config

Set the date (YYYY-MM-DD format) and time (HH:MM:SS 24-hour format). The time zone may be specified. For a list of the valid time zones, in the Avance Maintenance Console: click Preferences. Click Date & Time Configuration.
Usage: avcli datetime-config [time zone]
Examples:
$ avcli datetime-config 2010-12-31 6:03:10

$ avcli datetime-config 2010-12-31 20:09:22 America/New_York

proxy-config

Configure a proxy server. If no username is specified, AVCLI assumes no authentication is required to access the server. If a username is specified but no password, users are prompted for the password.
Usage: avcli proxy-config[––username] [––password]
Examples:
$ avcli ––port 8080 proxy.my-domain.com

$ avcli ––port 8080 ––username user ––password secret proxy.my-domain.com

$ avcli ––port 8080 ––username user proxy.my-domain.com

proxy-disable

Disable proxy configuration.
Usage: avcli proxy-disable

proxy-enable

Enable proxy configuration.
Usage: avcli proxy-enable

proxy-info

Display Information about the proxy configuration.
Usage: avcli callhome-info

snmp-config

Allow SNMP configuration with third-party tools.
Usage: avcli snmp-config [––enable-requests] [––enable-traps] [––port][recipients...]
––enable-requests enable SNMP requests; specified requests can be disabled

––enable-traps enable SNMP traps; specified traps can be disabled

––community name of the SNMP community

--port port for SNMP (default: 162)

recipients hosts to send traps to; required only when traps are enabled
Examples:
Enable SNMP requests, and traps and send them to localhost and snmp.my-domain.com:

$ avcli snmp-config ––enable-requests ––enable-traps ––community public localhost snmp.my-domain.com

Disable SNMP requests, enable traps, and send them to localhost:

$ avcli snmp-config ––enable-traps ––community public localhost

snmp-disable

Disable SNMP.
Usage: avcli snmp-disable

snmp-info

Display SNMP configuration.

System User Management

ad-join

Join Avance to the specified Active Directory domain, and enable Active Directory support.Usage: avcli ad-join> [––password]––username user with rights to join to the domain.

––password password of the user with rights to join to the domain. If no password is specified, users are prompted.

––domain Active Directory domain to join.
Examples:
$ avcli ad-join ––username domain\administrator ––password secret domain

$ avcli ad-join ––username domain\administrator domain

ad-disable

Disable Active Directory support.
Usage: avcli ad-disable

ad-enable

Enable active directory services.
Usage: avcli ad-enable

ad-info

Active Directory information.
Usage: avcli ad-info

ad-remove

Remove Avance from the Active Directory domain, and disable Active Directory supportUsage: avcli ad-remove> [––password] .

––username user with rights to remove Avance from the domain

––password password of the user with rights to remove Avance from the domain. If no password is specified, users are prompted.

––domain Active Directory domain
Examples:
$ avcli ad-remove ––username domain\administrator ––password secret domain

$ avcli ad-remove ––username domain\administrator domain

local-user-add

Add a new local user. If no password is specified, users are prompted. Users are prompted twice to verify the password.Usage: avcli local-user-add[––password] ––username local username

––password user account password

––realname user’s real name for this user

––email user’s email addressExamples: $ avcli local-user-add ––username bsmith ––realname “Bob Smith” ––email bsmith@example.com ––password secret

$ avcli local-user-add ––username bsmith ––realname “Bob Smith” ––email bsmith@example.com

local-user-delete

Delete local users.
Usage: avcli local-user-delete Examples:
$ avcli local-user-delete afjord

$ avcli local-user-delete afjord bsmith tkirch

local-user-edit

Usage: avcli local-user-edit[––realname] [––email] [––password] [––new-password] Edit an existing user. If the password option is not specified, the password is not changed.

The password option in local-user-edit is slightly different from local-user-add. The password option is a flag, and does not accept a value. If specified, users are prompted twice for the password; the password cannot be specified on the command line.

––username Avance local username

––password boolean flag to prompt the user for a new password

––new-password specify the password as a command line option, instead of prompting users as with ––password

––realname user’s real name

––email user’s email address
Examples:
$ avcli local-user-edit ––username bsmith ––email bsmith@example.net

$ avcli local-user-edit ––username bsmith ––realname “Robert Smith” ––email rsmith@example.com

$ avcli local-user-edit ––username bsmith ––email bsmith@example.net

local-user-info

Display information about one or more users specified.
Usage: avcli local-user-info [user...]

owner-config

Configure Avance owner information.Usage: avcli owner-config [––email] [––name] [––phone] ––email Email address of the owner

––name Name of the owner

––phone Phone number of the ownerExamples: $ avcli owner-config ––email “Bob Smith” ––email bsmith@example.org ––phone 800-555-1234

$ avcli owner-config ––phone 800-555-1234

owner-info

Display Avance owner information.
Usage: avcli owner-info

Managing Physical Machines (PMs)

node-add

Add a second PM to an Avance unit. This can be done only at install before the second node is added.Usage
avcli node-add

node-cancel

Cancel a node being recovered, added, or upgraded.
Usage
avcli node-cancel node

node-poweroff

Immediately stop processing in the selected PM and destroy memory state. This command will return a descriptive error unless the node targeted is in maintenance mode.Usage
avcli node-poweroff node

node-poweron

Start a PM in maintenance mode.Usage
avcli node-poweron node

node-upgrade

Upgrade the Avance software on a node. This must be part of an upgrade state machine complex operation. See page 52 for an example upgrade script.Usage
avcli node-upgrade –kit

node-workon

Put a PM in maintenance mode. Depending on the PM states, the following events occur:

If the PM is secondary, it is immediately placed in maintenance mode.
If the PM is primary:
- If the secondary PM is online and not in maintenance mode, all VMs are moved to it, and it becomes the primary. The selected PM is then placed in maintenance mode.
- If the secondary PM is in maintenance mode, all VMs are shut down and the selected PM is placed in maintenance mode.

Usage
avcli node-workon node

node-workoff

Remove the PM from maintenance mode, and synchronize it with its partner.Usage
avcli node-workoff node

node-shutdown

Shutdown the PM. The PM being shutdown must be in the maintenance mode prior to issuing this command.Usage
avcli node-shutdown ––help

Usage: avcli node-shutdown

Shutdown the specified node.

––force, -f override shutdown warning

––wait, -w wait for the command to complete

node-reboot

Reboot the PM. The PM must be in the maintenance mode prior to issuing this command.Usage
avcli node-reboot ––help

Usage: avcli node-reboot

Reboot the specified node.

––wait, -w wait for the command to complete

Managing Alerts

alert-delete

Delete some or all alerts.Usage
avcli alert-delete [alerts...|purge]Examples
$ avcli alert-delete alert:o10

$ avcli alert-delete alert:o10 alert:o11

$ avcli alert-delete purge

alert-info

Display alert information.

Usage:

avcli alert-info [alerts...]

alerts ID of alerts to be viewed, as displayed in the avcli alert-info command.

Example Output

The alert-info command with no arguments lists all undeleted alerts, as shown. (The ID is 644.)

[root@node1.outlaw ~]# avcli -u admin -p admin -H avance alert-info

alert:

-> name : Node Maintenance

-> id : alert:644

-> time : 2009.10.15 06:26:36.796

-> description : Alert has been cleared.__CR__

-> severity : 0

alert:

-> name : Node Maintenance

-> id : alert:1137

-> time : 2009.10.15 06:55:30.640

-> description : Alert has been cleared.__CR__

-> severity : 0

Diagnostic Files

diagnostic-create

Create a diagnostic file of various size and contents.Usage avcli diagnostic-create < ––wait >

minimal Smallest diagnostic file: 2–10 MB.

medium Approximately 10 MB.

stats File includes a medium dump plus statistics.

full Approximately 60 MB.

dump Up to 500 MB, including dumps of the VMs.Example Output cli -H eagles diagnostic-create -minimal

diagnostic:

-> id : buggrab:o862823

diagnostic-info

Display information about the file from diagnostic_create.Examples cli -H eagles diagnostic-info

diagnostic:

-> id : buggrab:o862823

-> date : Mon Apr 26 19:20:35 EDT 2010

-> type : minimal

-> status : busy

diagnostic-fetch

Display a diagnostic file. Specify a single file to save it in the current directory.Usage avcli diagnostic-fetch [––file] diagnostics…

––file Diagnostic file to save to the current directory. Valid only if one file is downloaded.

diagnostics Diagnostic file to fetch. Default names use this format:
diagnostic-type-name_YYYYMMDD_HHMMSS.zipExamples
$ avcli diagnostic-fetch buggrab:o10

$ avcli diagnostic-fetch ––file buggrab.zip buggrab:o10

$ avcli diagnostic-fetch buggrab:o10 buggrab:o11 buggrab:o12

diagnostic-delete

Delete a diagnostic file.

Usage

avcli diagnostic-delete diagnostic-id

diagnostic-id From the diagnostic-info command.

diagnostic-extract (R2.0.x)

Extract a diagnostic ZIP file grabbed with diagnostic-fetch.

Usage

avcli diagnostic-extract

Output goes to a directory called “diagnostic” with a subdirectory for each node’s logfiles.

node0-secondary:

total 244

drwxrwxr-x 10 cli_user user 4096 Apr 26 19:33 .

drwxrwxr-x 4 cli_user user 4096 Apr 26 19:33 ..

drwxrwxr-x 2 cli_user user 4096 Apr 26 19:33 drbd

drwxrwxr-x 4 cli_user user 4096 Apr 26 19:33 etc

drwxrwxr-x 2 cli_user user 4096 Apr 26 19:33 ha

drwxrwxr-x 2 cli_user user 4096 Apr 26 19:33 ipmi

drwxrwxr-x 3 cli_user user 4096 Apr 26 19:33 sbin

drwxrwxr-x 2 cli_user user 4096 Apr 26 19:33 sys

-rw-rw-r–– 1 cli_user user 83067 Apr 26 19:33 topo-raw.xml

-rw-rw-r–– 1 cli_user user 114457 Apr 26 19:33 topo.xml

drwxrwxr-x 6 cli_user user 4096 Apr 26 19:33 var

drwxrwxr-x 2 cli_user user 4096 Apr 26 19:33 xen

node1-primary:

total 248

drwxrwxr-x 11 cli_user user 4096 Apr 26 19:33 .

drwxrwxr-x 4 cli_user user 4096 Apr 26 19:33 ..

drwxrwxr-x 2 cli_user user 4096 Apr 26 19:33 drbd

drwxrwxr-x 4 cli_user user 4096 Apr 26 19:33 etc

drwxrwxr-x 2 cli_user user 4096 Apr 26 19:33 ha

drwxrwxr-x 2 cli_user user 4096 Apr 26 19:33 ipmi

drwxrwxr-x 3 cli_user user 4096 Apr 26 19:33 sbin

drwxrwxr-x 3 cli_user user 4096 Apr 26 19:33 shared

drwxrwxr-x 2 cli_user user 4096 Apr 26 19:33 sys

-rw-rw-r–– 1 cli_user user 83065 Apr 26 19:33 topo-raw.xml

-rw-rw-r–– 1 cli_user user 114455 Apr 26 19:33 topo.xml

drwxrwxr-x 6 cli_user user 4096 Apr 26 19:33 var

drwxrwxr-x 2 cli_user user 4096 Apr 26 19:33 xen
Managing Avance Upgrade Kits

kit-info

Display information about an upgrade kit.

avcli kit-info [kit.]Example Output avcli -u admin -p admin -H avance kit-info

kit:

-> name : unspecified

-> id : kit:o624

-> description : unspecified

-> version : R1.6.1 (svn:12345)

-> locked : true

kit-delete

Remove an upgrade kit.

avcli kit-delete

kit-upload

Upload an upgrade kit.

avcli kit-upload /var/kits/kit-avance.tar.bz2

Network/Storage Information

network-info

Display shared networks information.Usage avcli network-info [network...]

network Shared network name. Omit this argument to list shared networks on the Avance unit.Example Output [root]# avcli -u admin -p admin -H avance network-info

shared network:

-> name : priv0

-> id : sharednetwork:o84

-> fault-tolerant : ft

shared network:

-> name : network0

-> id : sharednetwork:o85

-> fault-tolerant : ft

storage-info

Display shared storage device information.Usage avcli storage-info [storage...]

storage Name or ID of a shared-storage device.Example Output [root@node1.outlaw ~]# avcli -u admin -p admin -H avance storage-info

shared storage:

-> name : shared-mirror-0001

-> id : sharedstorage:o39

-> fault-tolerant : ft

size:

-> free : 139,854,872,576

-> used : 20,145,242,112

-> total : 160,000,114,688

volumes:

volume:

-> name : boot-outlaw2

-> id : volume:o1598

-> size : 4,563,402,752

-> fault-tolerant : ft

volume:

-> name : data-outlaw2-1

-> id : volume:o1607

-> size : 2,684,354,560

-> fault-tolerant : ft

shared storage:

-> name : shared-mirror-0000

-> id : sharedstorage:o40

-> fault-tolerant : ft

size:

-> free : 59,861,106,688

-> used : 100,139,008,000

-> total : 160,000,114,688

volume-info

Display information about all volumes or optionUsage avcli volume-info [volume...]

volume Name or ID of a storage volume.Example Output [[cli_user@anna alum2]$ cli -H eagles volume-info

volume:

-> name : boot-eagles1

-> id : volume:o2006

-> size : 32,212,254,720

volume:

-> name : shared.fs

-> id : volume:o111

-> size : 1,073,741,824

volume:

-> name : win2k8_ES_std_x86_64_R2

-> id : volume:o1659

-> size : 3,221,225,472

volume:

-> name : xen-win-pv-drivers-5.5.0

-> id : volume:o108

-> size : 268,435,456

Creating Virtual CD/DVDs

media-create

Create a virtual CD (VCD) from a CD/DVD, ISO file, or URL. The VCD is installed on a shared-mirror volume in the Avance unit.Usage: avcli media-create [––shared-storage volume] [––name name] ISO location

- ––shared-storage volume

volume specifies the storage volume on which to install the ISO file. If not specified, Avance software uses the shared-mirror volume with the most free space.

––name name name specifies the name for the VCD. If omitted, Avance assigns a name based on the ISO file name.

ISO location Specifies the URL location of the ISO file.Examples
avcli media-create ––shared-storage shared-mirror-0001 ––name cd.iso http://hostname/cd.iso

avcli media-create http://hostname/cd.iso
avcli media-create http://hostname/cd1.iso http://hostname/cd2.iso

media-eject

Eject media from the specified VCDs.

avcli media-eject [––cdrom] [vm...]

––cdrom VCD to eject. Optional if the VM has a single CD/DVD-ROM device.

vm VM with the VCD.

media-info

Display VCD information.Usage avcli media-info deviceExample Output [root]# avcli media-info

iso:

-> name : xen-win-pv-drivers-4.2.0

-> id : volume:o43

-> size : 268,435,456

media-insert

Create a VCD and make available to VMs.Usage avcli media-insert ––iso [––cdrom] [virtual_machine...]

––iso ISO image to insert.

––cdrom Device to insert the VCD into. Optional if the VM has a single CD/DVD-ROM device.

virtual_machine VMs that can use the VCD.

Linux Repositories and Kickstart Scripts

repository-create

Create a new repository.Usage avcli repository-create uri

uri Uniform resource locator identifier (URI) of the repository.

repository-delete

Delete one or more repositories.

Usage avcli repository-delete repository…

repository Name or ID of the repository to delete. The repository-info command reports the names and IDs of the registered repositories.

repository-info

Report information on the registered repositories.Usage avcli repository-info [repository...]

repository Name or ID of a repository.Example [root@node1.outlaw ~]# avcli -u admin -p admin -H avance repository-info

repository:

-> name : Red Hat Enterprise Linux Server release 5.1 (Tikanga)

-> id : repository:o472

-> uri : http://yum.sn.stratus.com/rhel/5.1/os/i386

-> active : true

kickstart-create

avcli help kickstart-createUsage: avcli kickstart-create[––description][––repository]

Create a new kickstart from the specified URI.

––name Name of a kickstart file.

––description Description of the file.

––uri URI of the file.

––repository Repository the file is attached to. Automatically selected if there is only one repository.

kickstart-delete

Delete a kit.

avcli kickstart-delete <kickstart..>

kickstart Name of a kickstart file.

kickstart-info

Display kickstart file information.

[root@node1.outlaw ~]# avcli -u admin -p admin -H avance kickstart-info

kickstart:

-> name : interactive

-> repository : Red Hat Enterprise Linux Server release 5.1 (Tikanga)

-> id : template:o473

-> description : Interactive install

-> uri :

minimum-requirements:

-> storage : 0

-> console : required

-> expected-post-state : starting

kickstart:

-> name : test-appliance-kickstart-rhel51

-> repository : Red Hat Enterprise Linux Server release 5.1 (Tikanga)

-> id : template:o479

-> description : test-appliance-kickstart-rhel51

-> uri : http://build.sn.stratus.com/sn/trunk/../branches/releases/r1.5.0.hotfix/20091013-r37321/opt/kickstart/ks-test-appliance-rhel51.cfg

minimum-requirements:

-> storage : 0

-> console : optional

-> expected-post-state : starting

Managing VMs

vm-boot-attributes

Some business solutions require specific VMs to be running prior to starting other VMs. Use this command to specify the order in which VMs boot after powering on Avance or a failover which requires restarting VMs. Priority “1″ is the highest priority and those VMs are started first. Then priority “2″ and so on. The “application-start-time” should be set to the time it takes from starting the VM until the time the application is fully functional.

Usage

Set the boot attributes for the specified virtual machines.

avcli vm-boot-attributes>> [virtual machines...]

––priority priority from 1 to 1000

––application-start-time estimate start time of the VM and application in

minutes, minimum value is one minute

Examples:

$ avcli vm-boot-attributes ––priority 1 ––application-start-time 1 vm1

$ avcli vm-boot-attributes ––priority 1 ––application-start-time 1 vm:o100

vm-crash

Force a VM to crash. Use to collect and analyze a dump for a hung VM.Usage avcli vm-crash [virtual_machines...]

virtual_machines Names or IDs of the VMs, from vm-info.Examples
$ avcli vm-crash vm1

$ avcli vm-crash vm1 vm2

$ avcli vm-crash vm1 vm:o100

vm-create

Create a VM.Usage avcli vm-create[––interfaces] [––shared-storage]

––name VM Name.

––cpu Number of virtual CPUs in the VM.

––memory Memory (in MB) for the VM.

––cdrom CD-ROM for creating the VM. This cannot be combined with ––kickstart.

––kickstart Kickstart template for creating the VM. This cannot be combined with ––cdrom.

––interfaces Networks to attach to this VM. A network can be specified only once, and must not be private.

––shared-storage Shared storage to use for VM volumes. If not specified, the shared storage with the most free space is automatically selected.

––volumes Volumes to attach to this VM. Use this format:

Volume_size, [shared_storage_name volume_name]

Volume size defaults to MB, but use standard qualifiers for larger sizes.ExamplesVM named vm001 with one CPU and 512 MB memory, attached to network0, with a 1,024 MB volume:

$ avcli vm-create ––name vm001 ––cpu 1 ––memory 512 ––cdrom linux.iso
––interfaces network0 ––volumes 1024

VM named vm001 with one CPU and 512 MB memory, attached to network0, with a 1,024 MB volume, allocating from shared-mirror-0001, allowing Avance to generate the volume name:

$ avcli vm-create ––name vm001 ––cpu 1 ––memory 512 ––cdrom linux.iso
––interfaces netowrk0 ––volumes 1024 ––shared-storage shared-mirror-0001

VM named vm001 with one CPU and 512 MB memory, attached to network0, with a 1,024 MB volume named vm001_vol0, allocating from shared-mirror-0001:

$ avcli vm-create ––name vm001 ––cpu 1 ––memory 512 ––cdrom linux.iso ––interfaces network0 ––volumes 1024,shared-mirror-0001,vm001_vol0

VM named vm001 with one CPU and 512 MB memory, attached to network0 and network1, with a 10 GB volume and a 50 GB volume, allocating from shared-mirror-0001 and shared-mirror-0002, respectively:

$ avcli vm-create ––name vm001 ––cpu 1 ––memory 512 ––cdrom linux.iso
––-interfaces network0 network1 ––volumes 10GB,shared-mirror-0001 50GB,shared-mirror-0002

VM based on a kickstart template:

$ avcli vm-create ––name vm001 ––cpu 1 ––memory 512 ––kickstart template:o81 ––interfaces network0 ––volumes 10GB

vm-delete

Delete stopped VMs and optionally any attached volumes.

Usage

vm-delete [––volumes] <virtual_machines…>

virtual_machinesName or ID of the VMs from vm-info.

Examples

avcli vm-delete vm1

avcli vm-delete ––volumes vm1

avcli vm-delete ––volumes vm1 vm2

vm-dump

Dump the memory of a VM.Usage avcli vm-dump [virtual_machines...]

virtual_machines Name or ID of the VM from vm-info.Examples
$ avcli vm-dump vm1

$ avcli vm-dump vm1 vm2

$ avcli vm-dump vm1 vm:o100

vm-info

Display VM information.Usage avcli vm-info [virtual machine...]

virtual machine Name or ID of the VM.Example Output $ avcli vm-info

$ avcli vm-info vm1

$ avcli vm-info vm1 vm:o100

VM:

-> name : avance2

-> id : vm:o1624

-> uuid : fcddadc4-a34b-4733-b833-1bb917d8b8c7

-> cpus : 3

-> memory : 2,117,074,944

-> state : running

-> fault-tolerant : ft

interfaces:

interface:

-> shared network : network0

-> MAC : 00:04:fc:40:32:01

volumes:

volume:

-> name : boot-outlaw2

-> id : volume:o1598

-> size : 4,563,402,752

-> device : xvda

-> device-id : vbd:o1627

volume:

-> name : data-outlaw2-1

-> id : volume:o1607

-> size : 2,684,354,560

-> device : xvdb

-> device-id : vbd:o1626

volume:

-> name : data-outlaw2-0

-> id : volume:o1616

-> size : 2,684,354,560

-> device : xvdc

-> device-id : vbd:o1625

VM:

-> name : avance1

-> id : vm:o491

-> uuid : 7718d9da-6cb5-4d52-839f-e6b8b81b82d4

-> cpus : 1

-> memory : 536,870,912

-> state : running

-> fault-tolerant : ft

interfaces:

interface:

-> shared network : network0

-> MAC : 00:04:fc:40:32:00

volumes:

volume:

-> name : boot-outlaw1

-> id : volume:o484

-> size : 4,563,402,752

-> device : xvda

-> device-id : vbd:o492

volume:

-> name : data-outlaw1-huge

-> id : volume:o588

-> size : 78,651,588,608

-> device : xvdb

-> device-id : vbd:o604

vm-poweroff

Power off a VM immediately. Similar to disconnecting the power cord from a PM. Last resort only: use the vm‑shutdown command instead.Usage avcli vm-poweroff virtual_machine…

virtual_machine Name or ID of the VM from vm-info.Examples
$ avcli vm-poweroff vm1

$ avcli vm-poweroff vm1 vm2

$ avcli vm-poweroff vm1 vm:o100

vm-poweron

Power on a VM. Note that if a VM may fail to power on if there are inadequate resources such as VCPU or Memory. It may also fail to start if it is locked. Note that a VM is locked for the duration of an export, import or restore operation. This lock prevents a user from trying to start a VM while either of these operations are in progress. Should the operations fail unexpectedly the VM will remain locked. To restart the VM, it must first be explicitly unlocked with the the vm-unlock command is required before it can be successfully powered on.Usage avcli vm-poweron virtual_machine…

virtual_machine Name or ID of the VM from vm-info.Examples $ avcli vm-poweron vm1

$ avcli vm-poweron vm1 vm2

$ avcli vm-poweron vm1 vm:o100

vm-reprovision

Reprovision a single stopped VM.
Usage
avcli vm-reprovision [––cpu #] [––memory #] [––addVolumes] [––deleteVolumes] [––keepVolumes] [––interfaces]

––cpu Number of virtual CPUs to assign to the VM.

––memory Memory (in MB) to assign to the VM.

––shared-storage Shared storage for the VM. If omitted, the shared

storage with the most free space is automatically selected.

––addVolumes New volumes to attach to the VM. Use this format:

Volume_size, [shared_storage_name volume_name] Volume

size defaults to MB, but use standard qualifiers for larger sizes.

––deleteVolumes Names or IDs of volumes to detach from the VM, from

vm-info.

––keepVolumes Names or IDs of volumes to keep attached to the VM,

from vm-info. If a currently attached volume is not listed here, it will be detached but not destroyed.

––interfaces Additional networks to attach to the VM. A network

can be specified only once, and must not be private.

––name Name or ID of the VM to reprovision.Examples $ avcli vm-reprovision ––cpu 2 ––name vm1

$ avcli vm-reprovision ––cpu 2 ––name vm:o100

$ avcli vm-reprovision ––cpu 2 ––memory 2048 ––name vm:o100

Reprovision vm001, with one CPU and 512 MB memory, attached to network0, with a 1,024 MB volume named vm001_vol0, allocated from shared‑mirror-0001:

$ avcli vm-reprovision ––cpu 1 ––memory 512 ––interfaces network0

––addVolumes 1024,shared-mirror-0001,vm001_vol0 ––name vm1

Reprovision vm1 by deleting volumes volume:o411, data-vm1, and data-vm2:

$ avcli vm-reprovision ––deleteVolumes volume:o411 data-vm1 data-vm2
––name vm1

Reprovision vm1 by adding a data volume named data-1-7, deleting the volume volume:o1043, keeping volumes volume:o1, volume:o2, volume:o4, and attaching network interfaces sharednetwork:o129 and sharednetwork:o130:

$ avcli vm-reprovision ––cpu 3 ––memory 3359 ––addVolumes 2500,sharedstorage:o54,data-1-7 ––deleteVolumes volume:o1043
––keepVolumes volume:o1 volume:o2 volume:o4 ––interfaces sharednetwork:o129 sharednetwork:o130 ––name vm1

vm-shutdown

Gracefully shut down a VM. Similar to the Shutdown command in the OS. If a VM cannot be shut down cleanly, this command fails.
Usage
avcli vm-shutdown virtual_machine…

virtual_machine Names or IDs of the VMs from vm-info.Examples $ avcli vm-shutdown vm1

$ avcli vm-shutdown vm1 vm2

$ avcli vm-shutdown vm1 vm:o100

vm-export

Completely back up a stopped VM to an external directory. The entire VM can then be restored to this server with the vm-restore or vm-import commands. The VM can also be migrated to another Avance server with the vm-import command.

Note that a VM is locked for the duration of an export. This lock prevents a user from trying to start a VM while the export is in progress. Should the export fail and the VM needs to be restarted a vm-unlock command is required before issuing a vm-poweron command.
Usage:
avcli vm-export [––throttle] [––folder /path/exported-vms/vm1]

Export the specified virtual machine.

––name name or id of the virtual machine to export

––folder destination folder, defaults to the name of the VM.

––use-snapshot export using VM’s snapshot. Snapshot has to pre-

exist. When exporting using a snapshot, complete

snapshot is exported and you cannot use ––config-only

or ––data options.

––silent suppress output

––config-only use this option if you only want to export VM’s

configuration but no data. This option is not valid

when using ––use-snapshot.

––data use this option to export data only for the given

volumes.

This option is not valid when using ––use-snapshot.

––description user specified description for this export

––throttle use this option to slow down the import/export

operation.

Valid values are: none (do not use throttling), low

(slow down by about 25%), medium (slow down by about

50%) and high (slow down by about 75%). Default

value is none.

––compress this enables server side compression (i.e. gzip) of

the exported volume data. By default compression is

Off. Please note that compression is very CPU

intensive and might slow down your export by a factor

of 3 or more in some cases.

––use-https by default data is streamed over HTTP transport. Use

This option to use secure HTTPS transport instead.

Please note that streaming over HTTPS will give

slower performance than HTTP. But if you are

concerned about security, you should use this option.

Examples:

$ avcli vm-export ––name vm1

$ avcli vm-export ––folder /path/exported-vms/vm1 ––name vm1

$ avcli vm-export ––config-only ––name vm1

$ avcli vm-export ––compress ––use-https ––throttle low ––name vm1

$ avcli vm-export ––use-snapshot ––throttle high ––name vm1

$ avcli vm-export ––data volume1 volume2 ––name vm1

vm-import

Create a VM from the exported files generated by vm-export, or from an OVF file archive created by the XenConvert tool according to the instructions in the document Avance P2V, V2V and Cloning.

You can override default settings for cpu, memory, network, and storage assignments. vm-import uses meta-data from the archive to map the VM onto the Avance server. If the meta-data is missing, the command uses an algorithm to map network and disk resources.

When assigning shared networks to interfaces, or volumes to shared storage, every value must be specified. For example, if a VM has three disks, the –volumes option must specify three shared mirrors. Do not assign CD-ROMS when assigning volumes to shared mirrors. You can add interfaces to an imported VM by specifying additional shared network names.

Note: that a VM is locked for the duration of an import. This lock prevents a user from trying to start a VM while the import is in progress. Should the import fail and the VM needs to be restarted a vm-unlock command is required before issuing a vm-poweron command.
Usage
avcli vm-import [––name] [––throttle]

Import a virtual machines from an OVA or OVF VM archive file.

––archive OVA or OVF file archive to import

––no-auto-start if set, the VM is not started after import has

finished

––cpu number of CPU’s to assign to the imported VM,

Defaults to the amount in the archive.

––dry-run do not actually import a virtual machine, but show

The interface to shared network, and volume to shared mirror assignments.

––shared-storages list of shared mirrors to use for allocating VM’s

volumes, defaults to all available shared mirrors.

Allocation is done in a round robin fashion.

––interfaces list of shared networks to assign to the VM’s

interfaces, defaults to values in the archive, or the shared networks in alphabetical order.

––memory size of memory in MB to assign to the imported VM,

defaults to the amount in the archive.

––name name of the virtual machine, defaults to name of the

File directory minus the extension (.ova).

––data when specified, data is imported only for these

volumes.

––throttle limit the bandwidth between AVCLI and Avance to the

Throttle value as a percentage of available bandwidth. Valid throttle values are none, low, medium, and high, the default is none.

––volumes only import these volumes. If this optional argument is not specified, all available volumes from the OVF are imported.

Defaults to values in the archive, or round-robin assignment of shared mirrors.

––remap-volumes When specified, the vm-import operation will first attempt to remap all volumes to the shared-mirrors as defined in the archive.

After that the rules for ––volumes and ––shared-storages rules will be in effect.

––force when the OVF file is missing the isBootable flag (a

known Issue for XP) assume that the VHD pointed to by OVF is the bootable one.

––use-https by default data is streamed over HTTP transport, use

this option to use secure HTTPS transport instead.

Please note that streaming over HTTPS will give slower performance HTTP. But if you are concerned about security, you should use this option.

Assignment:

When assigning shared networks to interfaces or volumes to shared storage, every value must specified. If a VM has three disks, than the “—volumes” option must be passed the names of three shared mirrors. Likewise, this is true of interface assignments.

Interfaces can be added to a imported virtual machine by specifying additional shared network names. Additional volumes cannot be added in this manner. When assigning volumes to shared mirrors, no assignment should be provided for CD-ROM’s.

Examples:

$ avcli vm-import ––archive vm1.ova

$ avcli vm-import ––archive vm1.ovf

$ avcli vm-import ––name myVM ––throttle low ––archive vm1.ovf

$ avcli vm-import ––cpu 2 ––memory 1024 ––archive vm1.ovf

$ avcli vm-import ––interfaces network0 network1 ––archive vm1.ovf

$ avcli vm-import ––shared-storages sm-0000 sm-0001 ––archive vm1.ovf

$ avcli vm-import ––volumes boot_vol vol3 ––data vol3 ––archive vm1.ovf

vm-restore (R2.0.x)

A streamlined version of vm-import, restricted to importing a VM exported from the Avance server. Cannot retarget disks or networks, or adjust VCPUs or memory.

For a faster restore, run —throttle node (default). Throttle only when restoring a node while other VMs are running critical applications. Running —throttle high requires the fewest resources, and takes longer.

Note: that a VM is locked for the duration of a restore. This lock prevents a user from trying to start a VM while the restore is in progress. Should the restore fail and the VM needs to be restarted a vm-unlock command is required before issuing a vm-poweron command.
Usage
avcli vm-restore [––no-auto-start] [––cpu] [––memory] [––name]

[––shared-storages] [––interfaces] [––data]

[––dry-run] [––throttle] [––use-https]

––archive OVA or OVF file archive to import or restore.

––no-auto-start if set, the VM is not started after import/restore

Has finished.

––cpu number of CPU’s to assign to the VM, defaults to the

Amount in the archive.

––memory size of memory in MB to assign to the VM, defaults to

The value in the archive.

––name name to assign to the VM, defaults to the value in

The archive.

––shared-storages list of shared mirrors to use for allocating VM’s

volumes, defaults to all available shared mirrors.

Allocation is done in a round robin fashion.

––interfaces list of shared networks to assign to VM’s interfaces,

defaults to values in the archive or available shared

networks.

––data when specified, data is imported only for these

volumes.

––silent suppress output

––dry-run do not actually import/restore a virtual machine, but

Show the interface to shared network, and volume to

shared mirror assignments.

––throttle use this option to slow down the import/export

operation. Valid values are: none (do not use

throttling), low (slow down by about 25%), medium

(slow down by about 50%) and high (slow down by about

75%). Default value is none.

––use-https by default data is streamed over HTTP transport. Use

this option to use secure HTTPS transport instead.

Please note that streaming over HTTPS will give

slower performance than HTTP. But if you are

concerned about security, you should

use this option.
Examples:
$ avcli vm-restore ––archive vm1.ova
$ avcli vm-restore ––archive vm1/vm1.ovf
$ avcli vm-restore ––name myVM ––throttle low ––archive vm1.ovf
$ avcli vm-restore ––cpu 2 ––memory 1024 ––archive vm1.ovf
$ avcli vm-restore ––interfaces network0 network1 ––archive vm1.ovf
$ avcli vm-restore ––shared-storages sm-0000 sm-0001 ––archive vm1.ovf
$ avcli vm-restore ––data vol1 vol3 ––archive vm1.ovf

vm-unlock (R2.0.x)

This command allows the user to release a lock that might be preventing a VM from being “started”. The lock is created for the duration of a vm-export, vm-import, or vm-restore command. It is intended to prevent the VM from being started while the export, import, or restore operation is in process. In the event that either of these commands fails unexpectedly, the VM will remain locked. The VM must be unlocked with this command prior to being able to successfully start the VM with the vm-poweron command.

vm-snapshot-info (R3.0.x)

This command provides all of the basic information for snapshots on the unit. Here is an example of the output.Usage: avcli vm-snapshot-info vm-snapshot:

-> id : vmsnapshot:o188697

-> creation time : 7/20/12 6:33 AM

-> vm name : mexico2

-> snapshot name : mexico2

-> snapshot state : broken

-> standing-state : broken

-> ft-state : not_ft

-> cpus : 11

-> memory : 8,673

interfaces:

interface:

-> shared network : network0

-> MAC : 00:04:fc:00:c4:c1

volumes:

volume:

-> volume size : 21,474,836,480

-> volume name : boot-mexico2

-> shared storage : shared-mirror-000104

-> snapshot id : volumesnapshot:o188684

volume:

-> volume size : 4,294,967,296

-> volume name : data-mexico2-2

-> shared storage : shared-mirror-000101

-> snapshot id : N/A

volume:

-> volume size : 4,294,967,296

-> volume name : data-mexico2-1

-> shared storage : shared-mirror-000104

-> snapshot id : volumesnapshot:o188693

volume:

-> volume size : 4,294,967,296

-> volume name : data-mexico2-0

-> shared storage : shared-mirror-000101

-> snapshot id : N/A

vm-snapshot-create (R3.0.x)

This command is used to create a snapshot. By default all meta-data and volumes are included in the snapshot.Usage: avcli vm-snapshot-create [––volumes] [––description] Create a Virtual Machine snapshot. The VM must be powered off before snapshotting.

––name names/id of the virtual machine

––description user specified description for this snapshot

––volumes names of volumes to include in the snapshot. If not

specified all volumes are included in the snapshot.
Examples:
$ avcli vm-snapshot-create ––name vm1

$ avcli vm-snapshot-create ––name vm1 ––volumes volume:o100 volume:o101

vm-snapshot-delete (R3.0.x)

Usage: avcli vm-snapshot-delete] Delete the specified snapshots. Snapshots can be specified by name or id.
Examples:
$ avcli vm-snapshot-delete vmsnapshot:o100 vmsnapshot:o101

$ avcli vm-snapshot-delete carol1

Configuring Universal Power Supplies (UPS)

ups-config (R2.0.x)

Configure external or internal UPS monitoring.

Usage: avcli ups-config

ups-disable (R2.0.x)

Disable UPS monitoring.

Usage: avcli ups-disable

ups-info (R2.0.x)

Display UPS configuration information.

Usage: avcli ups-info

Appendix A: Simple Bash Script to Backup a VM

#!/bin/bash

# DESCRIPTION: Stops VM, backs it up, and the Restarts VM when it is done.

# Input Parameters.

avance_unit=$1

vm=$2

# some useful variables that can be customized.

avance_user=’admin’

avance_passwd=’admin’

# This should be the pathname to the AVCLI jar on your VM

avcli=”java -jar /test_logs/builds/sn/branches/dev/alum-dev/current/sm/java/yak/dist/avcli.jar -H $avance_unit -u $avance_user -p $avance_passwd”

archive=”./$avance_unit”-”$vm.ova”

echo “archive === $archive”

echo “”

echo “stopping the VM ($vm)…”

echo “$avcli ––log ./avcli.log vm-shutdown ––wait $vm”

$avcli vm-shutdown ––wait $vm

echo “”

echo “backing up the VM ($vm) to ($archive)…”

echo “$avcli ./avcli.log vm-export ––archive $archive $vm”

$avcli vm-export ––archive $archive $vm
echo “”
echo “starting the VM ($vm)…”
echo “$avcli ./avcli.log vm-poweron ––wait $vm”
$avcli vm-poweron ––wait $vm

exit 0

Appendix B: Sample AVCLI Scripts

Each AVCLI distribution includes three sample Perl scripts and a Linux bash script. The Perl scripts validate each command and return an error if any underlying command fails to execute correctly.

vm_backup.sh – stop VM, back up, and restart
shutdown.pl – shut down an Avance unit
buggrab.pl – grab a diagnostic from an Avance unit, and optionally explodes it
avanceUpgrade.pl – remotely upgrade an Avance unit

For Linux, these scripts requires Perl v5.8.5 or later. Windows requires version 5.10.1 or greater. Download the ActivePerl interpreter for Windows here:

http://www.activestate.com/activeperl/.

These scripts are part of the installation:

Linux: /usr/share/avance/avcli/sample_avcli_scripts/
Windows: C:\Program Files\Avance\sample_avcli_scripts\

Each script includes a set of variables at the top that can be used for customization.

# Set these variables for your local setup
my $opt_avcli = “avcli”;
my $opt_user = “admin”;
my $opt_password = “admin”;

$opt_avcli launches the AVCLI utility. In Windows, include the pathname to the AVCLI utility in the search path:

path = %path%;c:\Program Files\Avance

buggrab.pl

SYNOPSIS
buggrab.pl

buggrab.pl ––help

buggrab.pl ––unit––size minimal

buggrab.pl ––unit––u––p––size fullDESCRIPTION Create and download a diagnostic buggrab. Optionally attach expand it,

and optionally attach it to a fogbugz case. A logfile with

verbose messaging is generated in “buggrab-.log. This

log includes all AVCLI commands issued and their responses in XML

format.
ARGUMENTS
––help
Display this message and exit.
––H name
Specify the DNS name or IP address of the Avance unit in dotted

decimal notation (avance or 134.111.24.3). Other optional aliases:

––h, ––host, ––unit, and ––dut.
––u username
Specify Avance username (default: admin). Other optional aliases:

––user or ––username.
––p password
Specify Avance Host password (default: admin). Other optional

aliases: pass or ––password.
––id buggrab:oXXXXXX
Skip creation and grab a known diagnostic,

references as a buggrab OID (returned by diagnostic-info).
––size size
Size of diagnostic: minimal, medium, stats, full (default).
––unzip
Unzip the downloaded zip file.

. Verified only for Linux AVCLI client.

avanceUpgrade.pl

SYNOPSIS
avanceUpgrade

avanceUpgrade ––help

avanceUpgrade ––unit––isoDESCRIPTION avanceUpgrade.pl is passed arguments that identify a unit and the pathname

to an upgrade ISO image. If upgrading an HP platform, the script

can take an optional directory path containing the HP

Tools Media RPMS. The script generates output to the

Console. For example:

––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––

Jan 01 18:22:40 [ upgr-apple] *** STATE: INIT ****
Jan 01 18:22:40 [ upgr-apple] Upgrading “apple”, check communication path
Jan 01 18:22:45 [ upgr-apple] Check for valid pathname to iso … “/test…
Jan 01 18:22:51 [ upgr-apple] The Primary PM is “node0″
Jan 01 18:22:51 [ upgr-apple] First Node to be upgraded will be “node1″, ..
Jan 01 18:22:53 [ upgr-apple] *** STATE: UPLOAD-ISO ****
Jan 01 18:22:53 [ upgr-apple] Pushing the Upgrade ISO to the Avance unit ..
Jan 01 18:24:24 [ upgr-apple] *** STATE: WORKON-1ST-PM ****
Jan 01 18:24:24 [ upgr-apple] node1 will be placed in maintenance mode so ..
Jan 01 18:24:45 [ upgr-apple] node0 is in state normal, waiting for it to ..
Jan 01 18:25:07 [ upgr-apple] node1 is in state maintenance, waiting for …
Jan 01 18:25:09 [ upgr-apple] *** STATE: UPGRADE-1ST-PM ****
Jan 01 18:25:09 [ upgr-apple] Upgrading “node1″ [1st PM] using kit:o2174
Jan 01 18:25:43 [ upgr-apple] busy: (% done) Waiting for PM to PXE boot f..

––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––-

A logfile with verbose messaging is generated in

“upgrade-.log. This log includes all AVCLI commands issued and their responses in XML format.
ARGUMENTS
––help
Display this message and exit.
––H name
Specify the DNS name or the IP address of the Avance unit in dotted

decimal notation (i.e. avance or 134.111.24.3). Optional aliases:

are ––h, ––host, ––unit, and ––dut.
––u username
Specify Avance username; default is “admin”. Optional aliases:

are ––user or ––username.
––p password
Specify Avance Host password; default is “admin”. Optional

Aliases: pass or ––password.
––iso filename
Specify upgrade ISO path/filename.
––hputils dirname
An upgrade of an HP platform requires new HP utilities

to be loaded that are not distributed with the upgrade ISO. This

option allows the user to specify a local directory path

containing these tools. Each component file in this

directory is uploaded before beginning an upgrade. An optional

alias is ––firmware. Note that if “––hputils 1 is specified then the

default hputils in the trunk/current sandbox are used.
––kit kit:oXXX
Specifies an ISO that already exists on the Avance unit as a “kit”.

When specifying the kit, use the form “kit:oXXX”, from the AVCLI

“kit-info” command.
––kitonly
The script exits after the “kit” (and optionally the

“hputils”) have been uploaded. No upgrade is performed.
––avcli “cmd name”
The script expects the default “avcli” to be available in

your path or search list. This specifies an optional AVCLI name. For example:

––avcli “java -jar /sandbox/cli_user/dev/sm/yak/src/avcli.jar”

shutdown.pl

SYNOPSIS
shutdown.pl ––help

shutdown.pl -HDESCRIPTION This script illustrates how to issue an Avance shutdown command. The script exits when the command is issued, not when the unit is shut down. You can augment this to continually ping the unit but not return until ping responses terminate.
ARGUMENTS
––help
Display this message and exit.
––H name
Specify the DNS name or the IP address of the Avance unit in dotted

decimal notation (i.e. avance or 134.111.24.3). Other optional aliases

are ––h, ––host, ––unit, and ––dut.

vm_backup.sh

This Linux bash script requires two parameters: Avance unit, and the VM to backup. It performs the following steps:

Stops the VM
Backs up the VM
Re-Starts the VM

The script prints the progress of each step to stdout.

––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––

#!/bin/bash
# DESCRIPTION: Stops VM, backs it up, and the Restarts VM when it is done
#
# Input Parameters.
avance_unit=$1
vm=$2
# some useful variables that can be customized based on your installation
avance_user=’admin’
avance_passwd=’admin’
# This should be the pathname to the AVCLI jar on your VM
avcli=”java -jar /test_logs/builds/sn/branches/dev/alum-dev/current/sm/java/yak/dist/avcli.jar -H $avance_unit -u $avance_user -p $avance_passwd”
archive=”./$avance_unit”-”$vm.ova”
echo “archive === $archive”
echo “”
echo “stopping the VM ($vm)…”
echo “$avcli ––log ./avcli.log vm-shutdown ––wait $vm”
$avcli vm-shutdown ––wait $vm
echo “”
echo “backing up the VM ($vm) to ($archive)…”
echo “$avcli ./avcli.log vm-export ––archive $archive $vm”
$avcli vm-export ––archive $archive $vm
echo “”
echo “starting the VM ($vm)…”
echo “$avcli ./avcli.log vm-poweron ––wait $vm”
$avcli vm-poweron ––wait $vm
exit 0

Avance Command Line Interface Reference

Table of Contents

Download AVCLI

What is New

Version 4.0.0.1

Version 4.0.0.0

Version 3.1.1.0

Version 3.1.0.0

Version 3.0.0.0

Version 2.1.3.1

Version 2.1.3

Version 2.1.2

Installing the AVCLI Client

Verifying the Java Runtime Library version

Installing for Windows

AVCLI for Windows

Installing the RHEL Client

AVCLI for RHEL

Installing the Ubuntu 12.04 Client

AVCLI for Ubuntu 12.04

Quick Start

AVCLI Command Overview

Getting Help

Authentication and Security

Basic Command Syntax

AVCLI Output

Program Friendly – XML Output

AVCLI Error Status

Usage Errors – Command Syntax

AVCLI Exceptions

XML Encapsulated Errors

Catching errors programmatically

Pausing for Asynchronous Commands

Creating login shortcuts

Linux

Windows

Basic System Information/Commands

avance-eula-accept

avance-eula-reset

avcli avance-eula-reset

avance-set-dom0-memory

audit-export

avance-info

avance-shutdown

avance-shutdown-cancel

avance-shutdown-state

audit-info

System Configuration

callhome-disable

callhome-enable

callhome-info

dialin-disable

dialin-enable

dialin-info

ealert-config

ealert-disable

ealert-enable

ealert-info

license-info

license-file

ntp-config

ntp-disable

datetime-config

proxy-config

proxy-disable

proxy-enable

proxy-info

snmp-config

snmp-disable

snmp-info

System User Management

ad-join

ad-disable

ad-enable

ad-info

ad-remove

local-user-add

local-user-delete

local-user-edit

local-user-info