Read from stdin.
In the interests of space, sample LOIDs are generally shortened.
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:
The <well-known class type> argument is a string in the set of well-known strings. The set can be listed via the legion_wellknown_class tool (see page 40).
For this tool's purposes, 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 /class/LegionClass \
-w ClassObject
1
$
$ legion_exports_interface -c /class/LegionClass \
-w CommandLineObject
"CommandLineObject" is not a well known class. Exiting.
-1
$
$ legion_exports_interface -c /class/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.
The example below returns the interface of the LegionClass (the metaclass for all Legion classes).
$ legion_get_interface -c class/LegionClass Getting the interface of object:1.01.01..000001fc0b325... Object Interface: void deactivate(); RestoreStateReply restoreState(); SaveStateReply saveState(SaveStateRequest); LegionLOID ping(); LegionObjectInterface getInterface(); int exportsInterface(LegionObjectInterface); int addAttribute(ObjectAttribute); int addAttributes(ObjectAttributeList); int replaceAttribute(ObjectAttribute, ObjectAttribute); int replaceAttribute_s(ObjectAttribute, ObjectAttribute); int replaceAttributes(ObjectAttributeList, ObjectAttributeList); int replaceAttributes_s(ObjectAttributeSignatureList, ObjectAttributeList); int removeAttribute(ObjectAttribute); int removeAttribute_s(ObjectAttributeSignature); int removeAttributes(ObjectAttributeList); int removeAttributes_s(ObjectAttributeSignatureList); LegionAttributeList retrieveAttributes(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.
$ legion_ping -c foo Pinging: 1.01.66000000.14000000.000001fc0a72... Returned: 1.01.66000000.14000000.000001fc0a72... $
If the object is not accessible by the tool, the command will return an error.
$ legion_ping -c foo "foo" does not resolve to a valid loid in my context.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). The attribute description must not contain any spaces or begin with an uppercase letter.
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 favoritenames 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>] [-d <recorder context path> <debug session name>]Creates an instance of the class named in <class LOID> or <class context path>. No start-up parameters will be supplied for the class or new object. The following options are supported:
If the -h flag isn't used, the host is selected by the class. Similarly, the class will choose a vault if the -v flag isn't used. Normally, this means that a random host is selected, but some classes may act differently. If the -Ch or -Cv flag is used, the class will randomly choose a host or vault from the hosts or vaults listed in the specified context. In both cases, the system will not return the LOID of the randomly chosen host. The legion_host_vault_list and legion_vault_host_list (page 33 and page 37) commands will allow users to limit the placement of a given class's instances (i.e., any instances of class Foo can only be placed on hosts X, Y, and Z).
legion_create_object_r {-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.
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 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.
The following option is supported:
-v Run the command in a verbose setting. The output will include byte size and a brief description of each object. Legion will use one extra method invocation per implementation object.
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/newHostlegion_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_combine_domains [-help][-v] <list of domain cookie files>Joins a set of Legion domains (systems) to create a single, larger, multi-domain Legion system. Before you run this command, you must obtain a copy of the Legion domain cookie files from all of the involved domains (see legion_generate_domain_cookie and legion_print_domain_cookie [page 17]), including the current Legion domain. If you are joining domain A to domain B and domain B has already been joined to domain C, you will need cookie files from domains A, B, and C. This provides transitivity in the system join. All three domains will be joined to one another to form a single system. The command is implemented this way to avoid communication failures; if a LOID can be passed to an object (e.g., in a method continuation list), that object should be able to use the LOID for further communication.
Non-transitive or non-reflexive joins would allow communication of LOIDs for which an object could not obtain a binding. For example, object X in domain A might be able to bind to object Y in domain B and pass a method to it, but object Y might not be able to bind to object X to pass it the return value.
In addition to joining the binding trees of the involved domains, legion_combine_domains also creates context links in the current domain's context space to all of the remote domains' root contexts. These links appear in local context space in the following path: /domain/LegionDomain.<domain-id>.
If the command is run on domains that are already connected, it has no affect and is harmless.
There is currently no mechanism supporting "unjoining" of domains. However, Legion security mechanisms (e.g., ACLs) can be used to effectively forbid any use of the current domain by outside domains.
The following options are supported:
-help Print information about this command.
-v Provide a verbose output as the command is running.
The example below combines two domains. If either had previously been connected to another domain, three cookie files would be listed.
$ legion_combine_domains LegionDomainCookie.35d82a07 \ LegionDomainCookie.c8 Created 2 new domain interconnections $legion_create_implementation <binary path name> <architecture> {-l <class LOID> | -c <class context path>} [-c <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_classcreates 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.
The following optional parameters are supported:
legion_generate_domain_cookie
[-help] [-o <cookie output filename>]
Generates a domain cookie file for the current Legion domain, as required by legion_combine_domains (page 14). A cookie file contains binding information for the LegionClass in the current domain, security credentials for joining to the current domain, and information about the context space of the current domain (for creating interdomain context space links). The default cookie file name is LegionDomainCookie.<domain-id>, or you can use the -o flag to specify a name.
In a secure environment, you must be logged in as /users/admin for the current domain. This ensures that the required credentials can be generated and saved in the cookie file.
The following optional parameters are supported:
| -help | Print information about this command. |
| -o <cookie output filename> | Specify the local pathname of the resulting output cookie file. |
legion_init_arch
Creates and registers implementation objects for commonly used classes in the current architecture. This command is run on a new host to create its implementation objects in the proper place. Implementation objects for specific binary executables can be created with the legion_create_implementation utility (page 15).
$ 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 (page 14) for information about connecting Legion domains.
legion_print_domain_cookie
[-help] [-i <cookie input file>]
Displays the contents of a Legion domain cookie file (required for using legion_combine_domains [page 14]). By default the command displays the contents of the file LegionDomainCookie.<current-domain-id>, but any input file name can be specified using the -i option.
The following options are supported:
| -help | Print information about this command. |
| -i <cookie input file> | Specify the path of the cookie file to print. |
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_cp
[-help] [-r] [-v] [-m] [-p]
[-localsrc] [-localdest]
[-V <vault context path>]
<source path> <destination path>
Copies the file object or tree named in <source path> (named as either a context path or a local path) to a new, duplicate, file object or tree named in <destination path> (named as either a context path or a local path). Use the recursive mode (-r) to export objects to local file space. Analogous to the Unix cp command.
The following optional parameters are supported:
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>. Any active instances 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_export_dir
[-help] [-v] [-fc] [-cc]
<local base directory path> <target base context path>
The legion_export_dir command allows a complete directory tree in the local file system to be linked into Legion context space without requiring the creation of file copies. A new context will be created to match the local directory tree, and new context names will match the local directory's file names. The command executes only during the duration of time that you wish to use the exported files and directories: if you pause the command the tree's context space will not be available. Once you resume the command, the context will be available.
This is a temporary, read-only context: any changes that you make to the new context, such as changing or removing context names, will not be reflected in the local directory tree (and vice versa). For best results, do not make any changes to the exported directory tree or to the tree's context. For this same reason you should delete the tree's context space when you are finished.
To pause the command, press ^-C. To resume using the exported files, re-execute the command, specifying the same local base directory path and target context path. Use of exported files and directories while the command is not active will cause binding errors. The context space will not be automatically removed when the command is paused or stopped. To delete an exported directory tree's context space, use legion_rm -r while legion_export_dir is active.
The following options are supported:
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>}
Lists all of the given object's context names. This includes names assigned by other users.
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
[-laLRAdqvh] <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. For example, you can get more information about a particular context's objects with the -l, -a, and -A flags. The output below shows a complete list of all objects listed in this context, the objects' types, and any context aliases associated with each listed object.
$ legion_ls -laA /hosts
. (context)
/hosts
.. (context)
/class/..
/hosts/..
/vaults/..
/home/..
BootstrapHost (object)
/hosts/BootstrapHost
/hosts/host.DNS.name
host.DNS.name (object)
/hosts/BootstrapHost
/hosts/host.DNS.name
$
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.
Optional parameters do the following:
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
Prints your current context path. Similar to the Unix pwd command.
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.
Optional parameters do the following:
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 /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
<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 <tty 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.
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
<object context path>
Causes the Legion tty object currently set in the shell environment to stream directly into the file object named in <object 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
<object context path>
Causes the Legion tty object currently set in the shell environment to stop streaming into the file object named in <object 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 in <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.
legion_create_class
[-help] [-c <context path>]
[-sc <scheduler context path>]
[-sl <scheduler LOID>]
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 options are 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 any dangling context names for the host object.
Optional parameters do the following:
| -help | Print a help message. |
| -v | Run in verbose mode. |
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
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:
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 (automatically invoked on the host class) (page 11). 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 |
This command uses remote shell (rsh or ssh) classes to start a new host object on a specified host. Please note that you must be able to run rsh/ssh on the target host from your current machine without having to enter a password. You can set up an .rhosts file for rsh or an authorized_keys file for ssh to accomplish this: see the rsh and ssh man pages for further information.
You can run Legion commands on a remote host using rsh or ssh, once you set the proper environment variables. For sh, ksh, or bash, use:
LEGION_RSH=<rsh|ssh> LEGION_RCP=<rcp|scp> export LEGION_RSH LEGION_RCP
setenv LEGION_RSH <rsh|ssh> setenv LEGION_RCP <rcp|scp>
Optional parameters do the following:
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 (automatically invoked on the host class) (page 11). The <host name> is the host's DNS name.
This command uses remote shell (rsh or ssh) classes to start a new vault object on a specified host. Please note that you must be able to run rsh/ssh on the target host from your current machine without having to enter a password. You can set up an .rhosts file for rsh or an authorized_keys file for ssh to accomplish this: see the rsh and ssh man pages for further information.
You can run Legion commands on a remote host using rsh or ssh, once you set the proper environment variables. For sh, ksh, or bash, use:
LEGION_RSH=<rsh|ssh> LEGION_RCP=<rcp|scp> export LEGION_RSH LEGION_RCP
setenv LEGION_RSH <rsh|ssh> setenv LEGION_RCP <rcp|scp>
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. I.e., if you enter:
$ legion_class_host_list -c /class/myClass \ -t 1.01.07.d59d...
You will 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. I.e., if you enter:
$ legion_class_vault_list -c /class/myClass \ -t 1.01.07.01000...
You will get an error message. Legion will treat the vault's LOID as a context name.
legion_config_scheduler
{-l <scheduler LOID> | -c <scheduler context path>}
[-get_enactor] [-get_collection]
[-set_enactor {-l <Enactor LOID> | -c <Enactor path>}]
[-set_collection {-l <Collection LOID> | -c <Collection path>}]
This command can be used to query or configure the helper objects used by a basic Legion scheduler. Basic Legion Scheduler objects use a Collection helper object to obtain information about available resources upon which they can schedule objects. After constructing a schedule, basic Legion Schedulers use an Enactor helper object to implement scheduling decisions (to actually start up the scheduled objects). Use this command to assign a particular Collection and Enactor to a basic Legion Scheduler or vice versa.
The following optional parameters are supported:
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 can 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 include the host's LOID (via the -l flag) you must include the vault's LOIDs. That is, if you enter:
$ legion_host_vault_list -c /host/HostName \ -t 1.01.03.d49...
You will 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 that if you use the instance's LOID in the first parameter (i.e., with the -l flag) you must use the hosts' LOIDs in the [<host1> <host2> ... <hostn>] parameter.
legion_join_collection
{-l <Collection LOID> | -c <Collection path>}
{-l <member LOID> | -c <member path>}
This command joins the objects named in <member LOID> or <member path> to the Collection named in <Collection LOID> or <Collection path>. Any Legion object can be added to a Collection.
You can use the legion_query_collection command (page 35) to get information (in the form of object attributes) about the given collection.
legion_leave_collection
{-l <Collection LOID> | -c <Collection path>}
{-l <member LOID> | -c <member path>}
This command removes the object named in <member LOID> or <member path> from the Collection named in <Collection LOID> or <Collection path>.
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_query_collection
[-v]
{-l <Collection LOID> | -c <Collection path>}
<query>
This command searches for information of the Collection object named in <Collection LOID> or <Collection path>. The format of the <query> string is described in the paper "Constructing Distributed Schedulers Using the MESSIAHS Interface Language," by Steve J. Chapin and Eugene H. Spafford.
Examples of query strings are:
The following option is available:
The example below uses the default Collection (found in the /etc context), would be:
$ legion_query_collection -c /etc/Collection true 2 hits: 1.36ab9e4a.03.01000000.000001fc099204... 1.36ab9e4a.07.01000000.000001fc0d6e07... $
The output shows that there are two objects in the Collection, the bootstrap host and the bootstrap vault.
legion_set_default_placement
{-l <class LOID> | -c <class context name>}
{-l <host LOID> | -c <host context name>}
{-l <vault LOID> | -c <vault context name>}
Sets the default placement for objects of the class named in <class LOID> or <class context name> to the given host/vault pair. Default placement is used when a class has no associated Scheduler object or cannot contact its associated Scheduler object. When a default placement is set the user should take care to ensure that an implementation for the default placement host's architecture is available.
legion_set_scheduler
{-l <class LOID> | -c <class context path>}
{-l <Scheduler LOID> | -c <Scheduler context path>}
This commands sets the Scheduler named in <Scheduler LOID> or <Scheduler context path> for the class named in <class LOID> or <class context path>. This will be the default scheduler for that class. The class will then use the scheduler to determine which hosts and vaults should manage its instances (i.e., determine placements for the class's instances).
legion_set_scheduler_policy
{-l <class LOID> | -c <class context path>}
<policy>
This command can be used to set a class object's policy for using its default scheduler. See also legion_set_scheduler.
The legal values for <policy> are:
legion_set_varch
{-l <host LOID> | -c <host context path>} <arch>
Set a virtual host object's architecture. A virtual host object lives on host A (the physical host) but actually represents host B (the virtual host). If the legion_set_varch command is not run, Legion will assume that the virtual host object's architecture is the same as its physical host.
legion_set_vrun
{-l <host LOID> | -c <host context path>} <path>
This command configures a virtual host object. A virtual host object lives on host A (the physical host) but actually represents host B (the virtual host). Running this command indicates where the physical host can find scripts for starting and managing jobs on the virtual host. The <path> parameter is the local path for those scripts.
To configure a T3E virtual host object, you could run something like this:
$ legion_set_vrun -c /hosts/my_T3E $LEGION/src/T3E/SDSC
This tells Legion that the scripts are in $LEGION/src/T3E/SDSC.
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 use the vault's LOID (with the -l flag) you must use the hosts' LOIDs.
legion_check_system
[-help] [-v] [-q] [-fix CommandLine | -fix Contexts]
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 any warnings and errors in your system.
The following options are supported:
You can use a -fix flag to specify that offending command-line and/or context objects be reported and destroyed (you may use both -fix flags to specify that both types of offending objects be removed). The example here uses both flags and shows the discovery and removal of a bad context object:
$ legion_check_system -v -fix CommandLine -fix Contexts Checking UnixHostClass status Checking UnixVaultClass status Checking UnixImplementationCacheClass status Checking ContextClass status Checking CommandLineClass status Determining root context Checking root context status Checking current context status Validating the integrity of the class hierarchy legion_check_system: error, object in "error" state: 1.3746b561.06.b6f4d579.000001fc0b3af9621e5b883eee4cd21b 415bd3828bc4dcd9ec09b4667dbf989a1b6f7d4c44d77f650dd125b 581028fc5805e0176d69bd60beed84e55555fef2cf6031fa7. fix specified, destroying object - say good-bye [etc.] $
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>. This may include each object's LOID, status, and its owner's LOID and OA.
legion_version
Prints your Legion version number. For example, the output below indicates that the current system is University of Virginia Legion version 1.5.9.
$ legion_version VaL Legion version 1.5.9 $
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
legion_whereis
{-l <object LOID> | -c <object context path>}
This command returns a specified object's host and vault object. That is, the output gives the context path of the host and vault objects where the object and the object's persistent state are located. If the host or vault objects have been assigned aliases Legion will randomly return one of the context paths. Your output will look something like this:
$ legion_whereis -c Foo Host : /hosts/BootstrapHost Vault : /vaults/BootstrapVault $
This example looks up the location of object Foo. The output shows that the object is located on BootstrapHost and its persistent state is on BootstrapVault.
legion_whoami
You can use this command to find out which user id you are currently logged in with. Your output will look something like this:
$ legion_whoami /users/nemo $
This means that you are logged in as user nemo.
legion_add_acl
[-l <object LOID> | -c <object context name>] {-s | <filename>}
Adds an access control list to the object named in <object LOID> or <object context path> or, if no object is named, the current environment. This command resembles legion_set_acl, but it merges in a new access control list. For example, if the current access control set contains access control lists for methods A and B of class XYZ's instances, adding new access control lists for class XYZ's methods B and C will not change A, replace B, and add C.
The following options are supported:
legion_add_implicit_params
[-l <AuthenticationObject LOID> | -c <AuthenticationObject context path>]
{-s | <filename>}
Add an implicit parameter to the AuthenticationObject named in <AuthenticationObject LOID> or <AuthenticationObject context path> or, if no AuthenticationObject is named, the current environment. The arguments take the same input format as legion_set_implicit_params. New parameters merge into the existing implicit parameter set (i.e., new parameters override old ones of the same name). There is no way to remove or unset selected implicit parameters.
The following option is supported:
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. This command currently works only on unclaimed objects: if an object is already owned you would have to 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.
$ legion_change_permissions +r /users/bob 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_create_user_object
{-l <class LOID> | -c <class context path>}
[-h <host for new object> | -v <vault for new object>]
[-z <password>] <user name>
Creates a new object to represent a new Legion user id. The new object can be an instance of the AuthenticationObjectClass or another class that implements AuthenticationObjects.
The following options are supported:
| -h <host for new object> | Specify where the new object should be created. |