VMware has ended active development of this project, this repository will no longer be updated.¶ ↑

RVC - Ruby vSphere Console¶ ↑

Introduction¶ ↑

RVC is a console UI for VMware ESX and VirtualCenter. The vSphere object graph is presented as a virtual filesystem, allowing you to navigate and run commands against managed entities using familiar shell syntax. RVC doesn't (yet) have every feature vSphere Client does, but for common tasks it can be much more efficient than clicking through a GUI.

Installation¶ ↑

gem install rvc

To upgrade to the latest version: gem update rvc

Usage¶ ↑

% rvc 192.168.1.105
username: Administrator
password:
0 dc (datacenter)
192.168.1.105:/> cd dc/host/192.168.1.100/
192.168.1.105:/dc/host/192.168.1.100/> ls
0 host [192.168.1.100] (host): cpu 2*2*2.81 GHz, memory 2.00 GB
1 resourcePool [Resources]: cpu 4.35/4.35/normal, mem 0.48/0.48/normal
192.168.1.105:/dc/host/192.168.1.100/> ls host/vms/
0 foo: poweredOn
192.168.1.105:/dc/host/192.168.1.100/> i host/vms/foo
name: foo
host: dc/host/192.168.1.100/192.168.1.100
tools: guestToolsNotRunning
VC UUID: 5259d5d2-b767-43c9-db6d-fbf5cc4b6f02
power: poweredOn
cpus: 1
memory: 128 MB
nics:
 Network adapter 1: "VM Network" connected 00:0c:29:c6:5d:2a 
192.168.1.105:/dc/host/192.168.1.100/> off host/vms/foo
PowerOffVM foo: success
192.168.1.105:/dc/host/192.168.1.100/> quit

Enter “help” to see a list of all available commands.

All RVC commands exist in modules, and may optionally have aliases. For example, the command to power off a VM is actually “vm.off”, since it exists in the “vm” module, but since it is a common operation it has been aliased to “off”.

Paths¶ ↑

All vm operations need a full path, or relative path, rather than just the name of the resource. So to create a VM you would use:

/> vm.create -p /vm1/ha/host/hosta/resourcePool/pools/dev/ -d /vm1/ha/datastore/datastore1 /vm1/ha/vms/newvm

Features¶ ↑

Tab-completion¶ ↑

Commands and paths can be tab completed in the usual fashion. Whitespace must be escaped with a backslash.

Wildcards¶ ↑

Many commands such as “vm.on” can operate on multiple objects at once. RVC supports simple globbing using “*” as well as advanced regex syntax. To use a regex, prefix the path element with “%”. For example: “vm.on myvms/%^(linux|windows)” will power on VMs whose names start with “linux” or “windows” in the “myvms” folder. Note that it is necessary to explicitly anchor the pattern with “^” and “$” if you wish to match the whole path element.

Marks¶ ↑

192.168.1.105:/> mark a dc/vm/foo
192.168.1.105:/> on ~a
PowerOnVM foo: success
192.168.1.105:/> off ~a
PowerOffVM foo: success

Marks allow you to save a path for later use. Refer to a mark by prefixing its name with a tilde. The “ls” command automatically creates numeric marks for each object listed; these are the numbers in the first column. As a special case, you don't need to use a tilde with numeric marks. The “cd” command automatically creates the mark “~~” pointing to the previous directory. If a mark reference is input instead of a command then RVC will cd to the marked object. Thus, “~~” is a convenient way to toggle between two directories.

When the working directory is a descendant of a Datacenter object, the mark “~” refers to the Datacenter. For example “~/datastore” is a convenient way to get the datastore folder of the current datacenter.

Aggregate marks¶ ↑

More than one object can be given to the “mark” command. The resulting mark can be used with any command that accepts multiple objects. The “mark.edit” command opens up an editor showing the objects referenced by the given mark and allows you to remove some or add more.

Ruby mode¶ ↑

Beginning an input line with “/” causes RVC to treat it as Ruby code and eval it. This gives you direct access to the underlying RbVmomi library. If the line “//” is input then RVC will toggle between shell and Ruby mode.

Marks can be easily used in Ruby mode since there are magic variables with the same names. Since some marks, like numeric ones, aren't valid variable names, they also exist with a “_” prefix. By default only the first object in an aggregate mark will be returned; to get an array of them all use the '!' suffix.

The methods “this”, “conn”, and “dc” are provided in Ruby mode, returning the current object, connection, and datacenter respectively. The connection object is an instance of RbVmomi::VIM.

VMODL introspection¶ ↑

The “type” command can be used to display the properties and methods of a VMODL class. For example: “type Datacenter”.

In Ruby mode, a '#' at the end of the input line will display the output of the “type” command for the resulting object's class. This is very useful for exploring the vSphere API.

Multiple connections¶ ↑

RVC can connect to more than one ESX or VC server at the same time. Simply add more hosts to the command line, or use the command “connect”. Each connection is represented by a top-level node in the virtual filesystem. If more than one host is given on the command line, RVC will start in the root of the filesystem instead of automatically cd'ing to a connection.

VNC Clients¶ ↑

OSX¶ ↑

Using homebrew github.com/mxcl/homebrew install tiger-vnc using the command “brew install tiger-vnc”

this will allow you to use the vnc.view command

Extensibility¶ ↑

RVC is designed to let users easily add commands they need. You can create a command module, or add to an existing one, by adding a Ruby file to ~/.rvc or any directory on the RVC_MODULE_PATH environment variable. The syntax of a user command module is the same as those built-in to RVC, so see the “lib/rvc/modules” directory for examples.

If you create a generically useful RVC command, please consider sending in a patch so everyone can use it.

Development¶ ↑

Send patches to rlane@vmware.com, or fork the project on GitHub and send me a pull request. RVC developers hang out in #rvc on Freenode.