Tutorial:
Legion 1.4 Introduction to Host and Vault Objects


Table of Contents

 Hosts and Vaults
Host objects and Vault objects
The bootstrap host and vault
Creating objects on new hosts
Controlling instance placement on hosts and vaults

  Other relevant on-line documents:
  Logging in to a running Legion system
Legion graphical user interface
Introduction to Legion context space
Context-related commands
How to start remote programs in Legion
Object permissions
Legion tty objects
Running an MPI code in Legion
Running a PVM code in Legion
Quick list of all Legion commands
Usage of all Legion commands
Starting and shutting down Legion 1.4
Using Legion security features
Legion host and vault objects
Adding host and vault objects
The list of all on-line 1.4 tutorials


The Legion tutorials offer quick and simple instructions for various key procedures for a Legion system. More complete explanations of all of the procedures discussed here are available on separate pages, and can be found by clicking on the icon.

Depending on how your system is set up, you may need to set up your access to your system before you can run Legion commands. This will probably involve running a command such as this:

$ . ~LEGION/setup.sh

or

$ source ~LEGION/setup.csh
The exact syntax will depend on what kind of shell you are using and on where your Legion files are installed. Consult your system administrator for more information.


A new system contains a single host and vault (see "About the bootstrap host and vault," below), but in order to expand the resources available to your system's users, you will need to add host objects and vault objects to your system. This tutorial discusses the difference between hosts/vaults and host objects/vault objects, adding new hosts and vaults to your system, and setting up compatible host-vault pairs. Additional information includes creating objects on new hosts and controlling placement of class instances on your resources.


Hosts and vaults
A host is a physical machine (workstation, PC, etc.) that contains at least one processor and can contain active Legion objects.

A vault stores inactive Legion objects: it is a persistant storage space that manages the persistent storage space of inert (i.e., inactive) Legion objects and is the virtual representation of a persistent storage space on a processor. A vault can be in a file system, database system, tape drive, CD-rom, etc.


Host objects and vault objectsAdding new host objects
Adding new vault objects
Figure 1: Simple Legion system
A host object is a Legion object that represents and can run a physical host or collection of hosts in the Legion system. The host object guards the host's resources, and can activate or deactivate other Legion objects.

A vault object is a Legion object that represents and runs the vault. Like the host object, vault objects guard a vault's resources. They do not, however, activate or deactivate the objects that they manage.

Figure 1, left, shows this division of labor in a simple Legion system: Host Object1 represents Host1, and Vault ObjectA represents VaultA.



The bootstrap host and vault
A new Legion system contains one host, known as the bootstrap host, and one vault, known as the bootstrap vault, as well as one host object and one vault object to manage them. The latter are called the bootstrap host object and bootstrap vault object. Legion automatically assigned these objects context names when legion_initialize is run during the start-up procedure. Note, however, that while the bootstrap vault is assigned only one context name (BootstrapVault), the bootstrap host is assigned two context names (BootstrapHost and your.bootstrap.host.name). To see this use the legion_ls command:
$ legion_ls /hosts
BootstrapHost
your.bootstrap.host.name
$

$ legion_ls /vaults
BootstrapVault
$
Note that you may see other host or vault objects listed in the hosts and vaults contexts, especially if your system adminstrator has customized your context space for you.


Creating objects on new hosts
You can create new objects a new host with the legion_create_object command.

The full syntax of this command is:

legion_create_object 
	{-l <class loid> | -c <legion space path>}
	<context path for new object>
	[-h <host on which to place new object>]
	[-v <vault on which to place new object>]
	[-H <context path of preferred host class>]
	[-V <context path of preferred vault class>]
	[-Ch <context containing list of preferred hosts>]
	[-Cv <context containing list of preferred vaults>]
Note that you must include the context path or LOID of the class which will parent the new object: e.g., if you wish to create an instance of BasicFileClass you must include BasicFileClass's context path name (class/BasicFileClass in the example below) or LOID. To create this object on a different host object or vault object use the -h or -v flags plus the host object's or vault object's context path or LOID. The -H and -V flags will cause the class to create an instance on a host object or vault object of a specified class (note that you can create your own host classes to organize the types of hosts you wish to use). If the -Ch or -Cv flag is used, the class will create an instance of itself on a randomly choosen host object or vault object from among the hosts or vaults listed in a specified context.

The example below creates an instance of the BasicFileClass on aNewHost and assigns it the context name file.

$ legion_create_object -c class/BasicFileClass file -h hosts/aNewHost
1.01.66000000.01000000.000001fc0b0eec4e02...
$
The command's output is the new object's LOID. The newly created object's context name will appear in the current context (since we did not specify another context) but, as the -h flag specified, it was created on aNewHost (remember that an object's context path does not reflect its actual placement). Use the legion_get_host command to find out where an object is actually located: its host object's LOID is returned.
$ legion_get_host -c file
1.01.07.3eb53908.000001fc0d9b155044fb5...
$

Controlling instance placement on hosts and vaults
There are a group of Legion commands that let you control placement of a class's instances or of a specific instance. The legion_class_host_list and legion_class_vault_list commands let you control which host objects and vault objects a given class can place its instances on. The legion_instance_host_list command controls where a specific instance can be placed. There are also commands to display lists of a specified object's acceptable host objects (legion_get_candidate_hosts), vault objects (legion_get_candidate_vaults), and host-vault pairings (legion_get_candidate_placements). These commands are likely to be most useful for resource scheduling and management.