Legion 1.2
Reference Manual

2.0 Command-line functions

2.1 Calls on objects

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(ObjectAttribute- 
	List);
  LegionAttributeSignatureList retrieveAttributes_s(Object- 
	AttributeSignatureList);
  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.000001fc0a72cd9e3c85dad3e18062d
9d0080227e53892056c6610e12ed05e37988be980a3b837c058527
df442f84b65ec558bdac2698e62710032b31991e38a04cf2529
Returned: 1.01.66000000.14000000.000001fc0a72cd9e3c85dad3e18062d
9d0080227e53892056c6610e12ed05e37988be980a3b837c05852
9df442f84b65ec558bdac2698e62710032b31991e38a04cf2529
$
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_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
$

2.2 Calls on Class Objects

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:

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

<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

The optional parameter does the following:

<user id>			Specifies the appropriate user name on the rsh host
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 an object's context name: you must use the legion_context_remove or legion_rm command to remove the context name (if there is one) or you will get binding errors in that context. A simpler approach, however, would be to use the legion_rm command with the -destroy option to remove both the context name and the LOID.

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_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 LOID> or <object context path> resides.

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_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>.

2.3 Calls on LegionClass

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_create_implementation 
<binary path name> <architecture>
[-l <class LOID> | -c <context path>]

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

$ legion_create_implementation Legion/bin/linux/my_obj linux -c my_class
$

At the moment, possible architectures are

  • linux (corresponds to x86 running Red Hat 4.x Linux)
  • solaris (corresponds to Sun workstations running Solaris 5.x)
  • sgi (corresponds to SGI workstations running IRIX 5.x)
  • alpha_linux (corresponds to DEC Alphas running Red Hat 4.x Linux)
  • alpha_DEC (corresponds to DEC Alphas running OSF1 v4)
  • t90 (corresponds to Cray T90s running Unicos 10.x)
  • rs6000 (corresponds to IBM RS/6000s running AIX 4.2).
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
$

2.4 Calls on File and Context Objects

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>

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

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_context_list [<context path>]

Lists the entries contained in the context named in <context path>. This command is analogous to the Unix ls command. The default lists the current context.

legion_context_lookup <context path>

Displays the LOID associated with the name given in <context path>. If the name is not mapped in context space, the empty LOID (i.e., 0) is displayed.

legion_context_remove <context path>

Removes name-LOID mapping of the context named in <context path> from the context space. Analogous to the Unix rm command. Note that this command does not remove an object's LOID, only the context name. If you wish to remove both the object's context name and LOID use the legion_rm command. To remove the LOID, use the legion_destroy_object command.

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.

The following optional parameters are supported:

-localsource	Indicates that the source path is in the local files system
-localdest	Indicates that the target path is in the local file system.
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 the context names: you must use the legion_context_remove or legion_rm command to remove any names, or you will get binding errors. Use legion_rm with the -destroy option to remove both the name and the LOID of individual objects.

legion_direct_output {-l <object LOID> | -c <object path>}
{-l <tty LOID> | -c <tty 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 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_get_vault -c Foo
1.01.03.d49d1a40.000001fc0a69cbb8...
$
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_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 [-lLa] <context path>

Lists the contents of a named Legion context. This command is similar to legion_context_list, but includes optional parameters to get additional information about file objects. Note that the pathname can be relative or absolute. The command is also analogous to the Unix ls command.

The default setting lists the current context. Optional parameters do the following:

-l lists object type and information, if possible
-L lists LOIDs associated with names
-a lists all objects, not just contexts and files
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_rm [-deactivate | -destroy] <context path>

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

Optional parameters do the following:

-deactivate	in addition to deleting the object name, deactivates the associated object
-destroy	in addition to deleting the object name, destroys the associated object.
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 <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 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_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 <tty LOID> | -c <tty 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 by <tty LOID> or <tty 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.

2.5 Start-Up and Shutdown Functions

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:

-c 	assign the new object the name given in <context path>
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_print_config

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

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:

-i 	run the command in an interactive mode.
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.

Optional parameters do the following:

-local 		Shut down only a local host or vault.
-f 		Force the termination of a system.  This may leave processes running, however, and prevent a system restart.
-i		Put the shutdown in an interactive mode, which provides prompts for user actions.
-h		Return the command's complete syntax.
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>] 
[-N <context name>] [-U <user id>] {<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:

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

Optional parameters do the following:

-L <$LEGION> 		Specify $LEGION for host (default is "/home/Legion")
-O <$LEGION_OPR>	Specify $LEGION_OPR for host (default is current $LEGION_OPR)
-A <$LEGION_ARCH>	Specify the architecture type for the host (default is current $LEGION_ARCH)
-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)
legion_startup [-local]

Starts up basic Legion services.

The following optional parameter is supported:

-local 		starts up only a local host or vault
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:

-L <$LEGION>		Specify $LEGION for the vaults host (default is "/home/Legion")
-O <$LEGION_OPR>	Specify $LEGION_OPR for the vaults host (default is "/home/OPR")
-A <$LEGION_ARCH> 	Specify the architecture of the vaults host (default is current $LEGION_ARCH)
-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)

2.6 Scheduling support

legion_class_host_list 
[-l <class LOID> | -c <class context path>]
[{-a | -d} <host name>] [-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:

-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
-p	display the class's acceptable host list
-u	print usage

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...
$
legion_class_vault_list 
[-l {<class LOID> | -c <class context path>}
[{-a | -d} <vault name>] [-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:

-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
-p	display the class's acceptable vault list
-u	print usage
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 BootstrapVault. The next pairing, of BootstrapHost and NewVaultObject) 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} <vault name>] [-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:

-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
-p	display the host's acceptable vault list
-u	print usage

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_instance_host_list
{-l <LOID> | -c <context path>}
[{-a | -d} <host name>] [-p] [-u]

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

The following optional parameters are supported:

-c	use context paths to specify object and host
-l	use LOIDs to specify object and host 
-a	add named host to the object's acceptable host list
-d	delete named host from the object's acceptable host list
-p	display the object's acceptable host list

-u print usage

legion_vault_host_list
{-l <vault LOID> | -c <vault context path>}
[{-a | -d} <host name>] [-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:

-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
-p display the vault's acceptable host list
-u print usage

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...
$

2.7 General functions about the state of the 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>

Creates a database of current loads on all host objects in a system.

legion_host_stats {-l <host loid> | -c <host context path>}

Prints the number of objects and current load for the given host object.

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

legion_wellknown_class <wellknown class name>

Gets the class LOID of a Legion "well-known" class. Possible values for <wellknown class> are:

	LegionClass
	BootstrapMetaClass
	UnixHostClass
	UnixVaultClass
	CommandLineClass
	ContextClass
	ImplementationClass
	UnixImplementationCacheClass
	BindingAgentClass

2.8 Security

legion_create_user <user id>

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 id>. 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 id 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>]

Get the access control list of specified object

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_login [-l <user LOID> | <user id>] [-e <command>]

Allows user to log in to the Legion system as a user, and sets up implicit parameters and certificates for the user. Users are created with the legion_create_user command, after which the user can log in to the system with legion_login. On a successful login, a new shell is created. Logout is achieved by exiting the shell. Like Unix rsh, legion_login can also execute a specific command rather than create a new interactive shell. For example:

$ legion_login bob -e legion_ping -c bob

will run legion_ping on object bob in bob's shell.

Note that the command can be use without any arguments.

legion_passwd {-l <user LOID> | <user id>}

Changes a user's password: the command will prompt for the new password.

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:

-s 	Read from standard input
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:

-s 	Read from standard input

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.

The following options are used:

-o <out file>	Name of the file containing the resulting Fortran or MPL output ard input
-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)
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_java <java options> 

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.

2.10 Program support

legion_flogger [-v] {-n <number of processors>}
{-f <specification file name>} [<program class name>]
[<arg1>, <arg2>, ... <argn>]

This command runs a previously registered serial program, named in <program class name>, with all of the different input files, using a simple specification file, named in <specification file name>, to describe the names of the expected input and output files.

You must have already registered the program name and created the flogger specification file. The specification file might look something like this:

in in.dat in.dat.*
out out.dat

Where "in" identifies the line as a description of the input files (so it is a keyword). "in.dat" is the file name that the serial program expects for its input file. The final string, "in.dat.*," is a pattern that the flogger will use to match all the different input files in the current directory that will be individually fed to different runs of the serial program. "out" is a keyword indicating the output file specification, and "out.dat" is the name of the output file from the serial program. If "in.dat.123" is an input file, the flogger will direct the output to "out.dat.123."

Note that if your program prints to standard output you must direct your output to a Legion tty object with the legion_tty_watch command (if you have not yet created a tty object, see legion_set_tty).

The following parameters are used with this command:

-n <number of processors>	Specify the number of processors used to run the program
-f <specification file name>	The Unix path name of the flogger specification file

The following options are available with this command:

-v			Provide a verbose output as the command is running
<arg1>,<arg2>,...<argn>	Allows users to provide arbitrary command-line arguments for the program.
legion_mpi_debug [-q] {-c <instance context path>}

A utility program that allows the user to examine the state of MPI objects and print out their message queues. This is a handy way to debug a deadlock.

The -q flag will list the contents of the queues.

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.

legion_mpi_register 
<class name> <binary local path name> <platform type>

MPI implementation generally require that MPI executables reside in a given place on a disk. Legion's implementation objects have a similar requirement. The legion_mpi_register command registers the executables of different architectures for use with Legion's MPI. The command creates MPI-specific contexts, a class object, and an implementation for the program, and registers the name in Legion context space.

The command can be executed several times, if you have compiled your program on several architecture.

legion_mpi_run {-f <options file> [<flags>]} | 
{-n <number of hosts> [<flags>] <command> [<arguments>]}

Starts an MPI program. Note that the <command> argument is the Legion context name for the class created by legion_mpi_run.

Parameters used for this command are:

-f <options file>		Allows users to run multiple MPI binaries with a common
										MPI_COMM_WORLD
-n <number of processes>	Specify the number of hosts on which the program will run

supported <flags> are:

-h <host context path>	Specify the set of hosts on which the program will run (default is the system's default placement)
 <host context name>	Runs the first process (i.e., process zero) on this node
-p <PID context>	Specify a context name for PIDs (default is /mpi/instances/program_name)
-s 	  		Print statistics at exit
-v	 	 	Verbose option (up to four of these can be specified for increased detail)
-d <Unix path name>	Specify that all children change to the specified directory before they begin to run.

Note that if the -f flag is used, the -n flag, program name, and any arguments will be ignored. Any <flags> used with -f will be treated as defaults and applied to all processes executed by this command, unless otherwise specified in the options file. The legion_mpi_run utility will expect one binary per line in the options file, each line including any necessary arguments as they would appear on the command line. Each line can also contain any of the legion_mpi_run flags except the -f flag.

If the -f flag is not used, the MPI application named in the legion_mpi_run command will then be started with the given flags.

An example, here running MPI program vdelay on two hosts, would be:

 $ legion_mpi_run -n 2 /mpi/programs/vdelay

You can examine the running objects of your application with

$ legion_context_list /mpi/instances/program_name

This context will have an entry for each object in your application.

legion_pvm_register 
<class path name> <binary local path name> <platform type>

Registers a PVM task implementation. This setup is not necessary for tasks that will only be started from the command line (tasks that will not be "spawned"). Given the class named in <class path name>, the binary named in <binary local path register>, and the architecture type (currently Linux, Solaris, or SGI), this command creates an implementation object that can then be used by the Legion PVM Library.

Once you've registered an application, you can run it. If necessary, you can examine Legion context space with either

$ legion_context_list /pvm

to list the Tids of running PVM tasks, or

$ legion_context_list /pvm/tasks

to list the registered task classes.

You can also use Legion class utilities to examine the class state (e.g., legion_list_instances).

To register a Linux binary named matmult in Legion, enter:

$ legion_pvm_register /pvm/tasks/matmult matmult linux
legion_register_program 
<program class> <executable path> <legion arch>

This command allows uses to register a non-Legion executable program (specified by the <executable path> argument) and make the program available for use within the Legion system. The registered program will be associated with a Legion class object, named in <program class>: the class and the context path will be created, if the class was not already created by a previous execution of legion_register_program. The registered program will execute only on hosts of the architecture specified in <legion arch>.

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 on which the program should be executed.

For more information on this command please see "Registering non-Legion-compatible programs" in the Basic User Manual.

legion_register_runnable 
<program class> <executable path> <legion arch>

The legion_register_runnable command is similar to the legion_register_program command in that it allows programs to be registered for execution through the legion_run utility. However, whereas the legion_register_program tool is used to register non-Legion programs, legion_register_runnable is used to register programs that are linked against the Legion libraries and export the "runnable" object interface.

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.

For more information on this command please See Registering Legion-compatible programs in the Basic User Manual.

legion_run [-help] [-w] [-a <architecture>]
[-in <context path name>] [-out <context path name>] 
[-IN <local file name>] [-OUT <local file name>] 
[-f <options file>] <program class> [<arg1>, <arg2>, ... <argn>]

The legion_run command executes a single instance of a program associated with the program class specified in the <program class> argument. The command will randomly select a host to execute the program (observing the restriction that only hosts with an acceptable architecture may be selected). Support for directing scheduling (e.g. selecting a given host for remote execution) will be added in future releases. Arbitrary command-line arguments may be specified for the remote program.

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 following parameters are 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:

-help				Displays the command's syntax and provides a brief description
								     		of how to use its options.
-w				Specifies that the set tty object should be used. If no tty object has been set,
								     		the flag will be ignored.
-a				Allows users to specify what kind of architecture the program should be
								     		executed on.
-in <context path name>		Specifies the context path of a Legion file that 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>
								     		base-name.
-out <context path name>	Specifies the context path of a Legion file that 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> base-name. 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>).
-f <options 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 options, delimited by spaces, tabs, or blank lines.

For more information on this command please See Running a Legion application in the Basic User Manual.


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

Back to Reference Manual Table of Contents