Table of Contents

About host-vault pairs Controlling host-vault pairs Creating new host objects Creating new vault objects Other on-line tutorials & documentation

Click on the to move to the selected text. This tutorial deals with the basic host object. Other kinds of host objects that you may wish to use are the PCD host, the batch queue host, and the virtual host.

Adding new hosts and vaults to your system makes multiple processors and storage space available to your system. However, Legion hosts and vaults only work in compatible host-vault pairs. Figure 1 shows two such pairs: 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, Host A and Vault B can see each other, so HostObjectA-VaultObjectB is a compatible host-vault pair. However, Host C and Vault B can not see each other, so HostObjectC-VaultObjectB is not a compatible host-vault pair.

Figure 1: Compatible host-vault pair

Figure 2: Common persistent storage system

This is not an issue in systems with a single shared vault (e.g., a networked file system, tape drive, CD-rom, etc.). In figure 2, above, Vault A is the only available disk storage space. Any vault objects created in this system will be compatible with any host object on Hosts 1, 2, or 3. If Jane creates a new host object on Host 2 she can pair it with any existing vault object or create a new one. Either way, there is no need to worry about incompatible pairing.

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

Figure 3: Two different file systems

Hosts 1, 2, and 3 can see Vault A but not Vault B. If Jane wants to create a host object on Hosts 2 or 3 she can use 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 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 displays and changes 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 legion_vault_host_list command displays and changes 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 lists the compatible vaults for BootstrapHost (the -p flag signals that the list should be printed to standard output). The vaults are listed by LOID (use legion_list_names to see their context names).

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

The example below asks shows BootstrapVault's compatible hosts. Again, use legion_list_names to see context names.

$ 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 add and delete compatible hosts or vaults with the -a and -d flags. The example below removes aNewVault from BootstrapHost's list of acceptable vaults:

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

The legion_starthost command creates new host objects. You can create multiple host objects on a single host. The command uses remote shell (rsh or ssh) classes to start a new host object on the specified host. Be sure that the main system is active and the new host machine has the Legion binaries installed (or visible via NFS). You must be able to run rsh/ssh on the target host from your current machine without having to enter a password. You can set up an .rhosts file for rsh or an authorized_keys files for ssh to accomplish this: please see the rsh and ssh man pages for further information. You can run Legion commands on a remote host using rsh or ssh, once you set the proper environmental variables. For sh, ksh, or bash, use:

LEGION_RSH=<rsh|ssh>
LEGION_RCP=<rcp|scp>
export LEGION_RSH LEGION_RCP

For csh, use:

setenv LEGION_RSH <rsh|ssh>
set env LEGION_RCP <rcp|scp>

The legion_starthost command is run from an existing host, not on the new host.

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

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. 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. I.e.:

$ legion_starthost -N /hosts/aNewHost new.host.DNS.name /vaults/BootstrapVault

Note that we used the /hosts path: if you do not specify a path, the new name will be put in your current context. We suggest that you place all host names in the same context or group them together in some logical way.

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

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 <host name> must be a DNS name. The command uses remote shell (rsh or ssh) classes to start a new vault object on the specified host. You must be able to run rsh/ssh on the target host from your current machine without having to enter a password. You can set up an .rhosts file for rsh or an authorized_keys files for ssh to accomplish this: please see the rsh and ssh man pages for further information. You can run Legion commands on a remote host using rsh or ssh, once you set the proper environmental variables. For sh, ksh, or bash, use:

LEGION_RSH=<rsh|ssh>
LEGION_RCP=<rcp|scp>
export LEGION_RSH LEGION_RCP

For csh, use:

setenv LEGION_RSH <rsh|ssh>
set env LEGION_RCP <rcp|scp>

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.

The example below creates a vault object and uses the -N flag to assign it the context name aNewVault. It also lists BootstrapHost and aNewHost as compatible hosts.

$ legion_startvault -N vaults/aNewVault myhost.DNS.name \ hosts/BootstrapHost hosts/aNewHost Creating a Legion vault with the following attributes:
Host	= "myhost.DNS.name"
Context name	= "vaults/aNewVault"
$LEGION	= "/home/me/Legion"
$LEGION_OPR	= "/home/me/OPR"
$LEGION_OPA	= "/home/me/OPR/vault-aNewVault.OPA"
Architecture	= "linux"
User id	= "me"
Binary path	= "/home/me/Legion/bin/linux/UnixVaultObject"
Compatible hosts	= "hosts/BootstrapHost hosts/aNewHost"
Transferring configuration files to "me@myhost.DNS.name:/home/me/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 output here is similar to the legion_starthost output, and includes the new object's attributes and LOID. Two compatible hosts were listed, so the new vault is added on to BootstrapHost's and aNewHost's lists of compatible vaults and BootstrapHost and aNewHost is added to the new vault'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

---

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:34:43 2000

[Home] [General] [Documentation] [Software] [Testbeds] [Et Cetera] [Map/Search] legion@Virginia.edu http://legion.virginia.edu/