Sun and Oracle Community Voices How to Buy Log In United States [Change] English

Research Home
»  Spotlight Articles
»  Projects
»  Publications
»  People
»  Awards
»  Events
»  Downloads
»  Internships
»  Contrarian Minds
»  About Sun Labs
Project Guest VM: Running

Project Guest VM: Running

Introduction

Guest VM images can be run either with the run script or with the java script, both of which reside in the GuestVMNative/bin directory. The run script is slightly easier to use than the java script, which adheres strictly to the standard.

Both commands ultimately invokes the Xen xm create command to create a domain from the guestvm image. Therefore, you must have root privileges. We recommend that you use a separate shell for running images and do all development as a non-privileged user.

The system is currently incomplete, see here for known bugs and limitations.

Domain Configurations

Xen's xm command requires a "domain configuration file" to provide key information to the domain creation process. The run script uses domain configuration files from the xmconfigs subdirectory. The files in the xmconfigs directory should have names of the form domain_config_xxx, to enable selection by the run script. The default configuration is domain_config_generic which accesses the following environment variables: 
VCPUS          number of virtual CPUs to allocate to the domain
MEMORY         amount of initial domain memory in megabytes
MAXMEM         maximum amount of domain memory in megabytes
DISK0          location of virtual disk image zero to be attached to domain
DISK1          location of virtual disk image one to be attached to domain
DISK2          location of virtual disk image two to be attached to domain
BRIDGE         network bridge name
For backwards compatibility DISK is a synonym for DISK0.

If none of these variables are set, the configuration will default to: 

VCPUS          1
MEMORY         256
MAXMEM         1024
DISKs          none
BRIDGE         none

Run Script

The run command syntax is essentially similar to the standard Java launcher, javaexcept that it accepts some additional options that are specific to the Xen environment. Also, whereas the standard launcher enforces an ordering for arguments, i.e., 

run [options] [class | -jar jarfile] [args]
the run command will also accept unordered options with every option preceded by a keyword: 
run [options]
In this case the main class is idenified as -main class and each program argument must be preceded by a -a if the argument itself begins with a '-'. Here are the full set of options: 
  -k            set keyword argument mode
  -a arg        force arg as program arg (only necessary if arg has leading -)
  -main class   main class to invoke (only needed with -k)
  -echo         echo the full xm create command
  -cf cf        set the domain config file to xmconfigs/domain_config_cf (default generic)
  -d            run in debug mode (wait for Maxine Inspector to connect)
  -n            force -echo but do not execute the xm create command
  -Jargs        set VM argument(s)
  -mx n         equivalent to -J-Xmxn
  -ms n         equivalent to -J-Xmsn
  -name name    set domain name (default GuestVM-class-$USER-$$ or GuestVM-$USER-$$ if -jar)
  -memory n     set initial domain memory to n (default: from config file)
  -maxmem n     set maximum domain memory to n (default: from config file)
  -classpath    set the application classpath (default /guestvm/image/GuestVM/bin)
  -cp           synonym for -classpath
  -jar file     extract main class from jar file
  -js           enable Guest VM's Java thread scheduler

Environment

The Java platform makes some assumptions about the environment that reflect a traditional operating system environment, for example the existence of a file system, the notion of a current working directory and the notion of a "user" performing the launch. In particular the current working directory is typically inherited from the directory that was current when the launch command was issued. However, in keeping with the isolation properties of a virtualized environment like Xen, a Guest VM domain has no a priori connection to the launching environment, or to the user performing the launch (typically "root"). These values can be set through the use of Java properties but are given defaults to allow simple programs to be executed simply, vis: 
os.name             GuestVM
java.home           /guestvm/image/jre
user.name           guestvm
user.dir            /tmp
user.home           /tmp
The /guestvm/image file system is a readonly file system included in the image. It contents can be configured using an imagespec file.

Heap Size

A Guest VM domain automatically sizes the Java heap based on the initial domain memory, and will attempt to extend the domain memory up to maxmem if a garbage collection cannot reclaim sufficient memory to satisfy an allocation request. Therefore, there is generally no need to use the -Xms and -Xmx options, although these override the default behavior if specified.

A Guest VM domain attempts to respond to an xm memset request either by increasing or decreasing the heap size as appropriate. A decrease request forces a garbage collection and will only succeed if the collection freed up enough memory to satisfy the request, and the amount of memory returned may be less than that requested.

Note that decreasing the domain memory by too much may cause a subsequent OutOfMemory exception.

Running Simple Test programs

By default, /guestvm/image/GuestVM/bin contains a set of test programs that can validate the functionality of the system, e.g., the null (empty) program: 
# bin/run test.java.lang.Null
Using config file "./xmconfigs/domain_config_generic".
Started domain GuestVM-test.java.lang.Null-mjj
#
Note that an equivalent command using full keyword arguments would be: 
bin/run -k -main test.java.lang.Null
The full set of system properties can be display with: 
# bin/run test.java.lang.SysProps
Using config file "./xmconfigs/domain_config_generic".
Started domain GuestVM-test.java.lang.SysProps-mjj
System properties:
java.runtime.name=Java(TM) SE Runtime Environment
sun.boot.library.path=/guestvm/image/jre/lib/amd64
...
user.name=GuestVM
...
sun.cpu.isalist=amd64
#
To override the "user.name" property: 
# bin/run -J-Duser.name=mjj test.java.lang.SysProps
Using config file "./xmconfigs/domain_config_generic".
Started domain GuestVM-test.java.lang.SysProps-mjj
System properties:
java.runtime.name=Java(TM) SE Runtime Environment
sun.boot.library.path=/guestvm/image/jre/lib/amd64
...
user.name=mjj
...
sun.cpu.isalist=amd64
#

Running More Complex Programs

More complex programs will require access to classes that are not in the boot image. As a step towards that, note that the standard image build also includes some of the Maxine test programs in /guestvm/image/maxine/VM/bin. E.g., the "HelloWorld" program can be run using: 
# bin/run -cp /guestvm/image/maxine/VM/bin test.output.HelloWorld
Using config file "./xmconfigs/domain_config_generic".
Started domain GuestVM-test.output.HelloWorld-mjj
Hello World!
#
Accessing class files beyond those built into the image requires access to one of the file systems available under Guest VM, i.e., Ext2 for virtual disks, NFS or access to a file system exported by a sibling guest domain. See here for details on enabling and accessing file systems.

Assuming that a virtual disk configured as an Ext2 file system and populated with the standard platform classes in "/jdk1.6.0_11", e.g., using the script bin/ext2_cpjava, and mounted as /guestvm/java, then it is possible to run a program that uses any of the standard platform classes by setting the java.home property to "/guestvm/java/jdk1.6.0_11/jre", e.g.: 

bin/run -J-Djava.home=/guestvm/java/jdk1.6.0_11/jre SomeClass args
The bin/run_jre script provides a convenient way to specify this, e.g.: 
bin/run_jre SomeClass args
Of course, most programs require additional classes, e.g., their own jar files. These can be accessed either through NFS or the Sibling file system or, more typically, by copying the files onto an Ext2 file system on a separate virtual disk, and then setting the "-cp" option appropriately. E.g., assuming that the classes of the application have been copied to the /classes of the virtual disk defined by DISK1 in the guest configuration file, the following command could be used to run the application: 
bin/run_jre "J-Dguestvm.fs.table=ext2:/blk/0:/guestvm/java:ro;ext2:/blk/1:/guestvm/app" -cp /guestvm/app/classes SomeClass args
Note that the bin/run_jre scripts gets the version number for the JDK as stored on the virtual disk from the JAVA_HOME environment variable.

Command Line Limits

Xen has a limit of 1024 characters for the command line that is passed to a guest. Some Java applications that use the -classpath option to enumerate a large number of directories or jar files can exceed this limit. One solution is to create a single aggregating jar file that specifies the classpath using the Classpath attribute of the jar file manifest.

The java script

The java script is similar to the run script, except that it only accepts the standard Java options. In normal use this is not a limitation. For example, the previous example could equally well be run as follows:

bin/java -Djava.home=/guestvm/java/jdk1.6.0_11/jre "J-Dguestvm.fs.table=ext2:/blk/0:/guestvm/java:ro;ext2:/blk/1:/guestvm/app" -cp /guestvm/app/classes SomeClass args The equivalent of the -d option to the run script is -XX:GUKDebug. There is no equivalent for the -cf option. The java script does not provide a default value for -classpath. The name of the guest is set to GuestVM-$USER-$$, with the given shell variable substitutions.

Note that it is possible to execute scripts that expect the java to be in JAVA_HOME/bin/java by prefixing the GuestVMNative directory to the shell PATH variable, os as to mask the host system's launcher.

Network Access

Many programs will require network access. See here for details.

Running Big Applications

Running big applications, e.g. applications servers, is the ultimate test of the system. Maxine and Guest VM are making progress in that direction, but bugs and incompleteness of the JDK implementation for Guest VM currently limit what can be run.

Most large applications launch via complex shell scripts. Naturally, these need modification to run in the Guest VM environment. Typically, it is simplest to create a custom script for running on Guest VM.

The Hadoop application does run under Guest VM in standalone mode and we describe how to set it up here. This can then be used as a template for experimenting with other applications.