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 What's a host/vault and a host/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.

Figure 4: Simple Legion system.

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.

Figure 4, above, shows how this division of labor works in a simple Legion system. 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. You can see this with the legion_ls command:

$ legion_ls /hosts
BootstrapHost 
your.bootstrap.host.name
$

$ legion_ls /vaults
BootstrapVault
$ 

You can see that while there is one context name for the vault -- BootstrapVault -- there are two for the host -- BootstrapHost and the host's DNS name (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 the legion_create_object command.

The full syntax of this command is:

legion_create_object 
     {[-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. 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 an arbitrarily chosen 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 /class/BasicFileClass file \
  -h /hosts/aNewHost
1.01.66000000.01000000.000001fc0b0eec4e02...
$ 

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 file
1.01.07.3eb53908.000001fc0d9b155044fb5...
$ 

6.4 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 (<http://legion.virginia.edu/documentation.html>) for more information about these commands.

6.5 Backup vaults

Legion version 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 had been deactivated, the backup vaults will be current. If the object was running when the primary vault crashed, however, 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. 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.5.1 Assigning and synchronizing backup vaults

There are two commands related to backup vaults: legion_set_backup_vaults and legion_synch_vaults. The former adds and deletes vaults from the object's list of vaults and the latter synchronizes the copy of the object's state in the backup and primary vaults. Please see page 15 and page 18 in the Reference Manual for more information on these commands.

6.5.2 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 object'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 

6.5.3 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 10 in the Reference Manual for more information on these commands.

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

Free JavaScripts provided by The JavaScript Source

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