6.0 Host and vault objects

A new Legion system contains a single host object and vault object, called the bootstrap host and bootstrap vault. In order to expand the resources available to your system, however, you can add host objects and vault objects to your system.

6.1 Host/vault versus host/vault object

There is a difference between a host and a host object and between a vault and a vault object. Hosts and vaults refer to physical machines while host objects and vaults objects are Legion objects that manage hosts and vaults.

A host is a 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 single machine can have multiple vaults.

Figure 5: Simple Legion system.

A host object represents and can run a physical host or collection of hosts in the Legion system. The host object guards all or a portion of a host's resources, and can activate or deactivate other Legion objects. A host can have more than one host object. If there are multiple host objects, they each maintain a portion of the host's resources.

A vault object 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.

Figure 5 shows this division of labor. HostObject1 represents Host1 and VaultObjectA represents VaultA.

6.2 About the bootstrap host/vault

A new Legion system contains one host, the bootstrap host, and one vault, the bootstrap vault, as well as a bootstrap host object and a bootstrap vault object to manage them. Legion automatically assigns context paths to all new objects during the start-up procedure, and the bootstrap host and vault objects are given paths in the /hosts context:

$ legion_ls /hosts

$ legion_ls /vaults

While there is one context name for the vault, BootstrapVault, there are two for the host, BootstrapHost and the host's DNS name (i.e., your.bootstrap.host.name). 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.

6.3 Creating objects on new hosts

You can create new objects on a new host with legion_create_object. The full syntax of this command is:

{[-c] <class context path> | -l <class LOID>}
<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>]
[-d <recorder context path> <debug session name>]
[-debug] [-help]

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. You can create the new object on a specific host or vault object, a host or vault object of a specified class,1 or one of the host or vault objects in a specified context.

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

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

The command's output is the new object's LOID. The newly created object is created on aNewHost and given the context name file in the current context.

6.4 Look up an object' s host

To find out where an object is actually located, run legion_get_host. The output of this command is the object's host object's LOID.

$ legion_get_host file

You can then use legion_ls -L to get the host object' s context path.

6.5 Instance placement on hosts and vaults

There is a set of Legion commands to control placement of a class's instances or of a specific instance: legion_class_host_list and legion_class_vault_list let you change the list of hosts and vaults upon which a given class can place its instances, and legion_instance_host_list lets you control where a given object can be placed. There are also commands 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 the Reference Manual, man pages, or on-line tutorials for more information about these commands.

6.6 Backup vaults

Legion versions 1.7 and forward support backup vaults for certain types of objects. Backup vaults are used to replicate an object's persistent state in case the object's primary vault crashes or is unavailable. When the object deactivates, its state is copied to all of its backup vaults. When it is reactivated, its class will first check the object's primary vault for its persistent state. If the primary vault is unavailable, the class will look in one of the backup vaults.

Please note that the backup vaults may not have a current copy of the object's state. If the object was previously deactivated, the backup vaults will be current. But if the object was running when the primary vault crashed, the backup vaults' copy will be out-of-date. You should only use backup vaults for objects whose state does not change or who can tolerate recovery from with out-of-date state.

At present, backup vaults can be used for BasicFileClass, ContextClass, ImplementationObject, and UserAuthenticationObject objects.2 These classes all belong to the SKCC_MetaClass. SKCC stands for Simple K-Copy Class, meaning that the class's state is copied k times when an instance is deactivated.

6.6.1 WORM objects

Backup vaults are especially useful for objects whose state never changes, such as Write-Once Read-Many (WORM) objects. An object can be marked as a WORM object with the legion_set_worm command. A WORM object's state will be copied to its backup vaults only once. The legion_unset_worm command indicates that a WORM object is no longer using WORM semantics and that its state now needs to be updated each time the object deactivates. Please see page 12 in the Reference Manual for more information on these commands.

6.6.2 Assigning and synchronizing backup vaults

There are four commands related to backup vaults:


The first two set defaults for SKCC classes. The third adds and deletes vaults from the object's list of vaults and the fourth synchronizes the copy of the object's state in the backup and primary vaults. Please see the Reference Manual for more information on these commands.

6.6.3 Using replication

Any instance of one of the classes mentioned above can use backup vaults. You can use a current existing object or create a new one:

$ legion_cp -localsrc localfile Foo

You can then use legion_set_backup_vaults to set the instance's backup vaults:

$ legion_set_backup_vaults /home/myContext/Foo \
  -a /vaults/VaultA -a /vaults/VaultB

When Foo deactivates, its state will be replicated to VaultA and VaultB. At any point you can synchronize its backup vaults' copy of its state with legion_synch_vaults:

$ legion_synch_vaults /home/mycontext/Foo

Alternatively, if you are an SKCC class's owner you can use legion_skcc_set_class_vaults to make a list of backup vaults for the class's instances. The example below adds VaultA and VaultB to ClassFoo's list of backup vaults.

$ legion_skcc_set_class_vaults /home/myContext/ClassFoo \
-a /vaults/VaultA -a /vaults/VaultB

If you use this command to set up a list of backup vaults for a class, you can use legion_skcc_set_defaults to instruct Legion to use back up the class's instances onto a certain number of those backup vaults. For example:

$   legion_skcc_set_defaults -c /home/myContext/ClassFoo 3

Legion will now by default replicate all ClassFoo instances onto three of ClassFoo's backup vaults.

1. You can use legion_create_class, page 38 in the Reference Manual, to create your own host classes to organize the types of host objects you wish to use.

2. These are the default SKCC objects. Your system administrator may have changed this list.

Directory of Legion 1.8 Manuals
[Home] [General] [Documentation] [Software]
[Testbeds] [Et Cetera] [Map/Search]

Free JavaScripts provided by The JavaScript Source