The University of California, San Diego
UCSD

Site Contents

Page Contents

  1. Ush Tutorial
  2. Starting the Usher Shell
  3. Command List
  4. Connecting
  5. Listing Your Virtual Machines
  6. Listing Virtual Machine Managers
  7. Starting Virtual Machines
  8. Operations on Existing Virtual Machines
    1. Migrate
    2. Shutdown
    3. Cycle
    4. Destroy

Ush Tutorial

This tutorial covers usage of the Usher shell, ush. Though this is merely one of a handful of clients available for sending virtual machine management requests to the Usher Controller, it gives a flavor of they types of VM management operations supported by Usher.

Starting the Usher Shell

If ush is in your path, start the shell by issuing the 'ush' command.

begin.png

Starting ush brings up a brief note about getting help and the'ush>' prompt.

Command List

Get a list of available commands by issuing the '?' or 'help' command.

command_list.png

Connecting

Get command specific help with 'help <command>' or '? <command>'. Here, we're learning how to connect to the Usher Controller.

connect_help.png

Now, we'll want to connect. Ask your administrator where your Usher controller is running.

connected.png

Notice the the command returns immediately with '<Command 0 result pending...>', then returns the result soon after. This is because all commands in ush run asynchronously. Since we're invoking remote methods which may take some time to complete, we don't always want to wait around for the result before issuing another command. As soon as the result for a command is ready, it will appear with the corresponding command number prepended in green. Once connected, you'll see your username in blue before the 'ush>' prompt.

Listing Your Virtual Machines

You can get a list of your virtual machines by running the 'list' command. Below, I'm connected as user 'mmcnett'. As you can see, I've got VMs running in three different clusters: green, eggs, and ham. Names of virtual machine managers (VMMs) appear in magenta, with a list of virtual machines running there in white.

myvmlist.png

Notice that this command returned immediately (i.e. no 'result pending' message). Your client caches your list of VMs locally, so there was no need to connect to the Controller in this case. When you connect to the Usher Controller, you, in effect, subscribe to your list of VMs. This allows for a lot of list processing and pattern matching to be pushed out to clients rather than bog down the controller. It's good for other things too, but I won't go into details here.

If you want to get a global view of all VMs being managed by Usher, use the '-g' flag to list.

list2.png

Now, we see that user 'seuss' also has a few VMs running in his 'wocket' cluster. Notice that we had to send this request to the controller (hence the 'result pending' message), since our client doesn't cache this information.

Listing Virtual Machine Managers

To get a list of Virtual Machine Managers, use the 'vmm_list' command. Currently, options to this command are few, but a long listing with load details should be made available soon. Anyway, knowing what VMMs are out there may be helpful for destination options to the 'start' and 'migrate' commands (see below). Here's what you get now.

vmm_list.png

Starting Virtual Machines

Starting VMs consumes resources. Let's consult the online help before we do anything.

start-help.png

Wow, we get some pretty verbose help with lots of options here. Note that even this long screenshot doesn't capture all the options. Use your terminal's scroll back feature (or Shift-PgUp/Shift-PgDn) to see everything.

Fortunately, basic usage is pretty easy. Just 'start <VM name>'. Let's start a VM named 'horton'.

start1.png

There are a few things to notice here. First, my domain 'mmcnett.usher.ucsdsys.net' was automatically appended to my VM's name. This will always be the case, unless you append it yourself. So, 'start horton.mmcnett.usher.ucsdsys.net' would have produced the same result (although 'start horton.mmcnett' would have started a VM named 'horton.mmcnett.mmcnett.usher.ucsdsys.net') Next, notice that the Usher Controller decided where to place the new VM. In this example, the initial placement policy was random placement. Looks like our VM started up on vmm60.usher.ucsdsys.net. Cool.

Now, let's go to another terminal and try to ssh to our new VM. Keep in mind that it may take a minute for the new VM to boot up. If you're getting 'Connection refused' errors when trying to ssh to your new VM, then sshd hasn't started yet. Give it a few seconds and try again.

ssh.png

Groovy, the VM is up and DNS is resolving properly. I can also see that my home directory has been properly mounted. This will be my home directory for all VMs I create, regardless of cluster name. See the Using Your VMs section of the Documentation page for information on all the far out things you can do with your VMs.

OK, back to ush. Let's go ahead and create a cluster. We'll create the 'whoville' cluster running 30 virtual machines. Before we do this, we should verify that the command we type actually does what we think it will do by using the '--dryrun' flag.

start-dry.png

Yes, this looks like what we want. Let's go ahead and do it.

start2.png

Nice, but lets add one more running on vmm69 just for fun. We can use the '--dlist' flag to do this. Depending upon the Controller's policy, it will either honor our request to start on vmm69, or simply ignore it.

start3.png

Looks like the policy is pretty accommodating right now. Notice that we didn't need to give it a number (although we could if we wanted to do so). Usher figured out what the next free number for the 'whoville' cluster was and used it.

There are many other interesting options to start. Check them out by reading the command specific help ('help start').

Operations on Existing Virtual Machines

Now that we've got a few VMs running, we'll eventually need to manage them. Here's the current list of operations for existing virtual machines:

  • cycle: Destroy and restart (power cycle) a virtual machine or set of virtual machines
  • destroy: Destroy (power off) a virtual machine or set of virtual machines
  • migrate: Migrate a virtual machine or set of virtual machines
  • pause: Pause a virtual machine or set of virtual machines
  • reboot: Nicely reboot a virtual machine or set of virtual machines
  • resume: Resume a paused virtual machine or set of virtual machines
  • shutdown: Nicely shut down (i.e. send procs SIGTERM and unmount filesystems) a virtual machine or set of virtual machines.

Let's look at a few things we might want to do, knowing that other operations on existing VMs work much the same as the examples below. Remember, it's easy to test the outcome of a command before actually running it using the '--dryrun' flag. So, don't be afraid to play around with the options.

Migrate

The Controller's random placement didn't do so well distributing the VMs in our whoville cluster. Let's migrate a few off vmm60. We'll use the '--slist' flag to migrate to accomplish this.

migrate1.png

Worked like a charm. Again, our placement policy is random. We could have explicitly listed destination VMMs for the migration using the '--dlist' flag. As before, the Controller can choose to ignore or honor the '--dlist' flag depending upon its migration policy. For that matter, the Controller may even choose to ignore the migration request altogether.

Shutdown

Since we don't really need all the VMs we have running, let's shut half of them down. There are many ways to do this, but perhaps the easiest is to use the '-n', '-f', and '-l' flags.

shutdown1.png

That worked. We can even do operations on very complicated sets of VM names using regular expressions similar to those found in Perl. How about using a very simple regular expression to shutdown the rest of the whoville cluster.

shutdown2.png

Cycle

Sometimes a VM will crash or hang, and all we can do is either cycle or destroy it rather than nicely reboot or shutdown. Just for fun, let's cycle our 'green' cluster.

cycle1.png

Notice here, I just used the '-a' flag to specify that the operation should be applied to all VMs in the green cluster.

Destroy

Update: Destroy has been renamed 'poweroff'. This is a more appropriate name for what this command actually does since your VMs can be restarted after being destroyed. Destroy is still an alias for poweroff.

Ok, that's enough to get you going. See the online command specific help for the latest documentation and flags for all ush commands. Let's clean up by destroying all my VMs.

destroy1.png

Hope you enjoy Usher. For further assistance on using Usher and your Usher VMs, check out the Usher Documentation page and the 'usher-users' mailing list on the Usher mailing list page. Bug reports can be sent to 'usher-devel' or by creating a ticket (login required).

Last Updated: 2007-09-25 by mmcnett
Report problems to: Marvin McNett