Tutorial:
Legion 1.5 Expanding your Legion system: Adding new host and vault objects

Table of Contents

  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 Sample makefile for remote programs Object permissions Legion tty objects Running a PVM code in Legion

Running an MPI code in Legion Quick list of all Legion commands Usage of all Legion commands Starting and shutting down Legion 1.5 Using Legion security features Legion host and vault objects Adding host and vault objects The list of all on-line 1.5 tutorials

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

Figure 1: Compatible host-vault pair

Adding new hosts and vaults to your system makes multiple processors and storage space available to your system, but before you start expanding be aware that Legion hosts and vaults must work in compatible pairs. Figure 1, left, shows two pairs of compatible host-vaults: Host A and Vault B can "see" each other and Host C and Vault D can "see" each other.

All Legion host objects must be paired with at least one compatible vault object in order to carry out Legion processes: all Legion objects maintain an OPR on a vault and objects must have access to their inert state in order to function properly. Therefore, before you add a new host object or vault to your system you must consider any possible compatibility problems. An incompatible host object and vault object will not work together. In Figure 1, HostObjectA is compatible with VaultObjectB but not with VaultObjectD. Nor is VaultObjectB compatible with HostObjectC.

Figure 2: Common persistent storage system

This is not a concern in systems that use a single shared vault (e.g., a networked file system, database system, tape drive, CD-rom, etc.), as in Figure 2, right. Here, all vault objects will represent space in the only available disk storage space (Vault A). They will therefore all be accessible to any host object created on Hosts 1, 2, or 3. If user Jane, working on Host 1, wishes to create a new host object on Host 2 she can either pair the new host object with the currently existing BootstrapVault or create a new vault object on Vault A. Either way, there is no need to worry about incompatible pairing.

On the other hand, if Jane wants to add a new host from a foreign system (i.e., her bootstrap host object cannot "see" the new system's persistent storage space) she must create a new vault object in the foreign system and pair it with her new host object. Figure 3 (below) shows an example of this situation, with two different file systems and multiple hosts.

Figure 3: Multi-host and multi-vault system

Hosts 1-3 can see Vault A, and Hosts 4-6 can see Vault B. If Jane wants to create a host object on Hosts 2 or 3 she can pair it with BootstrapVault or create another vault object on Vault A. Either way, she does not need to worry about host-vault compatibility. However, if she wants to create a host object in another system, say on Host 4, she must pair it with a compatible vault object on Vault B, either by creating a new vault object or by getting permission to use a currently existing vault object.

Figure 4 (below) shows how this might work. Jane creates HostObject4 on Host 4 and VaultObjectB on Vault B. HostObject4 will manage her Legion work on Host 4, and VaultObjectB will manage the persistent storage of HostObject4's object.

Figure 4: Adding new resources to a Legion system

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 a new host object will be created on the new host using the current environment values of $LEGION and $LEGION_OPR. There are a variety of options in case the new host has a different architecture or different Legion environment variables or if you need to specify a different user id.

The legion_host_vault_list command manipulates a given host object's list of compatible vaults. Its usage is:

legion_host_vault_list {-l <host LOID> | -c <host context path>}
	[{-a | -d | -t} <vault1> <vault2> ... <vaultn>] [-p] [-u]

The example below lists the compatible vaults for BootstrapHost. Note the use of the -p flag: this signals that the list should be printed to standard output.

$ legion_host_vault_list -c hosts/BootstrapHost -p
** COMPATIBLE VAULT LISTING: 
**      1.01.03.3cb53908.000001fc0bb4fef12ecf6cc...
**      1.01.03.3db53908.000001fc0dd5621fadf70b0...
**      1.01.03.3eb53908.000001fc0d6e9041e262126...
$

There are three vaults listed here: you can use the legion_list_names command to see their context names. Similarly, the legion_vault_host_list command manipulates a vault's list of compatible host objects. Its usage is:

legion_vault_host_list {-l <vault LOID> | -c <vault context path>} 
	[{-a | -d | -t} <host1> <host2> ... <hostn>] [-p] [-u]

The example below asks shows BootstrapVault's compatible hosts.

$ legion_vault_host_list -c vaults/BootstrapVault -p
** COMPATIBLE HOST LISTING: 
**      1.01.07.3cb53908.000001fc0c29636eee98d...
**      1.01.07.3eb53908.000001fc0d9b155044fb5...
$

Both of these commands can also add and delete compatible hosts or vaults with the -a and -d flags. For example, to remove aNewVault from BootstrapHost's list of acceptable vaults and then see the adjusted list you would enter the following:

$ legion_host_vault_list -c hosts/BootstrapHost -d vaults/aNewVault -p
Deleted 1 vault(s) to host's compatibility set
** COMPATIBLE VAULT LISTING: 
**      1.01.03.3cb53908.000001fc0bb4fef12ecf6cc...
**      1.01.03.3db53908.000001fc0dd5621fadf70b0...
$

To add a host and then see the adjust list, you would enter the following:

$ legion_vault_host_list -c vaults/BootstrapVault -a hosts/AHost -p
Added 1 host(s) to vault's compatibility set
** COMPATIBLE HOST LISTING: 
**      1.01.07.3cb53908.000001fc0c29636eee98d...
**      1.01.07.3eb53908.000001fc0d9b155044fb5...
**      1.01.07.3fb53908.000001fc0c96beaba5730...
$

Adding a new host

About legion_starthost Creating objects on a new host

To add a new host, the main system must be active. Note that the new host must also have a Legion system installed and running, so that it can communicate with your Legion system and properly carry out Legion tasks.

The legion_starthost command is run from your current machine, not on the new host. This command uses remote shell (rsh) classes^* to start a new host object on a specified host. Note that you can start new host objects on your current host as well as on other hosts, since a single machine can contain more than one host object.

Normal usage is below.

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

You should specify a compatible vault whenever you create a new host object: you can run legion_starthost without a vault name and then use legion_host_vault_list to add a vault to the new host object's list of compatible vaults, but it is simpler to specify one or more compatible vault when you first create the new host object. In the example below, the default BootstrapVault is the new host object's compatible 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.000001fc0c7ce4...
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"
$

A good deal of information is returned. Legion first prints out the attributes of the newly created host object, which include its name, context name, local OPR and OPA path names, architecture, your Unix user id, local path name, and any compatible vault(s). 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. The output then shows the creation of the object: the new object is an instance of the UnixHostClass. Optional flags will let you change some of these attributes.

The output also lists the new host-vault pairs that were formed: the new host object is now on BootstrapVault's list of compatible hosts and BootstrapVault is on the new host object's list of compatible vaults.

An important detail is that the new host object is automatically assigned a context name:

Context name	= "/hosts/new.host.DNS.name"

If you do not specify a context name, Legion will use the host's DNS name as its context name and place in the /hosts context.

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

If you prefer to place the new host object in a different context or would like to use a different context name, use the -N flag. The example below repeats the example above, but assigns the new host object the context name aNewHost. Note that the argument specifies that the context name be put in the /hosts context path (otherwise it will be put in your current context).

This new host object can be seen in the /hosts context.

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

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

For information about adding process control daemon (PCD) host objects, please see section 10.0 of the System Administrator Manual.

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.

* An alternative procedure, using command-line utilities, is explained in section 3.0 in the Reference Manual. 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