Tutorial:
Legion 1.2 Host and Vault objects

Table of Contents

  What is a host and a vault?
What is a host object and vault object?
About the bootstrap host and vault
Adding new hosts
Adding new vaults
About host-vault pairs
Other relevant on-line documents:
  Starting and Shutting down Legion 1.2
Legion context space
How to start remote programs in Legion
Legion graphic user interface
Quick list of all Legion commands
Usage of all Legion commands
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.

What is a host and a vault?
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 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.

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

About the bootstrap host and vault
A new Legion system contains one host and one vault, and one host object and one vault object to manage them. The latter are called as 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 adminstrator has customized your context space for you.

Adding a new host

About legion_starthost
Creating objects on 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.

Normal usage is: 

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 the hosts that 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).

Adding a new vault

About legion_startvault
The procedure of starting a new vault is similar to starting a new host. Usage of the legion_startvault command is: 
legion_startvault [<flags>] {<host name>} 
	[<compatible host list>]
The example below 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. 
$ 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
$
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.

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. 

$ legion_startvault -N vaults/aNewVault 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	
$
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.

About host-vault pairs

More about host-vault pairing
Controlling instance placement on hosts and vaults
Figure 2: Compatible host-vault pair
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 2, 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 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 2, for instance, Host A can "see" Vault B, Host Object A manages Host A and Vault Object B manages space in Vault B. Host A is compatible with Vault B, so Host Object A can be paired with Vault Object B.

Figure 3: Common vault system

 

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 3, 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.


Figure 4: Multi-host and multi-vault system

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 4 (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 5 (below) shows how this might work. The user's Legion system creates HostObject4 and VaultObjectB, which are objects that can 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 curent 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.

Figure 5: Adding new resources to a Legion system