Calls on objects

legion_configure_profile

Edits information about your user profile, security settings, and fault tolerance settings. It is menu-driven. Hit the <enter> key to return to the previous menu level. When you run this command you'll be given the following options:

1. Edit Profile
   
2. Security
   
3. Fault Tolerance

The first option lets you edit your AuthenticationObject to include your e-mail address, name, and company.

The second option changes your security preferences for the message layer. You have the following choices:

1. Off (No encryption/No digest)
   
2. Protected (Digested messages/Encrypted credentials)
   
3. Private (Encrypted messages/Encrypted credentials)

These will change the settings for messages passed by your objects. We STRONGLY recommend that you read section 7.0 in the System Administrator Manual before using these options.

The third edits your fault tolerance settings for SKCC objects. The options are:

1. Edit SKCC Policy (default # backups - per user )
   
2. Edit SKCC Policy (default # backups - class-wide, class owner only)
   
3. Edit SKCC Vaults (class owner only)

These affect your SKCC objects (BasicFileClass, ContextClass, ImplementationObject, and UserAuthenticationObject are the default SKCC objects). Please see section 6.6 in the Basic User Manual for information on SKCC. Note that these options will affect previous settings. It uses the following commands to edit your settings:

legion_skcc_set_class_vaults
legion_skcc_set_defaults
legion_set_backup_vaults
legion_class_vault_list

Note that you cannot change settings on objects that you do not own or have permission to edit. If you are not the class owner, you can use the first option to set the default number of backup vaults for your SKCC objects.

legion_exports_interface
    {-l <LOID> | -c <context path>}
    {-w <well-known class type> | -f <function signature>}+
    [-debug] [-help]

Creates an interface from the list of <well-known class type> and <function signature> arguments specified in the argument list. Sends this interface to the object specified by <LOID> or <context path> in the form of a call to the object mandatory function named exportsInterface(). Prints to standard output the return value from the call:

1	if the interface of the object contains the entire interface of functions specified by the user
0	if any one or more of the functions are not exported by the object
-1	(without contacting the specified object) if the user creates a malformed argument list

The <well-known class type> argument is a string in the set of well known strings, which can be listed via the legion_wellknown_class tool.

For the purposes of this tool, "ClassObject" is a well-known class string. "CommandLineClass" and "BootstrapMetaClass" are not considered well-known classes because they do not have any special member functions, as shown in the examples below.

$ legion_exports_interface -c LegionClass -w ClassObject
1
$

$ legion_exports_interface -c /class/LegionClass \
  -w CommandLineObject
"CommandLineObject" is not a well known class. Exiting.
usage: legion_exports_interface
{-l <class loid> | -c <legion space path>}
{-w <well known class type> | -f <function signature>}+
-1
$

$ legion_exports_interface -c LegionClass -w LegionClass \
  -w ClassObject
1
$

$ legion_exports_interface -c /hosts/BootstrapHost \
  -w UnixHostClass
1
$

$ legion_exports_interface -c /hosts/BootstrapHost \
  -w ClassObject
0
$

$ legion_exports_interface -c /class/LegionClass \
  -f "     LegionLOID ping();"
1
$

$ legion_exports_interface -c /hosts/BootstrapHost \
  -f "     LegionLOID ping();" -w UnixHostClass
1
$

The following options are supported:

-debug	Catch and print Legion exceptions.
-help	Print command syntax and exit.

legion_FTPd
             [-help] [-v] [-p <port number>] [-a] [-m <max connections>]
             [-t <transfer block size>] [-o <max outstanding invocations>]
             [-d] [-w] [-e] [-rt <RMI timeout>] [-dt <detail timeout>]

Starts the Legion FTP daemon from the command line. This daemon is a Legion-enabled server tool for accessing Legion context space via FTP. Once you've started the daemon, you can use a standard FTP client software to view, store, and retrieve objects from your context space.

Once started, the daemon's operating parameters cannot be changed. To terminate, send a SIGINT or ^-c signal.

Please be aware that if you use the -a flag, other users will be able to use your daemon to view and use your context space. Your password will also travel in the clear over the network.

The Legion FTP daemon will only work for systems running Legion version 1.7 or higher. It implements the minimum requirements of an FTP server as outlined in RFC-959 and RFC-1123.

The following options are supported:

-debug	Catch and print Legion exceptions.
-v	Operate in verbose mode. All commands and responses will be echoed to stdout
-p <port number>	Specify a listening port for incoming FTP connections.
-a	All machines other than the local host to connect to the daemon.
-m <max connections>	Specify the maximum number of simultaneous FTP connections.
-t <transfer block size>	Specify the block size in bytes for Legion file object invocations.
-o <max outstanding invocations>	Specify the maximum number of outstanding Legion remote method invocations. If the -d flag is also enabled, only <max outstanding invocations> will be simultaneously queried for details. This flag also restricts the number of simultaneous file transfer block requests/sends.
-d	Specify that object details be retrieved during directory listings.
-w	If the -d flag has been enabled, Unix-style world access rights (r/w/x) will be displaced during directory listings. The SITE CHMOD command will also be enabled, allowing modification of individual object's world r/w/x rights.
-e	Encrypt all Legion communications. If you set this option and do not enable -a, you will have the highest level of data security.
-rt <RMI timeout>	Specify the Legion remote method invocation (RMI) time out value in seconds.
-dt <detail timeout>	Specify the time out value for looking up object details (use in conjunction with the -d flag).

legion_get_interface
    {-l <class LOID> | -c <context path>}
    [-debug] [-help]

Retrieves the interface of a Legion object, named by <class LOID> or <context path>, by calling that object's getInterface() member function. Prints the returned interface to stdout.

This example returns the interface of the LegionClass (the metaclass for all Legion classes).

$ legion_get_interface -c class/LegionClass
Getting the interface of object:1.01.01..000001fc0b325...
Object Interface:
  void deactivate();
  RestoreStateReply restoreState();
  SaveStateReply saveState(SaveStateRequest);
  LegionLOID ping();
  LegionObjectInterface getInterface();
  int exportsInterface(LegionObjectInterface);
  int addAttribute(ObjectAttribute);
  int addAttributes(ObjectAttributeList);
  int replaceAttribute(ObjectAttribute, ObjectAttribute);
  int replaceAttribute_s(ObjectAttribute,
        ObjectAttribute);
  int replaceAttributes(ObjectAttributeList, 
	ObjectAttributeList);
  int replaceAttributes_s(ObjectAttributeSignatureList, 
	ObjectAttributeList);
  int removeAttribute(ObjectAttribute);
  int removeAttribute_s(ObjectAttributeSignature);
  int removeAttributes(ObjectAttributeList);
  int removeAttributes_s(ObjectAttributeSignatureList);
  LegionAttributeList retrieveAttributes(
        ObjectAttributeList);
  LegionAttributeSignatureList retrieveAttributes_s(
        ObjectAttributeSignatureList);
  LegionAttributeList retrieveAllAttributes();
$

The following options are supported:

-debug	Catch and print Legion exceptions.
-help	Print command syntax and exit.

legion_ping 
    {-l <object LOID> | -c <context path>} [-timeout <seconds>]
    [-debug] [-help]

Calls the object-mandatory ping member function on the object named in <object LOID>. If the command returns, the object exists in an active state and its LOID is displayed. If the command does not return, the object is not accessible by the tool.

$ legion_ping -c foo
Pinging:  1.01.66000000.14000000.00...
Returned: 1.01.66000000.14000000.00...
$

The following options are supported:

-timeout <seconds>	The time-out flag specifies a maximum number of seconds to wait for the ping to complete successfully. If the object does not respond to the ping within that amount of time, legion_ping will exit. Please note that legion_ping failing due to a user-specified time-out does not necessarily mean that the object is inactive or otherwise unreachable. There is no default time-out setting.
-debug	Catch and print Legion exceptions.
-help	Print command syntax and exit.

legion_list_attributes
    {-l <object LOID> | -c <context path>} [-L] [<attribute name>]
    [-debug] [-help]

Lists an object's attributes from the command line. Optional parameters do the following:

-L	Lists the LOID of each attribute
<attribute name>	Specify the attribute to be listed (more than one attribute can be listed)
-debug	Catch and print Legion exceptions.
-help	Print command syntax and exit.

A very simple example of this command is below. An object's attributes can include architecture, operating system information, host or vault compatibility, encryption information, etc.

$ legion_list_attributes -c Foo
Foo:
  (ALL)
Total attributes retrieved 1
        favoritecolors('puce', 'apricot')
$

legion_list_invocations
    {-l <object LOID> | -c <object context path>}
    [-debug] [-help]

Prints a list of currently pending, started, and recently completed invocations for a given object. The output will include information about each invocation's status, timing, progress, and errors.

The following options are supported:

-debug	Catch and print Legion exceptions.
-help	Print command syntax and exit.

legion_object_info
    {[-c] <object context path> | -l <object LOID>} [-v]
    [-debug] [-help]

Prints information about a given object. The output (obtained from the object's class) will include the object's host, vault, owner, Object Address, status, etc. Optional parameters do the following:

-v	Print additional details about the specified object (host machine name and context name, OPA, and vault context name).
-debug	Catch and print Legion exceptions.
-help	Print command syntax and exit.

legion_skcc_set_class_vaults 
    <SKCC class context path> 
    {[-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>]}

Set an allowable set of backup vaults on which to store the specified SKCC class's replicated state. This applies to all of the class's instances. 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.

This overwrites any policies set via legion_class_vault_list. If you do not use legion_skcc_set_class_vaults, Legion will use the class vault restriction lists as specified with legion_class_vault_list. The specified class must belong to the SKCC metaclass. Current members are BasicFileClass, ContextClass, ImplementationObject, and UserAuthenticationObject.

You can use legion_set_backup_vaults to set vaults for a specific instance. Note, however, that legion_set_backup_vaults will overwrite the policy set by legion_skcc_set_class_vaults for that instance.

The following parameters must be used:

-l <SKCC class LOID> or -c <SKCC class context path>	Specify an SKCC class object.
-a	Add the specified vault to the object's list of backup vaults
-d	Delete the specified vault

legion_skcc_set_defaults 
    {[-l <SKCC class LOID> | -c <SKCC class context path>}
    <number of default vaults>

Specifies default level of state replication for instances of an SKCC class. Legion will now by default attempt to copy the instances' state on the specified number of vaults. You must be the class's owner to set this default.

The specified class must belong to the SKCC metaclass. You must have previously set up the class's backup vaults with the legion_skcc_set_class_vaults command. Currently, BasicFileClass, ContextClass, ImplementationObject, and UserAuthenticationObject are SKCC classes.

The following parameters must be used:

-l <SKCC class LOID> or -c <SKCC class context path>	Specify an SKCC class object.
<number of default vaults>	The maximum number of backup vaults that will hold copies of the SKCC class object's state.

legion_set_worm
    [[-c] <object context path> | -l <object LOID>]

This command tells Legion that the specified object has Write-Once Read-Many (WORM) semantics. It should be used in conjunction with the legion_set_backup_vaults command.

legion_unset_worm
    [[-c] <object context path> | -l <object LOID>]

This command tells Legion that the specified object no longer uses Write-Once Read-Many (WORM) semantics. It should be used in conjunction with the legion_set_worm command.

legion_update_attributes
    {[-c] <object context path> | -l <object LOID>} 
    [-a <new attribute>] [-d <attribute>] 
    [-r <old attribute> <new attribute>] 
    [-debug] [-help]

Adds, deletes, and replaces an object's attributes. The attribute(s) takes the form "name('val1 ... valn')". The attribute description must not contain any spaces or begin with an uppercase letter.

Optional parameters do the following:

-a <new attribute>	Add an attribute
-d <attribute>	Delete an attribute
-r <old attribute> <new attribute>	Replace an attribute
-debug	Catch and print Legion exceptions.
-help	Print command syntax and exit.

The following example adds the attribute color('red,blue') to object Foo, with the -a flag.

$ legion_update_attributes Foo -a "color('red,blue')"
legion_update_attributes:  Added 1 attributes(s) to object
$

Similarly, you can remove attributes, with the -d flag. Note, however, that if you must provide all of an attribute's parameters.

$ legion_update_attributes Foo -d "color('red')"
legion_update_attributes:  Warning - Deleted 0 attributes(s) from
object instead of 1 specified
     
$ legion_update_attributes Foo -d "color('red,blue')"
legion_update_attributes:  Deleted 1 attributes(s) from object
$

Calls on Class Objects

legion_activate_object 
    {-c <context path> | -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> or -l <template class LOID>	The orginal, existing class object.
<new class path>	The new class object's context path.

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.

legion_create_object
    {-l <class LOID> | -c <class context path>}
    <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 object of the class named in <class LOID> or <class context path>. No start-up parameters will be supplied for the class or new object.

If the -h flag isn't used, the host is selected by the class in which you are creating an instance. 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 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).

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.

legion_create_object_r 
    {-l <class LOID> | -c <class context path>} 
    <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.

<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
    [-debug] [-help] [-stay_down]
    {-l <object LOID> | -c <context path>}
    

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:

-debug	Catch and print Legion exceptions.
-help	Print command syntax and exit.
-stay_down	Forces object to stay inactive. It can only be reactivated by legion_allow_activation.

legion_destroy_object 
    {-l <object LOID> | -c <context path>}
    [-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 an object's context name: you must use the legion_rm command to remove the context name(s) or you will get binding errors in that context. (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_get_host {-l <object LOID> | -c <object context path>}
    [-debug] [-help]

This command looks up and returns the LOID of the host on which the object named in <object LOID> or <object context path> resides.

The following options are supported:

-debug	Catch and print Legion exceptions.
-help	Print command syntax and exit.

legion_get_vault {-l <object LOID> | -c <object context path>}
    [-debug] [-help]

Returns the LOID of the vault which the object named in <object context path> or <object LOID> is currently using to store its OPR.

The following options are supported:

-debug	Catch and print Legion exceptions.
-help	Print command syntax and exit.

legion_list_implementations [-vL] {-l <class LOID> | [-c] <class context path>}
    [-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. If the -vL flag is included, the output will include byte size and a brief description of each object.

The following options are supported:

-vL	Run the command in a verbose setting
-debug	Catch and print Legion exceptions.
-help	Print command syntax and exit.

Note that if the -v flag is used Legion will use one extra method invocation per implementation object.

legion_list_instances {-l <class LOID> | -c <context path>}
    [-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 -c /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

In a login session, the local binding agent caches some high-use objects' bindings and high-use contexts' LOIDs. These bindings may become stale, in which case you can manually refresh them with this tool. We suggest running it if you notice a consistent delay of around thirty seconds before and after commands respond.

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 persistant state: the object's persistant state is replicated and stored in multiple vaults when it is deactivated, so that if its main vault crashes the object's state is still available. However, the replication policy synchronizes the object's state when the object deactivates, so if the main vault crashes whle the object is still alive, the backup vaults will not have the object's most 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 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 from the object's list of backup vaults.
-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_vault {-l <instance LOID> | -c <instance context path>}
    {-l <vault LOID> | -c <vault context path>}
    [-permanent] [-debug] [-help]

Moves the OPR of the object named in <object LOID> or <object 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 the legion_instance_vault_list command)
-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 the -permanent flag 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, its state does not change. You can still run this command for a WORM object, but it is not necessary.

This command is implicitly called upon object deactivation.

This funcationality 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.

Calls on LegionClass

legion_add_class_mapping <metaclass LOID> <class LOID>
    [-debug] [-help]

This command notifies LegionClass that the meta-class named by <metaclass LOID> is the class of the class named by <class LOID>. LegionClass updates its class map accordingly.

The following options are supported:

-debug	Catch and print Legion exceptions.
-help	Print command syntax and exit.

legion_combine_domains [-v] <list of domain cookie files>
    [-debug] [-help]

Joins a set of Legion domains (systems) to create a single, larger, multi-domain Legion system. Before you run this command, you must obtain a copy of the Legion domain cookie files from all of the involved domains (see legion_generate_domain_cookie and legion_print_domain_cookie), including the current Legion domain. If you are joining domain A to domain B and domain B has already been joined to domain C, you will need cookie files from domains A, B, and C. This provides transitivity in the system join. All three domains will be joined to one another to form a single system. The command is implemented this way to avoid communication failures; if a LOID can be passed to an object (e.g., in a method continuation list), that object should be able to use the LOID for further communication.

Non-transitive or non-reflexive joins would allow communication of LOIDs for which an object could not obtain a binding. For example, object X in domain A might be able to bind to object Y in domain B and pass a method to it, but object Y might not be able to bind to object X to pass it the return value.

In addition to joining the binding trees of the involved domains, legion_combine_domains also creates context links in the current domain's context space to all of the remote domains' root contexts. These links appear in local context space in the following path: /domain/LegionDomain.<domain-id>.

If the command is run on domains that are already connected, it has no affect and is harmless.

There is currently no mechanism supporting "unjoining" of domains. However, Legion security mechanisms (e.g., ACLs) can be used to effectively forbid any use of the current domain by outside domains.

The following options are supported:

-v	Provide a verbose output as the command is running.
-debug	Catch and print Legion exceptions.
-help	Print command syntax and exit.

The example below combines two domains. If either had previously been connected to another domain, three cookie files would be listed.

$ legion_combine_domains LegionDomainCookie.35d82a07 \
     LegionDomainCookie.c8
Created 2 new domain interconnections.
$

legion_create_implementation 
    <binary path name> <architecture>
    [-l <class LOID> | -c <class context path>]
    [-c <object context path>] [-nc] [-v] [-a <attribute>]
    [-debug] [-help]

Creates an implementation object based on the binary executable named in <binary path name>. The new implementation object is associated with the class object named in <class LOID> or <context path>, and is marked as usable for hosts of a specified type (Linux, Solaris, or SGI).

The following options are supported:

-c <context path>	Specify a context path for the new object. Default is /impls/<binary_name>.<architecture>.<#>.
-nc	Specify that the new object have no context name.
-v	Run the command in verbose mode.
-a <attribute>	Assign the new object an extra attribute.
-debug	Catch and print Legion exceptions.
-help	Print command syntax and exit.

legion_generate_domain_cookie 
    [-o <cookie output filename>]
    [-debug] [-help]

Generates a domain cookie file for the current Legion domain, as required by legion_combine_domains. A cookie file contains binding information for the LegionClass in the current domain, security credentials for joining to the current domain, and information about the context space of the current domain (for creating interdomain context space links). The default cookie file name is LegionDomainCookie.<domain-id>, or you can use the -o flag to specify a name.

In a secure environment, you must be logged in as /users/admin for the current domain. This ensures that the required credentials can be generated and saved in the cookie file.

The following options are supported:

-o <cookie output filename>	Specify the local pathname of the resulting output cookie file.
-debug	Catch and print Legion exceptions.
-help	Print command syntax and exit.

legion_init_arch
    [-debug] [-help]

Creates and registers implementation objects for commonly used classes in the current architecture. This command is run on new hosts, so as to create the implmentation objects in the proper place. Implementation objects for specific binary executables can be created with the legion_create_implementation utility.

$ legion_init_arch
Initializing Legion implementations for "linux"

Creating an implementation (ContextObject) for
   ContextClass
Continue (y=yes, Y=yes to all, n=no, N=no to all, 
     v=verbose, V=verbose all)? Y
Creating an implementation (MetaClassObject) for
   LegionClass
Creating an implementation (ClassObject) for
   VanillaMetaClass
Creating an implementation (BindingAgent) for
   BindingAgentClass
Creating an implementation (BasicFileObject) for
   BasicFileClass
Creating an implementation (ttyObject) for
   ttyObjectClass
Creating an implementation (StatTreeObject) for
   StatTreeClass
$

The following options are supported:

-debug	Catch and print Legion exceptions.
-help	Print command syntax and exit.

legion_list_domains
    [-debug] [-help]

List the domains currently connected to your current Legion domain. The output will list the binding for your current domain and any domains linked to your current domain. Please see legion_combine_domains for information about connecting Legion domains.

The following options are supported:

-debug	Catch and print Legion exceptions.
-help	Print command syntax and exit.

legion_print_domain_cookie
    [-i <cookie input file>]
    [-debug] [-help]

Displays the contents of a Legion domain cookie file (required for using legion_combine_domains). By default the command displays the contents of the file LegionDomainCookie.<current-domain-id>, but any input file name can be specified using the -i option.

The following options are supported:

-i <cookie input filename>	Specify the path of the cookie file to print.
-debug	Catch and print Legion exceptions.
-help	Print command syntax and exit.

Calls on File and Context Objects

legion_activate_instances
    {-l <class LOID> | -c <class context path>}
    [-debug] [-help]

Activates all instances of the class named in <class context path> or <class LOID>. Instances that are already active will be unaffected.

The following options are supported:

-debug	Catch and print Legion exceptions.
-help	Print command syntax and exit.

legion_allow_activation
    [-entire_class] [-debug] [-help]
    {-l <LOID> | -c <context path>}

Activates the object or instances of the class named in <context path> or <LOID>. This should be used in association with the -stay_down option of legion_deactivate_object or legion_deactivate_instances.

The following options are supported:

-entire_class	Unlock all of the class's instances. You must be the class's owner in order to use this option.
-debug	Catch and print Legion exceptions.
-help	Print command syntax and exit.

legion_cat <context path1> <context path2> ... <context pathN>
    [-debug] [-help]

Prints the contents of the Legion file object(s) named in <context path> to standard output. It is similar to the Unix cat command.

$ legion_cat newFileObject
This is a test, just a test, nothing more.
$

The following options are supported:

-debug	Catch and print Legion exceptions.
-help	Print command syntax and exit.

legion_cd <context path>
    [-debug] [-help]

Changes the current working context to the context named in <context path>. Note that the path name can be relative or absolute. This command is analogous to the Unix cd command .

The following options are supported:

-debug	Catch and print Legion exceptions.
-help	Print command syntax and exit.

legion_context_add <object LOID> <context name>
    [-debug] [-help]

Adds a new name <context name> for the object named in <object LOID> to the current context space.

The following options are supported:

-debug	Catch and print Legion exceptions.
-help	Print command syntax and exit.

legion_context_create <context path>
    [-debug] [-help]

Creates a new context in Legion context space, and assigns it the name given in <context path>. This command is analogous to the Unix mkdir command. The new context will be placed in your current context. The output will contain the new context's location and its LOID.

The following options are supported:

-debug	Catch and print Legion exceptions.
-help	Print command syntax and exit.

legion_cp 
     [-r] [-v] [-m] [-p] [-localsrc] [-localdest] 
     [-V <vault context path>] <source file> <destination file>
    [-debug] [-help]

Copies the file named in <source file> (named as either a context path or a local path) to a new, duplicate, file object named in <destination file> (named as either a context path or a local path). The command is analogous to the Unix cp command. For example, to copy the file object Foo to /home/myContext/Bar, you would enter:

$ legion_cp Foo /home/myContext/Bar

You can now use wildcards in the <source path> parameter (for context space or local file space). Please note that you must escape the "*" character. The example below copies all files that start with "Foo" from local directory space into the /home/myContext context.

$ legion_cp -localsrc Foo\* /home/myContext

The new file objects are assigned the same names (e.g., if Foo\* finds Foo1 and Foo2, the duplicate file objects will be at /home/myContext/Foo1 and /home/myContext/Foo2).

Note that you cannot use wildcards in a destination path and you cannot copy multiple files to a single file object.

The following optional parameters are supported:

-v	Verbose mode. Prints information about which files and directories the command is currently working on.
-r	Recursive mode. If the <source path> is a directory, all of its contents are copied recursively. Only files and contexts/directories are handled. If other objects are encountered, they are skipped and legion_cp prints a warning message. Note that recursive mode automatically detects cycles in context space and prevents the recursive copy from revisiting context nodes in the cycle. A warning message is printed in the event that cycles are detected.
-localsrc	Indicates that the source path (<source path>) is in the local files system
-localdest	Indicates that the target path (<destination path>) is in the local file system.
-V <vault context path>	Specify a vault restriction for new objects created by this command. Supply the context path of the vault that should manage new objects created as legion_cp runs.
-m	Match-class mode. This mode indicates that when files or contexts are created by this command, they should match the class of their source context or file. By default, new files and contexts are created using the default file and context classes for your current Legion environment. This mode can only be used when copying within Legion context space (i.e., when no -localsrc or -localdest options are specified).
-p	Print out the size, transfer time, and transfer rate for each file copied.
-debug	Catch and print Legion exceptions.
-help	Print command syntax and exit.

legion_deactivate_instances 
    [-debug] [-help] [-stay_down]
    {-l <class LOID> | -c <class context path>}

Deactivates all instances of the class named in <class context path> or <class LOID>. Instances that are already deactivated will be unaffected.

The following options are supported:

-debug	Catch and print Legion exceptions.
-help	Print command syntax and exit.
-stay_down	Forces instances to stay inactive. It can only be reactivated by legion_allow_activation.

legion_destroy_instances 
    {-l <class LOID> | -c <class context path>}
    [-debug] [-help]

Destroys all instances of the class named in <class context path> or <class LOID>. If any instances are active, they are deactivated.

This command will remove the LOIDs of the specified class' instances in all contexts, not just the current context. However, it will not remove the context names: you must use the legion_rm command to 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_direct_output 
    {-l <LOID> | -c <object path>}
    {-l <tty LOID> | -c <tty context path>}
    [-debug] [-help]

Causes the object named in <object path> or <LOID> to direct its output (standard out and standard error) to the Legion tty object named by <tty LOID> or <tty context path>. Note, this command can only be invoked on objects that have dynamic output redirection enabled. If the command is invoked on an object that does not have redirection enabled, neither the object nor the tty is affected and an error message is displayed.

The following options are supported:

-debug	Catch and print Legion exceptions.
-help	Print command syntax and exit.

legion_export_dir 
    [-v] [-help] [-noserver] [-autorehash]
    <local directory path> <target context path>

The legion_export_dir command allows a complete directory tree in the local file system to be temporarily linked into Legion context space. A new context is created to replicate the local directory tree in context space. The files contained in the shared directory are copied in to Legion objects in the new context. The new context objects have the same names as the orginal files. For example, if the local directory contains three files called foo.txt, foo.doc, and foo.c, the new context will contain three Legion objects called foo.txt, foo.doc, and foo.c.

The command executes for as long as you wish: if you pause the command the tree's context space will not be available. Once you resume the command, the context will again be available.

To pause the command, run legion_export_dir_quit or (if the command was started in -noserver mode) press ^-C. To resume using the exported files, re-execute the command, specifying the same local base directory path and target context path. You can also run legion_rm -r on the new context, which will recursively delete the context and its contents, to stop the command.

You can make changes to the shared local directory while the command is running, but those changes won't be reflected in context space unless you use the -autorehash flag or run legion_export_dir_rehash.

The following parameters are required:

<local directory path>	A local directory or directory tree that you wish to export to Legion context space.
<target context path>	A new context path which will hold copies of the exported directory tree.

Optional parameters do the following:

-v	Verbose mode. Prints information about which files and directories the command is currently exporting.
-help	Print command syntax and exit.
-noserver	Keep the program attached to a terminal so that it can be shutdown via ^-C and its output can be monitored.
-autorehash	Periodically check the shared local directory so that any changes are reflected in context space.

legion_export_dir_quit 
    <target context path>

To be used in conjunction with legion_export_dir. Pauses legion_export_dir for the specified context path.

The following parameter is required:

<target context path>

A new context path which will hold copies of the exported directory tree.

legion_export_dir_rehash 
    <target context path>

To be used in conjunction with legion_export_dir. Tells the command to check the shared local directory for any changes and to update the shared context space accordingly.

The following parameter is required:

<target context path>

A new context path which will hold copies of the exported directory tree.

legion_get_host {-l <object LOID> | -c <object context path>}
    [-debug] [-help]

This command looks up and returns the LOID of the host on which the object named in <object context path> or <object LOID> currently resides.

$ legion_get_host -c Foo
1.01.07.d49d1a40.000001fc0c04724...
$

The following options are supported:

-debug	Catch and print Legion exceptions.
-help	Print command syntax and exit.

legion_get_vault {-l <object LOID> | -c <object context path>}
    [-debug] [-help]

Returns the LOID of the vault which the object named in <object context path> or <object LOID> is currently using to store its OPR.

$ legion_get_vault -c Foo
1.01.03.d49d1a40.000001fc0a69cbb8...
$

The following options are supported:

-debug	Catch and print Legion exceptions.
-help	Print command syntax and exit.

legion_list_names {-l <object LOID> | -c <object context path>} 
    [-debug] [-help]

Lists all of the given object's context names. This includes names assigned by other users.

The following options are supported:

-debug	Catch and print Legion exceptions.
-help	Print command syntax and exit.

legion_ln <context path> <new alias>
    [-debug] [-help]

Assigns an additional name, given in <new alias>, to the object named in <context path>. Analogous to the Unix ln command. Path names can be relative or absolute.

An object can have multiple context names, assigned by one or more users. The same context name can be assigned to different objects or to the same object so long as the contexts names are in different contexts (just as the same file names can be used in different levels of a Unix directory).

The following options are supported:

-debug	Catch and print Legion exceptions.
-help	Print command syntax and exit.

legion_ls [-laLRAdqv] [<context path>]
    [-debug] [-help]

Lists the contents of a named Legion context in ascii-alphabetical order. Note that the pathname can be relative or absolute. The command is analogous to the Unix ls command. The default setting lists the current context. You can include a context path in the <context path> parameter to list the contents of that context. For example:

$ legion_ls /hosts
BootstrapHost
my.host.DNS.name
$

You can now use wildcards in the <context path> parameter. Please note that you must escape the "*" character. I.e., to search for context objects containing "foo" in their names you would enter:

$ legion_ls \*foo\*

You cannot use wildcards with the -R flag.

Optional parameters do the following:

-l	List object type and information, if available. Objects of unknown type will be listed as object and faulty objects will be listed as not available.
-a	List "hidden" objects in the context, i.e. those objects whose names begin with a "." character. Examples would be the "." (current) and ".." (parent) contexts.
-L	Lists LOIDs associated with names.
-R	Print a recursive listing of the current context. You cannot use this flag with wildcards.
-A	List all known context aliases for each listed object.
-d	List contexts like other objects, rather than listing their contents.
-q	When creating a long listing, do not activate inactive objects.
-v	Run command in verbose mode.
-debug	Catch and print Legion exceptions.
-help	Print command syntax and exit.

You can get more information about the objects in the current or a selected object or about a particular object by including one or more flags and a context path name. The output below combines the -l, -a, and -A flags to get a list of all objects in the /hosts context, their type, and all of their context names.

$ legion_ls -laA /hosts
.                              (context)
        /hosts
..                             (context)
        /class/..
        /hosts/..
        /vaults/..
        /home/..
BootstrapHost                  (object)
        /hosts/BootstrapHost
        /hosts/stonesoup01.cs.virginia.edu
stonesoup01.cs.virginia.edu    (object)
        /hosts/BootstrapHost
        /hosts/stonesoup01.cs.virginia.edu
$

According to this, there are four names listed in /hosts, two referring to contexts and two to objects. We can see from the alternative context names, though, that BootstrapHost and my.host.DNS.name refer to the same object.

legion_mkdir <context path>
    [-debug] [-help]

Creates a new context in Legion context space, and assigns it the name given in <context path>. This command is analogous to the Unix mkdir command (it is also identical to the legion_context_create command). The new context will be placed in your current context. The output will contain the new context's location and its LOID.

The following options are supported:

-debug	Catch and print Legion exceptions.
-help	Print command syntax and exit.

legion_mv <context path> <new context path>
    [-debug] [-help]

Assigns a new context name, given in <new context path> to the object named in <context path>. Pathnames can be relative or absolute. Analogous to the Unix mv command.

The following options are supported:

-debug	Catch and print Legion exceptions.
-help	Print command syntax and exit.

legion_pwd
    [-debug] [-help]

Prints your current context path (similar to the Unix pwd command).

The following options are supported:

-debug	Catch and print Legion exceptions.
-help	Print command syntax and exit.

legion_rm [-r] [-f] [v] <context path list>
    [-debug] [-help]

Removes the context path[s] named in <context path list> from Legion context space. Pathnames can be relative or absolute. Analogous to the Unix rm command.

If the context path listed is the last (i.e., only) name mapped to a given object, the object will be destroyed. If there are other names mapped to the object, the object will be removed.

You can now use wildcards in the <context path list> parameter. Please note that you must escape the "*" character. I.e., to remove all context objects containing "foo" in their names you would enter:

$ legion_rm \*foo\*

Optional parameters do the following:

-r	Recursively remove one or more contexts and all of their contents.
-f	Force faulty objects (those with bad bindings) to be removed.
-v	Run this command in a verbose setting. This will indicate when objects are destroyed and when only names are being destroyed.
-debug	Catch and print Legion exceptions.
-help	Print command syntax and exit.

legion_set_tty <tty context path>
    [-debug] [-help]

This command will set an environment variable to indicate which tty object should be used by subsequent programs. By selecting a new current tty object, users can redirect the output to any window or file.

$ legion_set_tty /context_path/my-tty

Note that program output does not have to be directed to the same window in which the program is run. By setting a new current tty object, the output can be redirected to any window, or even a file. For example:

$ legion_create_object -c /class/ttyObjectClass \
  /context_path/my-tty
$ legion_set_tty /log-file

creates a tty object whose output is sent to a file. To view the tty output, use the legion_tty_watch command.

The following options are supported:

-debug	Catch and print Legion exceptions.
-help	Print command syntax and exit.

legion_tty <tty context path>
    [-debug] [-help]

This command can be used to direct all output from a particular shell back to that shell--i.e., create and set a tty object for a shell--in one step, rather than running legion_create_object, legion_set_tty, and legion_tty_watch. If no tty object exists at the path named in <context path> it creates a new object, sets it as the target tty, and starts the legion_tty_watch process in the background of the shell in which the command was run. If a tty object already exists at the named context path, the command sets that tty object as the target tty.

The following options are supported:

-debug	Catch and print Legion exceptions.
-help	Print command syntax and exit.

legion_tty_off
    [-debug] [-help]

Turns off the backgrounded legion_tty_watch process for that shell, i.e., stops directing the shell's output back to itself. Note that this only works when coupled with the legion_tty command (above).

The following options are supported:

-debug	Catch and print Legion exceptions.
-help	Print command syntax and exit.

legion_tty_redirect <object context path>
    [-debug] [-help]

Causes the Legion tty object currently set in the shell environment to stream directly into the file object named in <context path>. If the file does not already exist the system creates it. Existing files are appended to, not truncated. A single tty object can be simultaneously directed into any number of files (as well as watched from any number of terminal windows).

The following options are supported:

-debug	Catch and print Legion exceptions.
-help	Print command syntax and exit.

legion_tty_unredirect <object context path>
    [-debug] [-help]

Causes the Legion tty object currently set in the shell environment to stop streaming into the file object named in <context path>. If the tty object is not currently directing output to the named file the command is ignored.

The following options are supported:

-debug	Catch and print Legion exceptions.
-help	Print command syntax and exit.

legion_tty_watch [-l <tty LOID> | -c <tty context path>]
    [-debug] [-help]

Causes output written to a Legion tty object to be printed to standard output. If no command line parameters are specified, the current tty object set for the shell session is selected. Otherwise, the tty object named by <LOID> or <context path> is selected. Note, the command will not self-terminate: to stop the program send it a SIGINT (i.e., using ^C or "kill -INT"). Any number of legion_tty_watch sessions smay simultaneously watch the same Legion tty object.

The following options are supported:

-debug	Catch and print Legion exceptions.
-help	Print command syntax and exit.

legion_2drm
    <file name>

This command removes a 2D file object from Legion. It differs from legion_rm in that the object's subfiles are removed as well. If you use legion_rm to remove a 2D file object, the object's subfiles will not be removed.

The following parameter must be included:

file name

Local path of a 2D file object.

Start-Up and Shutdown Functions

legion_add_host_account
    {-l <host object LOID> | [-c] <host object context path>}
    {[-f <mapping file name>] | [<Unix user id> [-l <owner LOID> | -c <owner context path>]]}
    [-debug] [-help]

This command is used on PCD host objects. Adds a mapping between a Legion account and a Unix account and adds this mapping to a PCD host object's list of available accounts. The user's Unix user id is named in the <Unix user id> parameter. The host object is named in the <host object LOID>/<host object context path> parameter. The user's Legion user id can be given in the <owner LOID>/<owner context path> parameter.

The following optional parameters are supported:

-f <mapping file name>	Names a mapping file. The mapping file contains a list of Unix user id-Legion user name mappings for that PCD host object. There is no limit on the number of mappings that can be listed. One mapping per line. If a Unix id is listed but not mapped to a Legion user id, the account will be a guest account.
-debug	Catch and print Legion exceptions.
-help	Print command syntax and exit.

legion_create_class [-c <context path>] 
    [-sc <scheduler context path>] [-sl <scheduler LOID>]
    [-debug] [-help]

Creates a new instance of class VanillaMetaClass. The object will be placed in the current working context, unless specified with the -c flag. The following optional parameters are supported:

-c	Assign the new object the name given in <context path>
-sc <scheduler context path>	Specify the context path of the default scheduler object that the new class should use.
-sl <scheduler LOID>	Specify the LOID of the default scheduler object that the new class should use.
-debug	Catch and print Legion exceptions.
-help	Print command syntax and exit.

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

Destroy a given host object. All contexts objects on that host will be destroyed and all active objects will be deactivated. Optional parameters do the following:

-v	Run in verbose mode.
-debug	Catch and print Legion exceptions.
-help	Print command syntax and exit.

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

Destroy a given vault object. Legion will attempt to move all of the vault's current OPRs off of the vault object and then destroy the vault object. If any OPRs cannot be successfully moved the process will abort and an error message will be displayed.

The following options are supported:

-debug	Catch and print Legion exceptions.
-help	Print command syntax and exit.

legion_initialize

Populates the Legion system with basic classes and implementations. This command should be run after a Legion system is started for the first time (using legion_startup). On subsequent activations of the system, the state created by this utility will already exist, so this command should not be run again.

legion_list_host_accounts
    {-l <host object LOID> | [-c ]<host object context path>}
    <user id> [-debug] [-help]-help]

This command is used on PCD host objects. It removes one or more account mappings from the host object's list of available accounts. The parameter is the user's Unix user id. If no host is named in the <host object LOID>/<host object context path> parameter, your current host object will be the default host.

The following options are supported:

-debug	Catch and print Legion exceptions.
-help	Print command syntax and exit.

legion_make_setup_script [-o <script basename>] [-OPR <OPR dir name>]
    [-L <$LEGION dir name>]
    [-debug] [-help]

Generates a Legion setup script for your system. This script sets the environment variables for Legion users.

The following options are supported:

-o <script basename>	Specify the basename for the resulting setup scripts (default is /home/xxxx/OPR/setup). This command will generate two setup scripts, one for /bin/sh derivative users and one for csh-derivative users. The scripts will be named <script basename>.sh and <script basename>.csh, respectively.
-OPR <OPR dir name>	Specify the OPR directory name that will be set up when the resulting scripts are run. This directory will contain the user's local copy of Legion-Class.config (default is "Legion-OPR"). The user's local version of the directory will be placed in the user's $HOME.
-L <$LEGION dir name>	Specify the value of $LEGION, which is the directory where the resulting scripts are run. The default is the current value of $LEGION.
-debug	Catch and print Legion exceptions.
-help	Print command syntax and exit.

legion_print_config
    [-debug] [-help]

Prints the "well-known" binding for LegionClass in the current Legion configuration.

The following options are supported:

-debug	Catch and print Legion exceptions.
-help	Print command syntax and exit.

legion_remove_host_account
    [-l <host object LOID> | [-c] <host object context path>]
    [-debug] [-help]-help]

This command is used on PCD host objects. It lists the available accounts on a host object. If no host object argument is provided, your current host object will be used as a default.

The following options are supported:

-debug	Catch and print Legion exceptions.
-help	Print command syntax and exit.

legion_setup_state [-i]
    [-debug] [-help]

Creates OPRs for the basic Legion system objects. This script should be run when starting a Legion system for the first time.

The following options are supported:

-i	Run the command in an interactive mode.
-debug	Catch and print Legion exceptions.
-help	Print command syntax and exit.

legion_shutdown [-local] [-f] [-i] [-h]
    [-debug] [-help]

Shuts down a running Legion system, preserving the state of all objects for subsequent reactivation of the system. Optional parameters allow users to shut down individual hosts and to specify an interactive shutdown.

Optional parameters do the following:

-local	Shuts down only a local host or vault.
-f	Forces the termination of a system, may leave processes running and prevent a system restart.
-i	Puts the shutdown in an interactive mode, which will provide prompts for user actions.
-h	Returns the command's complete syntax.
-debug	Catch and print Legion exceptions.
-help	Print command syntax and exit.

legion_shutdown_class 
    {-l <class LOID> | -c <context path>}
    [-debug] [-help]

Deactivates the class object named in <class LOID> or <context path> and all of its instances. This command operates recursively: if applied to a metaclass, for example, it would deactivate the metaclass, all of its class instances, all of their instances, etc.

The following options are supported:

-debug	Catch and print Legion exceptions.
-help	Print command syntax and exit.

legion_starthost 
    [-L <$LEGION>] [-O <$LEGION_OPR>] [-A <$LEGION_ARCH>] 
    [-B <path>] [-N <context name>] [-U <user id>] 
    <new host name> [<compatible vault list>]
    [-debug] [-help]

Creates a new host object on the specified <new host name>, using the legion_create_object_r command (which is automatically invoked on the host class). The <new host name> is the host's DNS name. The legion_starthost command selects the following default values for the new object:

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

Optional parameters do the following:

-L <$LEGION>	Specify $LEGION for host (default is the local $LEGION value)
-O <$LEGION_OPR>	Specify $LEGION_OPR for host (default is the local $LEGION_OPR value)
-A <$LEGION_ARCH>	Specify the architecture type for the host (default is the local $LEGION_ARCH value)
-B <path>	Specify the basename of the host binary (default is "UnixHostObject")
-N <context name>	Specify the context name for the host object (default is "/hosts/<host name>")
-U <user id>	Specify the user id for host (default is current user id)
-debug	Catch and print Legion exceptions.
-help	Print command syntax and exit.

legion_startup [-local]
    [-debug] [-help]

Starts up basic Legion services.

The following optional parameters are supported:

-local	starts up only a local host or vault
-debug	Catch and print Legion exceptions.
-help	Print command syntax and exit.

legion_startvault 
    [-L <$LEGION>] [-O <$LEGION_OPR>] [-A <$LEGION_ARCH>] 
    [-N <context name>] [-U <user id>] <host name>
    [<compatible host list>]
    [-debug] [-help]

Creates a new vault object on the specified <host name>, using the legion_create_object_r command (which is automatically invoked on the host class). The <host name> is the host's DNS name.

The following optional parameters are supported:

-L <$LEGION>	Specify $LEGION for the vaults host (default is the local $LEGION value)
-O <$LEGION_OPR>	Specify $LEGION_OPR for the vaults host (default is the local $LEGION_OPR value)
-A <$LEGION_ARCH>	Specify the architecture of the vaults host (default is the local $LEGION_ARCH value)
-N <context name>	Specify the context name for the vault object (default is "/vaults/vault-<host name>")
-U <user id>	Specify the user id to use on the vaults host (default is current user id)
-debug	Catch and print Legion exceptions.
-help	Print command syntax and exit.

Scheduling Support

legion_add_sub_collection
    {-l <collection LOID> | -c <collection path>}
    {-l <member LOID> | -c <member path>} [-q <query>]

This command creates a new parent-subcollection relationship. A subcollection is a collection object that is polled by another collection object (called the parent collection) with a specified MESSIAHS-type query. If no query is specified, the default value of 'true' will be used. You can run this command multiple times to start multiple queries on a single subcollection.

A parent collection can have more than one subcollection and can run multiple queries on a single subcollection. A subcollection can have more than one parent as well as its own subcollections.

You must designate a parent collection (named in <collection LOID> or <collection path>). The member (named in <member LOID> or <member path>) is the subcollection. Both collections must already exist.

You can edit the collection_update_frequency_secs attribute with the legion_update_attributes command. E.g.,

$ legion_update_attributes -c /etc/Collection \
"collection_update_frequency_secs(600)"

will set the default collection to update itself every 10 minutes. The default setting is 300 seconds.

The following option is supported:

-q <query>

A MESSIAHS-style query that will be run on the subcollection. The default selection is 'true'. See legion_query_collection for details.

legion_class_host_list 
    [-l <class LOID> | -c <class context path>]
    [{-a | -d | -t} <host1> <host2> ... <hostn>] [-p] [-u]
    [-debug] [-help]

Manipulates the list of hosts upon which the class named in <class context path> or <class LOID> can place its instances. The list of acceptable hosts for a given class consists only of hosts that have been added to the list. The list therefore may not necessarily include all possible hosts. If there are no hosts listed as acceptable the user can assume that all hosts are acceptable.

The following optional parameters are supported:

-c	Use context paths to specify class and host
-l	Use dotted hex LOIDs to specify class and host
-a	Add named host to the class's acceptable host list
-d	Delete named host from the class's acceptable host list
-t	Test whether or not a host is on the class's acceptable host list
-p	Display the class's acceptable host list
-u	Print usage
-debug	Catch and print Legion exceptions.
-help	Print command syntax and exit.

The example below adds a new host to the list of acceptable hosts of BasicFileClass, using the -a flag.

$ legion_class_host_list -c /class/BasicFileClass \
  -a /hosts/newHost
** ADDED 1 host(s) to class's acceptable host set

The -p flag can then be used to check the listing.

$ legion_class_host_list -c /class/BasicFileClass -p
** ACCEPTIBLE HOST LISTING: 
**      1.01.07.d59d1a40.000001fc094e23...
$

You can use the -a, -d, and -t flags more than once when running the command but regardless of how you list them on the command line Legion will process them in a specific order when you run the command: first adding any new hosts, then deleting old hosts, then testing any hosts, and finally printing out the results. Note also that if you give the class's context name in the first parameter (i.e., with the -c flag) you must use the hosts' context names in the <host1>, <host2>, ...<hostn> parameter. Similarly, if you give the class's LOID (with the -l flag) you must use the hosts' LOIDs. In other words, if you were to enter:

$ legion_class_host_list -c /class/myClass \
  -t 1.01.07.d59d...

You would get an error message. Legion will treat the host's LOID as a context name.

legion_class_vault_list 
    {-l <class LOID> | -c <class context path>}
    [{-a | -d | -t} <vault1> <vault2> ... <vaultn>] [-p] [-u]
    [-debug] [-help]

Manipulates the list of vaults upon which the class named in <class context path> or <class LOID> can place its instances' OPRs. Optional parameters are:

-c	Use context paths to specify class and vault
-l	Use LOIDs to specify class and vault
-a	Add named vault to the class's acceptable vault list
-d	Delete named vault from the class's acceptable vault list
-t	Test whether or not a vault is on the class's acceptable vault list
-p	Display the class's acceptable vault list
-u	Print usage
-debug	Catch and print Legion exceptions.
-help	Print command syntax and exit.

You can use the -a, -d, and -t flags more than once when running the command but regardless of how you list them on the command line Legion will process them in a specific order when you run the command: first adding any new vaults, then deleting old vaults, then testing any vaults, and finally printing out the results. Note also that if you give the class's context name in the first parameter (i.e., with the -c flag) you must use the vaults' context names in the <vault1>, <vault2>, ...<vaultn> parameter. Similarly, if you give the class's LOID (with the -l flag) you must use the vaults' LOIDs. In other words, if you were to enter:

$ legion_class_vault_list -c /class/myClass \
  -t 1.01.07.01000...

You would get an error message. Legion will treat the vault's LOID as a context name.

legion_config_scheduler
    {-l <Scheduler LOID> | -c <Scheduler context path>} 
    [-get_enactor] [-get_collection] 
    [-set_enactor {-l <Enactor LOID> | -c <Enactor path>}] 
    [-set_collection {-l <Collection LOID> | -c <Collection path>}]
    [-debug] [-help]

This command can be used to query or configure the helper objects used by a basic Legion scheduler. Basic Legion Scheduler objects use a Collection helper object to obtain information about available resources upon which they can schedule objects. After constructing a schedule, basic Legion Schedulers use an Enactor helper object to implement scheduling decisions (to actually start up the scheduled objects). Use legion_config_scheduler to assign a particular Collection and Enactor to a basic Legion Scheduler or vice versa.

The following optional parameters are supported:

-get_enactor	Print the LOID of a basic Legion Scheduler's currently assigned Enactor helper object
-get_collection	Print the LOID of a basic Legion Scheduler's currently assigned Collection helper object
-set_enactor	Set the Enactor named in <Enactor LOID> or <Enactor path> to the Scheduler
-set_collection	Set the Collection named in <Collection LOID> or <Collection path> to the Scheduler
-debug	Catch and print Legion exceptions.
-help	Print command syntax and exit.

legion_host_vault_list 
    {-l <host LOID> | -c <host context path>}
    [{-a | -d | -t} <vault1> <vault2> ... <vaultn>] [-p] [-u]
    [-debug] [-help]

Used to display and manipulate list of vaults with which the host named in <host context path> or <host LOID> can interoperate.

The following optional parameters are supported:

-c	Use context paths to specify host and vault
-l	Use dotted hex LOIDs to specify host and vault
-a	Add named vault to the host's acceptable vault list
-d	Delete named vault from the host's acceptable vault list
-t	Test whether or not a vault is on the host's acceptable vault list
-p	Display the host's acceptable vault list
-u	Print usage
-debug	Catch and print Legion exceptions.
-help	Print command syntax and exit.

To list the vaults that a host can operate on, for instance, you would type in:

$ legion_host_vault_list -c /hosts/HostName -p
** COMPATIBLE VAULT LISTING: 
**      1.01.03.d49d1a40.000001fc0a69cbb845...
$

You can use the -a, -d, and -t flags more than once when running the command but regardless of how you list them on the command line Legion will process them in a specific order when you run the command: first adding any new vaults, then deleting old vaults, then testing any vaults, and finally printing out the results. Note also that if you give the host's context name in the first parameter (i.e., with the -c flag) you must use the vaults' context names in the <vault1>, <vault2>, ...<vaultn> parameter. Similarly, if you give the host's LOID (with the -l flag) you must use the vaults' LOIDs. In other words, if you were to enter:

$ legion_host_vault_list -c /host/HostName \
  -t 1.01.03.d49...

You would get an error message. Legion will treat the vault's LOID as a context name.

legion_instance_host_list
    {-l <instance LOID> | -c <instance context path>}
    [{-a | -d | -t} <host1> <host2> ... <hostn>] [-p] [-u]
    [-debug] [-help]

Manipulates the list of acceptable hosts upon which the instance named in <instance LOID> or <instance context path> can be placed.

The following optional parameters are supported:

-c	Use context paths to specify instance and host
-l	Use LOIDs to specify instance and host
-a	Add named host to the instance's acceptable host list
-d	Delete named host from the instance's acceptable host list
-t	Test whether or not a host is on the instance's acceptable host list
-p	Display the instance's acceptable host list
-u	Print usage
-debug	Catch and print Legion exceptions.
-help	Print command syntax and exit.

You can use the -a, -d, and -t flags more than once when running the command but regardless of how you list them on the command line Legion will process them in a specific order when you run the command: first adding any new hosts, then deleting old hosts, then testing any hosts, and finally printing out the results. Note also that if you give the instance's context name in the first parameter (i.e., with the -c flag) you must use the hosts' context names in the <host1>, <host2>, ...<hostn> parameter. Similarly, if you give the instance's LOID (with the -l flag) you must use the hosts' LOIDs. In other words, if you were to enter:

$ legion_instance_host_list -c myInstance \
   -t 1.01.07.01000...

You would get an error message. Legion will treat the host's LOID as a context name.

legion_instance_vault_list
    {-l <instance LOID> | -c <instance context path>}
    [{-a | -d | -t} <vault1> <vault2> ... <vaultn>] [-p] [-u]
    [-debug] [-help]

Manipulates the list of acceptable vaults upon which the instance named in <instance LOID> or <instance context path> can be placed.

The following optional parameters are supported:

-c	Use context paths to specify instance and vault
-l	Use LOIDs to specify instance and vault
-a	Add named vault to the instance's acceptable vault list
-d	Delete named vault from the instance's acceptable vault list
-t	Test whether or not a vault is on the instance's acceptable vault list
-p	Display the instance's acceptable vault list
-u	Print usage
-debug	Catch and print Legion exceptions.
-help	Print command syntax and exit.

You can use the -a, -d, and -t flags more than once when running the command but regardless of how you list them on the command line Legion will process them in a specific order when you run the command: first adding any new vaults, then deleting old vaults, then testing any vaults, and finally printing out the results. Note also that if you give the instance's context name in the first parameter (i.e., with the -c flag) you must use the vaults' context names in the <vault1>, <vault2>, ...<vaultn> parameter. Similarly, if you give the instance's LOID (with the -l flag) you must use the vaults' LOIDs. In other words, if you were to enter:

$ legion_instance_vault_list -c myInstance \
   -t 1.38736c78.03.01000000.000...

You would get an error message. Legion will treat the vault's LOID as a context name.

legion_join_collection
    {-l <Collection LOID> | -c <Collection path>}
    {-l <member LOID> | -c <member path>}
    [-debug] [-help]

This command joins the objects named in <member LOID> or <member path> to the Collection named in <Collection LOID> or <Collection path>. Any Legion object can be added to a Collection.

Use the legion_query_collection command to get information (in the form of object attributes) about the given collection.

The following options are supported:

-debug	Catch and print Legion exceptions.
-help	Print command syntax and exit.

legion_leave_collection
    {-l <Collection LOID> | -c <Collection path>}
    {-l <member LOID> | -c <member path>}
    [-debug] [-help]

This command removes the object named in <member LOID> or <member path> from the Collection named in <Collection LOID> or <Collection path>.

The following options are supported:

-debug	Catch and print Legion exceptions.
-help	Print command syntax and exit.

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

Lists all OPRs currently stored in a given vault. The output includes information about inert objects' LOIDs, OPA, owner, and status.

The following options are supported:

-debug	Catch and print Legion exceptions.
-help	Print command syntax and exit.

legion_list_sub_collections
    {-l <collection LOID> | -c <collection path>}

List a collection's set of subcollections and queries.

legion_make_schedule
    {-c <class context path> | -l <class LOID>}
    [-n <number of nodes>] [-f <specification file>]
    [-q <query>] [-help]

This command creates a host file for running an instance of the class named in <class context path> or <class LOID>. The hos