Flings
Apps and tools built by our engineers that are intended to be played with and explored.

Ruby vSphere Console

Ruby vSphere Console

Summary

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.

System Requirements

Ruby 1.8.7+, preferred version is 1.9.2.

Instructions

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

Video

Change Log

Engineers

Rich Lane

Works in the Hypervisor group.

Add Comment

29 thoughts on “Ruby vSphere Console

  1. Pete

    I’m having a weird behavior. When I run rvc on one system, it always exits after executing one command. On another system, I get a new prompt and can enter new commands, even if I use the “-c command” option.

    I want the first behavior. Does anyone have any suggestions why the difference and what to do about it?

    Thankjs.

    Reply
  2. Sean Clark

    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>

    Reply
  3. Cere Davis

    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

    Reply
  4. Tim

    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?

    Reply
  5. Dominic

    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!

    Reply
  6. Dominic

    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!

    Reply
  7. Lucas

    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?

    Reply
  8. Mike

    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!

    Reply
  9. Mike

    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!

    Reply
    1. Rich Lane

      Specify the –folder option to pick which VM folder to add the VM to. You don’t need to connect directly to the host.

      Reply
      1. Mike

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

        Reply
  10. Alex

    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'

    Reply
    1. Alex

      Replying to my own message. On github there is an update that supposedly enables custom ports. I have not tested yet.

      Reply
  11. David

    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.

    Reply
    1. bar

      Hi David,
      can i get a little help with this patch ?
      where do i use it ? on what file ? do i change the lines in the vmrc.rb file ?

      Reply
  12. Roman

    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$

    Reply
    1. Roman

      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”

      Reply
    1. Mike

      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?

      Reply
  13. Mike

    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’,

    Reply

Leave a Reply

Your email address will not be published. Required fields are marked *

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>