Legion Host and Vault Objects

Adding new hosts
Supported <flags> for legion_starthost are:

`-L <$LEGION>`	Specify $LEGION for the new host (default is "/home/xxxx/Legion")
`-O <$LEGION_OPR>`	Specify $LEGION_OPR for host (default is current $LEGION_OPR)
`-A <$LEGION_ARCH>`	Specify the architecture type for the host (default is current $LEGION_ARCH)
`-N <context name>`	Specify the context name for the host object (default is "/hosts/<new host name>")
`-U <user id>`	Specify a Unix user id for host (default is current Unix user id)
`-C <host class>`	Specify the context path of the host class (default is "/class/UnixHostClass")

This command first creates a new host object on the specified <new host name> (the host's DNS name). It selects the following additional default values for the new object:

<$LEGION_OPA>	= $LEGION_OPR/Host-$HOST.OPA
<binary path>	= $LEGION/bin/$LEGION_ARCH/UnixHostObject

An OPA (Object Persistent representation Address) is used to track a specific OPR. In this case, the OPA will represent the persistent state of the new host object. The binary path is the binary path of the program that will be run on the new host in order to start the new host object. Currently, this path can be altered only by editing the legion_start source file, in the $LEGION/src/CoreObjects/ClassObjects/rshStartClassObject directory.

These flags and defaults need to be carefully considered when adding new hosts and vaults to your system. If the new host has a different architecture or a different directory structure, use the -A, -L, or -O flags to specify these parameters. The -U flag allows you to specify a Unix user id for the new object, so that a system administrator can add host objects to another user on the same Unix system. This can be useful should you wish to create a guest user id that has limited access privileges to the new host. The -C flag allows you to start an instance of a different class, so that users can create new host classes and have more flexibility in managing their resources. (Legion currently comes with only one host class, UnixHostClass, but users can add more host classes as necessary, either by creating instances of the UnixHostClass or by writing new classes.)

If the new host object's architecture is not the same as the current host object's architecture, you should run the legion_init_arch tool in order to create implementation objects to match the new architecture (see section 9.0 of the System Administrator Manual, for information about implementations, and section 9.2 of the System Administrator Manual, for information about running legion_init_arch).

Adding new vaults
Supported <flags> for legion_startvault are:

`-L <$LEGION>`	Specify $LEGION for the vaults host (default is "/home/Legion")
`-O <$LEGION_OPR>`	Specify $LEGION_OPR for the vault's host (default is "/home/OPR")
`-A <$LEGION_ARCH>`	Specify the architecture of the vault's host (default is current $LEGION_ARCH)
`-N <context name>`	Specify the context name for the vault object (default is "/vaults/vault-<host name>")
`-U <user id>`	Specify a Unix user id (default is current Unix user id)
`-C <vault class>`	Specify the context path of the vault class (default is "/class/UnixVaultClass")

This commands creates a new vault object on the storage system of a specified host (named in <host name>). The flags are similar to the legion_starthost flags. The -L, -O, or -A flags can be used to specify a different architecture or a different directory structure. The -N flag allows you to specify a context name. The -U flag allows you to specify a Unix user id for the new object, so that a system administrator (or anyone with root privileges) can add vault objects to another user on the same Unix system. This can be useful should you wish to create a guest user id that has limited access privileges to the new host. The -C flag allows you to start an instance of a different class. That is, if you do not use this flag, the new host object will be an instance of class UnixVaultClass. This flag allows users to create new vault classes, so as to give users more flexibility in managing their resources.

Manipulating host-vault pairing
The legion_host_vault_list command will list a host object's list of compatible vaults. The example below lists the compatible vaults for the BootstrapHost. Note the -p flag, which signals that the list should be printed out.

$ legion_host_vault_list -c hosts/BootstrapHost -p
** COMPATIBLE VAULT LISTING: 
**      1.01.03.3cb53908.000001fc0bb4fef12ecf6cc...
**      1.01.03.3db53908.000001fc0dd5621fadf70b0...
**      1.01.03.3eb53908.000001fc0d6e9041e262126...
$

(If you are not sure what the context names of these vaults are, use the legion_context_lookup command.)

To view the list of a vault's compatible hosts, use legion_vault_host_list. The example below asks that the list of hosts for BootstrapVault be printed.

$ legion_vault_host_list -c vaults/BootstrapVault -p
** COMPATIBLE HOST LISTING: 
**      1.01.07.3cb53908.000001fc0c29636eee98d...
**      1.01.07.3eb53908.000001fc0d9b155044fb5...
$

There are two hosts listed here, BootstrapHost and AliasHostObject.

Both of these commands can add and delete hosts or vaults from the list with specific flags (-a and -d, respectively). For example, to remove NewVaultObject2 from BootstrapHost's list of acceptable vaults, you would enter the following:

$ legion_host_vault_list -c hosts/BootstrapHost -d \ vaults/NewVaultObject2 -p                                           
Deleted 1 vault(s) to host's compatibility set
** COMPATIBLE VAULT LISTING: 
**      1.01.03.3cb53908.000001fc0bb4fef12ecf6cc...
**      1.01.03.3db53908.000001fc0dd5621fadf70b0...
$

The next example adds a host to BoostrapVault's list of compatible hosts.

$ legion_vault_host_list -c vaults/BootstrapVault -a \ hosts/AnotherHost -p
Added 1 host(s) to vault's compatibility set
** COMPATIBLE HOST LISTING: 
**      1.01.07.3cb53908.000001fc0c29636eee98d...
**      1.01.07.3eb53908.000001fc0d9b155044fb5...
**      1.01.07.3fb53908.000001fc0c96beaba5730...
$

Creating objects
New objects can be created on the new host with the legion_create_object command.

The full syntax of this command is:

legion_create_object 
	{-l <class loid> | -c <legion space 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 list of preferred hosts>]
	[-Cv <context containing list of preferred vaults>]

Note that if you must include the context path of the class which will parent the new object: if you wish to create an instance of BasicFileClass you must include the context path name class/BasicFileClass (this path name can change, of course, depending on whether you are using absolute or relative path names and what your current context is). To create the object on a different host or vault, use the -h or -v flags plus the host or vaults context path. The -H and -V flags will cause the class to create an instance on a host or vault of a specified class (note that users can create their own classes of hosts as is most convenient to organize the types of hosts that they wish to work with). If the -Ch or -Cv flag is used, the class will create an instance of itself on a randomly choosen host or vault from among the hosts or vaults listed in a specified context.

The example below creates an instance of the BasicFileClass on the AliasHostObject and assigns it the context name File. The output is the new object's LOID.

$ legion_create_object -c class/BasicFileClass file -h hosts/AliasHostObject
1.01.66000000.01000000.000001fc0b0eec4e02...
$

The newly created object will appear in the current context (since we did not specify another context) but, as the command requested, it was placed on AliasHostObject. This is an important feature of context space, and the user should be careful to remember that context space does not necessarily reflect the actual organization or location of objects. To find an object's actual location at any time, use the legion_get_host command. The output of this command is the host object's LOID.

$ legion_get_host -c file
1.01.07.3eb53908.000001fc0d9b155044fb5...
$

Controlling instance placement on hosts and vaults
There are a group of Legion commands that allow users to control placement of a class's instances or of a specific instance. You can use the legion_class_host_list and legion_class_vault_list commands to control the list of hosts or vaults upon which a given class can place its instances, or the legion_instance_host_list and legion_instance_vault_list to control where a given object can be placed. There are also command that will display lists of a specified object's acceptable hosts (legion_get_candidate_hosts), vaults (legion_ get_candidate_vaults), and host-vault pairings (legion_get_candidate_placements). These commands are likely to be most useful for resource scheduling and management.