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.
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.
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.
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.
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.
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.
There are three vaults listed here: use legion_list_names to see their context names (see page 31 in the Reference Manual).
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:
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.
Normal usage is below (please see page 42 in the Reference Manual for flags and default settings).
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.
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.
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.1
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).
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.
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)
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.
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.
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.