7.0 Host and vault objects

A new system contains a single host and vault, called the bootstrap host and bootstrap vault, but in order to expand the resources available to your system users will want to add host objects and vault objects to your system.

7.1 What is a host object and vault object?

A host is a physical machine (workstation, PC, etc.) that contains at least one processor and can contain active Legion objects.

A vault stores inactive Legion objects: it is a persistent storage space that manages the persistent storage space of inert (i.e., inactive) Legion objects and is the virtual representation of a persistent storage space on a processor. A vault can be in a file system, database system, tape drive, CD-rom, etc.

A host object is a Legion object that represents and can run a physical host or collection of hosts in the Legion system. The host object guards the host's resources, and can activate or deactivate other Legion objects.

A vault object is a Legion object that represents and runs the vault. Like the host object, vault objects guard a vault's resources. They do not, however, activate or deactivate the objects that they manage.

See Simple Legion system , above, shows how this division of labor works in a simple Legion system. Host Object1 represents Host1 and Vault ObjectA represents VaultA.

7.2 About the bootstrap host and vault

A new Legion system contains one host, known as the bootstrap host, and one vault, known as the bootstrap vault, as well as one host object and one vault object to manage them. The latter are called the bootstrap host object and bootstrap vault object. Legion automatically assigned these objects context names when the legion_initialize is run during the start-up procedure. Note, however, that while the bootstrap vault is assigned only one context name ( BootstrapVault ), the bootstrap host is assigned two context names ( BootstrapHost and your.bootstrap.host.name ).

To see this use the legion_ls command:

$ legion_ls /hosts
$ legion_ls /vaults

You may see other host or vault objects listed in the hosts and vaults contexts, especially if your system administrator has customized your context space for you.

7.3 Creating objects on new hosts

You can create new objects on a new host with the legion_create_object command.

The full syntax of this command is:


{-l <class LOID> | -c <class context path>}

<context path for new object>

[-h <host on which to place new object>]

[-v <vault on which to place new object>]

[-H <context path of preferred host class>]

[-V <context path of preferred vault class>]

[-Ch <context containing preferred hosts>]

[-Cv <context containing preferred vaults>]

Note that you must include the context path or LOID of the class which will parent the new object: e.g., if you wish to create an instance of BasicFileClass you must include BasicFileClass's context path name ( /class/BasicFileClass in the example below) or LOID. To create this object on a different host object or vault object use the -h or -v flags plus the host object's or vault object's context path or LOID. The -H and -V flags will cause the class to create an instance on a host object or vault object of a specified class (note that you can create your own host classes to organize the types of host objects you wish to use). If the -Ch or -Cv flag is used, the class will create an instance of itself on a randomly choosen host object or vault object from among the host objects or vault objects listed in a specified context.

The example below creates an instance of the BasicFileClass on aNewHost and assigns it the context name file .

$ legion_create_object -c /class/BasicFileClass file \
  -h /hosts/aNewHost

The command's output is the new object's LOID. The newly created object's context name, file , will appear in the current context (since we did not specify another context) but, as the -h flag specified, it was created on aNewHost (remember that an object's context path does not reflect its actual placement). To find out where an object is actually located you can use the legion_get_host command. The output of this command is the object's host object's LOID.

$ legion_get_host -c file
7.4 Controlling instance placement on hosts and vaults

There are a group of Legion commands that let you control placement of a class's instances or of a specific instance. The legion_class_host_list and legion_class_vault_list commands let you change the list of hosts and vaults upon which a given class can place its instances. The legion_instance_host_list command lets you control where a given object can be placed. There are also command to display lists of a specified object's acceptable hosts, vaults, and host-vault pairings. These commands are likely to be most useful for resource scheduling and management. Please see section See Command-line functions of the Reference Manual for information on the usage of these commands, look on the man pages, or the on-line tutorials (at <http://legion.virginia.edu>).