9.0 Host and vault objects

Please see Host and vault objects in the Basic User Manual for information about Legion host and vault objects and an introduction to some basic host- and vault-related commands.

9.1 About host-vault pairs

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 9, right, 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.

Figure 9Compatible host-vault pair

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. HostObjectA in Figure 9 is compatible with VaultObjectB but not with VaultObjectD, while VaultObjectB is not compatible with HostObjectC.

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 10, left. 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.

Figure 10Common persistent
storage system

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 11 (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. 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 11Multi-host and multi-vault system

Figure 12 (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.

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. This process will be discussed in Adding a new host.

Figure 12Adding new resources to a Legion system
9.2 Manipulating host-vault pairing

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 (see Listing an object's names in the Basic User Manual) to see their context names.

The legion_vault_host_list command manipulates a vault's list of compatible host objects.

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...
$
9.3 Adding 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 or ssh) classes to start a new host object on a specified host. 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.* Please note that 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 file for ssh to accomplish this: 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 environrmental variables:

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

Normal usage is below (please see legion_starthost flags for flags and default settings).

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

There is a substantial amount of information 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.

Note that the new host object is automatically assigned a context path, in this case /hosts/new.host.DNS.name. Use the -N flag to place the new host object in a different context or would assign it a specific context name.

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

This assigns the new host object the context name aNewHost (the example specifies that the context name be put in the /hosts context path: otherwise it will be put in the current context). If the -N flag is used, the new host object will not be assigned the default DNS name.

9.3.1 legion_starthost flags

Supported <flags> for legion_starthost are:

-L <$LEGION> Specify $LEGION for the new host
(default is "/home/xxxx/Legion")

-O <$LEGION_OPR> Specify $LEGION_OPR for host
(default is current $LEGION_OPR)

-A <$LEGION_ARCH> Specify the architecture type for the host
(default is current $LEGION_ARCH)

-B <path> Specify the basename of the host binary
(default is "UnixHostObject")

-N <context name> Specify the context name for the host object
(default is /hosts/<new host name>)

-U <user id> Specify a Unix user id for host
(default is current Unix user id)

-C <host class> Specify the context path of the host class
(default is /class/UnixHostClass)

This command creates a new host object on the specified host object. It selects the following additional default values for the new object:

<$LEGION_OPA> = $LEGION_OPR/Host-$HOST.OPA
<binary path> = $LEGION/bin/$LEGION_ARCH/UnixHostObject

The OPA (Object Persistent representation Address) is used to track a specific OPR (Object Persistent Representation, the inert state of an object): in this case, the OPA will represent the persistent state of the new host object. The binary path is the local path of the program that will start the new host object on the new host. Currently, this path can be altered only by editing the legion_start source file in the $LEGION/src/CoreObjects/ClassObjects/rshStartClassObject directory.

These flags and defaults need to be carefully considered when adding new hosts and vaults to your system. If the new host has a different architecture or a different directory structure, use the -A, -L, or -O flags to specify these parameters.

The -B flag allows you to specifies the basename of the executable host program that will be started on the target host: this file should be located in the target host's $LEGION/bin/$LEGION_ARCH directory. Note that a single class can manage instances with different implementations as long as all of the instances support the same interfaces (e.g., there are two implementations for /class/UnixHostClass, UnixHostObject and PCDUnixHost).

The -U flag allows you to specify a Unix user id for the new object, so that a system administrator can add host objects to another user on the same Unix system. This can be useful should you wish to create a guest user id that has limited access privileges to the new host or if you need to work under a different user id on the host.

The -C flag allows you to start an instance of a different class, so that users can create new host classes and have more flexibility in managing their resources. Legion currently comes with only one host class, UnixHostClass, but users can add more host classes as necessary, either by creating instances of the UnixHostClass or by writing new classes.

If the new host object's architecture is not the same as the current host object's architecture, you should run the legion_init_arch tool in order to create implementation objects to match the new architecture (see Implementation model for information about implementations and Implementation tools for information about running this command).

9.3.2 The host object's log

Legion maintains a log containing information about all processes that are executed on your host objects in the $OPR directory. Each host object has a separate log, called $OPR/<host object name>.log. The log includes information about the process's LOID, owner (if applicable), binary executable, OPR, status, and start/stop times.

9.4 Adding a new vault

Starting a new vault is similar to starting a new host object. The legion_startvault command usage is: (see legion_startvault flags, below, for legion_startvault's flags and default settings)

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

The example below creates a vault object on the host we created above (aNewHost) and uses the -N flag to assign the new vault the context path /vaults/aNewVault.

$ legion_startvault -N /vaults/aNewVault new.host.DNS.name \
   /hosts/BootstrapHost /hosts/aNewHost
Creating a Legion vault with the following attributes:
     Host		= "new.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@new.host.DNS.name:/home/xx/OPR"
Creating an instance of "/class/UnixVaultClass" 1.36188412.03.04...
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 compatible hosts are aNewHost and BootstrapHost. The <host name> parameter uses the host's DNS name but the compatible host list uses the host objects' context path (i.e., /hosts/aNewHost). If you do not specify any compatible host objects, the new vault's list of compatible hosts will be empty and the new vault will be unusable.

The output is similar to the legion_starthost output, and includes the new vault's attributes and LOID. Two compatible host objects were added to the aNewVault's list of compatible hosts and the new vault was added to BootstrapHost and aNewHost's lists of compatible vaults.

You can use the legion_vault_host_list command to add and remove hosts from a vault's list of compatible hosts (see legion_vault_host_list in the Reference Manual), 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.

9.4.1 legion_startvault flags

Supported <flags> for legion_startvault are:

-L <$LEGION> Specify $LEGION for the vaults host
(default is "/home/Legion")

-O <$LEGION_OPR> Specify $LEGION_OPR for the vault's host
(default is "/home/OPR")

-A <$LEGION_ARCH> Specify the architecture of the vault's host
(default is current $LEGION_ARCH)

-N <context name> Specify the context name for the vault object
(default is /vaults/vault-<host name>)

-U <user id> Specify a Unix user id
(default is current Unix user id)

-C <vault class> Specify the context path of the vault class
(default is /class/UnixVaultClass)

This commands creates a new vault object in the storage system of a specified host (named in <host name>). The flags are similar to the legion_starthost flags. The -L, -O, or -A flags can be used to specify a different architecture or a different directory structure. The -N flag allows you to specify a context name. The -U flag allows you to specify a Unix user id for the new object. The -C flag allows you to start an instance of a different class. This flag allows users to create new vault classes, so as to give users more flexibility in managing their resources.


* An alternative procedure, using command-line utilities, is explained in the Reference Manual on Alternative ways to start and shut down. If possible, we recommend using the rsh procedure explained here, since it is faster and easier.


Back to System Administrator Manual Table of Contents

Directory of Legion 1.5 Manuals