Tutorial:
Introduction to Host and Vault Objects

Table of Contents
Introduction
Hosts and vaults and their objects
The bootstrap host and vault
Creating objects on new hosts
Controlling instance placement on hosts and vaults
Other on-line tutorials & documentation
Click on the to move to the selected text.


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 where your Legion files are installed (i.e., the value of ~legion will depend on your individual Legion net). Consult your system administrator for more information.

The following style conventions are used in these tutorials:


Introduction
A new system contains a bootstrap host and bootstrap vault, represented by special Legion objects called host objects and vault objects. In order to expand the resources available to your system, you may need to add hosts and vaults to your system. This tutorial discusses hosts, host objects, vault, and vault objects. Additional information includes creating objects on new hosts and controlling placement of class instances on your resources.


Hosts and vaults and their objects
Figure 1: Simple Legion system
Figure 1, left, shows this division of labor in a simple Legion system.

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 a file system, database system, tape drive, CD-rom, etc.

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. In figure 1, Host Object1 represents Host1.

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. In figure 1, Vault ObjectA represents VaultA.



The bootstrap host and vault
A brand 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 (called the bootstrap host object) and one vault object (called the bootstrap vault object) to manage them. Legion assigns these default objects context paths during the start-up procedure. You may notice that while the bootstrap vault has one context name, /vaults/BootstrapVault, the bootstrap host gets two, /hosts/BootstrapHost and /hosts/<bootstrap.DNS.name>. Use the legion_ls command to see what hosts and vaults are in your system: legion_ls /hosts shows hosts and legion_ls /vaults shows vaults.

Creating objects on a new hostCreating new host objects
Creating new vault objects
You can create new objects on 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 arbitrarily 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.


Other relevant on-line documents:
Click on the to go to the page.
Logging in to a running Legion system
Introduction to Legion context space
Context-related commands
Legion tty objects
Running a PVM code in Legion
Running a Legion MPI code
Running native MPI code
Quick list of all 1.7 Legion commands
Usage of all 1.7 Legion commands
FAQs for running programs in Legion
Starting a new Legion system
Legion security
Legion host and vault objects
Adding host and vault objects
Brief descriptions of all on-line tutorials

Last modified: Thu Jun 15 16:35:59 2000

 

[Home] [General] [Documentation] [Software]
[Testbeds] [Et Cetera] [Map/Search]

legion@Virginia.edu
http://legion.virginia.edu/