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.
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.
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:
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 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.
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.
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.
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.
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.