11.0 Host and vault objects

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

11.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 10, 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 10: Compatible 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 10 is compatible with VaultObjectB but not with VaultObjectD, while VaultObjectB is not compatible with HostObjectC.

Figure 11: 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 11, 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 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 12 (below) shows an example of this situation, with two different file systems and multiple hosts.

Figure 12: 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 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 13 (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 13: 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. This process will be discussed in section 11.3.

11.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
{[-c] <host context path> | -l <host LOID>}
[{-a | -d | -t} <vault1> <vault2> ... <vaultn>]
[-p] [-debug] [-help]

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

$ legion_host_vault_list 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: use legion_list_names to see their context names (see page 31 in the Reference Manual).

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

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

The example below shows BootstrapVault's compatible hosts.

$ legion_vault_host_list 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 -a and -d. 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 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 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...
$

11.3 Adding a new host

The main system must be active in order to add a new host. The new host machine must also have the Legion binaries installed (or visible via NFS).

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 environment 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>
setenv LEGION_RCP <rcp|scp>

Normal usage is below (please see page 42 in the Reference Manual 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.¹

11.3.1 legion_starthost flags

Supported <flags> for legion_starthost are:

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 remote path of the program that will start the new host object on the new (remote) host. I.e., it is a path on the remote host.

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 -A, -L, or -O 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 section 10.0 for information about implementations and section 10.2 for information about running this command).

11.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 $LEGION_OPR directory. Each host object has a separate log, called $LEGION_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.

11.4 Adding a new vault

Starting a new vault is similar to starting a new host object. The legion_startvault command usage is: (see section 11.4.1, 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 -N 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 legion_vault_host_list to add and remove hosts from a vault's list of compatible hosts (see page 55 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.

11.4.1 legion_startvault flags

Supported <flags> for legion_startvault are:

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.

11.5 Backup vaults

In the current releases, instances of the BasicFileClass, ContextClass, UserAuthenticationObject, and ImplementationClass classes can have their state replicated on backup vaults. If an instance's primary vault is dead or unavailable during the instance's reactivation, a copy of the instance's state can be retrieved from one of its backup vaults. Please see section 6.6 in the Basic User Manual for more information.

1. An alternative procedure, using command-line utilities, is explained in the Reference Manual on page 119. If possible, we recommend using the rsh procedure explained here, since it is faster and easier.

Table of Contents 1.0 Introduction    1.1 About this manual    1.2 Style conventions    1.3 About Legion 2.0 Installing and running Legion    2.1 Legion structure    2.2 Space requirements    2.3 Software requirements    2.4 RSA and OpenSSL    2.5 Downloading binary files 3.0 Starting a new system    3.1 Before you start    3.2 Set up the environment    3.3 Starting a single host system       3.3.1 Choose a bootstrap host       3.3.2 Set up and configure the system       3.3.3 Start up       3.3.4 Initialize       3.3.5 Set security       3.3.6 Starting up other packages    3.4 Starting a multihost system       3.4.1 Set up       3.4.2 Create a new vault       3.4.3 Create a new host       3.4.4 Adding new users to a secure net       3.4.5 Working in the new net    3.5 Making a set-up script for users 4.0 System shutdown    4.1 Shutting down an insecure system    4.2 Shutting down a secure system 5.0 System restart 6.0 Summary of commands    6.1 Starting a new system    6.2 Start working in a running system    6.3 Shutdown    6.4 Restart 7.0 About Legion security    7.1 Message layer    7.2 MayI layer    7.3 Special implications of security    7.4 Legion and Kerberos    7.5 Session file 8.0 Using security features    8.1 Authentication objects    8.2 Security and context space    8.3 Creating new users    8.4 Logging in users    8.5 Changing user passwords    8.6 Changing implicit parameters and ACL information 9.0 Legion core objects    9.1 Core class objects 10.0 Implementation model    10.1 Implementation caches    10.2 Implementation tools 11.0 Host and vault objects    11.1 About host-vault pairs    11.2 Manipulating host-vault pairing    11.3 Adding a new host       11.3.1 legion_starthost flags       11.3.2 The host object's log    11.4 Adding a new vault       11.4.1 legion_startvault flags    11.5 Backup vaults 12.0 Process control daemon host objects    12.1 Adding a PCD host object       12.1.1 Configure the daemon       12.1.2 Start the daemon and the host object    12.2 PCD host commands       12.2.1 Adding a new account       12.2.2 Removing an account       12.2.3 Viewing available accounts    12.3 How the PCD host object works    12.4 Using a PCD host as your bootstrap host 13.0 Batch queue host objects    13.1 Starting a batch queue host object    13.2 Setting the local queue    13.3 Before running objects on the new host    13.4 Troubleshooting 14.0 Virtual hosts

15.0 Setting up a native MPI host

16.0 Legion domains    16.1 Naming Legion domains    16.2 Domains and binding services    16.3 Joining domains    16.4 Related commands       16.4.1 Listing currently connected domains       16.4.2 Generating cookies       16.4.3 Displaying cookies       16.4.4 Connecting domains 17.0 Resource management    17.1 Scheduling-related commands       17.1.1 Configuring the scheduler       17.1.2 Setting a class's default scheduler       17.1.3 Setting scheduler policy       17.1.4 Adding resources to a collection       17.1.5 Subcollections Getting help Index

Directory of Legion 1.8 Manuals [Home] [General] [Documentation] [Software] [Testbeds] [Et Cetera] [Map/Search] Free JavaScripts provided by The JavaScript Source

legion@Virginia.edu
http://legion.virginia.edu/