Legion 1.2
Basic User Manual

Appendices

A-4.0 Alphabetical list of Legion commands

Full documentation of these commands can be found in the Reference Manual, in "Command-line functions". There are also man pages for all Legion commands included in the system release package, and on-line tutorials on the Legion web site (http://legion.virginia.edu/Documentation.html).

legion_activate_instances {-l <class LOID> | -c <class context path>}

legion_activate_object {-l <object LOID> | -c <context path>}

legion_add_class_mapping <metaclass LOID> <class LOID>

legion_bfs <file> [-o <out file>] [-BackEnd]

legion_cat <context path>

legion_class_host_list [-l <class LOID> | -c <class context path>] [{-a | -d} <host name>] [-p] [-u]

legion_class_vault_list [-l <class LOID> | -c <class context path&g [{-a | -d} <vault name>] [-p] [-u]

legion_classof {-l <object LOID> | -c <context path>}

legion_context_add <object LOID> <context name>

legion_context_create <context path>

legion_context_list [<context path>]

legion_context_lookup <context path>

legion_context_remove <context path>

legion_cp [-localsource | -localdest] <source file> <destination file>

legion_create_class [-c < context path>]

legion_create_implementation <binary path name> <architecture> [-l <class LOID> | -c <context path>]

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

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

legion_create_stat_tree <base context path>

legion_create_user <user id>

legion_deactivate_instances {-l <class LOID> | -c <class context path>}

legion_deactivate_object {-l <object LOID> | -c <context path>}

legion_destroy_instances {-l <class LOID> | -c <class context path>}

legion_destroy_object {-l <object LOID> | -c <context path>}

legion_direct_output {-l <LOID> | -c <object path>} {-c <tty path> | -l <tty LOID>}

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

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

legion_get_acl [-l <LOID> | -c <context>]

legion_get_candidate_hosts {-c <object context path> | -l <object LOID>}

legion_get_candidate_placements {-l <class LOID> <instance LOID>} | {-c <class context path> <instance context path>} [<max placements>]

legion_get_candidate_vaults {-l <object LOID> | -c <object context path>}

legion_get_host {-l <object LOID> | -c <object context path>}

legion_get_implicit_params [-l <LOID> | -c <context path>]

legion_get_interface {-l <class LOID> | -c <context path>}

legion_get_vault {-l <object LOID> | -c <object context path>}

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

legion_host_vault_list {-l <host LOID> | -c <host context path>] [{-a | -d} <vault name>] [-p] [-u]

legion_import_tree [<unix directory path> [<legion context path>]]

legion_init_arch

legion_initialize

legion_instance_host_list {-l <LOID> | -c <context path>} [{-a | -d} <host name>] [-p] [-u]

legion_java <java options>

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

legion_list_instances {-l <class LOID> | -c <context path>}

legion_list_objects {-l <host LOID> | -c <host context path>}

legion_ln <context path> <new alias>

legion_login [-l <user LOID> | <user id>] [-e <command>]

legion_ls [-lLa] <context path>

legion_mplc

legion_mpi_debug [-q] {-c <instance context path>}

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

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

legion_mv <context path> <new context path>

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

legion_ping {-l <object LOID> | -c <context path>}

legion_print_config

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

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

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

legion_rm [-deactivate | -destroy] <context path>

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

legion_set_acl {-l <object LOID> | -c <object context path>]} [-s | filename]

legion_set_context <context path>

legion_set_host {-l <object LOID> | -c <object context path} [{-l <host LOID> | -c <host context path>}

legion_set_implicit_params {-l <object LOID> | -c <object context path>} [-s | filename]

legion_set_tty <tty context path>

legion_set_vault {-l <object LOID> | -c <object context path} [{-l <vault LOID> | -c <vault context path>}

legion_setup_state [-i]

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

legion_shutdown_class {-l <class LOID> | -c <context path>}

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

legion_startup [-local]

legion_startvault [-L <$LEGION>] [-O <$LEGION_OPR>] [-A <$LEGION_ARCH>] [-N <context name>] [-U <user id&g {<host name>} [<compatible host list>]

legion_tty_redirect <context path>

legion_tty_unredirect <context path>

legion_tty_watch {-l <tty LOID> | -c <tty context path>}

legion_update_attributes {-l <object LOID> | -c <context path>} [{-a | -d | -t} <attribute description>] [-u]

legion_vault_host_list {-l <vault LOID> | -c <vault context path>} [{-a | -d} <host name>] [-p] [-u]

legion_wellknown_class <wellknown class name>

A-5.0 Subject listing of Legion commands

Full documentation of these commands can be found in the Reference Manual, in "Command-line functions". There are also man pages for all Legion commands included in the system release package, and on-line tutorials on the Legion web site (http://legion.virginia.edu/Documentation.html).

A-5.1 Calls on Objects

legion_exports_interface {-l <LOID> | -c <context path>}

{-w <well known class type> | -f <function signature>}+

legion_get_interface {-l <class LOID> | -c <context path>}

legion_ping {-l <object LOID> | -c <context path>}

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

legion_update_attributes {-l <object LOID> | -c <context path>} [{-a | -d | -t} <attribute description>] [-u]

A-5.2 Calls on Class Objects

legion_activate_object {-l <object LOID> | -c <context path>}

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

legion_create_object_r {-l <class LOID> | -c <class context pa <context path> <host name> <host architecture> <$LEGION> <$LEGION_OPR> <$LEGION_OPA> <binary path> [<user id>]

legion_deactivate_object {-l <object LOID> | -c <context path>}

legion_destroy_object {-l <object LOID> | -c <context path>}

legion_list_instances {-l <class LOID> | -c <context path>}

legion_get_host {-l <object LOID> | -c <object context path>}

legion_get_vault {-l <object LOID> | -c <object context path>}

legion_set_host {-l <object LOID> | -c <object context path} {-l <host LOID> | -c <host context path>}

legion_set_vault {-l <object LOID> | -c <object context path} {-l <vault LOID> | -c <vault context path>}

A-5.3 Calls on LegionClass

legion_add_class_mapping <metaclass LOID> <class LOID>

legion_create_implementation <binary path name> <architecture> [-l <class LOID> | -c <context path>]

legion_init_arch

A-5.4 Calls on File and Context Objects

legion_activate_instances {-l <class LOID> | -c <class context path>}

legion_cat <context path>

legion_context_add <object LOID> <context name>

legion_context_create <context path>

legion_context_list [<context path>]

legion_context_lookup <context path>

legion_context_remove <context path>

legion_cp [-localsource | -localdest] <source file> <destination file>

legion_deactivate_instances {-l <class LOID> | -c <class context path>}

legion_destroy_instances {-l <class LOID> | -c <class context path>}

legion_direct_output {-l <LOID> | -c <object path>} {-l <tty LOID> | -c <tty path>}

legion_get_host {-l <object LOID> | -c <object context path>}

legion_get_vault {-l <object LOID> | -c <object context path>}

legion_import_tree [<unix directory path> [<legion context path>]]

legion_ln <context path> <new alias>

legion_ls [-lLa] <context path>

legion_mv <context path> <new context path>

legion_rm [-deactivate | -destroy] <context path>

legion_set_context <context path>

legion_set_tty <tty context path>

legion_tty_redirect <context path>

legion_tty_unredirect <context path>

legion_tty_watch {-l <tty LOID> | -c <tty context path>}

A-5.5 Start-Up and Shutdown Functions

legion_create_class [-c < context path>]

legion_initialize

legion_print_config

legion_setup_state [-i]

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

legion_shutdown_class {-l <class LOID> | -c <context path>}

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

legion_startup [-local]

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

A-5.6 Scheduling Support

legion_class_host_list [-l <class LOID> | -c <class context path>]
     [{-a | -d} <host name>] [-p] [-u]

legion_class_vault_list [-l {<class LOID> | -c <class context path>} [{-a | -d} <vault name>] [-p] [-u]

legion_get_candidate_hosts {-l <object LOID> | -c <object context path>}

legion_get_candidate_placements {-l <class LOID> <instance LOID>} | {-c <class context path> <instance context path>} [<max placements>]

legion_get_candidate_vaults {-l <object LOID> | -c <object context path>}

legion_host_vault_list {-l <host LOID> | -c <host context path> [{-a | -d} <vault name>] [-p] [-u]

legion_instance_host_list {-l <LOID> | -c <context path>} [{-a | -d} <host name>] [-p] [-u]

legion_vault_host_list {-l <vault LOID> | -c <vault context path>} [{-a | -d} <host name>] [-p] [-u]

A-5.7 General Functions About the State of the System

legion_classof {-l <object LOID> | -c <context path>}

legion_create_stat_tree <base context path>

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

legion_list_objects {-l <host LOID> | -c <host context path>}

legion_wellknown_class <wellknown class name>

A-5.8 Security

legion_create_user <user id>

legion_get_acl [-l <LOID> | -c <context>]

legion_get_implicit_params [-l <LOID> | -c <context>]

legion_login [-l <user LOID> | <user id>] [-e <command>]

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

legion_set_acl {-l <object LOID> | -c <object context path>}

[-s | filename]

legion_set_implicit_params {-l <object LOID> | -c <object context path>} [-s | filename]

A-5.9 Application Development

legion_bfs <file> [-o <out file>] [-BackEnd]

legion_mplc

legion_java <java options>

A-5.10 Program Support

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

legion_mpi_debug [-q] {-c <instance context path>}

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

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

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

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

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

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

A-6.0 More information on adding host and vault objects

A-6.1 Adding new hosts

Supported <flags> for legion_starthost are:

-L <$LEGION>		Specify $LEGION for the new host (default is "/home/xxxx/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/<new host name>")
-U <user id>		Specify a Unix user id for host (default is current Unix user id)
-C <host class>		Specify the context path of the host class (default is "/class/UnixHostClass")

This command first creates a new host object on the specified <new host name> (the host's DNS name). It selects the following additional default values for the new object:

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

An OPA (Object Persistent representation Address) is used to track a specific OPR (Object Persistent Representation, the inert state of an object): in this case, the OPA will represent the persistent state of the new host object. The binary path is the binary path of the program that will be run on the new host in order to start the new host object. Currently, this path can be altered only by editing the legion_start source file, in the $LEGION/src/CoreObjects/ClassObjects/rshStartClassObject directory.

These flags and defaults need to be carefully considered when adding new hosts and vaults to your system. If the new host has a different architecture or a different directory structure, use the -A, -L, or -O flags to specify these parameters. The -U flag allows you to specify a Unix user id for the new object, so that a system administrator can add host objects to another user on the same Unix system. This can be useful should you wish to create a guest user id that has limited access privileges to the new host. The -C flag allows you to start an instance of a different class, so that users can create new host classes and have more flexibility in managing their resources. (Legion currently comes with only one host class, UnixHostClass, but users can add more host classes as necessary, either by creating instances of the UnixHostClass or by writing new classes.)

If the new host object's architecture is not the same as the current host object's architecture, you should run the legion_init_arch tool in order to create implementation objects to match the new architecture (see section 9.0 of the System Administrator Manual, for information about implementations, and section 9.2 of the System Administrator Manual, for information about running legion_init_arch).

A-6.2Adding new vaults

Supported <flags> for legion_startvault are:

-L <$LEGION>		Specify $LEGION for the vaults host (default is "/home/Legion")
-O <$LEGION_OPR>	Specify $LEGION_OPR for the vault's (default is "/home/OPR")
-A <$LEGION_ARCH>	Specify the architecture of the vault's 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 a Unix user id (default is current Unix user id)
-C <vault class>	Specify the context path of the vault class (default is "/class/UnixVaultClass")

This commands creates a new vault object on the storage system of a specified host (named in <host name>). The flags are similar to the legion_starthost flags. The -L, -O, or -A flags can be used to specify a different architecture or a different directory structure. The -N flag allows you to specify a context name. The -U flag allows you to specify a Unix user id for the new object, so that a system administrator (or anyone with root privileges) can add vault objects to another user on the same Unix system. This can be useful should you wish to create a guest user id that has limited access privileges to the new host. The -C flag allows you to start an instance of a different class. That is, if you do not use this flag, the new host object will be an instance of class UnixVaultClass. This flag allows users to create new vault classes, so as to give users more flexibility in managing their resources.

A-6.3 Manipulating host-vault pairing

The legion_host_vault_list command will list a host object's list of compatible vaults. The example below lists the compatible vaults for the BootstrapHost. Note the -p flag, which signals that the list should be printed out.

$ legion_host_vault_list -c hosts/BootstrapHost -p
** COMPATIBLE VAULT LISTING:
**      1.01.03.3cb53908.000001fc0bb4fef12ecf6cc...
**      1.01.03.3db53908.000001fc0dd5621fadf70b0...
**      1.01.03.3eb53908.000001fc0d6e9041e262126...
$

There are three vaults listed here: if you are not sure what the context names of these vaults are, use the legion_context_lookup command.

To view the list of a vault's compatible hosts, use legion_vault_host_list. The example on the next page asks for the list of BootstrapVault's compatible hosts.

$ legion_vault_host_list -c vaults/BootstrapVault -p
** COMPATIBLE HOST LISTING: 
**      1.01.07.3cb53908.000001fc0c29636eee98d...
**      1.01.07.3eb53908.000001fc0d9b155044fb5...
$

There are two hosts listed here, BootstrapHost and aNewHost.

Both of these commands can add and delete hosts or vaults from the list with specific flags (-a and -d, respectively). For example, to remove aNewVault from BootstrapHost's list of acceptable vaults, you would enter the following:

$ legion_host_vault_list -c hosts/BootstrapHost -d vaults/aNewVault -p
Deleted 1 vault(s) to host's compatibility set
** COMPATIBLE VAULT LISTING: 
**      1.01.03.3cb53908.000001fc0bb4fef12ecf6cc...
**      1.01.03.3db53908.000001fc0dd5621fadf70b0...
$

The next example adds a host to BootstrapVault's list of compatible hosts.

$ legion_vault_host_list -c vaults/BootstrapVault -a hosts/AnotherHost -p
Added 1 host(s) to vault's compatibility set
** COMPATIBLE HOST LISTING: 
**      1.01.07.3cb53908.000001fc0c29636eee98d...
**      1.01.07.3eb53908.000001fc0d9b155044fb5...
**      1.01.07.3fb53908.000001fc0c96beaba5730...
$

Back to Basic User Manual Table of Contents