Ruby vSphere Console

Version: 1.1.0 | File Size: 54.5 KB | Upload Date: 04/8/2011

This fling is covered under the MIT License.

32,273 views

(17 votes)

Tags: ESX, Gem, RbVmomi, Ruby, VirtualCenter, vSphere

Summary
System Requirements
Instructions

Ruby vSphere Console (RVC) is a Linux console UI for vSphere, built on the RbVmomi bindings to the vSphere API. 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.

Features

Tab Completion
Commands and paths can be tab completed in the usual fashion. Whitespace must be escaped with a backslash.
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.
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.

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.
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.

Ruby 1.8.7+, preferred version is 1.9.2.

gem install 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".

Comments

vSphere 5 support?
Sean Clark says:

Is this supported with vSphere 5? I tried to connect to my vSphere 5 VC and no love. I'm running ruby 1.9.2p290 on WinXP.

from C:/Ruby192/bin/rvc:19:in `load'

C:\ruby>rvc a... Show more

Is this supported with vSphere 5? I tried to connect to my vSphere 5 VC and no love. I'm running ruby 1.9.2p290 on WinXP.

from C:/Ruby192/bin/rvc:19:in `load'

C:\ruby>rvc administrator:Molly1834@192.168.1.200
0 ProtectedDC (datacenter)
C:/Ruby192/lib/ruby/gems/1.9.1/gems/rvc-1.6.0/bin/rvc:161:in `trap': unsupported
signal SIGCHLD (ArgumentError)
from C:/Ruby192/lib/ruby/gems/1.9.1/gems/rvc-1.6.0/bin/rvc:161:in `'
from C:/Ruby192/bin/rvc:19:in `load'
from C:/Ruby192/bin/rvc:19:in `'

C:\ruby> Show less

March 3, 2012 at 12:17 am | Reply
- Mike says:
  
  The new RVC 1.6 works great in ESX/ESXi 4.x and 5.x for me.
  
  Wow I really like 1.6!
  
  March 29, 2012 at 8:09 am | Reply
  - Mike says:
    
    (Er, vSphere 4.x / 5.x....)
    
    March 29, 2012 at 8:10 am | Reply
VDS fails for cisco 1000V?
Cere Davis says:

The following command fails for VDS on my system. Perhaps related to Cisco 1000V switch being used as the VDS?

10.42.101.181/DC_3X2/networks/VSJ3X2N1KVSM01> vds.summarize VSJ3X2N1KVSM01
NoMeth... Show more

The following command fails for VDS on my system. Perhaps related to Cisco 1000V switch being used as the VDS?

10.42.101.181/DC_3X2/networks/VSJ3X2N1KVSM01> vds.summarize VSJ3X2N1KVSM01
NoMethodError: undefined method `name' for nil:NilClass
/var/lib/gems/1.8/gems/rvc-1.6.0/lib/rvc/extensions/DistributedVirtualPortgroup.rb:293:in `translate_respool'
/var/lib/gems/1.8/gems/rvc-1.6.0/lib/rvc/extensions/DistributedVirtualSwitch.rb:101:in `summarize'
/var/lib/gems/1.8/gems/rvc-1.6.0/lib/rvc/extensions/DistributedVirtualSwitch.rb:99:in `each'
/var/lib/gems/1.8/gems/rvc-1.6.0/lib/rvc/extensions/DistributedVirtualSwitch.rb:99:in `summarize'
/var/lib/gems/1.8/gems/rvc-1.6.0/lib/rvc/modules/vds.rb:33:in `summarize'
/var/lib/gems/1.8/gems/rvc-1.6.0/lib/rvc/shell.rb:109:in `send'
/var/lib/gems/1.8/gems/rvc-1. 6.0/lib/rvc/shell.rb:109:in `eval_command'
/var/lib/gems/1.8/gems/rvc-1.6.0/lib/rvc/shell.rb:57:in `eval_input'
/var/lib/gems/1.8/gems/rvc-1.6.0/bin/rvc:184
/usr/local/bin/rvc:19:in `load'
/usr/local/bin/rvc:19
/10.42.101.181/DC_3X2/networks/VSJ3X2N1KVSM01>

/10.42.101.181/DC_3X2/networks/VSJ3X2N1KVSM01> ls
0 VSJ3X2N1KVSM01 (vds)
/10.42.101.181/DC_3X2/networks/VSJ3X2N1KVSM01> vds.summarize 0
NoMethodError: undefined method `name' for nil:NilClass
/var/lib/gems/1.8/gems/rvc-1.6.0/lib/rvc/extensions/DistributedVirtualPortgroup.rb:293:in `translate_respool'
/var/lib/gems/1.8/gems/rvc-1.6.0/lib/rvc/extensions/DistributedVirtualSwitch.rb:101:in `summarize'
/var/lib/gems/1.8/gems/rvc-1.6.0/lib/rvc/extensions/DistributedVirtualSwitch.rb:99:in `each'
/var/lib/gems/1.8/gems/rvc-1.6.0/lib/rvc/extensions/DistributedVirtualSwitch.rb:99:in `summarize'
/var/lib/gems/1.8/gems/rvc-1.6.0/lib/rvc/modules/vds.rb:33:in `summarize'
/var/lib/gems/1.8/gems/rvc-1.6.0/lib/rvc/shell.rb:109:in `send'
/var/lib/gems/1.8/gems/rvc-1.6.0/lib/rvc/shell.rb:109:in `eval_command'
/var/lib/gems/1.8/gems/rvc-1.6.0/lib/rvc/shell.rb:57:in `eval_input'
/var/lib/gems/1.8/gems/rvc-1.6.0/bin/rvc:184
/usr/local/bin/rvc:19:in `load'
/usr/local/bin/rvc:19
/10.42.101.181/DC_3X2/networks/VSJ3X2N1KVSM01> c Show less

February 28, 2012 at 3:29 pm | Reply
ruby within rvc
Tim says:

are there any examples available of this? i'd like to be able to power off then unregister all of the vm's in a datastore, and then register them in a new cluster. Is this something that could be done that way?

February 28, 2012 at 11:48 am | Reply
Reverting snapshots
Dominic says:

Hello,

I am trying to use rvc to revert a vm to a specific snapshots. I have no problem restoring VM to its current running snapshot; however, it seems that I can not revert to other snapshots for a given VM. Is is possible to do somethings like:

ha-datacenter/vm> snapshot.revert vm_name snapshot_name

Thanks!

November 21, 2011 at 3:14 pm | Reply
Specify a snapshot for revert?
Dominic says:

My VM's have two snapshots. Depending on the type of testing I am performing, I need to revert to a specific snapshot. I simply need do something like:

ha-datacenter/vm> snapshot.revert vm-na... Show more

My VM's have two snapshots. Depending on the type of testing I am performing, I need to revert to a specific snapshot. I simply need do something like:

ha-datacenter/vm> snapshot.revert vm-name snapshotname

That command fails, of course, as "snapshot.revert" is only takes 1 arg: the name of the VM. Help and documentation indicates that "snapshot.revert" default to the current snapshot. How can I used rvc to revert to other snapshots besides the current running snapshot?

Thanks! Show less

November 21, 2011 at 1:08 pm | Reply
fault.RestrictedVersion
Lucas says:

Thanks for a cool utility!
I'm trying to use this against ESXi host to view a VM, but I get this error:

/172.24.x.x/ha-datacenter/vm> v 1
RestrictedVersion: fault.RestrictedVersion.summary

After looking around, it seems like this error has something to do with licensing of ESX vs ESXi.
Is it not possible to use this utility to view consoles of ESXi hosts?

September 26, 2011 at 11:29 am | Reply
- Rich Lane says:
  
  AFAIK only vSphere Client can be used with the free ESXi. The non-free ESXi works fine.
  
  October 4, 2011 at 2:52 pm | Reply
Editing VMX files on ESX
Mike says:

We have ESX where I work and I'm using datastore.edit ("edit") to alter the values of a .VMX file.

The guest is powered off, of course.

Sometimes, datastore.edit will handle the (un)registration, while other times, it will not.

Can anybody help me with the entire process?

Example:
vm.off
datastore.edit
vm.unregister
vm.register
vm.on

Thanks, in advance!

August 3, 2011 at 8:33 am | Reply
Example of vm.register in RVC?
Mike says:

Hi!

Does anybody have an example of using the register command in RVC? I assume you have to connect through a host, not a datacenter.

I always seem to get something like:
/myhost> vm.register /my/path/to/myguest/myguest.vmx
Expected Folder but got RbVmomi::VIM at "."

Thanks!

July 26, 2011 at 3:10 pm | Reply
- Rich Lane says:
  
  Specify the --folder option to pick which VM folder to add the VM to. You don't need to connect directly to the host.
  
  July 27, 2011 at 10:23 am | Reply
  - Mike says:
    
    Thanks for the speedy reply! Actually, I think I now know a little more about the process, so may I re-ask my question a totally different way? :-)
    
    I have been having a real hard time editing VMX... Show more
    
    Thanks for the speedy reply! Actually, I think I now know a little more about the process, so may I re-ask my question a totally different way? :-)
    
    I have been having a real hard time editing VMX files and having them "stick."
    
    As I now understand the process of Editing Guest Settings, if I want to edit a VMX file (at a low API level), I would do something like this:
    Power off the VM
    Download the VMX
    Edit the VMX
    Re-upload the VMX
    Unregister the VM / VMX / guest
    Register the VMX
    Power on the VM
    
    However, if I understand things better now, in RVC, we could simply do this:
    Power off the VM
    Edit the VMX from the *correct location* (edit implied download / "edit" / upload)
    Power on the VM (unregistering / registering should be automatic)
    
    ...but the "correct location" is the key... The VMX file appears in many locations.
    
    We need the reference for the host's VMX file, right? If so, the VMX at the host location can be discovered with basic.info (look for "host:" and navigate to the correct VMX file).
    
    If so, then it would be much easier:
    vm.off /{vcenter}/host/{datacenter}/{cluster}/hosts/{host}/vms/{guest}
    
    datastore.edit /{vcenter}/host/{datacenter}/{cluster}/hosts/{host}/vms/{guest}/files/{vmxfile}
    
    vm.on /{vcenter}/host/{datacenter}/{cluster}/hosts/{host}/vms/{guest}
    
    Then, it would handle all the (un)registering for you....
    
    Am I right in my assumptions or am I missing something?
    
    Thanks!!! Show less
    
    July 27, 2011 at 3:47 pm | Reply
Custom port?
Alex says:

Does rvc support connection to custom ports?

Tried: rvc 10.100.1.3:13443

I get:
/usr/lib/ruby/1.8/net/http.rb:586:in `connect': SSL_connect returned=1 errno=0 state=SSLv2/v3 read server... Show more

Does rvc support connection to custom ports?

Tried: rvc 10.100.1.3:13443

I get:
/usr/lib/ruby/1.8/net/http.rb:586:in `connect': SSL_connect returned=1 errno=0 state=SSLv2/v3 read server hello A: unknown protocol (OpenSSL::SSL::SSLError) from /usr/lib/ruby/1.8/net/http.rb:586:in `connect' from /usr/lib/ruby/1.8/net/http.rb:553:in `do_start' from /usr/lib/ruby/1.8/net/http.rb:548:in `start' from /usr/lib/ruby/gems/1.8/gems/rbvmomi-1.2.3/lib/rbvmomi/trivial_soap.rb:43:in `restart_http' from /usr/lib/ruby/gems/1.8/gems/rbvmomi-1.2.3/lib/rbvmomi/trivial_soap.rb:20:in `initialize' from /usr/lib/ruby/gems/1.8/gems/rbvmomi-1.2.3/lib/rbvmomi/connection.rb:22:in `initialize' from /usr/lib/ruby/gems/1.8/gems/rvc-1.4.1/lib/rvc/modules/vim.rb:58:in `new' from /usr/lib/ruby/gems/1.8/gems/rvc-1.4.1/lib/rvc/modules/vim.rb:58:in `connect' from /usr/lib/ruby/gems/1.8/gems/rvc-1.4.1/lib/rvc/modules/vim.rb:56:in `loop' from /usr/lib/ruby/gems/1.8/gems/rvc-1.4.1/lib/rvc/modules/vim.rb:56:in `connect' from /usr/lib/ruby/gems/1.8/gems/rvc-1.4.1/bin/rvc:88 from /usr/lib/ruby/gems/1.8/gems/rvc-1.4.1/bin/rvc:85:in `each' from /usr/lib/ruby/gems/1.8/gems/rvc-1.4.1/bin/rvc:85 from /usr/bin/rvc:19:in `load' Show less

July 5, 2011 at 12:11 am | Reply
- Alex says:
  
  Replying to my own message. On github there is an update that supposedly enables custom ports. I have not tested yet.
  
  October 24, 2011 at 9:29 pm | Reply
David says:

Hi,

For all that can't install vmrc (vmrc.install), here is a little patch to appli:
--- /tmp/vmrc.rb 2011-05-11 15:02:34.614969088 +0200
+++ ./rvc-1.3.6/lib/rvc/modules/vmrc.rb 2011-04-27 11:07:... Show more

Hi,

For all that can't install vmrc (vmrc.install), here is a little patch to appli:
--- /tmp/vmrc.rb 2011-05-11 15:02:34.614969088 +0200
+++ ./rvc-1.3.6/lib/rvc/modules/vmrc.rb 2011-04-27 11:07:14.735264117 +0200
@@ -143,6 +143,8 @@
dst_filename = File.join(dst, e.name)
case e.ftype
when :file
+ dst_dirname = File.dirname(dst_filename)
+ FileUtils.mkdir_p dst_dirname if !File.directory?(dst_dirname)
zf.extract e.name, dst_filename
File.chmod(e.unix_perms, dst_filename) if e.unix_perms
when :directory

locate vmrc.rb in your gem path, then once in vmrc, retry to install vmrc.

David. Show less

May 11, 2011 at 6:06 am | Reply
Roman says:

not much luck here on OS X here either:

sauron:~ garfield$ rvc x.x.x.x
Install the "ffi" gem for better tab completion.
No VMRC available for OS darwin10.0
/Library/Ruby/Gems/1.8/gems/rvc-1.3.6/... Show more

not much luck here on OS X here either:

sauron:~ garfield$ rvc x.x.x.x
Install the "ffi" gem for better tab completion.
No VMRC available for OS darwin10.0
/Library/Ruby/Gems/1.8/gems/rvc-1.3.6/lib/rvc/modules/vmrc.rb:39:in `reload_modules': uninitialized constant RVC::CmdModule::VMRC_NAME (NameError)
from /Library/Ruby/Gems/1.8/gems/rvc-1.3.6/lib/rvc/modules.rb:61:in `glob'
from /Library/Ruby/Gems/1.8/gems/rvc-1.3.6/lib/rvc/modules.rb:61:in `reload_modules'
from /Library/Ruby/Gems/1.8/gems/rvc-1.3.6/bin/rvc:61
from /usr/bin/rvc:19:in `load'
from /usr/bin/rvc:19
sauron:~ garfield$ Show less

May 1, 2011 at 3:30 am | Reply
- Roman says:
  
  answering my own post:
  just adding the later used constants with empty values fixes the crash. unified diff below.
  
  --- /Library/Ruby/Gems/1.8/gems/rvc-1.3.6/lib/rvc/modules/vmrc.rb ... Show more
  
  answering my own post:
  just adding the later used constants with empty values fixes the crash. unified diff below.
  
  --- /Library/Ruby/Gems/1.8/gems/rvc-1.3.6/lib/rvc/modules/vmrc.rb 2011-05-01 12:47:32.000000000 +0200
  +++ /Library/Ruby/Gems/1.8/gems/rvc-1.3.6/lib/rvc/modules/vmrc.rb 2011-05-01 12:45:03.000000000 +0200
  @@ -34,6 +34,8 @@
  VMRC_BIN = "vmware-vmrc"
  else
  $stderr.puts "No VMRC available for OS #{RbConfig::CONFIG['host_os']}"
  + VMRC_NAME = ""
  + VMRC_BIN = ""
  end
  
  VMRC_BASENAME = "#{VMRC_NAME}.xpi"
  
  Show less
  
  May 1, 2011 at 3:49 am | Reply
vSauce says:

This doesn't seem to work in Mac OS X 10.6.7

April 25, 2011 at 7:01 pm | Reply
- Mike says:
  
  SFL is "spawn-for-legacy".
  
  SFL supports these Rubies:
  (On MacOS) MRI 1.8.6, 1.8.7, 1.9.1, 1.9.2-rc2
  (On UNIX) MRI 1.8.6, 1.8.7, 1.9.1, 1.9.2pre
  (On Windows) MRI 1.9.1, 1.9.2pre
  
  Unfort... Show more
  
  SFL is "spawn-for-legacy".
  
  SFL supports these Rubies:
  (On MacOS) MRI 1.8.6, 1.8.7, 1.9.1, 1.9.2-rc2
  (On UNIX) MRI 1.8.6, 1.8.7, 1.9.1, 1.9.2pre
  (On Windows) MRI 1.9.1, 1.9.2pre
  
  Unfortunately, SFL does not support these:
  MRI 1.8 on Windows
  Other Ruby implementations such as JRuby, Rubinius and MacRuby
  
  http://www.ruby-forum.com/topic/912179
  https://github.com/ujihisa/spawn-for-legacy
  
  In the little snippet, below, I used Process.spawn() and not just spawn().
  
  Oddly, on my Ubuntu Lucid 32 bit node and on my Lucid 64 bit node, both with MRI Ruby 1.8.7, I can use Kernel.spawn() but not plain old spawn(), so I chose Process.spawn() to avoid confusion.
  
  Try to install sfl:
  sudo gem install sfl
  
  Check your ruby version:
  ruby -v
  
  Then try it in irb:
  require 'rubygems'
  require 'sfl'
  spawn 'ls'
  Process.spawn 'ls'
  Kernel.spawn 'ls'
  
  (You may have to provide full paths to commands you may run, like this:
  Process.spawn('/bin/ls')
  
  Does it work on your mac? Show less
  
  April 26, 2011 at 8:18 am | Reply
- Mike says:
  
  Oh, and Process.spawn() should already work for MacRuby, if I am reading this correctly:
  http://www.macruby.org/trac/ticket/590
  
  April 26, 2011 at 8:20 am | Reply
Mike says:

RVC is an awesome utility!!! :-)

I do notice one issue, though. :-(

On Ruby 1.8.7, the datastore.* commands, such as edit, download, and upload do not work, since spawn() is not implemented. ... Show more

RVC is an awesome utility!!! :-)

I do notice one issue, though. :-(

On Ruby 1.8.7, the datastore.* commands, such as edit, download, and upload do not work, since spawn() is not implemented. It seems that Process.spawn() / Kernel.spawn() is a Ruby 1.9.x thing.

How I fixed it:
sudo gem install sfl
Edited /usr/lib/ruby/gems/1.8/gems/rbvmomi-1.2.3/lib/rbvmomi/vim/Datastore.rb as follows:
Added -
require 'sfl'
Changed both 'spawn' entries, as follows -
pid = spawn CURLBIN, "-k", '--noproxy', '*', '-f',
-to-
pid = Process.spawn CURLBIN, "-k", '--noproxy', '*', '-f', Show less

April 25, 2011 at 3:38 pm | Reply
Matt Yang says:

I suppose it works on ESXi just like CML vClient

April 17, 2011 at 8:34 pm | Reply
Alex says:

I noticed you only referenced ESX and vCenter. Will this work equally well for ESXi hosts?

Thank you

April 16, 2011 at 8:50 am | Reply
- Rich Lane says:
  
  Yes, RVC supports ESXi.
  
  May 27, 2011 at 2:00 pm | Reply
Andi says:

Cool stuff

Is there a way to use this with the vDR appliance, to check if jobs where runnung and so forth?

April 16, 2011 at 5:22 am | Reply