Legion 1.2
Basic User Manual

5.0 Working in context space

As in Unix space, users move around context space with command-line utilities, or commands. The remainder of this document discusses the basic tools for manipulating context space. Most of these tools are similar to Unix commands, in the hopes that users will be able to understand and use them more easily. There are a variety of resources available for learning The Reference Manual lists all commands and instructions for using them, and man pages for all commands are included in new Legion systems (ask your system administrator if you are unsure how to use man pages). The Legion web site has on-line tutorials and postscript documents that provide information about context space and legion commands (http://legion.virginia.edu). In this manual, an alphabetical list of all commands and their syntax is in the "Alphabetical list of Legion commands" and a subject list is in the "Subject listing of Legion commands."

5.1 View a context's contents

Just as the ls command in Unix allows users to view the files located in a particular directory, the legion_context_list command shows all objects contained in a particular context. The root context of a new system will look something like this:

$ legion_context_list
.
class
hosts
vaults
home
$

But a user logging into a running Legion system might see something like this in his or her home context:

$ legion_context_list
.
class
hosts
vaults
home
Foofile
Fooclass
Fooobject
$

To view sub-contexts (similar to sub-directories), the name of a context1 is used an as argument:

$ legion_context_list /hosts
.
..
BootstrapHost
your.host.DNS.name
$

The legion_ls command will also list the contents of a context. It is similar to the legion_context_list command, but it can return more specific information. When used without flags, the command will only list the contexts and file objects contained in the current context.

$ legion_ls
.
class
hosts
vaults
home
Foofile
$

There are three optional flags, which will return varying levels of detail. The -a flag will list all objects contained in the context.

$ legion_ls -a
.
class
hosts
vaults
home
Foofile
Fooclass
Fooobject
$

The -l flag includes objects' type. File objects return their file size. Notice that when used without the -a flag it returns only contexts and file objects.

$ legion_ls -l
.                             (context)
class                         (context)
hosts                         (context)
vaults                        (context)
home                          (context)
Foofile                        43 bytes
$

$ legion_ls -la
.                             (context)
class                         (context)
hosts                         (context)
vaults                        (context)
home                          (context)
Foofile                        43 bytes
Fooclass                        (class)
Fooobject
$

The -L flag will list the LOIDs associated with the objects contained in the current context. Notice that, again, it lists only contexts and file objects in the context:

$ legion_ls -L
. 1.01.05.01000000.00000...2
class 1.01.05.02000000.00000...
hosts 1.01.05.03000000.00000...
vaults 1.01.05.04000000.00000...
home 1.01.05.05000000.00000...
Foofile 1.01.66000000.02000000.00000...
$

As with legion_context_list, this command can be used with path names to list the contents of sub-contexts.

$ legion_ls -la /class
.                             (context)
..                            (context)
LegionClass                     (class)
VanillaMetaClass                (class)
BootstrapMetaClass              (class)
BasicFileClass                  (class)
ttyObjectClass                  (class)
JobProxyClass                   (class)
BatchQueueMetaClass             (class)
StatTreeClass                   (class)
AuthenticationObjectClass       (class)
UnixHostClass                   (class)
UnixVaultClass                  (class)
BindingAgentClass               (class)
CommandLineClass                (class)
ContextClass                    (class)
UnixImplementationClass         (class)
UnixImplementationCacheClass    (class)
StatelessProxyMetaClass         (class)
StatelessClasses              (context)
$

5.2 Looking up an object's LOID

Users can look up the LOID associated with an object named in a context by using the legion_context_lookup command. The output will be a "dotted hex" LOID. Usage of this command requires including the object's context space name (its context path) as a parameter.

$ legion_context_lookup /hosts/BootstrapHost
1.01.07.01000000.000001fc0a8e60138a9...
$

5.3 Create a new context

New contexts can be created with the legion_context_create command. This is similar to the Unix mkdir command. Note that the output includes the new context's location and its LOID.

$ legion_context_create /tmp
Creating context "tmp" in parent "/".
New context LOID = "1.01.05.07000000.000001fc0d02..."
$

5.4 Changing the working context

The legion_set_context command will change the current working context, as can be seen in the following example.

$ legion_set_context /tmp

The sub-context tmp is now the current working context. Note that this command sets an environment variable in the shell in which it has been invoked. The command is implemented as an alias (as supported by your shell) that sources the script legion_set_context.sh.

5.5 Assigning alternate names to existing contexts

Users can create alternate names for objects with legion_ln, a command similar to the Unix ln command. Note that it works only with objects that already have a context name. If no context name has been assigned, you will need to use a different command (such as legion_context_add: see "Assigning a context name to a LOID") to assign a name to assign a name to the LOID.

Here the new name Foo is assigned to the BootstrapHost object and placed in the current working context (rather than the hosts context, where the object's original context name BootstrapHost is located).

$ legion_ln /hosts/BootstrapHost Foo

$ legion_ls -la
.                             (context)
..                            (context)
Foo                                    
$

An object's alternate context names can be in different contexts: BootstrapHost is in the hosts context, and Foo is in the current context. Both names refer to the same LOID and either one can be used to control the object.

$ legion_context_lookup Foo
1.01.07.01000000.000001fc0a8e60138a9...
$

$ legion_context_lookup /hosts/BootstrapHost
1.01.07.01000000.000001fc0a8e60138a9...
$

5.6 Assigning a context name to a LOID

The legion_context_add command maps an object's LOID to a context name. It can be used to assign a name to a previously unnamed object or to assign an extra name to a previously named object. Either way you need to provide the object's full LOID as an argument.

In the example below, the name newName is assigned to a LOID.

$ legion_context_add 1.01.66000000.05... newName

5.7 Renaming an object

An object can be renamed with the legion_mv command (similar to the Unix mv command). In the example below, object Foo is renamed Bar.

$ legion_mv Foo Bar

The name Foo is automatically removed from the current context. This process affects only a specific context path: any other use of the name Foo, whether somewhere else in this user's or any other user's context space, will be unchanged.

5.8 Removing names

Users can remove context names with either legion_rm or legion_context_remove.

$ legion_rm Bar

or

$ legion_context_remove Bar

Neither of these commands, as used in these two examples, will affect the associated object: removing a context name does not destroy the object. If you wish to destroy or deactivate the object use the legion_rm command with, respectively, the -destroy or -deactivate flags.

The legion_destroy_object command, on the other hand, destroys the object but not its context name(s). This command should therefore not be used with objects that have context names, unless the names are then removed with either legion_rm or legion_context_remove.

5.9 Using the same name in different contexts

As discussed in "Organizing context space," the same context name can be used to refer to different Legion objects. For example, the name Foo can be assigned to two different objects in two different contexts, the current working context and the tmp context.

The name Foo is assigned to an object in the current context, with the legion_ln command.

$ legion_ln 1.01.05.6e0c2... Foo

The same name, in the tmp context, is then assigned to a different object.

$ legion_ln 1.01.66000... /tmp/Foo

Alternatively, the same name can be used in different context paths to refer to the same object:

$ legion_ln 1.01.05.6e0c2... Foo
$ legion_ln 1.01.05.6e0c2... /tmp/Foo

5.10 Copying a local file to a Legion file object

The contents of a local file can be copied to a new Legion file object with the legion_cp command. The example below copies the contents of a local Unix file, UnixTextFile.txt, to a new Legion file object, called newFileObject, in the current working context.

$ legion_cp -localsource UnixTextFile.txt newFileObject

The -localsource flag indicates that UnixTextFile.txt can be found in the local file system.

5.11 Copying a Legion file object

Use the legion_cp command to copy of a file object.

$ legion_cp newFileObject newFileObject_copy

The -localdest flag will copy the contents of a Legion file object to a new file in the local file system.

$ legion_cp -localdest newFileObject anotherTextFile.txt

5.12 Viewing a file object's contents

Users can view the contents of a Legion file object with the legion_cat command, similar to the Unix cat command. The contents are printed to standard output.

$ legion_cat newFileObject
This is a test, just a test, nothing more.
$

5.13 Importing a local Unix directory tree

The contents of a local directory tree can be copied from local file space into context space with the legion_import_tree command. The contents of Unix binary files will automatically be copied into new Legion file objects. In the example below, the contents of the Unix directory legion.practice will be copied into the current Legion context. A listing of the Unix directory's contents shows that the directory contains one sub-directory and three files. The subdirectory nextlevel also contains three files.

$ ls -Fa legion.practice
./	../	nextlevel/	nothing	nothing2	nothing3
$ ls -Fa legion.practice/nextlevel
./	../	nextnothing	nextnothing2	nextnothing3
$

The default values of legion_import_tree are the current Unix directory and the current Legion context (in this case, the home context "."), but users can specify the directory path and/or the context (see the Reference Manual for full usage).

$ legion_import_tree legion.practice 
Making legion context "./nextlevel”
Creating context "nextlevel" in parent ".".
New context LOID = "1.01.05.47b53908.000001fc0c01650..."
Copying contents of "legion.practice/nextlevel" into "./nextlevel"
Copying unix file "legion.practice/nextlevel/nextnothing" to legion file "./nextlevel/nextnothing"
Copying unix file "legion.practice/nextlevel/nextnothing2" to legion file "./nextlevel/nextnothing2"
Copying unix file "legion.practice/nextlevel/nextnothing3" to legion file "./nextlevel/nextnothing3"
Copying unix file "legion.practice/nothing" to legion file "./nothing"
Copying unix file "legion.practice/nothing2" to legion file "./nothing2"
Copying unix file "legion.practice/nothing3" to legion file "./nothing3"
$

Note that Legion copied the contents of the nextlevel subdirectory into a new sub-context called nextlevel:

$ legion_ls -la
.                             (context)
class                         (context)
hosts                         (context)
vaults                        (context)
home                          (context)
nextlevel                     (context)
nothing                        43 bytes
nothing2                       46 bytes
nothing3                       46 bytes

$ legion_ls -la /nextlevel
nextnothing3                   46 bytes
nextnothing2                   46 bytes
nextnothing                    43 bytes
..                            (context)
.                             (context)
$

The legion_cat command shows that the new file objects contain the same information as the Unix files:

$ cat legion.practice/nextlevel/nextnothing3
3: This is a test, just a test, nothing more.
$

$ legion_cat /nextlevel/nextnothing3
3: This is a test, just a test, nothing more.
$

1. Full path syntax can be used as well as relative path syntax in all Legion commands.Back

2. In this and some of the following examples the entire LOID is not reproduced, in the interests of space and readability.Back


Back to Getting Started sectional index

Back to Basic User Manual Table of Contents