2.2 Calls on class objects

legion_activate_object 
      {[-c] <object context name> | -l <object LOID>} [-debug] [-help]

Activates the object named in <object LOID> or <context path> (i.e., instantiates that object as a process) if it is inert. If the object is already active, the command has no effect.

The following options are supported:

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

Creates an instance of the class named in <class LOID> or <class context path>. No start-up parameters will be supplied for the class or new object. The following options are supported:

If the -h flag isn't used, the host is selected by the class. Similarly, the class will choose a vault if the -v flag isn't used. Normally, this means that a random host is selected, but some classes may act differently. If the -Ch or -Cv flag is used, the class will randomly choose a host or vault from the hosts or vaults listed in the specified context. In both cases, the system will not return the LOID of the randomly chosen host. The legion_host_vault_list and legion_vault_host_list (page 45 and page 52) commands will allow users to limit the placement of a given class's instances (i.e., any instances of class Foo can only be placed on hosts X, Y, and Z).

legion_create_object_r 
      {[-c] <class context name> | -l <class LOID>} 
      <context path> <host name> <host architecture> 
      <$LEGION> <$LEGION_OPR> <$LEGION_OPA> 
      <binary path> [<user id>]
      [-debug] [-help]

Causes the specified class object to create a new object on the host named in <host name> using the rsh¹ (remote shell) mechanism. The object will be managed with rsh, if the class it is invoked on is an rshStartClass. If this utility is invoked on a normal class, normal object create mechanism will be used, and the object will not be managed by rsh. This command is generally used only by the legion_create_host and legion_create_vault scripts, not by users.

The additional arguments specify information for the rsh environment.

Optional parameters do the following:

legion_deactivate_object 
      [stay_down] [-debug] [-help] 
      {[-c] <object context name> | -l <object LOID>}

Deactivates the object named in <object LOID> or <context path> (moves it to an inert state) if it is currently active. If the object is already inactive, the command has no effect.

The following options are supported:

legion_destroy_object 
      {[-c] <object context name> | -l <object LOID>} [-debug] [-help]

Deletes the object named in <context path> or <object LOID>. More specifically, it removes the object's LOID but not its context name (if there is one). If the object is active, the command deactivates the object. In all cases, it deletes the OPR (object persistent representation) associated with the object.

This command will not remove any context name associated with the object: you must use the legion_rm command to remove the object's name(s) or you will get binding errors. (You can use legion_ls -A to check for multiple context names.)

The following options are supported:

legion_list_implementations 
      [-vL] {-c <class context name> | -l <class LOID>} 
      [-debug] [-help]

Lists the implementation objects associated with the class named in <class LOID> or <class context path>. In its default setting the output will consist of each implementation object's LOID and architecture type.

The following options are supported:

legion_list_instances 
      {[-c] <class context name> | -l <class LOID>} 
      [-debug] [-help]

Displays information about the instances of the class named by <context path> or <class LOID>. For every instance, the tool displays the class's LOID, current object address, status (active or inert), the host on which it resides, and the vault that holds its OPR. The example below shows that class BasicFileClass has two instances, and that both are currently running.

$ legion_list_instances /class/BasicFileClass
Class 1.01.66000000..000001fc0d63e97... knows about the following instances:
LOID: 1.01.66000000.01000000.000001fc0a00...
        Current oa: [xxx.xxx.xxx.xxx: 2020]
        Current host: 1.01.07.30232908.000001fc0...
        Current vault: 1.01.03.2e232908.000001fc0...
        Status: object-running
LOID: 1.01.66000000.02000000.000001fc0edd...
        Current oa: [xxx.xxx.xxx.xxx: 1895]
        Current host: 1.01.07.31232908.000001fc0...
        Current vault: 1.01.03.2e232908.000001fc0...
        Status: object-running
$

The following options are supported:

legion_refresh_local_cache

Manually refresh some high-use objects' bindings and high-use contexts' LOIDs in your current login session.

legion_set_backup_vaults
      {[-c] <instance context path> | -l <instance LOID>}
      [-nodeac[tivate]] 
      {[-a | -d] [-c <vault1 context path> | -l <vault1 LOID>]
           [-a | -d] [-c <vault2 context path> | -l <vault2 LOID>] ...
           [-a | -d] [-c <vaultn context path> | -l <vaultn LOID>]}
       | {-Cv <vault context path> -n <total number of vaults>}

Specify one or more backup vaults for an object. Backup vaults are used to replicate an object's persistent state: the object's persistent state is replicated and stored in multiple vaults when it is deactivated, so that if its main vault crashes, its state is still available. However, the replication policy synchronizes the object's state when the object deactivates: if the main vault crashes while the object is still active, the backup vaults will not have the object's current state. If the object needs to be reactivated, it will use an out-of-date state.

Therefore, this command should only be used for objects that can tolerate potentially old states. As of the 1.7 release, this functionality is supported for the following classes: ContextClass, BasicFileClass, AuthenticationObjectClass, and ImplementationObjectClass.

You can either give a list of specific vaults or a context path from which a specified number of vaults will be selected. For example, to add Vault2 and Vault3 to object Foo's list of backup vaults, you would enter:

$ legion_set_backup_vaults /home/mycontext/Foo \
    -a /vaults/Vault2 -a /vaults/Vault3

To add any two vaults from the /vaults context, you would enter:

$ legion_set_backup_vaults /home/mycontext/Foo \
   -Cv /vaults -n 2

Use legion_object_info (page 10) to view an object's list of backup vaults.

The following options are supported:

legion_set_binding_agent
      [-unset] [-make_default] [-make_default_only]
      {-l <object context path> | -c <object LOID>}

Set or unset the binding agent named in <object context path> or <object LOID> as the user's current and/or future login session binding agent.

The following options are supported:

legion_set_host 
      {[-c] <instance context path> | -l <instance LOID>} 
      {[-c] <host context path> | -l <host LOID>} [-debug] [-help]

Calls the set_host() class-mandatory member function on the class of the instance named by in <instance LOID> or <instance context path>, causing the instance to migrate to the host named in <host LOID> or <host context path>.

In the example below, object Foo's host is changed from BootstrapHost to newHost.

$ legion_set_host -c Foo -c /hosts/newHost

The following options are supported:

legion_set_vault 
      {[-c] <instance context path> | -l <instance LOID>} 
      {[-c] <vault context path> | -l <vault LOID>} [-permanent]
      [-debug] [-help]

Migrates the state (OPR) of the object named in <instance LOID> or <instance context path> to the vault named in <vault LOID> or <vault context path>.

The following options are supported:

Be careful with the -permanent flag. If none of the instance's acceptable hosts match the chosen vault (i.e., there are no compatible host-vault pairs) the instance cannot be reactivated. Alternatively, the chosen vault may be compatible only with hosts for which the class has no implementation.

Please note that this command can fail for many reasons, including:

• the instance does not exist
• the user does not have permission to perform the migration
• the target vault does not exist
• the target vault will not grant the request to create a new OPR for the object
• the source vault is unavailable or will not grant the request to get the current OPR
• other machine or system failure
• the specified vault is unacceptable

The class object will enforce the current restrictions on its instance's acceptable vaults before it migrates the object's state. You may need to change the instance's list of acceptable vaults (via the legion_instance_vault_list command) to include the target vault before running legion_set_vault.

This command is not exactly the equivalent of a true object migration, since the object is not reactivated after its state is moved. Where the object reactivates depends on the scheduling decision made at the time the reactivation occurs. If the -permanent flag is not used and the instance's acceptable vault list is not otherwise altered, future activations of the instance may be on different vaults. If -permanent is used, all future activations must use the specified vault, until the acceptable vault list is altered.

legion_synch_vaults      {[-c] <instance context path> | -l <instance LOID>}
      [-nodeac[tivate]]

Synchronize the specified object's state in its main and backup vaults. The command copies the state contained in the object's main vault to all of its backup vaults. It will deactivate the object before synchronizing vault state unless the -nodeactivate flag is used.

If the object has been marked as Write-Once Read-Many (WORM) with the legion_set_worm command (page 10), its state does not change. You can still run this command for a WORM object, but it will not update its state.

This command is implicitly called upon object deactivation.

As of version 1.7, this functionality is supported for ContextClass, BasicFileClass, AuthenticationObjectClass, and ImplementationOb-jectClass objects.

The following option is supported:

1. If preferred, ssh can be used in place of rsh. back

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