Note that there are man pages for all of the commands listed here, as well as on-line tutorials on the Legion web site (<http://legion.virginia.edu>). Please see your system administrator if you are not sure how to use man pages.
legion_exports_interface
{-l <LOID> | -c <context path>}
{-w <well-known class type> | -f <function signature>}+Creates an interface from the list of <well-known class type> and <function signature> arguments specified in the argument list. Sends this interface to the object specified by <LOID> or <context path> in the form of a call to the object mandatory function named exportsInterface(). Prints to standard output the return value from the call: 1 if the interface of the object contains the entire interface of functions specified by the user, and 0 if any one or more of the functions are not exported by the object. Prints -1 (without contacting the specified object) if the user creates a malformed argument list. <well-known class type> is a string in the set of well known strings, which can be listed via the legion_wellknown_class tool.
For the purposes of this tool, "ClassObject" is a well-known class string. "CommandLineClass" and "BootstrapMetaClass" are not considered well-known classes because they do not have any special member functions, as shown in the examples below.
$ legion_exports_interface -c LegionClass -w ClassObject
1
$
$ legion_exports_interface -c /class/LegionClass -w CommandLineObject
"CommandLineObject" is not a well known class. Exiting.
usage: legion_exports_interface
{-l <class loid> | -c <legion space path>}
{-w <well known class type> | -f <function signature>}+
-1
$
$ legion_exports_interface -c LegionClass -w LegionClass -w ClassObject
1
$
$ legion_exports_interface -c /hosts/BootstrapHost -w UnixHostClass
1
$
$ legion_exports_interface -c /hosts/BootstrapHost -w ClassObject
0
$
$ legion_exports_interface -c /class/LegionClass -f " LegionLOID ping();"
1
$
$ legion_exports_interface -c /hosts/BootstrapHost -f " LegionLOID ping();" -w UnixHostClass
1
$
legion_get_interface {-l <class LOID> | -c <context path>}Retrieves the interface of a Legion object, named by <class LOID> or <context path>, by calling that object's getInterface() member function. Prints the returned interface to stdout.
This example returns the interface of the LegionClass (the metaclass for all Legion classes).
$ legion_get_interface -c class/LegionClass Getting the interface of object:1.01.01..000001fc0b325eb41c4d b8b415b7fca6d419a648bb495d69aa8153494da0fb08d1d7e16fccf8ae7e809428c910a03f64037f0bcf64e5a99a330616e67d79b21b2a364f65 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(); $
legion_ping {-l <object LOID> | -c <context path>}Calls the object-mandatory ping member function on the object named in <object LOID>. If the command returns, the object exists in an active state and its LOID is displayed. If the command does not return, the object is not accessible by the tool.
$ legion_ping -c foo Pinging: 1.01.66000000.14000000.000001fc0a72cd9e3c85dad3e18062d9d0080227e53892056c6610e12ed05e37988be980a3b837c058527df442f84b65ec558bdac2698e62710032b31991e38a04cf2529 Returned: 1.01.66000000.14000000.000001fc0a72cd9e3c85dad3e18062d9d0080227e53892056c6610e12ed05e37988be980a3b837c058527df442f84b65ec558bdac2698e62710032b31991e38a04cf2529 $
legion_list_attributes
{-l <object LOID> | -c <context path>} [-L] [<attribute name>]Lists an object's attributes from the command line. Optional parameters do the following:
| -L | Lists the LOID of each attribute |
| <attribute name> | Specify the attribute to be listed (more than one attribute can be listed) |
A very simple example of this command is below. An object's attributes can include architecture, operating system information, host or vault compatibility, encryption information, etc.
$ legion_list_attributes -c Foo
Foo:
(ALL)
Total attributes retrieved 1
favoritecolors('puce', 'apricot')
$
legion_list_invocations {-l <object LOID> | -c <object context path>}Prints a list of currently pending, started, and recently completed invocations for a given object. The output will include information about each invocation's status, timing, progress, and errors.
legion_object_info [-l <object LOID> | -c <object context path>]
Prints information about a given object. The output (obtained from the object's class) will include the object's host, vault, owner, Object Address, status, etc.
legion_update_attributes
{-l <object LOID> | -c <context path>}
[{-a | -d | -t} <attribute description>] [-u]Adds, deletes, test, and updates attributes, named in <attribute description>, of an object named in <context path> or <object LOID> from the command line. The <attribute description> parameter takes the form name(val1 ... valn). Optional parameters do the following:
| -a | Add an attribute |
| -d | Delete an attribute |
| -t | Test an attribute |
| <attribute description> | Specify an attribute to be updated |
| -u | Update an object's attributes |
The following example adds the attribute favoritecolors to object Foo, with the -a flag.
$ legion_update_attributes -c foo -a "favoritenames(bob, fred)" IN make_attr_from_input - favoritenames(bob, fred) ** ADDED 1 attributes(s) to object $
Similarly, you can remove attributes, with the -d flag. Note, however, that all parameters must be included in order to remove an attribute:
$ legion_update_attributes -c foo -d \ "favoritenames(bob)" IN make_attr_from_input - favoritenames(bob) ** WARNING - DELETED 0 attributes(s) from object instead of 1 specified $ legion_update_attributes -c foo -d \ "favoritenames(bob, fred)" IN make_attr_from_input - favoritenames(bob, fred) ** DELETED 1 attributes(s) from object $
legion_activate_object
{-l <object LOID> | -c <context path>}Activates the object named in <object LOID> or <context path> (i.e., instantiates that object as a process) if it is inert. If the object is already active, the command has no effect.
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>]Creates an object of the class named in <class LOID> or <class context path>. No start-up parameters will be supplied for the class or new object.
If the -h flag isn't used, the host is selected by the class in which you are creating an instance. Similarly, the class will choose a vault if the -v flag isn't used. Normally, this means that a random host is selected, but some classes may act differently. If the -Ch or -Cv flag is used, the class will randomly choose a host or vault from the hosts or vaults listed in the specified context. In both cases, the system will not return the LOID of the randomly chosen host. The legion_host_vault_list and legion_vault_host_list commands will allow users to limit the placement of a given class's instances (i.e., any instances of class Foo can only be placed on hosts X, Y, and Z).
The following options are supported:
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>]Causes the specified class object to create a new object on the host named in <host name> using the rsh1 (remote shell) mechanism. The object will be managed with rsh, if the class it is invoked on is an rshStartClass. If this utility is invoked on a normal class, normal object create mechanism will be used, and the object will not be managed by rsh. This command is generally used only by the legion_create_host and legion_create_vault scripts, not by users.
The additional arguments specify information for the rsh environment.
legion_deactivate_object
{-l <object LOID> | -c <context path>}Deactivates the object named in <object LOID> or <context path> (moves it to an inert state) if it is currently active. If the object is already inactive, the command has no effect.
legion_destroy_object
{-l <object LOID> | -c <context path>}Deletes the object named in <context path> or <object LOID>. More specifically, it removes the object's LOID but not its context name (if there is one). If the object is active, the command deactivates the object. In all cases, it deletes the OPR (object persistent representation) associated with the object.
This command will not remove any context name associated with the object: you must use the legion_rm command to remove the object's name(s) or you will get binding errors. (You can use legion_ls -A to check for multiple context names.)
legion_list_implementations [-v]
{-l <class LOID> | -c <class context path>}Lists the implementation objects associated with the class named in <class LOID> or <class context path>. In its default setting the output will consist of each implementation object's LOID and architecture type. If the -v flag is included, the output will include byte size and a brief description of each object.
The following option is supported:
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>}Displays information about the instances of the class named by <context path> or <class LOID>. For every instance, the tool displays the class's LOID, current object address, status (active or inert), the host on which it resides, and the vault that holds its OPR. The example below shows that class BasicFileClass has two instances, and that both are currently running.
$ legion_list_instances -c /class/BasicFileClass
Class 1.01.66000000..000001fc0d63e97... knows about the following instances:
LOID: 1.01.66000000.01000000.000001fc0a00...
Current oa : [xxx.xxx.xxx.xxx : 2020]
Current host : 1.01.07.30232908.000001fc0...
Current vault: 1.01.03.2e232908.000001fc0...
Status : object-running
LOID: 1.01.66000000.02000000.000001fc0edd...
Current oa : [xxx.xxx.xxx.xxx : 1895]
Current host : 1.01.07.31232908.000001fc0...
Current vault: 1.01.03.2e232908.000001fc0...
Status : object-running
$
legion_set_host {-l <object LOID> | -c <object context path}
{-l <host LOID> | -c <host context path>}Calls the set_host() class-mandatory member function on the class of the object named by in <object LOID> or <object context path>, causing that object to migrate to the host named in <host LOID> or <host context path>.
In the example below, object Foo's host is changed from BootstrapHost to newHost.
$ legion_set_host -c Foo -c /hosts/newHost
legion_set_vault {-l <object LOID> | -c <object context path}
{-l <vault LOID> | -c <vault context path>}Moves the OPR of the object named in <object LOID> or <object context path> to the vault named in <vault LOID> or <vault context path>.
legion_add_class_mapping <metaclass LOID> <class LOID>
This command notifies LegionClass that the meta-class named by <metaclass LOID> is the class of the class named by <class LOID>. LegionClass updates its class map accordingly.
legion_combine_domains [-help] [-v] [-C <target domain context path>] <OPR Directory for target domain>
Joins a Legion domain to your current Legion domain, thus creating a larger multi-domain system. Before running this command, be sure to place copies of both the new (target) domain's binding file (found in the $LEGION_OPR/LegionClass.configure file) and its related metadata file in a directory in your local file system: these configuration files will be used to determine the binding for LegionClass objects in the target domain. These file's directory path should be included in the <OPR Directory for target domain> parameter when you run the command.
If other domains were previously combined with the current or target domains they will be connected to the new system as well.
Once the two domains have been joined, their objects can communicate with each other and with objects in any other domains in the multi-domain system. However, their context spaces will remain separate. Use the -C flag to avoid this: specify a name in your local domain's context space that can act as a root context for the target domain's context space. Note that if you use this option you must place a copy of the target domain's $LEGION_OPR/legion_context_env.sh configuration file in your local configuration directory (the directory named in the <OPR Directory for target domain> parameter). This file will be used to determined the target domain's root context's LOID.
The following options are supported:
The example below combines the current domain with net2:
$ legion_combine_domains -v ~/OPR-net2 Current Legion domain root: Type 302 binding:[ 1.35d82a07.01..000001f c0c0e21f57326b63336de9fc4d88d7bf5a314d9 f1df1079abb0938b29b3643e6c9a8413ea6fd58 4f82be29b0ba56cdd0d421a609a4ba9ecf995c8 ddb20b16d6df : [128.143.63.51 : 19870 : 903621581 ] ] Combined list of Legion 2 domain roots: Type 302 binding:[ 1.c8.01..000001fc0a533 f08413082b08857f283c8a0aa34193ea7478b2c 608163414ca5f13939bb0e5d48788b543d5fddd 05e49735487150edf8256d78002bb04454da7ea e82697 :[128.143.63.52 : 16022 : 903624 927 ] ] Type 302 binding:[ 1.35d82a07.01..000001f c0c0e21f57326b63336de9fc4d88d7bf5a314d9 f1df1079abb0938b29b3643e6c9a8413ea6fd58 4f82be29b0ba56cdd0d421a609a4ba9ecf995c8 ddb20b16d6df : [128.143.63.51 : 19870 : 903621581 ] ] Created 2 new domain interconnections. $
legion_create_implementation
<binary path name> <architecture>
{-l <class LOID> | -c <class context path>} [-c <context path>]
[-nc] [-help] [-v] [-a <attribute>]Creates an implementation object based on the binary executable named in <binary path name>. Each class maintains a list of the implementation objects that are suitable for its instances. There are a set of implementation objects created when your system was initialized (use legion_ls -la /impl to see a list). Several different implementation objects might be maintained by a class to support the use of multiple platforms--a class might have implementation objects for different architectures, for different operating systems, with different memory requirements, etc.
The new implementation object is associated with the class object named in <class LOID> or <context path>, and is marked as usable for hosts of a specified type (linux, solaris, etc.). For example,
$ legion_create_implementation Legion/bin/linux/my_obj linux -c my_class $
creates a new implementation object for my_obj. The new object is automatically assigned the context path /impls/my_obj.linux.1 (if you ran the example a second time, the new object would be called /impls/my_obj.linux.2). You can use the -c <context path> flag to specify a different context path or the -nc flag to specify that no context path be assigned.
At the moment, possible architectures are
legion_init_arch
Creates and registers implementation objects for commonly used classes in the current architecture. This command is run on new hosts to create its implementation objects in the proper place. Implementation objects for specific binary executables can be created with the legion_create_implementation utility.
$ legion_init_arch Initializing Legion implementations for "linux" Creating an implementation (ContextObject) for ContextClass Continue (y=yes, Y=yes to all, n=no, N=no to all, v=verbose, V=verbose all)? Y Creating an implementation (MetaClassObject) for LegionClass Creating an implementation (ClassObject) for VanillaMetaClass Creating an implementation (BindingAgent) for BindingAgentClass Creating an implementation (BasicFileObject) for BasicFileClass Creating an implementation (ttyObject) for ttyObjectClass Creating an implementation (StatTreeObject) for StatTreeClass $
legion_list_domains
List the domains currently connected to your current Legion domain. The output will list the binding for your current domain and any domains linked to your current domain. Please see legion_combine_domains for information about connecting Legion domains.
legion_activate_instances
{-l <class LOID> | -c <class context path>}Activates all instances of the class named in <class context path> or <class LOID>. Instances that are already active will be unaffected.
legion_cat <context path>
Prints the contents of the Legion file object named in <context path> to standard output. It is similar to the Unix cat command.
$ legion_cat newFileObject This is a test, just a test, nothing more. $
legion_context_add <object LOID> <context name>
legion_context_create <context path>
Creates a new context in Legion context space, and assigns it the name given in <context path>. This command is analogous to the Unix mkdir command. The new context will be placed in your current context. The output will contain the new context's location and its LOID.
legion_cp [-localsource | -localdest] <source file> <destination file>
Copies the file named in <source file> (named as either a context path or a local path) to a new, duplicate, file object named in <destination file> (named as either a context path or a local path). The command is analogous to the Unix cp command.
legion_deactivate_instances
{-l <class LOID> | -c <class context path>}Deactivates all instances of the class named in <class context path> or <class LOID>. Instances that are already deactivated will be unaffected.
legion_destroy_instances
{-l <class LOID> | -c <class context path>}Destroys all instances of the class named in <class context path> or <class LOID>. If any instances are active, they are deactivated.
This command will remove the LOIDs of the specified class' instances in all contexts, not just the current context. However, it will not remove any context name associated with this object: you must use the legion_rm command to remove the object's name(s), or you will get binding errors. (You can use legion_ls -A to check for multiple context names.)
legion_direct_output {-l <object LOID> | -c <object path>}
{-l <tty LOID> | -c <tty context path>}Causes the object named in <object path> or <object LOID> to direct its output (standard out and standard error) to the Legion tty object named by <tty context path> or <tty LOID>. Note that this command can only be invoked on objects that have dynamic output redirection enabled. If the command is invoked on an object that does not have redirection enabled, neither the object nor the tty is affected and an error message is displayed.
legion_get_host {-l <object LOID> | -c <object context path>}This command looks up and returns the LOID of the host on which the object named in <object context path> or <object LOID> currently resides.
$ legion_get_host -c Foo 1.01.07.d49d1a40.000001fc0c04724... $
legion_get_vault {-l <object LOID> | -c <object context path>}Returns the LOID of the vault which the object named in <object context path> or <object LOID> is currently using to store its OPR.
legion_import_tree [<unix directory path> [<legion context path>]]
Recursively copies a local directory tree in Unix space, named by <unix directory path>, into a Legion context, named by <legion context path>. The output will include the new context's LOID and location. Pathnames can be relative or absolute. Default values are the current working directory and the current working context.
legion_list_names {-l <object LOID> | -c <object context path>}legion_ln <context path> <new alias>
Assigns an additional name, given in <new alias>, to the object named in <context path>. Analogous to the Unix ln command. Path names can be relative or absolute.
An object can have multiple context names, assigned by one or more users. The same context name can be assigned to different objects or to the same object so long as the contexts names are in different contexts (just as the same file names can be used in different levels of a Unix directory).
legion_ls [-laLAdqvh] <context path>
Lists the contents of a named Legion context in ascii-alphabetical order. Note that the pathname can be relative or absolute. The command is analogous to the Unix ls command. The default setting lists the current context. You can include a context path in the <context path> parameter to list the contents of that context. For example:
$ legion_ls /hosts BootstrapHost my.host.DNS.name $
You can get more specific information (object type, LOID, other context aliases, state) about objects with the flags, described below.
Optional parameters do the following:
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_mv <context path> <new context path>
Assigns a new context name, given in <new context path> to the object named in <context path>. Pathnames can be relative or absolute. Analogous to the Unix mv command.
legion_pwd
legion_rm [-r] [-f] [-v] <context path list>
Removes the context path[s] named in <context path list> from Legion context space. Pathnames can be relative or absolute. Analogous to the Unix rm command.
If the context path listed is the last (i.e., only) name mapped to a given object, the object will be destroyed. If there are other names mapped to the object, the object will remain.
legion_set_context <context path>
Changes the current working context to the context named in <context path>. Note that the path name can be relative or absolute. Analogous to the Unix cd command.
legion_set_tty <context path>
This command will set an environment variable to indicate which tty object should be used by subsequent programs. By selecting a new current tty object, users can redirect the output to any window or file.
$ legion_set_tty /context_path/my-tty
Note that program output does not have to be directed to the same window in which the program is run. By setting a new current tty object, the output can be redirected to any window, or even a file. For example:
$ legion_create_object -c /class/ttyObjectClass my-tty $ legion_set_tty /log-file
creates a tty object whose output is sent to a file. To view the tty output, use the legion_tty_watch command (below).
legion_tty <context path>
This command can be used to direct all output from a particular shell back to that shell--i.e., create and set a tty object for a shell--in one step, rather than running legion_create_object, legion_ set_tty, and legion_tty_watch. If no tty object exists at the path named in <context path> it creates a new object, sets it as the target tty, and starts the legion_tty_watch process in the background of the shell in which the command was run. If a tty object already exists at the named context path, the command sets that tty object as the target tty.
legion_tty_off
Unsets (stops) the Legion tty object for the current shell so that Legion programs executed in that shell after legion_tty_off is run will not display their output to a Legion tty object. This command also shuts off the background legion_tty_watch process for the current shell. This command only works on tty objects that have been set with the legion_tty command. See legion_tty_watch for information on turning off other tty objects.
Note that this does not destroy the tty object. The object can be reused with legion_tty, legion_set_tty, or legion_tty_ watch.
legion_tty_redirect <context path>
Causes the Legion tty object currently set in the shell environment to stream directly into the file object named in <context path>. If the file does not already exist the system creates it. Existing files are appended to, not truncated. A single tty object can be simultaneously directed into any number of files (as well as watched from any number of terminal windows).
legion_tty_unredirect <context path>
Causes the Legion tty object currently set in the shell environment to stop streaming into the file object named in <context path>. If the tty object is not currently directing output to the named file the command is ignored.
legion_tty_watch [-l <LOID> | -c <context path>]
Causes output written to a Legion tty object to be printed to standard output. If no command line parameters are specified, the current tty object set for the shell session is selected. Otherwise, the tty object named in <LOID> or <context path> is selected. Note, the command will not self-terminate: to stop the program send it a SIGINT (i.e., using ^C or "kill -INT"). Any number of legion_tty_watch sessions may simultaneously watch the same Legion tty object.
legion_create_class [-c < context path>]
Creates a new instance of class VanillaMetaClass. The object will be placed in the current working context, unless specified with the -c flag. The following optional parameter is supported:
legion_destroy_host [-help] [-v]
{-l <host LOID> | -c <host context path>}Destroy a given host object. All contexts objects on that host will be destroyed and all active objects will be deactivated. Legion will automatically search your context space and remove and dangling context names for the host object.
legion_destroy_vault {-l <vault LOID> | -c <vault context path>}Destroy a given vault object. Legion will attempt to move all of the vault's current OPRs off of the vault object and then destroy the vault object. If any OPRs cannot be successfully moved the process will abort and an error message will be displayed.
legion_initialize
Populates the Legion system with basic classes and implementations. This command should be run after a Legion system is started for the first time (using legion_startup). On subsequent activations of the system, the state created by this utility will already exist, so this command should not be run again.
legion_make_setup_script [-help] [-o <script basename>] [-OPR <OPR dir name>] [-L <$LEGION dir name>]
Generates a Legion setup script for your system. This script sets the environment variables for Legion users.
The following options are supported:
legion_print_config
legion_setup_state [-i]
Creates OPRs for the basic Legion system objects. This script should be run when starting a Legion system for the first time. The following optional parameter is supported:
legion_shutdown [-local] [-f] [-i] [-h]
Shuts down a running Legion system, preserving the state of all objects for subsequent reactivation of the system. Optional parameters allow users to shut down individual hosts and to specify an interactive shutdown.
legion_shutdown_class
{-l <class LOID> | -c <context path>}Deactivates the class object named in <class LOID> or <context path> and all of its instances. This command operates recursively: if applied to a metaclass, for example, it would deactivate the metaclass, all of its class instances, all of their instances, etc.
legion_starthost
[-L <$LEGION>] [-O <$LEGION_OPR>] [-A <$LEGION_ARCH>] [-B <path>]
[-N <context name>] [-U <user id>] [-C <host class>]
{<new host name>} [<compatible vault list>]Creates a new host object on the specified <new host name>, using the legion_create_object_r command (which is automatically invoked on the host class). The <new host name> is the host's DNS name. The legion_starthost command selects the following default values for the new object:
Optional parameters do the following:
legion_startup [-local]
legion_startvault
[-L <$LEGION>] [-O <$LEGION_OPR>] [-A <$LEGION_ARCH>]
[-N <context name>] [-U <user id>] {<host name>}
[<compatible host list>]Creates a new vault object on the specified <host name>, using the legion_create_object_r command (which is automatically invoked on the host class). The <host name> is the host's DNS name.
The following optional parameters are supported:
legion_class_host_list
[-l <class LOID> | -c <class context path>]
[{-a | -d | -t} <host1> <host2> ... <hostn>] [-p] [-u]Manipulates the list of hosts upon which the class named in <class context path> or <class LOID> can place its instances. The list of acceptable hosts for a given class consists only of hosts that have been added to the list. The list therefore may not necessarily include all possible hosts. If there are no hosts listed as acceptable the user can assume that all hosts are acceptable.
The following optional parameters are supported:
The example below adds a new host to the list of acceptable hosts of BasicFileClass, using the -a flag.
$ legion_class_host_list -c /class/BasicFileClass -a /hosts/newHost ** ADDED 1 host(s) to class's acceptable host set
The -p flag can then be used to check the listing.
$ legion_class_host_list -c /class/BasicFileClass -p ** ACCEPTIBLE HOST LISTING: ** 1.01.07.d59d1a40.000001fc094e23... $
You can use the -a, -d, and -t flags more than once when running the command but regardless of how you list them on the command line Legion will process them in a specific order when you run the command: first adding any new hosts, then deleting old hosts, then testing any hosts, and finally printing out the results. Note also that if you give the class's context name in the first parameter (i.e., with the -c flag) you must use the hosts' context names in the <host1> <host2> ... <hostn> parameter. Similarly, if you give the class's LOID (with the -l flag) you must use the hosts' LOIDs. In other words, if you were to enter:
$ legion_class_host_list -c /class/myClass -t 1.01.07.d59d...
You would get an error message. Legion will treat the host's LOID as a context name.
legion_class_vault_list
[-l {<class LOID> | -c <class context path>}
[{-a | -d | -t} <vault1> <vault2> ... <vaultn>] [-p] [-u]Manipulates the list of vaults upon which the class named in <class context path> or <class LOID> can place its instances' OPRs. Optional parameters are:
You can use the -a, -d, and -t flags more than once when running the command but regardless of how you list them on the command line Legion will process them in a specific order when you run the command: first adding any new vaults, then deleting old vaults, then testing any vaults, and finally printing out the results. Note also that if you give the class's context name in the first parameter (i.e., with the -c flag) you must use the vaults' context names in the <vault1> <vault2> ... <vaultn> parameter. Similarly, if you give the class's LOID (with the -l flag) you must use the vaults' LOIDs. In other words, if you were to enter:
$ legion_class_vault_list -c /class/myClass -t 1.01.07.01000...
You would get an error message. Legion will treat the vault's LOID as a context name.
legion_get_candidate_hosts
{-l <object LOID> | -c <object context path>}Display the LOIDs of acceptable hosts for the object named in <object context path> or <object LOID>.
legion_get_candidate_placements
{-l <class LOID> <instance LOID>} | {-c <class context path> <instance context path>} [<max placements>]Displays a list of acceptable host/vault pairings for the class and instance named in <class context path> <instance context path> or <class LOID> <instance LOID>. The optional parameter <max placements> limits the number of feasible placements displayed. The default value set for this parameter (-99) indicates that there's no upper limit in the number of placements that should be returned. If the user specifies a max number, it's passed on to the object via the method call, and only that number of placements will be returned.
The output of this command lists the LOIDs of the instance (abbreviated as inst), host, implementation object (abbreviated as impl obj), and vault of each pairing. The instance LOID appears in each listed pairing.
The example below displays the list of pairings for instance Foo of class BasicFileClass. In this case, there are two possible vaults (BootstrapVault and NewVaultObject) but only one host (BootstrapHost): there are therefore two possible pairings, and two lists. The first pairing, of BootstrapHost and BootstrapVault, lists the LOID of Foo, BootstrapHost, BasicFileClass's implementation object, and Bootstrap-Vault. The next pairing, of BootstrapHost and NewVault-Object) repeats the LOIDs of Foo, BootstrapHost, and the implementation object, and ends with the NewObjectVault's LOID.
$ legion_get_candidate_placements -c /class/BasicFileClass Foo
max = -99
ALL_PLACEMENTS = -99
Candidate Placements for Foo:
inst = 1.01.66000000.01000000.000001...
host = 1.01.07.d49d1a40.000001fc0c04...
impl obj = 1.01.08.d89d1a40.000... arch = 1
vault = 1.01.03.d49d1a40.000001fc0a6...
inst = 1.01.66000000.01000000.000001...
host = 1.01.07.d49d1a40.000001fc0c04...
impl obj = 1.01.08.d89d1a40.000... arch = 1
vault = 1.01.03.d69d1a40.000001fc0ac...
$
legion_get_candidate_vaults
{-l <object LOID> | -c <object context path>}Display the LOIDs of acceptable vaults for the object named in <object context path> or <object LOID>.
$ legion_get_candidate_hosts -c /vaults/NewVaultObject 1.01.07.d49d1a40.000001fc0c0472... 1.01.07.d59d1a40.000001fc094e23... 1.01.07.d69d1a40.000001fc0b6810... $
legion_host_vault_list
{-l <host LOID> | -c <host context path>]
[{-a | -d | -t} <vault1> <vault2> ... <vaultn>] [-p] [-u]Used to display and manipulate list of vaults with which the host named in <host context path> or <host LOID> can interoperate.
The following optional parameters are supported:
To list the vaults that a host can operate on, for instance, you would type in:
$ legion_host_vault_list -c /hosts/HostName -p ** COMPATIBLE VAULT LISTING: ** 1.01.03.d49d1a40.000001fc0a69cbb845... $
You can use the -a, -d, and -t flags more than once when running the command but regardless of how you list them on the command line Legion will process them in a specific order when you run the command: first adding any new vaults, then deleting old vaults, then testing any vaults, and finally printing out the results. Note also that if you give the host's context name in the first parameter (i.e., with the -c flag) you must use the vaults' context names in the <vault1> <vault2> ... <vaultn> parameter. Similarly, if you give the host's LOID (with the -l flag) you must use the vaults' LOIDs. In other words, if you were to enter:
$ legion_host_vault_list -c /host/HostName -t 1.01.03.d49...
You would get an error message. Legion will treat the vault's LOID as a context name.
legion_instance_host_list
{-l <LOID> | -c <context path>}
[{-a | -d | -t} <host1> <host2> ... <hostn>] [-p] [-u]Manipulates the list of hosts upon which the instance named in <LOID> or <context path> can be placed.
The following optional parameters are supported:
You can use the -a, -d, and -t flags more than once when running the command but regardless of how you list them on the command line Legion will process them in a specific order when you run the command: first adding any new hosts, then deleting old hosts, then testing any hosts, and finally printing out the results. Note also that if you give the instance's context name in the first parameter (i.e., with the -c flag) you must use the hosts' context names in the <host1> <host2> ... <hostn> parameter. Similarly, if you give the instance's LOID (with the -l flag) you must use the hosts' LOIDs. In other words, if you were to enter:
$ legion_instance_host_list -c myInstance -t 1.01.07.01000...
You would get an error message. Legion will treat the host's LOID as a context name.
legion_list_oprs {-l <vault LOID> | -c <vault context path>}Lists all OPRs currently stored in a given vault. The output includes information about inert objects' LOIDs, OPA, owner, and status.
legion_vault_host_list
{-l <vault LOID> | -c <vault context path>}
[{-a | -d | -t} <host1> <host2> ... <hostn>] [-p] [-u]Display and manipulates the list of hosts with which the vault named in <vault LOID> or <vault context path> can interoperate.
The following optional parameters are supported:
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... $
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 vault'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 vault's LOID (with the -l flag) you must use the hosts' LOIDs. In other words, if you were to enter:
$ legion_vault_host_list -c /vaults/VaultName -t 1.01.07...
You would get an error message. Legion will treat the host's LOID as a context name.
legion_check_system [-help] [-v] [-q]
Checks the status of the key elements of your Legion system: LegionClass, host objects, root context object, etc. The output will include a summary of warnings and errors currently running in your system.
legion_classof
{-l <object LOID> | -c <context path>}Displays the LOID of the class of the object named in <context path> or <object LOID>.
$ legion_classof -c Foo The class of 1.01.66000000.01000000.000001fc0... is 1.01.66000000..000001fc0d085b2c33... $
legion_create_stat_tree <base context path>
legion_host_stats {-l <host loid> | -c <host context path>}
legion_list_objects {-l <host LOID> | -c <host context path>}Lists the Legion objects currently managed by (i.e., running on) the host object named in <host context path> or <host LOID>. This may include each object's LOID, status, and its owner's LOID and OA.
legion_version
Prints which version of Legion you are current running. For example, the output below indicates that the current system is a University of Virginia Legion system version 1.3.5.
$ legion_version VaL Legion version 1.3.5 $
legion_wellknown_class <wellknown class name>
Gets the class LOID of a Legion "well-known" class. Possible values for <wellknown class> are:
LegionClassBootstrapMetaClass UnixHostClass UnixVaultClass CommandLineClass ContextClass ImplementationClass UnixImplementationCacheClass BindingAgentClass legion_whoami
You can use this command to find out which user id you are currently logged in as. Your output will look something like this:
2.8 Security
legion_change_owner [-h] [-v] [-r] {-l <object LOID> | -c <object context path>} {-l <target owner LOID> | -c <target owner context path>
Changes an object's owner. Note that you must be logged in as both the current owner and the target owner in order to run this command.
The following options are supported:
legion_change_permissions [+-rwx] [-v] [-help] <group/user context path> <target context path>
Changes an object's read, write, and execute permissions so that you can allow the user or group named in <group/user context path> to use the object named in <target context path>. This tool manipulates an object's access control list (ACL) so that other users can call methods on your objects. For our purposes, "read" methods are defined as methods that obtain but do not modify an object's state, "write" methods are methods that modify an object's state, and "execute" methods are methods that run an object. The example below would allow bob to read object foo.
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:
legion_create_user <user name>
This command is actually a simple wrapper around the legion_create_user_object command. The full command give more control to the creation of AuthenticationObjects.
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 name>. The command will prompt for a password for the new user, and will return the new object's LOID. Note that the context in which the user name is placed 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.
legion_get_acl [-l <loid> | -c <context>]legion_get_implicit_params [-l <loid> | -c <context>]]
Get the implicit parameters of a specified object or the current environment. When used without an argument, the command will return the implicit parameters of the current environment: when an object is named in either <object LOID> or <object contexts path> the object's implicit parameters will be returned.
legion_init_security
Creates the initial user (called by default /user/admin) in a new Legion system. This command should be run immediately after legion_initialize when you are starting your system. The script creates a new context called /users, a new user object called admin. The context name admin is placed in the new /users context. You will be asked to give a password. You can change the admin's password with the legion_passwd command.
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 [-l <user LOID> | <user name>] [-e <command>]legion_login -x [-e <command>]
Allows user to log in to the Legion system as a user, and sets up implicit parameters and security credentials for the user. Note that the command can be run without any arguments (although it will prompt for a user name if a user LOID or user name is not given). User names are context names for AuthenticationObjects (special objects that contain a user password, initial implicit parameters, and other information), created with the legion_create_user command. On a successful login, a new shell is created. Logout is achieved by exiting the shell.
The -e flag can be used to specify a different program to run with security credentials instead of a Unix shell. For example:
will run legion_ping on object bob in bob's shell.
The -x flag can be used to start a subshell or (using the -e flag) to execute a command without the user's login privileges. This takes advantage of a side benefit of legion_login: command-line tools can use legion_login's special caching service to accelerate the execution of subsequent Legion commands. This service is available even if no credentials have been obtained from an authentication object. For example:
will run legion_ping on object bob. If special privileges were required to ping bob, the command would fail.
legion_passwd {-l <user LOID> | <user name>}legion_set_acl {-l <object LOID> | -c <object context path>} [-s | filename]
Sets the access control list of the Legion object named in <object context path> or <object LOID>. The following option is supported:
legion_set_implicit_params [-l <object LOID> | -c <object context path>] [-s | filename]
Set the implicit parameters of a specified AuthenticationObject or the current environment. When used without an argument, the command will set the implicit parameters of the current environment. The following option is supported:
2.9 Application development
legion_bfs <file> [-o <out file>] [-BackEnd]
Parses Fortran programs containing Legion Basic Fortran Support (BFS) pseudo-comments to produce standard Fortran output, or parses Legion BFS IDL files to produce Mentat Programming Language (MPL) output. If the input <file> ends with .f, it is treated as Fortran with pseudo-comments. If the input <file> ends with .bfs, it is treated as BFS IDL.
legion_generate_idl [<flags>] <input file local path>
This command generates Legion stub files for CORBA input IDL files. Optional flags allow you to include information about the preprocessor and the back end and to specify whether or not trans code, client stubs, and head files should be created. If you run the command with no flags, Legion will generate client-side and server-side stubs. For example:
On the other hand, the example below will generate client-side stubs, a trans file, and header files.
The following options are supported:
legion_make [-help] [-v] [-a <architecture>] [-h <host context path>] [-e <make command>] [-OUT <remote file>] [<arg1> <arg2> ... <argn>]
Compiles programs on a remote host. The command tars your current directory, copies it to a remote host, untars it, and executes a make command. The resulting compiled binaries can be registered with Legion via the directory's makefile or can be copied back to your current directory with one or more -OUT options. Be aware that legion_make will tar everything in and below your current directory, so be sure that you are in the correct directory before running it.
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:
To be more specific, use the -h flag:
The following options are supported:
legion_make_idl [-notrans] [-noclient] [-v] [-noreg] [-s <suffix string>] [-run] [-help] <application name>
This command compiles Legion stubs and implementation code of CORBA client and server classes. The resulting binary executable files can be run in Legion systems. You can use the -run option to compile and execute your code in one step. Unless specified, Legion will compile client-side and class code and will register the resulting binary executable files with Legion (with the legion_mplc_reg_impl command).
The following options are supported:
legion_make_multi [-help] [-v] [-a <architecture>][-e <make command>] [<arg1> <arg2> ... <argn>]
Compile a program on multiple platforms. Like the legion_make command, this tars the current directory, copies it to a remote host, untars it, and executes a make command on it. The resulting compiled binaries can be registered with Legion via the directory's makefile. Optional flags let you specify different architectures and make commands.
The following options are supported:
legion_mplc
Compiles MPL (Mentat Programming Language) programs. There are several possible parameters to this command: please see the MPL Manual for more information (the MPL Manual is available from the Legion web site at http://legion.virginia.edu/Documentation.html).
legion_mplc_reg_impl <class name> <binary path> <stateless | stateful | sequential> <arch>
Registers the given binary, named in <binary path>, as a stateful, stateless, or sequential Mentat object for the architecture named in <arch> and under the class object named in <class name>. This command is automatically run when you use the legion_mplc command (without the -nolegion option) to compile an MPL program.
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:
Executes java applications that use the Legion-Java interface. The command relies on the ability to call other Legion command-line tools, so it should be run only on machines that have Legion-supported platforms and have Legion installed and running. Note that you must include $LEGION/src/Java/client in your CLASSPATH environment variable in order for the command to run correctly.
The <java options> argument can include any command-line options accepted by the locally installed "java" interpreter. This set of options will always include the Java class to be executed.
legion_stateless_add_workers <class name> <worker name1> <worker name2> ... <worker nameN>
Creates additional MPL stateless object workers. By default, when a stateless class is created or registered in context space it instantiates a single worker. That worker is used by all other objects wishing to call a remote method invocation on that class. Adding more workers allows message calls to be handled more efficiently.
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.
legion_stateless_configure <stateless class context path> [-n <number of replicas>] [-Ch <host context path>] [-w <max number work requests>] [-update] [-Flush] [-status]
This command configures stateless Legion classes so that requests sent to a stateless class are first routed to a proxy object, which selects a worker to service the requests. You can use flags to control the number of replica workers, their placement, and the number of work requests that a worker may service at a given time.
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:
The following options are supported:
legion_stateless_remove_workers <class name> <worker name1> <worker name2> ... <worker nameN>
Removes MPL stateless object workers. The <class name> parameter should be the stateless class object's context name. The <worker name> parameters should be the context name of the unwanted worker objects. Note that you can use full or relative path names.
2.10 Program support
legion_link [-CC <compiler>] [-Fortran] [-pvm] [-mpi] [-L<library path>] [-l<library>] [-v] [-o <output file>] [-bfs] [-help] <object file list>
This command, similar to the Unix ld command, links together a set of object files and libraries to produce an executable program. The legion_link command automatically binds the produced executables to the Legion libraries. It can be used with object files and libraries created from C, C++, or Fortran source code. If any Fortran object files are linked, the -Fortran flag must be included.
The following options are available with this command: