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
BootstrapHost 
your.bootstrap.host.name
$

$ legion_ls /vaults
BootstrapVault
$

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:

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. You can create the new object on a specific host or vault object, a host or vault object of a specified class,¹ 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
1.01.66000000.01000000.000001fc0b0eec4e02...
$

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

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

legion_skcc_set_class_vaults
legion_skcc_set_defaults
legion_set_backup_vaults
legion_synch_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.

Table of Contents 1.0 Introduction    1.1 About this manual    1.2 Style conventions    1.3 About Legion 2.0 Setting up and logging in    2.1 Preparing your Legion environment    2.2 Logging in       2.2.1 Logging in as a user       2.2.2 Changing your password       2.2.3 About object permissions       2.2.4 Checking your log in status       2.2.5 Logging out       2.2.6 Using Legion in a Kerberos environment    2.3 Changing your profile 3.0 An introduction to context space 4.0 Context space    4.1 Legion object names    4.2 About the LOID    4.3 Organizing context space 5.0 Working in context space    5.1 Viewing contexts       5.1.1 Read a context's contents       5.1.2 Look up LOIDs       5.1.3 Create a new context       5.1.4 Changing your current context       5.1.5 Check your current context    5.2 Naming objects       5.2.1 Assign a context name to a LOID       5.2.2 Give an object extra context names       5.2.3 Change an object's context path       5.2.4 List context names       5.2.5 Remove names and objects       5.2.6 Remove an entire context       5.2.7 Use the same name in different contexts    5.3 Moving between local files and contexts       5.3.1 Copying          5.3.1.1 Copy a local file to Legion          5.3.1.2 Copy from Legion to a local file          5.3.1.3 Copy from Legion to another Legion file object          5.3.1.4 Using wildcards when copying       5.3.2 Look at a file object's contents       5.3.3 Importing a local Unix tree       5.3.4 File sharing: temporarily link files to Legion 6.0 Host and vault objects    6.1 Host/vault versus host/vault object    6.2 About the bootstrap host/vault    6.3 Creating objects on new hosts    6.4 Look up an object's host    6.5 Instance placement on hosts and vaults    6.6 Backup vaults       6.6.1 WORM objects       6.6.2 Assigning and synchronizing backup vaults       6.6.3 Using replication 7.0 Running a Legion application 8.0 Executing programs remotely    8.1 Linked and independent programs    8.2 Registering independent programs       8.2.1 Independent programs       8.2.2 Legion-linked programs    8.3 Running a program remotely       8.3.1 Choosing a remote host       8.3.2 Command-line arguments       8.3.3 Getting input files to the remote host          8.3.3.1 Before the program starts          8.3.3.2 After the program has started       8.3.4 Getting output files from the remote host          8.3.4.1 Before the program starts          8.3.4.2 After the program has started       8.3.5 Option file       8.3.6 Creating and using a probe file       8.3.7 Blocking vs. nonblocking       8.3.8 About legion_probe_run       8.3.9 Context scratch space       8.3.10 Retrieving files from context scratch space    8.4 Example    8.5 Converting a C/C++ program 9.0 PVM    9.1 Core PVM interface    9.2 Tids &apm; LOIDs    9.3 Task classes       9.3.1 Legion-PVM library    9.4 Compilation    9.5 Registering compiled tasks    9.6 Examples    9.7 Running PVM code with the fewest changes 10.0 MPI    10.1 Legion MPI       10.1.1 Task classes       10.1.2 Legion MPI libraries       10.1.3 Compilation       10.1.4 Register compiled tasks       10.1.5 Running the MPI application       10.1.6 Example       10.1.7 Input and output files          10.1.7.1 Input and output flags          10.1.7.2 Subroutines       10.1.8 Scheduling MPI processes       10.1.9 Debugging support       10.1.10 Checkpointing support          10.1.10.1 Example          10.1.10.2 API (C & Fortran)          10.1.10.3 Running the above example          10.1.10.4 Recovering from failure          10.1.10.5 Restarting application          10.1.10.6 Compiling/makefile          10.1.10.7 Limitations          10.1.11 Functions supported          10.1.12 Running a Legion MPI code with the fewest changes    10.2 Native MPI       10.2.1 Task classes       10.2.2 Compilation       10.2.3 Register compiled tasks       10.2.4 Running a native MPI application       10.2.5 Making Legion calls from native MPI programs       10.2.6 Example       10.2.7 Scheduling native MPI processes 11.0 Executing remote programs    11.1 Sample record and replay A-1 Sample makefile A-2 About Legion tty objects    A-2.1 Simple tty management    A-2.2 Complex tty management A-3 Alphabetical list of Legion commands A-4 Subject listing of Legion commands    A-4.1 Calls on objects    A-4.2 Calls on class objects    A-4.3 Calls on LegionClass    A-4.4 Calls on file and context objects    A-4.5 Start-up and shutdown functions    A-4.6 Scheduling support    A-4.7 General functions about the state of the system    A-4.8 Security    A-4.9 Application development    A-4.10 Program support Getting help References Index

Directory of Legion 1.8 Manuals [Home] [General] [Documentation] [Software] [Testbeds] [Et Cetera] [Map/Search] Free JavaScripts provided by The JavaScript Source

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