Table of Contents
 |
 Calls on objects Calls on class objects Calls on LegionClass Calls on file and context objects Start-up and shutdown functions Scheduling support
| |
General functions about the state of the system Security Application development Program support Alphabetical list of commands Other on-line tutorials & documentation
|
to move to the selected text.
$ . ~legion/setup.sh
or
$ source ~legion/setup.cshThe following style conventions are used in these tutorials:
Calls on objects
legion_configure_profile
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:
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:
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]| 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 |
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
$
| -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>]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]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();
$
| -debug | Catch and print Legion exceptions. |
| -help | Print command syntax and exit. |
legion_ping
{-l <object LOID> | -c <context path>} [-timeout <seconds>]
[-debug] [-help]$ legion_ping -c foo Pinging: 1.01.66000000.14000000.00... Returned: 1.01.66000000.14000000.00... $
| -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]| -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. |
$ 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]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]| -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>]}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>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>]
legion_unset_worm
[[-c] <object context path> | -l <object LOID>]
legion_update_attributes
{[-c] <object context path> | -l <object LOID>}
[-a <new attribute>] [-d <attribute>]
[-r <old attribute> <new attribute>]
[-debug] [-help]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. |
$ legion_update_attributes Foo -a "color('red,blue')"
legion_update_attributes: Added 1 attributes(s) to object
$$ 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]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>]}| -c <template class path> or -l <template class LOID> | The orginal, existing class object. |
| <new class path> | The new class object's context path. |
| -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]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]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>}
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]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]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]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]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]$ 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
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>}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
$ 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>} | -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]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 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]]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]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]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]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]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]$ 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]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]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]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>}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]$ 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]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]The following options are supported:
| -debug | Catch and print Legion exceptions. |
| -help | Print command syntax and exit. |
legion_context_create <context path>
[-debug] [-help]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]$ 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>}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]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]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 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>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>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]$ 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]$ 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]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]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]$ 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]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]The following options are supported:
| -debug | Catch and print Legion exceptions. |
| -help | Print command syntax and exit. |
legion_pwd
[-debug] [-help]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]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]$ 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
The following options are supported:
| -debug | Catch and print Legion exceptions. |
| -help | Print command syntax and exit. |
legion_tty <tty context path>
[-debug] [-help]The following options are supported:
| -debug | Catch and print Legion exceptions. |
| -help | Print command syntax and exit. |
legion_tty_off
[-debug] [-help]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]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]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]The following options are supported:
| -debug | Catch and print Legion exceptions. |
| -help | Print command syntax and exit. |
legion_2drm
<file name>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]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]| -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]| -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]The following options are supported:
| -debug | Catch and print Legion exceptions. |
| -help | Print command syntax and exit. |
legion_initialize
legion_list_host_accounts
{-l <host object LOID> | [-c ]<host object context path>}
<user id> [-debug] [-help]-help]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]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]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]The following options are supported:
| -debug | Catch and print Legion exceptions. |
| -help | Print command syntax and exit. |
legion_setup_state [-i]
[-debug] [-help]
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]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]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]| <$LEGION_OPA> | = $LEGION_OPR/Host-$HOST.OPA |
| <binary path> | = $LEGION/bin/$LEGION_ARCH/UnixHostObject |
| -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]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]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>]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)"
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]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
$ legion_class_host_list -c /class/BasicFileClass -p ** ACCEPTIBLE HOST LISTING: ** 1.01.07.d59d1a40.000001fc094e23... $
$ legion_class_host_list -c /class/myClass \ -t 1.01.07.d59d...
legion_class_vault_list
{-l <class LOID> | -c <class context path>}
[{-a | -d | -t} <vault1> <vault2> ... <vaultn>] [-p] [-u]
[-debug] [-help]| -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...
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]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]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... $
$ legion_host_vault_list -c /host/HostName \ -t 1.01.03.d49...
legion_instance_host_list
{-l <instance LOID> | -c <instance context path>}
[{-a | -d | -t} <host1> <host2> ... <hostn>] [-p] [-u]
[-debug] [-help]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...
legion_instance_vault_list
{-l <instance LOID> | -c <instance context path>}
[{-a | -d | -t} <vault1> <vault2> ... <vaultn>] [-p] [-u]
[-debug] [-help]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...
legion_join_collection
{-l <Collection LOID> | -c <Collection path>}
{-l <member LOID> | -c <member path>}
[-debug] [-help]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]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]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>}
legion_make_schedule
{-c <class context path> | -l <class LOID>}
[-n <number of nodes>] [-f <specification file>]
[-q <query>] [-help]The following options are available:
| -n <number of nodes> | Specify the number of nodes required for this run. Default is 1. |
| -f <specification file> | Name a specification file that contains relative performance ratios for different architectures. E.g., the specification file could contain the lines:
|
| -q <query> | Specify a MESSIAHS query that can be used to prune the list of hosts on which the run can be scheduled. |
| -help | Print command syntax and exit. |
legion_query_collection
{-l <Collection LOID> | -c <Collection path>} <query>
[-debug] [-help]Collection queries can be constructed using the interface below.
<query> | —> | <bool-expression> |
<bool-expression> | —> | true | TRUE | True | false | FALSE | False |
| —> | <comparison-expr> | |
<comparison-expr> | —> | <expr> == <expr> |
| —> | <expr> <= <expr> | |
| —> | <expr> >= <expr> | |
| —> | <expr> < <expr> | |
| —> | <expr> > <expr> | |
| —> | <expr> <> <expr> | |
| —> | <expr> != <expr> | |
| —> | <expr> or <expr> | |
| —> | <expr> xor <expr> | |
| —> | <expr> and <expr> | |
| —> | not <expr> | |
| —> | match (<string>, <string>) | |
<expr> | —> | <comparison-expr> |
| —> | <int-const> | |
| —> | <oct-const> | |
| —> | <float-const> | |
| —> | <string> | |
| —> | $<identifier> | |
| —> | - <expr> | |
| —> | ~ <expr> | |
| —> | <expr> + <expr> | |
| —> | <expr> - <expr> | |
| —> | max (<expr>, <expr>) | |
| —> | min (<expr>, <expr>) | |
| —> | <expr> / <expr> | |
| —> | <expr> * <expr> | |
| —> | <expr> mod <expr> | |
| —> | int (<expr>) | |
| —> | float (<expr>) | |
| —> | (<expr>) | |
<int-const> | —> | __any valid integer constant__ |
<oct-const> | —> | 0[0-7]* |
<float-const> | —> | __any valid float constant__ |
<string> | —> | ".*" |
<identifier> | —> | [a-zA-Z]+ |
Variables are of the form $VARNAME (e.g. $system_arch). The official variable names will be those exported by resource objects in their attributes. To get some idea of the current set of attributes, consult the documentation on resource objects (for the most up-to-date information, invoke the retrieve_all_attributes() method on a resource object and examine the results).
Examples of query strings are:
| 'true' | This query would return the list of all objects contained in the Collection. |
| 'match($host_os_name,"SunOS")' | This query would return the list of all objects contained in the Collection with an attribute of the form (host_os_name,"SunOS"). |
| 'match($host_os_name,"SunOS")' or 'match($host_os_name,"Linux")' | This collection would return the list of all objects contained in the Collection with an attribute of either (host_os_name,"SunOS") or (host_os_name,"Linux"). |
The following options are available:
| -v | Run in verbose mode. The resulting list of objects matching the query will be displayed along with the attributes of each object. Otherwise, only the list of matching objects (without their attributes) will be displayed. |
| -debug | Catch and print Legion exceptions. |
| -help | Print command syntax and exit. |
The example below uses the default Collection (found in the /etc context), would be:
$ legion_query_collection -c /etc/Collection true 2 hits: 1.36ab9e4a.03.01000000.000001fc099204... 1.36ab9e4a.07.01000000.000001fc0d6e07...
legion_remove_sub_collection
{-l <collection LOID> | -c <collection path>}
{-l <member LOID> | -c <member path>} [-q <query>]The following option is supported:
| -q <query> | A MESSIAHS-style query that is being run on the subcollection. See legion_query_collection for details. |
legion_set_default_placement
{-l <class LOID> | -c <class context name>}
{-l <host LOID> | -c <host context name>}
{-l <vault LOID> | -c <vault context name>}
[-debug] [-help]The following options are supported:
| -debug | Catch and print Legion exceptions. |
| -help | Print command syntax and exit. |
legion_set_scheduler
{-l <class LOID> | -c <class context path>}
{-l <Scheduler LOID> | -c <Scheduler context path>}
[-debug] [-help]The following options are supported:
| -debug | Catch and print Legion exceptions. |
| -help | Print command syntax and exit. |
legion_set_scheduler_policy
{-l <class LOID> | -c <class context path>}
<policy> [-debug] [-help]The legal values for <policy> are:
| 0 | This policy value specifies that the class named in <class LOID> or <class context path> should use its default scheduler if the scheduler is currently active. It is intended to protect bootstrap classes, which may be involved in activating Schedulers and Scheduler helper objects. Typically, this policy is not recommended for user class objects.
Classes using this policy should have a default placement available. See legion_set_default_placement. |
| 1 | This policy value specifies that the class should always use its default Scheduler, even if the Scheduler is not active. This is recommended for user classes, which usually require help from a Scheduler object when making placement decisions. |
| -debug | Catch and print Legion exceptions. |
| -help | Print command syntax and exit. |
legion_set_varch
{-l <host LOID> | -c <host context path>} <arch>
[-debug] [-help]The following options are supported:
| -debug | Catch and print Legion exceptions. |
| -help | Print command syntax and exit. |
legion_set_vrun
{-l <host LOID> | -c <host context path>} <path>
[-debug] [-help]To configure a T3E virtual host object, you could run something like this:
$ legion_set_vrun -c /hosts/my_T3E $LEGION/src/T3E/SDSC
This tells Legion that the scripts are in $LEGION/src/T3E/SDSC.
The following options are supported:
| -debug | Catch and print Legion exceptions. |
| -help | Print command syntax and exit. |
legion_vault_host_list
{-l <vault LOID> | -c <vault context path>}
[{-a | -d | -g} <host1> <host2> ... <hostn>] [-p] [-u]
[-debug] [-help]The following optional parameters are supported:
| -c | use context paths to specify vault and host |
| -l | Use LOIDs to specify vault and host |
| -a | Add named host to the vault's acceptable host list |
| -d | Delete named host from the vault's acceptable host list |
| -t | Test whether or not a host is on the vault's acceptable host list |
| -p | Display the vault's acceptable host list |
| -u | Print usage |
| -debug | Catch and print Legion exceptions. |
| -help | Print command syntax and exit. |
To view the list of hosts that a given vault can operate on, you could use something like the example below.
$ legion_vault_host_list -c /vaults/VaultName -p ** COMPATIBLE HOST LISTING: ** 1.01.07.d49d1a40.000001fc0c04724... ** 1.01.07.d59d1a40.000001fc094e23c... ** 1.01.07.d69d1a40.000001fc0b68108... $
$ legion_vault_host_list -c /vaults/VaultName \ -t 1.01.07...
General Functions about the State of the System
legion_classof
{-l <object LOID> | -c <context path>}
[-debug] [-help]$ legion_classof -c Foo The class of 1.01.66000000.01000000.000001fc0... is 1.01.66000000..000001fc0d085b2c33... $
The following options are supported:
| -debug | Catch and print Legion exceptions. |
| -help | Print command syntax and exit. |
legion_create_stat_tree <base context path>
[-debug] [-help]The following options are supported:
| -debug | Catch and print Legion exceptions. |
| -help | Print command syntax and exit. |
legion_get_accounting_data [-v] [-help] [-debug]
{<pull-source1> <pull-source2> ... <pull-sourcen>}
{-d <local target directory>}
[-ot <seconds>] [-it <seconds>]The host object(s)'s current status is also retrieved and placed in the target directory as a log file. If all the requested accounting information is successfully gathered, the queried hosts are instructed to trim their logs.
You must including the following parameters:
| <pull-source1> <pull-source2> ... <pull-sourcen> | |
| One or more hosts that should be queried for account information. A pull-source can be one of the following:
-c <host context path>
-l <host LOID>
-Class <host class context name>
-ClassLoid <host class LOID>
-Context <context containing a group of hosts>
-File <local Unix file>
If you use the -File flag, the specified file must contain a list of Legion host context paths or LOIDs. | |
| -d <local target directory> | A local directory that will contain the accounting logs. |
The following options are supported:
| -v | Run command in verbose mode. This will return information about which log requests are currently being processed. |
| -debug | Catch and print Legion exceptions. |
| -help | Print command syntax and exit. |
| -ot <seconds> | Outcall timeout in seconds (default is 60 seconds). |
| -it <seconds> | Incall timeout in seconds (default is 60 seconds). |
legion_host_stats {-l <host loid> | -c <host context path>}
[-debug] [-help]The following options are supported:
| -debug | Catch and print Legion exceptions. |
| -help | Print command syntax and exit. |
legion_list_objects
{-l <host LOID> | -c <host context path>}
[-debug] [-help]The following options are supported:
| -debug | Catch and print Legion exceptions. |
| -help | Print command syntax and exit. |
legion_update_accounting_db
[-v] <local configuration file path> <local logfile directory>The tool may attempt to perform reverse context lookups on object LOIDs in order to determine human readable identifiers (i.e., context paths). For suitable results, we suggest that you only run this command if you are logged in as /users/admin.
You must include the following parameters.
| <local configuration file path> | A local text file that contains database configuration information in this format: |
| |
| <local logfile directory> | A local directory that contains accounting information logs. |
The following option is supported:
| -v | Run in verbose mode. Print information about which log requests the command is currently working on. |
legion_update_stat_tree
[-v] [-help] [-t <repeat delay seconds>]
[-site <top site context path>]
[-collection <collection context path>]The following options are supported:
| -v | Verbose mode. |
| -help | Print command syntax and exit. |
| -t <repeat delay seconds> | Specify that the command should operate in continuous mode, continually updating the stat tree every <repeat delay seconds> seconds. Use Ctrl-C to quit out of continuous mode. |
| -site <top site context path> | Specify the top-level context to update. The default starting point is /sites. |
| -collection <collection context path> | Specify a collection to satisfy host information requests. The default collection is /etc/DefaultCollection. |
legion_version
[-debug] [-help]$ legion_version VaL Legion version 1.3.5 $
The following options are supported:
| -debug | Catch and print Legion exceptions. |
| -help | Print command syntax and exit. |
legion_wellknown_class <wellknown class name>
[-debug] [-help]The following options are supported:
| -debug | Catch and print Legion exceptions. |
| -help | Print command syntax and exit. |
legion_whereis
{-l <object LOID> | -c <object context path>}
[-debug] [-help]$ legion_whereis -c Foo Host : /hosts/BootstrapHost Vault : /vaults/BootstrapVault $
The following options are supported:
| -debug | Catch and print Legion exceptions. |
| -help | Print command syntax and exit. |
legion_whoami
[-debug] [-help]$ legion_whoami /users/nemo $
The following options are supported:
| -debug | Catch and print Legion exceptions. |
| -help | Print command syntax and exit. |
Security
legion_add_acl [-l <object LOID> | -c <object context name>] {-s | <filename>}
[-debug] [-help]The following options are supported:
| -s | Read from stdin |
| -debug | Catch and print Legion exceptions. |
| -help | Print command syntax and exit. |
legion_add_implicit_params
[-l <AuthenticationObject LOID> | -c <AuthenticationObject context path>]
{-s | <filename>}
[-debug] [-help]The following options are supported:
| -s | Read from stdin |
| -debug | Catch and print Legion exceptions. |
| -help | Print command syntax and exit. |
legion_change_acl
{[-c] <object context path> | -l <object LOID>}
<function pattern> <modifications>Please note that if you have never altered the specified object's ACL before the object's permissions are by default set for Empty Function. In this setting, only the object's owner, the admin user, and the object's class can call the function. When you change the object's permissions for one or more functions, the set of allowed or denied users is merged with the Empty Function list. That is, if you add user John to the Allowed list for object Foo's getInterface(), the list will now contain four users: you (the owner), admin, Foo's class, and John.
The following parameters are required:
| <function pattern> | Lets you specify a Unix-like wildcard argument that indicates which funcations should be modified. Can contain any standard wildcard pattern (e.g., *, ?, [], and [^]). |
| <modifications> | A list of statements that add/remove users or groups from the specified functions for the specified Legion object. It can contain these elements:
Legion checks the deny list before it checks allow, so if a user or group is on both lists, Legion will consider it denied. |
You can list multiple <modifications> in a single run. For example, if you wished to alter SomeFile's ACL to allow SomeUser and SomeGroup to call any functions with "read" in them (such as read_hosts_contexts() or get_ready_time()), you would enter:
$ legion_change_acl /home/legion/SomeFile "*read*" \ +allow /users/SomeUser +allow /users/SomeGroup
Note that you must include the full user context path.
The next example changes SomeContext's ACL. It denies SomeUser and allows SomeGroup the right to call any function with "multiLookup" in it.
$ legion_change_acl /home/legion/SomeContext "*multiLookup*" \ +deny /users/SomeUser +allow /users/SomeGroup
legion_change_permissions [+-rwx] [-v]
<group/user context path> <target context path>
[-debug] [-help]This command works on common Legion object types: context, file, class, tty, implementation, host, and vault objects all fall into this category.
The following optional parameters are supported:
| -r | Deny read permissions to the target object. |
| +r | Grant read permissions to the target object. |
| -w | Deny write permissions to the target object. |
| +w | Grant write permissions to the target object. |
| -x | Deny execute permissions to the target object (note that this option is for class objects only). |
| +x | Grant execute permissions to the target object (note that this option is for class objects only). |
| -v | Run the command in verbose mode. |
| -debug | Catch and print Legion exceptions. |
| -help | Print command syntax and exit. |
legion_create_user [-a <admin path>] [-z <password>]
[-h <new home context>] [-c <AuthenticationClass path>]
<user id path> [-debug] [-help]The user id is the context name of an AuthenticationObject: the legion_create_object utility creates the object and assigns it the context name given in <user id path>. Please note that this argument is a full path (relative or absolute). Note also that the user id's context has nothing to do with that user's privileges in that context.
Once a user is created, the legion_login command is used to log in. The command will prompt for a password for the new user (unless you use the -z option), and will return the new object's LOID.
The following options are supported:
| -a <admin path> | Specify the admin object's context path. Default is /users/admin. |
| -z <password> | Specify the new user id's password. The default setting will prompt for the password after the command has been run. This option is not recommended for casual use, since the password will be visible on the command line. |
| -h <new home context> | Specify the new user's home context. Default is /home/<user id>. |
| Specify the AuthenticationClass which you wish to instantiate. Default is /class/AuthenticationClass. | |
| -debug | Catch and print Legion exceptions. |
| -help | Print command syntax and exit. |
legion_create_user_object {-l <class LOID> | -c <class context path>}
[-h <host for new object> | -v <vault for new object>]
[-f <implicit parameter file>] [-z <password>] <user name>
[-debug] [-help]The following optional parameters are supported:
| -h <host for new object> | Specify where the new object should be created. |
| -v <vault for new object> | Specify which vault should store the new object's persistent state. |
| -f <implicit parameter file> | This option names a file containing implicit parameters to be stored in the newly created AuthenticationObject (handed out on legion_login). The filename can be "-", in which case the command reads the parameters from the standard input.
Note that these are *not* the implicit parameters that control the behavior of the new AuthenticationObject. Upon login, the user's environment will be set to contain the latter set of implicit parameters, and they will affect the creation of all subsequent objects. This option is intended to make it easier to administer the system. In particular, admin can create user accounts that include implicit parameters that by default give the admin access rights to all of the users' subsequently created objects. |
| -z <password> | Include the user id's password in the command line arguments. This option is not recommended for casual use, as the password is potentially visible to other users in the system while the command is executing. |
| -debug | Catch and print Legion exceptions. |
| -help | Print command syntax and exit. |
legion_get_acl [-l <object LOID> | -c <object context name>]
[-debug] [-help]The following options are supported:
| -debug | Catch and print Legion exceptions. |
| -help | Print command syntax and exit. |
legion_get_implicit_params [-l <object LOID> | -c <object context name>]
[-debug] [-help]The following options are supported:
| -debug | Catch and print Legion exceptions. |
| -help | Print command syntax and exit. |
legion_init_Apps
legion_init_Extra
legion_init_HPC
legion_init_security
After running legion_init_security you must login as admin in order to use the system. Use the legion_login command, with /user/admin as the <user name> parameter. This command only needs to be run once, when the system is first started. Only one /user/admin should exist in a system.
legion_login [<user id path> | -l <user id LOID>]
[-p <password>] [-debug] [-help]The following options are supported:
| -p <password> | Enter the password from the command line. This method is not secure. | -debug | Catch and print Legion exceptions. |
| -help | Print command syntax and exit. |
legion_logout
[-debug] [-help]We strongly recommend that users insert this command into a .logout file or some other script that is run when a user logs out. This ensures that credential files do not remain in the system for unnecessarily long periods.
The following options are supported:
| -debug | Catch and print Legion exceptions. |
| -help | Print command syntax and exit. |
legion_modify_parameters
[-debug] [-help] <argument>The <argument> parameter must contain one of the following:
-l -p [<param type>] <param name> -d [<param type>] <param name> [<param value>] -a <param type> <param name> <param value>
If you use -p, -d, or -a in your <argument>, <param type> must be one of the following values:
| STRING_PARM | A string parameter. |
| FUNCTIONID_PARM | A parameter describing a function identifier. |
| INT_PARM | An implicit parameter containing an integer value. |
| LOID_PARM | An implicit parameter containing a valid LOID. |
The following options are supported:
| -l | List all of the implicit parameters in the user's current Legion session. |
| -p | Print a specific set of implicit parameters in the user's current Legion session. |
| -d | Delete a specific implicit parameter (or a set) from the user's current Legion session. |
| -a | Add a new implicit parameter to the user's current Legion session. |
| -debug | Catch and print Legion exceptions. |
| -help | Print command syntax and exit. |
legion_passwd {<user id context> | -l <user id LOID>}
[-debug] [-help]The following options are supported:
| -debug | Catch and print Legion exceptions. |
| -help | Print command syntax and exit. |
legion_set_acl [-l <object LOID> | -c <object context path>]
{-s | <filename>}
[-debug] [-help]The following option is supported:
| -s | Read from standard input |
| -debug | Catch and print Legion exceptions. |
| -help | Print command syntax and exit. |
legion_set_implicit_params
[-l <object LOID> | -c <object context path>]
{-s | <filename>}
[-debug] [-help]The following option is supported:
| -s | Read from standard input |
| -debug | Catch and print Legion exceptions. |
| -help | Print command syntax and exit. |
legion_set_message_security
[-c <AuthenticationObject context path> | -l <AuthenticationObject LOID>]
{Off | Protected | Private} [-help]The arguments take the same input format as legion_add_implicit_params. New parameters merge into the existing implicit parameter set (i.e., new parameters override old ones of the same name).
You must include one of the following parameters:
| Off | No encryption or digesting of messages |
| Protected | Message digested for verification and credentials encrypted for authentication |
| Private | Message and credentials encrypted for authentication and verification |
The following option is supported:
| -help | Print command syntax and exit |
legion_show_acl
{[-c] <object context path> | -l <object LOID>}
[<function pattern>] [-showLoids]The following options are supported:
| <function pattern> | Lets you use a Unix-like wildcard argument to list specific functions. You can use any of the standard wildcard patterns (*, ?, [], and [^]). |
| -showLoids | If Legion is unable to display a user's or group's context path, it will print a LOID (instead of unknown). |
For example, if you asked to see object /home/spw4s's ACL for all functions containing "MayI" in their names, you would see something like this:
$ legion_show_acl /home/legion "*MayI*"
Access to Function "_4MayI_6GetACL":
Allowed:
/users
<Unknown>
/users/legion
Denied:
Access to Function "_4MayI_6SetACL_23LRef<AccessControlList>":
Allowed:
<Unknown>
/users/legion
Denied:
Access to Function "_4MayI_17LegionCheckAccess_30LRef<Legion
FunctionIdentifier>23LRef<AccessControlList>26LRef
<LegionCertificateSet>i":
Allowed:
Empty
Denied:
$Application Development
legion_bfs
<file> [-o <out file>] [-BackEnd] [-help]The following options are used:
| -o <out file> | Name of the file containing the resulting Fortran or MPL output |
| -BackEnd | Instructs the legion_bfs compiler to produce output for IDL files included in the Fortran input file (ignored when the input is a BFS IDL file) |
| -help | Print command syntax and exit. |
legion_make [-v] [-a <architecture>] [-h <host context path>]
[-e <make command>] [-OUT <remote file>] [<arg1> <arg2> ... <argn>]
[-debug] [-help]If no remote host or architecture is specified (with the -h or -a flags) the command will run on a random host. For example, the following command would build the tar file on a random Alpha Linux host:
$ legion_make -a alpha_linux
$ legion_make -h /hosts/HostFoo
| -v | Run in verbose mode (up to four of these flags may be used). |
| -a <architecture> | Specify what kind of platform should be used to execute the command. |
| -h <host context path> | Specify which host should execute the programd. |
| -e <make command> | Specify an executable command (other than make) to be run on the remote host |
| -OUT <result file> | Specifies the local path name of a file that should be copied out of the remote program's current working directory after the program terminates. The default setting does not copy anything back to your current directory. |
| <arg1> <arg2> ... <argn> | Optional arguments passed to the make commands: they can specify make targets or other build parameters. |
| -debug | Catch and print Legion exceptions. |
| -help | Print command syntax and exit. |
For more information, see the FAQ.
legion_make_multi [-v] [-a <architecture>][-e <make command>]
[<arg1> <arg2> ... <argn>]
[-debug] [-help]The following options are supported:
| -v | Verbose mode. Print actions as command executes. |
| -a <architecture> | Specify an architecture on which to run make. This option can be specified multiple times to request concurrent builds on multiple platforms. If no architectures are specified, a remote make for the current architecture ($LEGION_ARCH) is performed. |
| -e <make command> | Specify the make-command for the remote build (default is "make"). |
| <arg1> <arg2> ... <argn> | These optional arguments are passed to the remote "make" command. They can specify make targets or other build parameters. |
| -debug | Catch and print Legion exceptions. |
| -help | Print command syntax and exit. |
For more information, see the FAQ.
legion_mplc
[<flags>]
legion_mplc_reg_impl <class name> <binary path>
<stateless | stateful | sequential> <arch> [-help]In the example below, MentatObject is a stateful Mentat object in the local path /home/legion/bin on a linux or alpha_linux machine. To register it as belonging to a class with the context path name /ClassObject/MentatObject in linux or alpha_linux architectures, you would enter:
$ legion_mplc_reg_impl /ClassDirectory/MentatObject \ /home/legion/bin/MentatObject stateful linux
$ legion_mplc_reg_impl /ClassDirectory/MentatObject \ /home/legion/bin/MentatObject stateful alpha_linux
The following option is supported:
| -help | Print command syntax and exit. |
legion_output_state
{-l <object loid> | -c <object context path>} | StartupState
[-debug] [-help] Warnings
Information
Low Level Debug
High Level Debug
Errors
Fatal Errors
There are two ways to use this command. You can dynamically change which of a specified object's output types are filtered out and which are displayed. This option also allows the user to change the location of the output (from stderr, stdout, and any Unix file they want).
Or, you can use the StartupState option, in which case the command will print instructions for bringing up a new system with the desired output state.
Please note: if you use StartupState, legion_output_state does not contact Legion and therefore does not run as a Legion program. I.e., you can execute it outside of a running Legion system. Otherwise, it runs as a normal Legion command-line tool.
The following options are supported:
| -debug | Catch and print Legion exceptions. |
| -help | Print command syntax and exit. |
legion_record
{-uf <local storage file name> | -c <recorder context path>}
[-name <debug session name> ] [-t <interval>]
<client application> [<arg1> <arg2> ... <argN>]
[-debug] [-help]Only one execution of the application will be recorded in the storage file at a time. If you record again to the same storage file you will overwrite previous data.
If you wish to use a Legion recorder object to record your application's activity, you must start the recorder object separately (i.e., legion_create_object -c /class/RecorderObject).
If you wish to record a server object (i.e., one that is not created by the client application, but instead exists on its own), you must start the server object in record mode independently of the client application.
The following options are supported:
| -name <session name> | Specify a name for the debug session. If this option is not used, a random name will be chosen. |
| -t <interval> | Specifies how much time (in seconds) the legion_record utility waits between health checks on its objects. These health checks are used to poll the recorder object to learn about object death. The default setting is 30 seconds. |
| -debug | Catch and print Legion exceptions. |
| -help | Print command syntax and exit. |
legion_replay
{-uf <local storage file name> | -c <recorder context path> -name <debug session name>}
{-list | [-cmd <debugger>] [-local] <session number>}
[-debug] [-help]You must use one of the following sets of parameters to specify which session you wish to start. Sessions are named in legion_record. If you used a Legion recorder object, you'll need to provide the debug session name as well.
The following options are supported:
| -uf <local storage file name> | The local file that was used to record your session. |
| -c <recorder context path> | The Legion recorder object that was used to record your session (must be accompanied by debug session name). |
| -name <debug session name> | The desired debug session name. |
| -list | Display the sessions in the storage file. |
| -cmd <debugger> | Specify a debugging program (i.e. gdb, xdb, etc.) to run on the storage file. Default is gdb. |
| -local | Indicates that the debugging session should be replayed on your local machine. The default will start a remote session on the machine which executed the original object. |
| -debug | Catch and print Legion exceptions. |
| -help | Print command syntax and exit. |
legion_stateless_add_workers <class name>
<worker name1> <worker name2> ... <worker nameN>
[-debug] [-help]The <class name> parameter should be the stateless class object's context name. The <worker name> parameters should be the desired context name of the new worker objects. Note that you can use full or relative path names.
The following options are supported:
| -debug | Catch and print Legion exceptions. |
| -help | Print command syntax and exit. |
legion_stateless_configure <stateless class context path>
[-n <number of replicas>] [-Ch <host context path>]
[-w <max number work requests>] [-FlUsH]
[-debug] [-help]The current version of the proxy object uses a self-scheduling algorithm. When N work requests have been farmed out, the proxy will store any pending requests in an internal queue: when a worker is available, the proxy assigns it a request from the queue. N here is given by the following formula:
N = <number of replicas> * <max number of workers>
| -n <number of replicas> | Specify the number of workers to be used. Default is 1. |
| -Ch <context containing list of hosts> | Name a host where the work requests should be executed. |
| -w <max number of work requests> | Specify the maximum number of work requests that each worker should service at a time. Default is 5. |
| -update | Tell the proxy object that the worker interface has changed. |
| -Flush | Remove all work requests for this class. |
| -status | Display the command's status information (a tty must be on). |
| -debug | Catch and print Legion exceptions. |
| -help | Print command syntax and exit. |
legion_stateless_remove_workers <class name>
<worker name1> <worker name2> ... <worker nameN>
[-debug] [-help]The following options are supported:
| -debug | Catch and print Legion exceptions. |
| -help | Print command syntax and exit. |
Program Support
legion_ft_initialize
legion_link [-CC <compiler>] [-Fortran] [-FC <compiler>] [-pvm] [-mpi]
[-L<library path>][-l<library>] [-v] [-o <output file>]
[-bfs] <object file list> [-debug] [-help]If any Fortran object files are linked, the -Fortran flag must be included. If you specify a Fortran compiler with the -FC flag, the -Fortran flag is automatically implied.
The following options are available with this command:
| -CC <compiler> | Select a C++ compiler to perform linkage. The default value is based on the default compiler used by the Legion system on your platform. | |||||||||
| -Fortran | If any Fortran object files are linked, the -Fortran flag must be included. | |||||||||
| -FC <compiler> | Select a Fortran compiler. This flag implies the -Fortran flag, but the two can be used together. Currently supported <compiler> options are:
| |||||||||
| -pvm | Link the produced executable to the Legion PVM compatibility library. | |||||||||
| -mpi | Link the produced executable to the Legion MPI compatibility library. | |||||||||
| -l<library path> | Include the | |||||||||
| -l<library> | Link against the specified library. | |||||||||
| -v | Provide a verbose output as the command is running | |||||||||
| -o <output path> | Specify the local path of the resulting program. The default is a.out. | |||||||||
| -bfs | Link the produced executable to the Legion Basic Fortran Support (BFS) library. | |||||||||
| -debug | Catch and print Legion exceptions. | |||||||||
| -help | Print command syntax and exit. |
legion_manage_job
[-help] [-k] [-cp <priority>]
[-fr] [-nc] [-q <context name>] <ticket number>Use -fr to force the job to restart. Only the job's owner and the system administrator can perform these operations.
The following parameter is used with this command:
| <ticket number> | The job ticket number (assigned when you ran legion_nq) |
The following options are supported:
| -help | Print this help message. |
| -k | Kill the job (job owner and system administrators only). |
| -cp <priority> | Change the job's priority. |
| -fr | Force the job to restart (job owner and system administrators only). |
| -nc | No file clean up. |
| -q< <context path> | Specify a JobQueue object. Default is /etc/JobQueue. |
legion_manage_queue
[-help] [-purge]
[-maxrs <slots>] [-q <context name>]If you are a system administrator, you can also use the -maxrs flag to set the maximum number of job slots and the -purge flag to kill all of the object's jobs.
The following options are supported:
| -help | Print this help message. |
| -purge | Kill all jobs/reset queue (system administrators only). |
| -maxrs <slots> | Set number of total run slots (system administrators only). |
| -q <context path> | Specify queue object. Default is /etc/JobQueue. |
legion_mpi_debug
[-q] {-c <program instance context>} [-help]There are a few limitations in legion_mpi_debug: If an MPI object doesn't respond, it will hang, and it won't go on to query additional objects. An MPI object can only respond when it enters the MPI library; if it is in an endless computational loop, it will never reply.
The following options are available with this command:
| -q | List the contents of the queues. |
| -help | Print command syntax and exit. |
legion_mpi_probe
[-help] [-debug] [-v[erbose]]
[-all ] [-list]
[-in <context path name> ] [-out <context path name> ]
[-IN <local file name> ] [-OUT <local file name> ]
[-showscratch] [-stat <remote file name> ]
<pid context name>The following parameters must be used with this command:
| <pid context name> | The context that contains the MPI instance LOIDs associated with the job. |
The following options are available with this command:
| -help | Print command syntax and exit. |
| -debug | Run in debug mode. |
| -v[erbose] | Run in verbose mode. |
| -all | Perform operation on all instances (default is instance 0). |
| -list | List all files in the remote program's working directory. |
| -in <context path name> |
Context path of a Legion file object whose contents should be copied into the remote program's current working directory.
The local file will have the same name as the <context path name> basename. |
| -out <context path name> |
Context path of a Legion file object whose contents should be copied out of the remote program's current working directory. If the file doesn't exist, you will get an error message.
The local source file will have the same name as the <context path name> basename. This tool will not check to see if the job has finished, so it may copy out an incomplete file |
| -IN <local file name> | Similar to the -in option, but operates on a file in legion_probe_run's local execution environment (i.e., the file named in <local file name>). |
| -OUT <local file name> | Similar to the -out option, but operates on a file in legion_probe_run's local execution environment (i.e., the file named in <local file name>). |
| -stat <remote file name> | Print the status of a particular file in the remote job's current working directory. |
| -showscratch | Print the archive context scratch space. If the run hasn't yet finished or if legion_mpi_run dies or is killed before the job finishes, this space will contain -OUT files that haven't yet been copied out. |
legion_mpi_register
<class name> <binary local path name> <platform type>
[-help]The command can be executed several times, if you have compiled your program on several architecture.
The following option is supported:
| Print command syntax and exit. |
legion_mpi_run
{-f <option file> [<flags>]} |
{-n <number of processors> [<flags>]
<program class> [<arg1> <arg2> ... <argn>]}| -f <option file> | Allows users to start multiple MPI applications via an option file. All applications must be previously registered through legion_mpi_register and have a common MPI_COMM_WORLD. |
| -n <number of processors> | Specify the number of processorss on which the program will run. |
Supported <flags> (a set of special flags for running in a fault tolerant mode is listed below) are:
| -v | Verbose option (up to four can be specified for increased detail). |
| -h <host set context path> | Specify the set of hosts on which the program will run. The context path should not resolve to a particular host but to a context containing the names of one or more hosts. The default setting is the system's default placement: i.e., the system will pick a compatible host pick and try to run the object. If it fails the system will try another compatible host. |
| -HF <local specification file> | Use a specification file in local file space for scheduling objects from the current execution. You must use a specific format when creating this file (see below). |
| Use a specification file in context space for scheduling objects from the current execution. You must use a specific format when creating this file (see below). | |
| -in <context path> | Tells Legion to copy the contents of a Legion file object to the remote program's current working directory before execution. The remote file will have the same name as the file object. This flag can be used multiple times to indicate multiple input files. You can also use wildcards to specify groups of files. |
| -out <context path> | Name of an output file that should be copied from the remote program's current working directory into your context space after the program terminates. The new file object will have the same name as the original output file unless the -a flag is used, in which case the name will be <name>.<mpi object id>. This flag can be used multiple times. You can also use wildcards to specify groups of files.
Output files that are not found in the program's current working directory will be copied but will appear as empty files. If the program crashes, the files will be left in the program's current working directory. |
| -IN <local file name> | Tells Legion to copy the contents of a local file to the remote program's current working directory before execution. The remote file will have the same name as the local file. This flag can be used multiple times to indicate multiple input files. You can also use wildcards to specify groups of files. |
| -OUT <local file name> | Name of an output file that should be copied from the remote program's current working directory into your local directory after the program terminates. The new file will have the same name as the original output file unless the -a flag is used, in which case the name will be <name>.<mpi object id>. This flag can be used multiple times. You can also use wildcards to specify groups of files.
Output files that are not found in the program's current working directory will be copied but will appear as empty files. If the program crashes, the files will be left in the program's current working directory. |
| -a | Pass the files named in the -in/-out/-IN/-OUT parameters to all nodes. The default setting gives these files only to node 0.
Files named in the -out/-OUT parameters will be copied to files that use the following conventions: <name>.<mpi object id>, where <name> is the <output file> given in the -out/-OUT parameters. |
| -stdin <context path> | Map stdin to the Legion file object named in <context path>. By default, this file object will only be passed to node 0, unless use the -A flag. |
| -stdout <context path> | Map stdout to the Legion file object named in <context path>. By default, this file object will only be passed to node 0, unless use the -A flag. |
| -stderr <context path> | Map stderr to the Legion file object named in <context path>. By default, this file object will only be passed to node 0, unless use the -A flag. |
| -STDIN <local file; | Map stdin to the local file named in <local file>. By default, this file object will only be passed to node 0, unless use the -A flag. |
| -STDOUT <local file> | Map stdout to the local file named in <local file>. By default, this file object will only be passed to node 0, unless use the -A flag. |
| -STDERR <local file> | Map stderr to the local file named in <local file>. By default, this file object will only be passed to node 0, unless use the -A flag. |
| -A | Pass the files named in the -std*/-STD* parameters to all nodes. The default setting gives these files only to node 0. |
| -p <context path> | Specify a context name for program's instance LOIDs. Default is:
/mpi/instances/ program_nameunless security is enabled, in which case the default is: /home/<user_name>/mpi/instances/<program_name>If the context does not exist it will be created. |
| -0 <host context name> | Runs the first process (i.e., process zero) on this node. |
| -d <Unix path name> | Specify that all children change to the specified directory before they begin to run. |
| -S | Print statistics at exit. |
| Set the environment variable named in <variable_name> to a specified value on all MPI processes after they have called MPI_Init(). This option may be repeated multiple times to set additional environment variables. | |
| -help | Print command syntax and exit. |
$ legion_mpi_run -n 2 /mpi/programs/vdelay
Use legion_ls to examine the running objects of your application . The /mpi/instances/<program_name> context has an entry for each object in your application. E.g.,
$ legion_ls /mpi/instances/vdelay
Specification file
A specification file is a text file that contains a list ofhosts and the number of Legion objects that can be scheduled on those hosts. Objects from your application(s) will be scheduled on these hosts. You can use legion_make_schedule to produce this file or write it yourself. List one host and one integer indicating the number of objects the host can create (default is 1) per line. List the host by its Legion context name. A host can be listed multiple times in one file, in which case the integer values accumulate. E.g.:
/hosts/BootstrapHost 5 /hosts/slowMachine1 /hosts/bigPBSqueue 100 /hosts/slowMachine2 1
Wildcards
You can also use wildcards to work with groups of input/output files. The following wildcards can be used with -in/-out and -IN/-OUT:
| * | match 0 or more characters |
| ? | match any one character |
| [-] | match any character listed between the brackets (use these to specify a range of characters) |
| \ | treat the character as a literal |
$ legion_mpi_run -n 2 -IN done.[0-9] /mpi/programs/mpiFoo
You can use wildcards on the command line or in an option file. They can only be used with file names, however, not with directories.
Option file
The option file contains a list of the MPI applications that you wish to execute, as well as any necessary arguments, as they would appear on the command line. You will be starting all of the listed applications with a single legion_mpi_run. All applications must have been registered with Legion (through legion_mpi_register) and use a common MPI_COMM_WORLD. THe file must list one binary (and any arguments) per line. Each line can also contain one or more legion_mpi_run flags (but not -f). For example:
-n 2 /mpi/programs/mpitest -n 3 /mpi/programs/mpitest_c
If you use an option file, Legion will ignore the -n flag, program name, and any arguments given on the command line. Any <flags> will be treated as defaults and applied to all processes executed by this command (unless otherwise specified in the option file).
Fault tolerant mode
There is a set of special legion_mpi_run flags that can be used when running in a fault tolerant mode.
| -ft | Turn on fault tolerance. |
| -s <checkpoint server> | Specifies the checkpoint server to use. |
| -R <checkpoint server> | Recovery mode. |
| -g <ping interval> | Specify a ping interval. Default is 90 seconds. |
| -r <reconfiguration interval> | Specify a period (in seconds) for detecting failure. If an object does not respond within the specified period, the application restarts from the last consistent checkpoint. Default value is 360 seconds. |
These flags are used in specific combinations. You must use the -ft in all cases and you must use either -s or -R. The -g and -r flags are optional. Please see section 10.1.10 in the Basic User Manual for more information on running in fault tolerant mode. See also the FAQ.
legion_native_mpi_config_host
[<wrapper>] [-debug] [-help]| <wrapper> | Specify a wrapper script that locates mpirun on the host. The default specifies the legion_native_mpich_wrapper script, which is for an MPICH implementation. |
| -debug | Catch and print Legion exceptions. |
| -help | Print command syntax and exit. |
legion_native_mpi_init
[<architecture>] [-debug] [-help]| <architecture> | Specify an architecture for which an implementation for this class can be registered. |
| -debug | Catch and print Legion exceptions. |
| -help | Print command syntax and exit. |
legion_native_mpi_register
<class name> <binary path> <architecture>
[-help]$ legion_native_ mpi_register charmm /myMPIprograms/charmm linux
You can run register a program multiple times, perhaps with different architectures or different platforms. If you have not registered this program before, this will create a context in the current context path (the context's name will be the program's class name -- in this case, charmm) and registers the name in Legion context space.
The following option is supported:
| -help | Print command syntax and exit. |
legion_native_mpi_run
[-v] [-a <architecture>] [-h <host context path>]
[-IN <local input file>] [-OUT <local result file>]
[-in <Legion input file>] [-out <Legion result file>]
[-n <nodes>] [-t <minutes>]
[-legion] [-help] [-debug] <program context path>
[<arg 1> <arg 2> ... <arg n>]| -h <host context path> | Specify the host on which the program will run. The default setting is the system's default placement, which is to pick a compatible host and try to run the object. If the host fails, the system will try another compatible host. |
| -v | Verbose option. |
| -a <architecture> | Specify the architecture on which to run. |
| -IN <local input file> | Specify an input file that should be copied to the remote run from the local file system. |
| -OUT <local result file> | Specify a result file that should be copied back from the remote run to the local file system. |
| -in <Legion input file> | Specify an input file that should be copied to the remote run from the Legion context space. |
| -out <Legion result file> | Specify a result file that should be copied out from the remote run into Legion context space. |
| -n <nodes> | Specify the number of nodes for the remote MPI run. |
| -t <minutes> | Specify the amount of time requested for the remote MPI run. This option is only meaningful if the host selected to run the remote program enforces time limits for jobs. |
| -legion | Indicate whether the application makes Legion calls (see section section 10.2.5 on page 64 in the Basic User manual). |
| -help | Print command syntax and exit. |
| -debug | Catch and print Legion exceptions. |
| <arg1> <arg2> ... <argn> | Arguments to be passed to the remote MPI program. |
For more information, see the FAQ.
legion_nq
[-help] [-w] [-v]
[-a <arch> ] [-h <host context path>]
[-in <context name>] [-out <context name>]
[-IN <local file name> ] [-OUT <local file name>]
[-f <options file> ] [-novrun] [-t <minutes>]
[-n <nodes>] [-r <minutes>] [-p <priority>] [-d]
<program class> [ <arg1> <arg2> ... <argn>]You can use the -in/-out and -IN/-OUT options to copy input and output files between your local host, the remote host, and context space. You can also use an options file.
Use -p to set a job's priority in the priority queue. Priorities are used when the number of submitted jobs is larger than the number of jobs that are allowed to execute simultaneously. If so, the job with the highest priority will be allowed to execute when a slot becomes available.
The command will propagate tty information to the JobQueue object so that stdout and stderr output can to redirected to legion_nq window
A JobQueue can be used to start, monitor, and clean up remote jobs. The JobQueue object is owned by the Legion system administrator (i.e., the admin user) and takes care of preparing, starting, and monitoring the job's progress. It assigns a ticket to each submitted job and a job record, which hold job-related information, and puts the job in a priority queue. The system administrator sets a maximum number of simultaneously running jobs (with legion_manage_queue) and the JobQueue tries to start jobs as slots become available.
If the job starts successfully, its record is moved the list of running jobs. If it fails, its record is moved to the list of failed jobs. The job will be retried after another job has been started or has failed or the number of job slots is increased. Waiting jobs can be given higher and lower levels of priority by the job owners and/or the system administrator.
The JobQueue does not block and wait for a job to finish. When a job terminates (for whatever reason), its job proxy object (an object on the remote host which actually starts the job) notifies the JobQueue object.
The JobQueue also periodically pings running jobs, updates job statistics, kills jobs that have either overrun their maximum allocated running time, and removes jobs records marked for deletion.
A Legion system can have multiple JobQueue objects, responsible for different parts of the system's resources. You can use legion_manage_queue to manage individual JobQueue objects.
Note that jobs run with the JobQueue still must be registered, with either the legion_register_program or legion_register_runnable.
Parameter
The following parameter is used with this command:
| <program class> | Specifies the program class of which an instance should be executed. This program class should have been previously created with the legion_register_program or legion_register_runnable command. |
Options
The following options are supported
| -help | Print this help message. |
| -w | Display standard I/O from the remote program. |
| -v | Verbose mode. |
| -a <architecture> | Specify the preferred Legion platform type on which the remote program should run. |
| -h <host context path> | Specify the context path of the Legion host object on which the remote program should run. |
| -in <context path> | Copy the specified Legion file to the current working directory of the remote program. |
| -out <context path> | Copy the specified Legion file's contents out of the current working directory of the remote program into Legion context space. The remote object's path should be the same as the <context path>. |
| -IN <local file name> | Send the specified local file to the current working directory of the remote program. |
| -OUT <local file name> | Copy a file out of the current working directory of the remote program into the specified path in your local file system. |
| -f <options file> | Obtain options from the specified file. An options file can contain one or more legion_nq flags delimited by spaces, tabs, or newlines. An options file is especially useful if your program uses several -in/-out or -IN/-OUT flags. You can include any flags but not arbitrary command-line arguments. |
| -novrun | Disable use of the virtual architecture on virtual hosts. The remote program will run on the physical architecture for the selected host. This option is not usually appropriate for user tasks. WARNING: the registered implementation for the virtual architecture of the selected host should also be usable on the physical architecture of the selected host if this option is used (e.g., a script). |
| -t <minutes> | Specify a requested amount of time (in minutes). This option is only meaningful if the host selected to run the remote program enforces time limits for jobs. Otherwise, this option is not required. |
| -n <nodes> | If the remote program is a native parallel job (e.g., a program written to use the local vendor MPI implementation), this option selects the number of nodes that should be allocated for the job. This option is not meaningful if the host selected to run the remote program is a uniprocessor, or does not support multi-node allocations. |
| -r <minutes> | Specify the maximum amount of time (in minutes) that the queuing system will wait for the program to complete before attempting to restart it. Default is 0 (no restarts). |
| -p <priority> | Specify job priority for the queuing system. Value range from 0 to 9, 0 being the highest priority. The default is 5. Users can assign values from 5 to 9. Only system administrators can assign values 0 to 4 (after job submission) with the legion_manage_job command. |
| -q <context path> | Specify a JobQueue object. Default is /etc/JobQueue. |
| -d | Deactivate -IN files and temporary contexts to save process slots. |
| <arg1> <arg2> ... <argn> | Provide arbitrary command-line arguments for the program. |
legion_probe_run
[-help] [-debug]
[-pwd] [-hostname] [-list] [-stat <remote file name] [-statjob]
[-in <context path name>] [-out <context path name>]
[-IN <local file name>] [-OUT <local file name>]
[-setscratch <context path>] [-showscratch] [-kill]
{-p[robe] <local file name> | -l <probe LOID>}You must have used the -p option when starting legion_run in order to use this command: this option creates a local file called a probe file that can contact your remote job. If you do not have a probe file for your job, legion_probe_run will be unable to locate your job.
Note that if you start a nonblocking run, the remote host will hold the results for six hours after the job terminates. If you do nothing, the host will tar up the job's current working directory and move it into your context scratch space. If you run legion_probe_run at any point (whether to retrieve output files or just to check the job's status) during those six hours, the clock restarts and the remote host will wait for another six hours before tarring and moving the job's directory. If you do not use the -kill option to clean up the job's directory, it will eventually be tarred and moved.
One of the following parameters must be used with this command:
| -p[robe] <local file name> | The name of the local probe file associated with the desired job. |
| -l <probe LOID> | The probe's LOID (may not be supported in all releases). |
The following options are available with this command:
legion_pvm_register
<class path name> <binary local path name> <platform type>
[-help]Once you've registered an application, you can run it. If necessary, you can examine Legion context space with either
$ legion_ls /pvm
$ legion_ls /pvm/tasks
To register a Linux binary named matmult in Legion, enter:
$ legion_pvm_register /pvm/tasks/matmult matmult linux
The following option is supported:
| -help | Print command syntax and exit. |
legion_register_program
<program class> <executable path> <legion arch>
[-debug] [-help]Programs registered through legion_register_program can be executed with the legion_run command. See also legion_register_runnable for information about registering Legion programs.
The following parameters are used with this command:
| <program class> | The Legion context path name of the class with which the registered program should be associated |
| <executable path> | The local file path of the executable program to register. This can be any program that could be run from the shell command prompt, including scripts, and binary executable generated by any programming language. |
| <legion arch> | The platform type that the program should be executed. |
| -debug | Catch and print Legion exceptions. |
| -help | Print command syntax and exit. |
legion_register_runnable
<program class> <executable path> <legion arch>
[-debug] [-help]The following parameters are used with this command:
| <program class> | The Legion context space path of the class with which the registered program should be associated |
| <executable path> | The local file path of the executable program to register. This program should be a valid Legion object implementation that has been linked with the Legion library, and that exports the Legion "runnable" interface. |
| <legion arch> | The platform type on which the program should be executed. |
| -debug | Catch and print Legion exceptions. |
| -help | Print command syntax and exit. |
legion_run
[-help] [-debug] [-v[erbose]] [-w] [-a <arch>] [-h <host>]
[-block] [-non[-]block] [-d[ir] <dir>] [-D <var=value>]
[-in <contextfile>] [-out <contextfile>]
[-IN <localfile>] [-OUT <localfile>]
[-stdin <localfile>] [-stdout <localfile>] [-stderr <localfile>]
[-novrun] [-p[robe] <localfile>] [-setscratch <context>]
[-meta <option=value>]
[-f <options file>] <program class> [<arg1> ... <argn>]Note that any number of input and output files may be specified for a single execution of legion_run (i.e., the -in/-out and -IN/-OUT options can be repeated). The -f flag can be used to specify legion_run options in the file named in <options file>, rather than on the command line.
The following parameter is used with this command:
| <program class> | Specifies the program class of which an instance should be executed. This program class should have been previously created with the legion_register_program or legion_register_runnable command. | ||||||||||
| The following optional parameters are supported: | |||||||||||
| -debug | Catch and print Legion exceptions. | ||||||||||
| -help | Print command syntax and exit. | ||||||||||
| -v[erbose] | Run command in verbose mode. | ||||||||||
| -w | Directs legion_run's output to your current tty object. If you have not created and set a tty object for your current window you will not be able to see any output and an error message will appear. | ||||||||||
| -a <architecture> | Allows users to specify what kind of architecture the program should be executed on. | ||||||||||
| -h <host context path name> | Specify which host should execute program. | ||||||||||
| -non[-]block | Specify that legion_run be run in nonblocking mode. Once it starts your program, it will exit and free up your command line. The default setting is blocking. | ||||||||||
| -block | Specify that legion_run be run in blocking mode. The command will start your program and block at the command line until the program finishes. This is the default setting. | ||||||||||
| -d <remote host directory> | Specify that the program run in a particular directory on its remote host. | ||||||||||
| -D[ir] <var=value> | Set environment variable var to value value. | ||||||||||
| -in <context path name> | Context path of a Legion file object whose contents should be copied into the remote program's current working directory before execution begins. The local file will have the same name as the <context path name> basename. | ||||||||||
| -out <context path name> | Context path of a Legion file object whose contents should be copied out of the remote program's current working directory after the program terminates. The local source file will have the same name as the <context path name> basename. Note that output files are copied out regardless of the cause of program termination. Partial results will be available if the program crashes. Output files that are not found in the program's current working directory are skipped. | ||||||||||
| -IN <local file name> | Similar to the -in option, but operates on a file in the local execution environment of legion_run (i.e., the file named in <local file name>). | ||||||||||
| -OUT <local file name> | Similar to the -out option, but operates on a file in the local execution environment of legion_run (i.e., the file named in <local file name>). | ||||||||||
| -stdin <local file name> | Specify a local file from which the remote job gets its standard input. | ||||||||||
| -stdout <local file name> | Specify a local file to which the remote job writes its standard output. | ||||||||||
| -stderr <local file name> | Specify a local file to which the remote job writes its standard error. | ||||||||||
| -novrun | Do not run on a virtual host. I.e., disable use of the "virtual architecture" on virtual hosts. The remote program will run on the physical architecture for the selected host. This option is usually not appropriate for user tasks. Warning: the registered implementation for the virtual architecture of the selected host should be usable on the physical architecture of the selected host (e.g., a script). | ||||||||||
| -meta <option=value> |
Specify metaoptions for the run. These options may be meaningful only for certain combinations of jobs and machines. Listed below is the set of supported options and their meaning.
| ||||||||||
| -t <minutes> | Deprecated: see -meta nodes=<num>. Specifies the amount of time (in minutes) needed to run the program. If this option is not used, the host will assign the job its default time block. This option is only meaningful if the host selected to run the remote program enforces time limits for jobs: otherwise this option is not required. | ||||||||||
| -n <nodes> | Deprecated: see -meta minutes=<num>. If the remote program is a native parallel job (e.g., a program written to use the local vendor MPI implementation), use this option to specify the number of nodes that should be allocated to the job. This option is not meaningful if the host selected to run the remote program is a uniprocessor or does not support multi-node allocations. | ||||||||||
| -p[robe] <local file name> | Store the remote job's tracking name in a file on the local host. You must use this option if you wish to run legion_probe_run. | ||||||||||
| -setscratch <context path> | Specify a portion of your context space to be used as context scratch space. | ||||||||||
| -f <option file> | Allows users to specify options for running legion_run in a separate file rather than listing them on the command line. This is useful for programs that make extensive use of the -in/-out or -IN/-OUT options. The file can contain one or more of the legion_run options, delimited by spaces, tabs, or blank lines. The program class name and arbitrary command-line arguments may not be included in this file. No other information should be included. | ||||||||||
| <arg1> <arg2>... <argn> | Allows users to provide arbitrary command-line arguments for the program. | ||||||||||
legion_run_multi
[-help] [-debug] [-v[erbose]] [-z[ero]] [-r[estart]]
[-e[xec] command] [-x <exceptfile> ] [-a[rch] <arch> ]
[-d[ir] <dif1> ] [-D <var=value> ]
{-n <number of processors> | -s[chedule] <schedfile> }
-f[ile] <specfile> [-t[ime] <timefile>]
[-hm <hostmapfile>] [-jm <jobmapfile>] [-display]
[--] <program class> [<arg1> <arg2> ... <argn>]Before you run this command, you must have registered the program name and created a specification file. The specification file format is:
keyword filename pattern
You must fill in all three fields on each line. One file per line.
Specification file
The first field, the keyword, provides information about the file named in the second field. Possible keywords are IN/in, OUT/out, CONSTANT/constant, and stdin/stdout/stderr. The case determines the file's location (except for std*):
constant/in/out Legion context space CONSTANT/IN/OUT/ local file space stdin/stdout/stderr
The CONSTANT/constant keywords indicate identical input for multiple runs (e.g., input that is used for each run, such as a password). The std* keywords refer to local files that stdin, stdout, and stderr use. A separate stdout and stderr are created for each run. If you do not indicate a stdout file, standard output will be sent to your Legion tty object. Multiple IN/in, OUT/out, and CONSTANT/constant files may be specified, one per line.
The second field is the name of an input or output file that your program expects to read or write to in the local directory of whichever host it runs on.
The third field is the naming pattern for input and output files. You may use "*" as a pattern holder for IN/in and OUT/out files. The pattern holder allows you to specify large groups of files in different directories for input and output.
For example, suppose that you want to run program Foo. Foo needs two input files, FooFoo and MyFoo, and produces one output file, Bar, and a password. Your specification file would look like this:
IN FooFoo /mylocaldir/foo*.ent in MyFoo /mycontext/bar*.gif OUT Bar /mylocaldir/output*.stuff CONSTANT secret /etc/passwd
Legion looks in local space for files that fit the specified patterns and finds five sets of files:
IN LOCAL SPACE IN CONTEXT SPACE /mylocaldir/foo1.ent /mycontext/bar1.gif /mylocaldir/foo2.ent /mycontext/bar2.gif /mylocaldir/foo3.ent /mycontext/bar3.gif /mylocaldir/foo4.ent /mycontext/barA.gif /mylocaldir/foo5.ent /mycontext/barB.gif
Notice that the first three files in each column have common patterns (1, 2, and 3) whereas the last two do not (4 and 5, A and B). The files with mismatched patterns are discarded, leaving three sets of input files, or three jobs that can be run:
IN LOCAL SPACE IN CONTEXT SPACE /mylocaldir/foo1.ent /mycontext/bar1.gif /mylocaldir/foo2.ent /mycontext/bar2.gif /mylocaldir/foo3.ent /mycontext/bar3.gif
These jobs can be identified by their pattern: 1, 2, and 3. Before going any further, Legion checks for any previously created output files. It finds a file called /mylocaldir/output1.stuff, so it knows that job 1 has already been run. The remaining jobs, 2 and 3, have not. Legion then copies the remaining four input files to the two hosts that will run the jobs:
/mylocaldir/foo2.ent copied to --> HostA/FooFoo /mycontext/bar2.gif HostA/MyFoo /mylocaldir/foo3.ent HostB/FooFoo /mycontext/bar3.gif HostB/MyFoo
The jobs are run and an output file called Bar is created on HostA and on HostB. HostA/Bar's contents are copied to a file in the original host's local directory space called /mylocaldir/output2.stuff, signalling that job 2 is finished. HostB/Bar's contents are copied to /mylocaldir/output3.stuff, signalling that job 3 is finished.
A more complex specification file might look like this:
IN FILE1 /usr/localtmp/dump/pdb*.ent in NEXT2 /home/an4m/pictures/*.gif OUT THEN3 output* out FILE4 ./dssp*log CONSTANT Crypt /etc/passwd constant Salt-File /home/admin/user-list
The program must be written so as to read/write the files named in the second field from its current directory. In this case, the registered program must read FILE1, NEXT2, Crypt, and Salt-File, and write THEN3 and FILE4. When legion_run_multi is called on the registered program with the above specification file, it looks for matching patterns:
/usr/localtmp/dump/pdb1egs2.ent in your local directory /home/an4m/pictures/1egs2.gif in your Legion context
These are sent as input files for run 1egs2, which generates two output files:
output1egs2 in your local directory ./dssp1egs2log in your Legion context
Exception file
The exceptions file is an addendum to the specification file. It specifies additional switches for specific patterns. This allows you greater flexibility and control when running large batches of jobs. The information in the exceptions file is passed directly to legion_run or, if you use the -e flag, to whichever command you have specified (legion_run_multi command is essentially a script that calls multiple legion_runs or whichever command specified).
For example, suppose that the following jobs match the patterns in your specification file:
ABC DEFGH 123 9999 GIRAFFE
The specification file already provides input/output/constant information for all of these jobs and command line flags provide additional instructions. However, you wish to fine-tune these instructions for just jobs DEFGH and 123. In the exceptions files, you can specify these two jobs and give your additional instructions:
DEFGH -h /hosts/special_host_name 123 -v -IN /tmp/myJob/ExtraStuff
The first line tells Legion that you wish to run job DEFGH on a specific host. The second line says that job 123 requires an additional input file and that you wish to run the job in a verbose form.
These instructions combine with any other specifications that were provided on the command line and/or in the specification file.
Limitations, caveats, warnings
Display
The display window and the arguments mentioned in this section are currently available to npacinet users only since they were not included in the 1.8 binaries distributed from the Legion web site.
You can start up a display showing the progress of runs. There are two ways to start a display: the legion_run_multi -display flag or the legion_show_multi command-line tool.
The -display flag will start up a graphic window displaying the status of current jobs and of the hosts that are running those jobs. The display window uses a time file, a job map file, and a host map file. The time file contains the history of jobs that have run or are currently running. The host map file contains information about the hosts on which jobs are currently running. The job map file contains information about the jobs which are currently running.
If you use -display you do not need to use the -t, -hm, or -jm flags, since -display automatically creates and later cleans up the time and map files for executing legion_run_multi. You can use these flags, if you wish, to specify a path name for any or all of the time and map files. Note that in that case the specified files will not be deleted when the runs are finished. If you then run legion_run_multi again and specify the same file names, Legion will overwrite existing host and job map files and append new information to the existing time file.
The legion_show_multi command will start up a display window as well. However, you must have used the -t, -hm, and -jm flags when you started legion_run_multi to create the time and map files.
The time and map files are in your local file space.
Parameters
You must specify at least one of the following two parameters:
You must specify the following two parameters:
| -f <specification file path> | The specification file's Unix path name. |
| <program class name> | The program's Legion class name (created when the program was registered in Legion). |
Options
The following options are available with this command:
| -help | Print command syntax and exit. |
| -debug | Turn debugging mode on. In this mode, legion_run_multi prints copious output regarding which patterns must be run. This flag also turns on the verbose mode (-v). |
| -v[erbose] | Provide a verbose output as the command is running. |
| -z[ero] | Consider input and output files of zero size to be valid. If this option is used, a zero-sized input file can be used to start a job and a zero-sized output file can be used to signal a completed job. |
| -r[estart] | Restart incomplete jobs (five times max). |
| -e[xec] <command> | Run some other <command>. The default is legion_run. |
| -x <exceptions file path> | The exceptions file's Unix path path. |
| -a[rch] <architecture> |
Platform architecture for remote hosts. At the moment, possible architectures are limited to:
|
| -d[ir] <dir> | Remote directory to which each job must change before execution. |
| -D <var=value> | Environment variable to be set for each job. |
| -t[ime] <timefile> | Specify a file for recording the job history of the processes. This file will list jobs by their name and gives the time that each job was checked, when it was checked (measured in seconds since January 1, 1970), the status that was returned (e.g., Started, Error), and (if known) the host that it was run on. The file is in your local directory. |
| -- | End switches for legion_run_multi. |
| <arg1> <arg2>... <argn> | Provide arbitrary command-line arguments for the registered program. |
legion_show_multi *
[-help] [-hm <hostmap>] [-jm <jobmap>]
[-t <timefile>] [-sm <schedfile>]
[-f <specfile>] [-x <exptfile>] [ <jobname>]For more information, see the FAQ.
Alphabetical list of Legion commands
Other relevant on-line documents:
| Click on the to go to the page. | ||
|
Logging in to a running Legion system Introduction to Legion context space Context-related commands Legion tty objects Running a PVM code in Legion Running a Legion MPI code Running native MPI code
|
|
Quick list of all 1.7 Legion commands Usage of all 1.7 Legion commands FAQs for running programs in Legion Starting a new Legion system Legion security Legion host and vault objects Adding host and vault objects Brief descriptions of all on-line tutorials
| |
Last modified: Tue Jul 31 12:23:22 2001
|
[Testbeds] [Et Cetera] [Map/Search]
legion@Virginia.edu
|
