Legion 1.2
Basic User Manual

6.0 Host and vault objects

A new system contains a single host and vault, called the bootstrap host and bootstrap vault, but in order to expand the resources available to your system's users will want to add host objects and vault objects to your system.

6.1 What is a host object and vault object?

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

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 4, right, shows how this division of labor works in a simple Legion system, Host Object1 representing Host1 and Vault ObjectA representing VaultA.

6.2 About 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 the 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_context_list command:

$ legion_context_list /hosts
.
..
BootstrapHost 
your.bootstrap.host.name
$

$ legion_context_list -la /vaults
.
..
BootstrapVault
$

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

6.3 Adding a new host

To add a new host, the main system must be active. If necessary, start it with the first-time start-up or restart procedure, as appropriate. Note that the new host must also have Legion distribution tree installed, so that it can communicate with your Legion system and properly carry out Legion tasks.

You will be adding the host from your current machine using the legion_starthost command. This command uses remote shell (rsh) classes.1

Normal usage is below (please see "Adding new hosts" for legion_starthost's flags and default settings).

legion_starthost [<flags>] {<new host name>} [<compatible vault list>]

The legion_starthost command can be used to start new host objects on your current host as well as on other hosts: a single machine can contain more than one host object representing and managing the resources available to it. Note that you can create multiple vault objects in a single vault.

You should specify a compatible vault whenever your create a new host object: the command does not require a vault name in order to create a new host object. There are commands for adding and removing vaults from a host's list of compatible vaults, and you can add vaults to this list after creating the host object, but if possible it is simpler to specify at least one compatible vault when running legion_starthost.

In the example below, the system's default BootstrapVault is used as the new host's vault.

$ legion_starthost new.host.DNS.name /vaults/BootstrapVault
Creating a Legion host object with the following attributes:
        Host		= "new.host.DNS.name"
	Context name	= "/hosts/new.host.DNS.name"
	$LEGION		= "/home/xx/Legion"
	$LEGION_OPR	= "/home/xx/OPR"
	$LEGION_OPA	= "/home/xx/OPR/new.host.DNS.name.OPA"
	Architecture	= "linux"
	User id		= "xx"
	Binary path	= "/home/xx/Legion/bin/linux/UnixHostObject"
	Compatible vaults  = "vaults/BootstrapVault"
Transferring configuration files to "xx@new.host.DNS.name:/home/xx/OPR"
Creating an instance of "/class/UnixHostClass"
1.01.07.44b53908.000001fc0c7ce483a068...
Adding "/hosts/new.host.DNS.name" to the host list for "vaults/BootstrapVault"
Added 1 host(s) to vault's compatibility set
Adding "vaults/BootstrapVault" to the vault list for "/hosts/new.host.DNS.name"
Added 1 vault(s) to host's compatibility set
Configuring well-known binaries for "/hosts/new.host.DNS.name"
$

In this sample output, a good deal of information is returned. Legion prints out the attributes of the newly created host object, which include its name, context, path name, vault, and LOID. It also shows the binary executable files for basic Legion objects (e.g., an implementation object) being added and configured to the new host. These files allow the new host to start new Legion objects as necessary.

Note that the output lists the new host-vault pairs that are formed when the object is created. Since the command listed one compatible vault, BootstrapVault, the new vault will only be added to BootstrapHost's list of compatible vaults and only BootstrapVault will be added to the new host's list of compatible vaults. More than one vault can be listed as compatible when creating a host object.

One other important detail is that the host's DNS name is assigned to the new object as its context name and placed in the hosts context.

$ legion_ls -la /hosts
.                             (context)
..                            (context)
BootstrapHost
bootstrap.host.DNS.name
new.host.DNS.name
$

If you prefer to place the new host object in a different sub-context, or if you would like to assign it a specific context name, you can use the -N flag. The example below creates a host object on the same host as above, but assigns it the context name aNewHost. Note that the argument specifies that the context name be put in the hosts sub-context (otherwise it will be put in your current context).

$ legion_starthost -N /hosts/aNewHost new.host.DNS.name /vaults/BootstrapVault
Creating a Legion host object with the following attributes:
	Host		= "new.host.DNS.name"
	Context name	= "hosts/aNewHost"
	$LEGION		= "/home/xx/Legion"
	$LEGION_OPR	= "/home/xx/OPR"
	$LEGION_OPA	= "/home/xx/OPR/aNewHost.OPA"
	Architecture	= "linux"
	User id		= "xx"
	Binary path	= "/home/xx/Legion/bin/linux/UnixHostObject"
	Compatible vaults  = "vaults/BootstrapVault"
Transferring configuration files to "xx@new.host.DNS.name:/home/xx/OPR"
Creating an instance of "/class/UnixHostClass"
1.01.07.3eb53908.000001fc0d9b155044fb5...
Adding "hosts/aNewHost" to the host list for "vaults/BootstrapVault"
Added 1 host(s) to vault's compatibility set
Adding "vaults/BootstrapVault" to the vault list for "hosts/aNewHost"
Added 1 vault(s) to host's compatibility set
Configuring well-known binaries for "hosts/aNewHost"
$

Run the legion_ls command to see that the new hosts have been added to the system.

$ legion_ls -la /hosts
.                             (context)
..                            (context)
BootstrapHost                          
bootstrap.host.DNS.name                
aNewHost                        
$

Note that the new host object's specified context name (aNewHost) is listed but not its DNS name (new.host.DNS.name).

6.4 Adding a new vault

The procedure of starting a new vault is similar to starting a new host. Usage of the legion_startvault command is below (please see "Adding new vaults" for legion_startvault's flags and default settings).

legion_startvault [<flags>] {<host name>} [<compatible host list>]

The example on the next page adds a vault object on the host, uses the -N flag to assign it the context name aNewVault, and lists it as compatible with BootstrapHost.

The output here is similar to the legion_starthost output, and includes the new object's attributes and LOID. Once again, only one host was listed as compatible, so the new vault is added on to BootstrapHost's list of compatible vaults and only BootstrapHost is added to the new vault's list of compatible hosts. Note that if you do not specify any compatible hosts the vault's list of compatible hosts will be empty. There are commands for adding and removing hosts from a vault's list of compatible hosts, and you can add hosts to this list after creating the vault, but if possible it is simpler to specify at least one compatible host when running legion_startvault.

$ legion_startvault -N /vaults/aNewVault the.host.DNS.name /hosts/BootstrapHost
Creating a Legion vault with the following attributes:
	Host		= "the.host.DNS.name"
	Context name	= "vaults/aNewVault"
	$LEGION		= "/home/xx/Legion"
	$LEGION_OPR	= "/home/xx/OPR"
	$LEGION_OPA	= "/home/xx/OPR/vault-aNewVault.OPA"
	Architecture	= "linux"
	User id		= "xx"
	Binary path	= "/home/xx/Legion/bin/linux/UnixVaultObject"
	Compatible hosts	= "hosts/BootstrapHost"
Transferring configuration files to "xx@the.host.DNS.name:/home/xx/OPR"
Creating an instance of "/class/UnixVaultClass"
1.01.03.3db53908.000001fc0dd5621fadf70b0...
Adding "vaults/aNewVault" to the vault list for "hosts/BootstrapHost"
Added 1 vault(s) to host's compatibility set
Adding "hosts/BootstrapHost" to the host list for "vaults/aNewVault"
Added 1 host(s) to vault's compatibility set
$

To add more than one host to the vault object's compatibility list, just add the names of the host objects. The next example repeats the previous command to create a new vault object called aNewVault that will be compatible with BootstrapHost as well as with aNewHost.

The end of the output shows aNewVault being added to BootstrapHost's and aNewHost's lists of compatible vaults, and those two hosts being added to aNewVault's list of compatible hosts.

$ legion_startvault -N /vaults/aNewVaultaNewVault the.host.DNS.name \ /hosts/BootstrapHost /hosts/aNewHost
Creating a Legion vault with the following attributes:
	Host		= "the.host.DNS.name"
	Context name	= "vaults/aNewVault"
	$LEGION		= "/home/xx/Legion"
	$LEGION_OPR	= "/home/xx/OPR"
	$LEGION_OPA	= "/home/xx/OPR/vault-aNewVault.OPA"
	Architecture	= "linux"
	User id		= "xx"
	Binary path	= "/home/xx/Legion/bin/linux/UnixVaultObject"
	Compatible hosts	= "hosts/BootstrapHost hosts/aNewHost"
Transferring configuration files to "xx@the.host.DNS.name:/home/xx/OPR"
Creating an instance of "/class/UnixVaultClass"
1.01.03.3eb53908.000001fc0d6e9041e262126...
Adding "vaults/aNewVault" to the vault list for "hosts/BootstrapHost"
Added 1 vault(s) to host's compatibility set
Adding "hosts/BootstrapHost" to the host list for "vaults/aNewVault"
Added 1 host(s) to vault's compatibility set
Adding "vaults/aNewVault" to the vault list for "hosts/aNewHost"
Added 1 vault(s) to host's compatibility set
Adding "hosts/aNewHost" to the host list for "vaults/aNewVault"
Added 1 host(s) to vault's compatibility set
$

6.5 About host-vault pairs

Hosts and vaults are always paired: a host or vault is unusable by itself. Adding new hosts and vaults to your system makes multiple processors and storage space available to your system. However, only compatible hosts and vaults can be paired. Figure 5, right, shows a compatible host-vault pair: the host and vault can "see" each other and can therefore pass objects between them, as the objects are activated and deactivated.

All Legion host objects must be paired with at least one compatible vault object in order to carry out Legion processes. There are several commands (see "Manipulating host-vault pairing") for adding, deleting, and viewing lists of acceptable hosts or vaults, but before you add a new host or vault to your system you must consider any possible compatibility problems. This is a critical point, since if a paired host object and vault object cannot communicate with each other, the Legion objects that they control will be unusable. In Figure 5, for instance, Host A can "see" Vault B, HostObjectA manages Host A and VaultObjectB manages space in Vault B. Host A is compatible with Vault B, so HostObjectA can be paired with VaultObjectB.

This is not a concern in systems with a single shared vault (e.g., a networked file system, database system, tape drive, CD-rom, etc.), as in Figure 6, left. Here, any vault objects will represent space in the only available disk storage space (Vault A) accessible to Host 1, Host 2, and Host 3. If the user on Host 1 wishes to add Host 2 to her system, she can either pair the new host object with the BootstrapVault already in her current system or create a new vault object (on Vault A) to manage the new host object's persistent storage needs. Either way, there is no need to worry about non-compatible pairing.

On the other hand, if this same user wanted to add a new host from a foreign system (i.e., a system with a persistent storage space that is not accessible to her bootstrap host object), she would also need to create a new vault object in the foreign system and pair it with the new host object. Figure 7 (below) shows an example of this situation, with two different file systems and multiple hosts. Hosts 1-3 can see Vault A, and Hosts 4-6 can see Vault B. Again, if the user wanted to add a host from her own system she could either assign the new host object a currently existing BootstrapVault from Vault A or create a new vault object on Vault A without worrying about host-vault compatibility. But if she wants to add a host from the second system, say Host 4, she must pair it with a compatible vault object on Vault B (either by creating a new vault object with legion_startvault or by using one that has already been created and that she has permission to use).

Figure 8 (below) shows how this might work. The user's Legion system creates HostObject4 and VaultObjectB, objects that represent and manage the user's Legion processes on Host 4 and Vault B. HostObject4 will manage the user's Legion work on Host 4, and VaultObjectB will manage persistent storage of any objects that HostObject4 creates or uses. Assuming that there are no conflicts in architecture, environment, etc., you can add a new host to your system with the legion_starthost command and the new host's DNS name and a new host object (representing new.host.DNS.name) will be created on the new host using the current values of $LEGION and $LEGION_OPR from your current environment. If the new host has a different architecture or has different Legion environment variables, or if the user wishes to specify a different user id, the user can specify this with legion_starthost flags.

6.6 Creating objects on new hosts

New objects can be created on the 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 if you must include the context path of the class which will parent the new object: if you wish to create an instance of BasicFileClass you must include the BasicFileClass context path name (/class/BasicFileClass in the example below). To create the object on a different host or vault, use the -h or -v flags plus the host's or vault's context path. The -H and -V flags will cause the class to create an instance on a host or vault of a specified class (note that users can create their own classes of hosts as is most convenient to organize the types of hosts that they wish to work with). If the -Ch or -Cv flag is used, the class will create an instance of itself on a randomly choosen host or vault 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. The command's output is the new object's LOID.

$ legion_create_object -c /class/BasicFileClass file -h /hosts/aNewHost
1.01.66000000.01000000.000001fc0b0eec4e02...
$

The newly created object's context name, file, will appear in the current context (since we did not specify another context) but, as the -h flag specified, it was placed on aNewHost. This is an important feature of context space: an object's context path does not reflect its actual placement. To find an object's actual location at any time, use the legion_get_host command. The output of this command is the host object's LOID.

$ legion_get_host -c file
1.01.07.3eb53908.000001fc0d9b155044fb5...
$

6.7 Controlling instance placement on hosts and vaults

There are a group of Legion commands that allow users to control placement of a class's instances or of a specific instance. You can use the legion_class_host_list or legion_class_vault_list commands to control the list of hosts or vaults upon which a given class can place its instances, or the legion_instance_host_list and legion_ instance_vault_list to control where a given object can be placed. There are also command that will display lists of a specified object's acceptable hosts (legion_get_candidate_hosts), vaults (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. Please see "Command-line functions" in the Reference Manual for information on the usage of these commands, look on the man pages, or the on-line tutorials (at http://legion.virginia.edu/Documentation.html).


1. An alternative procedure, using command-line utilities, is explained in the Reference Manual in "Starting extra hosts and vaults from the command line." If possible, we recommend using the rsh procedure explained here, since it is faster and easier. Note, though, that ssh can be used in place of rsh. Back


Back to Getting Started sectional index

Back to Basic User Manual Table of Contents