Tutorial:
Legion 1.3 Context Space


Table of Contents

  What is context space?
How context space works
Using context space

     View a context's contents
     Looking up an object's LOID
     Create a new context
     Changing the working context
     Checking the current working context
     Assigning alternate names to existing context names
     Assigning a context name to a LOID
     Renaming an object
     Removing names
     Using the same name in different contexts
     Copying a file object
     Viewing the contents of a file object
     Importing a local Unix directory tree

Other relevant on-line documents:
  Starting and shutting down Legion 1.3
Legion host and vault objects
How to start remote programs in Legion
Legion graphical user interface
Legion tty objects
Quick list of all Legion commands
Usage of all Legion commands

The Legion tutorials offer quick and simple instructions for various key procedures for a Legion system. More complete explanations of all of the procedures discussed here are available on separate pages, and can be found by clicking on the icon.

Depending on how your system is set up, you may need to set up your access to your system before you can run Legion commands. This will probably involve running a command such as this:

$ . ~LEGION/setup.sh

or

$ source ~LEGION/setup.csh
The exact syntax will depend on what kind of shell you are using and on where your Legion files are installed. Consult your system administrator for more information.


What is context space?

Context space is a way of organizing Legion space. It is similar to Unix's system of directories and files, but where Unix file names are location specific, context space can be arranged to suit the user's convenience. Contexts are string names assigned to Legion objects, which may be located on a machine hundreds of miles away from the user's machine. The user can assign the object a name (or multiple names) without worrying about the object's physical location. Context space is organized into a series of sub-contexts, similar to Unix directories, and can be assigned mnemonic or logical names as suits the user. A single sub-context can contain context names that refer to objects located on a single machine or separated by large distances.


How context space works

About the LOID

All Legion objects are automatically assigned a unique system-level indentifying name, called a LOID (Legion Object Identifier). The LOID allows the system to find objects scattered on several different machines. Since a LOID consists of several lines of numbers, it can be awkward at best for a user to track objects via their LOIDs. Instead, users can assign a simple string name to a LOID. This name, called a context name, exists only in that user's context space and refers only to a particular LOID. Context names are grouped into contexts and the contexts are organized into a hierarchy of sub-contexts, similar to a Unix directory structure.

These sub-contexts are named and organized by the user, and should be arranged to suit the user's convenience. Each user maintains his or her own context space, and names objects according to his or her own arrangement. Each user's context space is independent of any other user's context space, so different users can assign context names to the same object without interfering with each other.


What am I looking at?

An introduction to hosts and vaults
More about organizing context space
Legion users spend a great deal of time working in context space, so it is important to understand the initial geography of your system's context space and how to negotiate that space. A typical newly installed system has the basic elements of context space: there are four sub-contexts and several starter context names for commonly used objects. Figure 1, below, shows the contents a newly installed Legion system's context space. Note that your system may differ, since a system adminstrator may have already customized your space to take advantage of your system's resources.

To see the contents of your context space, you can use either the legion_context_list or the legion_ls command. The full context path name for BootstrapHost in the system shown in Figure 1 would be /hosts/BootstrapHost.1 For more information on viewing context space and using the other context-related commands, please see "Using context space" (below).

Figure 1: Contents of a typical new Legion system context space

A new Legion system includes four basic sub-contexts, called class, hosts, vaults, and home. These in turn contain context names that refer to the initial contents of a new system: the class sub-context contains context names of particular classes of Legion objects, the hosts sub-context contains names of the host objects currently in your system, and the vaults sub-context contains names of the vault object currently in your system. The home sub-context is initially empty.

When newly installed, hosts contains two names, BootstrapHost and the DNS name of the bootstrap host. (A host is a machine in a Legion system. A vault is a file storage system used to store inactive Legion objects. A host object represents and manages a given host in a Legion system, and a vault object represents and manages a given vault in a Legion system.) Both of these names point to the bootstrap host, which was chosen when the system was configured. On the other hand, vaults contains only one name, BootstrapVault, which points to the bootstrap vault object (click here for information on Legion hosts and vaults).

The newly started class sub-context contains context names for all of the basic Legion object classes, such as BasicFileClass and ttyObjectClass. Note that these classes are themselves objects, even though they are responsible for managing a given set of objects. All Legion objects are organized into classes, and all classes are organized into a hierachy of metaclasses, with LegionClass as the supreme metaclass. Note also that the context space illustrated in Figure 1 does not reflect this heirarchy. This is a key feature of Legion: the physical location and organization of Legion objects is unrelated to any user's context space. The objects named in a host sub-context do not even have to know of each other's existence or even be able to communicate with each other. They do not even have to be hosts: the user can create, delete, and use contexts as he or she chooses.

There are also several binary files which are included with Legion. These files contain programs for running the commands utilities, library functions, and various programs.


Using context space

Like Unix space, users move around context space with command-line utiltities, 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 quickly and painlessly. A complete list and explanation of Legion commands is available here, and a quick list of the commands' syntax is available here. Man pages for all commands are also included in new Legion systems: ask your system adminstrator if you are unsure how to use man pages.

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. A home context of a new system will look something like this:
$ legion_context_list
.
class
hosts
vaults
home
$
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
Foofile
Fooclass
Fooobject
$
To view sub-contexts (similar to sub-directories), the name of a context is used an as argument. 2
$ 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 sub-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 (as the legion_context_list command does). Thus, the next list shows a tty object that had not appeared before.
$ legion_ls -a
.
class
hosts
vaults
Foofile
Fooclass
Fooobject
$
The -l flag will include the object's 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 LOIDs3 associated with the objects contained in the current context. Notice that, again, it will not list all objects in the context.

$ legion_ls -L
. 1.01.05.01000000.00000...
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)
$

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.680c2608.000001fc0c1e0...
$

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.6c0c2608.000001fc0c923..."
$

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.

Checking the current working context

You can use the legion_pwd command to check your current working context. It will print your current context path on the command line. So, for example, the output below tells you that you are in the tmp sub-context.
$ legion_pwd
/tmp
$
This command is similar to the Unix pwd command.

Assigning alternate names to existing context names

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 also below) 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 manipulate the object.
$ legion_context_lookup Foo
1.01.07.680c2608.000001fc0c1e0a395a4...
$

$ legion_context_lookup /hosts/BootstrapHost
1.01.07.680c2608.000001fc0c1e0a395a4...
$

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 context 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.
$ legion_context_add 1.01.66000000.05... newName

Renaming an object

An object can be renamed with the legion_mv command (similar to the Unix mv command). In this example, object Foo is renamed Bar.
$ legion_mv Foo Bar
The name Foo is automatically removed from the user's context space. This process only affects a specific context path: any other use of the name Foo, whether in this user's or any other user's context space, will be unaffected.

Removing names

Users can remove names from context space with either legion_rm or legion_context_remove.
$ legion_rm Bar
or
$ legion_context_remove Bar
Neither of these commands, as used in these 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 either the -destroy or -deactivate flags. The -r flag allows you to recursively destroy or deactivate a sub-context and all of its contents.

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.

Using the same name in different contexts

The same context name can be used to refer to different objects in different contexts. 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.66000000... /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

Copying a 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 newFileObject
The -localsource flag indicates that UnixTextFile.txt can be found in the local file system.

Viewing the contents of a file object

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 a standard output.
$ legion_cat newFileObject
This is a test, just a test, nothing more.
$

Importing a local Unix directory tree

The contents of a local directory tree can be copied from Unix 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 desired directory path and/or context path.
$ 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" "./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 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 nextnothing3
3: This is a test, just a test, nothing more.
$


1. Legion uses a the Unix-style slash ("/") in the default context space path names, so the examples here will follow that style. However, it is possible to change this to the DOS-style backslash ("\") via the primitive context manipulation routines provided by the Legion library.[Back]

2. Full path syntax can be used as well as relative path syntax in all Legion commands. [Back]

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