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:

-debug

Catch and print Legion exceptions.

-help

Print command syntax and exit.

legion_copy_class
     [-v] [-h] 
     {[-c <template context> | -l] <template LOID>} 
     <new class path> [-a <attribute>]* 
     {-mc [-c <metaclass context> | -l <metaclass LOID>]}

Make a copy of a class object. You must use an existing class object as the template. The command creates another class object that has the same metaclass and implementations as the template.

The following parameters are required:

-c <template class path> |
-l <template class LOID>

The original, existing class object.

<new class path>

The new class object's context path.

The following options are supported:

-v

Run in verbose mode.

-h

Print command syntax and exit.

-a <attribute>

Specify an attribute that should be copied from the template to the new class object. You can use this parameter multiple times to specify more than one attribute.

-mc [-c <metaclass path> | -l <metaclass LOID>]

Specify the new class object's metaclass (default is the template's metaclass).

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:

-h

Specify a host for the new object.

-v

Specify a vault for the new object.

-H

Specify the preferred host class's context path.

-V

Specify the context path of the preferred vault.

-Ch

Specify a context which contains a list of the preferred hosts.

-Cv

Specify a context which contains a list of the preferred vaults.

-d

Automatically start a legion_record session for the newly created object. This allows you to debug server objects. The object's relevant activity will be recorded by a previously started Legion recorder object, named in <recorder context path>.

-debug

Catch and print Legion exceptions.

-help

Print command syntax and exit.

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 47 and page 55) 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> | -l <class LOID>} <new object context> 
     <host name> <host architecture> <$LEGION> <$LEGION_OPR>  
     <$LEGION_OPA> <binary path> [<user id>]
     [-debug] [-help]

Create a new object on a specified host with the rsh1 (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_class and legion_create_vault scripts, not by users.

The additional arguments specify information for the rsh environment.

The following parameters are required:

-c <class context> or
-l <class LOID>

The new object's class.

<instance context path>

The new object's context path.

<host name>

Specifies the host upon which the new object should be placed. Note that this should be a DNS name.

<host architecture>

Specifies the host's architecture.

<$LEGION>

Specifies the Legion environment variable on the rsh host.

<$LEGION_OPR>

Specifies LEGION_OPR for host.

<$LEGION_OPA>

Specifies the OPR address for the object, i.e, a unique directory in which the object will maintain its persistent representation on the remote host.

<binary path>

Binary executable path for the object on the remote host.Optional parameters do the following:

<user id>

Specifies the appropriate user name on the rsh host.

-debug

Catch and print Legion exceptions.

-help

Print command syntax and exit.

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:

-stay_down

Forces object to stay inactive. It can only be reactivated by legion_allow_activation (page 26).

-debug

Catch and print Legion exceptions.

-help

Print command syntax and exit.

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:

-debug

Catch and print Legion exceptions.

-help

Print command syntax and exit.

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:

-vL

Run the command in a verbose setting. The output will include byte size and a brief description of each object. Legion will use one extra method invocation per implementation object.

-debug

Catch and print Legion exceptions.

-help

Print command syntax and exit.

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:

-debug

Catch and print Legion exceptions.

-help

Print command syntax and exit.

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 instance. Use legion_skcc_set_class_vaults to set backup vaults for a class (page 11).

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. This functionality is currently 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:

-nodeac[tivate]

Do not deactivate the specified object when setting up its backup vaults

-a

Add the specified vault to the object's list of backup vaults

-d

Delete the specified vault

-Cv

Select the backup vaults from the specified context path

-n

Number of vaults to be selected

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:

-unset

Clear the current binding agent.

-make_default

Set the specified binding agent to be the user's binding agent for the current login session and any future login sessions.

-make_default_only

Set the specified binding agent to be the user's binding agent for the any future login sessions but do not set it as the current session's binding agent.

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:

-debug

Catch and print Legion exceptions.

-help

Print command syntax and exit.

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:

-permanent

Makes the migration permanent. I.e., the object's acceptable vault list will be change to list only the new vault. No further migration can occur without user intervention via legion_instance_vault_list (see page 49).

-debug

Catch and print Legion exceptions.

-help

Print command syntax and exit.

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 12), 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.

This functionality is currently supported for ContextClass, BasicFileClass, AuthenticationObjectClass, and ImplementationObjectClass objects.

The following option is supported:

-nodeac[tivate]

Do not deactivate the specified object when setting up its backup vaults.


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

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/