Tutorial:
Legion 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
     Assigning alternate names to existing context names
     Renaming an object
     Removing names
     Assigning a context to a LOID
     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.0
Legion host and vault objects
How to start remote programs in Legion
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 three 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 three basic sub-contexts, called class, hosts, and vaults. 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.

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 (this object was automatically installed on the bootstrap host when the system was configured).

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. Note that 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
$
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
aFile
anotherFile
ttyObject
$
To view sub-contexts (similar to sub-directories), the name of a context is used an as argument. 1
$ 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
aFile
anotherFile
$
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
aFile
anotherFile
ttyObject
$
The -l flag will include the object's type. File objects return their file size. Notice that this flag does not return all objects in the context. You would need to include the -a flag to see the ttyObject in the list.
$ legion_ls -l 
.                             (context)
class                         (context)
hosts                         (context)
vaults                        (context)
aFile                          43 bytes
anotherFile                    46 bytes
$
The -L flag will list the LOIDs2 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.680c2608.000001fc0b5...
class 1.01.05.690c2608.000001fc0b745...
hosts 1.01.05.6a0c2608.000001fc0b8b2100...
vaults 1.01.05.6b0c2608.000001fc0d8b895bd9d3...
aFile 1.01.66000000.02000000.000001fc0e28dd8...
anotherFile 1.01.66000000.03000000.000001fc0...
$
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)
StatTreeClass                   (class)
UnixHostClass                   (class)
UnixVaultClass                  (class)
BindingAgentClass               (class)
CommandLineClass                (class)
ContextClass                    (class)
UnixImplementationClass         (class)
UnixImplementationCacheClass    (class)
$

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. In this case, there are no objects contained in the 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.
$ legion_set_context /tmp
The sub-context tmp is now the current working context.
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 below) to assign a name to the LOID.

In the example below, the new name Foo is assigned to the BootstrapHost object, then the legion_ls command is used to verify that the new name has been created.

$ legion_ln /hosts/BootstrapHost Foo

$ legion_ls -la
.                             (context)
..                            (context)
Foo                                    
$
Note that the same object can be named in different contexts: BootstrapHost is in the hosts context, and Foo is in the current context. Both names refer to the same LOID, however, 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...
$

Renaming an object
An object can be renamed with the legion_mv command. This is similar to the Unix mv command. In this example, object Foo is renamed Bar. The name Foo is automatically removed from the user's context space. (Note that if another user has assigned the same object the name Foo, or if the name has exists in another part of this users's context space, the other name will be unaffected.)
$ legion_mv Foo Bar

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

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
This command will not destroy the associated object, however. If you wish to destroy or deactivate the object, use the legion_rm command with either the -destroy or -deactivate flags. If used with no flags, the command will destroy only the context name.

The legion_destroy_object command, on the other hand, will destroy the object but not the context name. It should generally not be used with objects that have context names, unless you can then remove all of the object's context names with either legion_rm or legion_context_remove.


Assigning a context to a LOID
Users can also assign names directly to a LOID, with the legion_context_add command.

In the example below, the legion_context_lookup command is used to look up the Foo's LOID, Foo is assigned the additional context name newName and legion_context_list and legion_context_lookup are used to verify that Foo and newName share the same LOID.

$ legion_ls -la
.                      
..                     
Foo                    

$ legion_context_lookup Foo
1.01.66000000.05...

$ legion_context_add 1.01.66000000.05... newName

$ legion_context_list
.
..
Foo
newName

$ legion_context_lookup newName
1.01.66000000.05...
$

Using the same name in different contexts
As with Unix directories, the same context name can be used to refer to different objects in different contexts. To demonstrate this, the name Foo can be assigned to two different objects in two different contexts, the current working context (tmp) and tmp2. Foo was already assigned to an object in the previous section: the steps below will create a new sub-context that is also called Foo.

A new context, called tmp2, is created in the parent context with the legion_context_create command.

$ legion_context_create /tmp2
Creating context "tmp2" in parent "/".
New context LOID = "1.01.05.6d0c2..."
$
The current context is changed to the new tmp2 context:
$ legion_set_context /tmp2
A new context, called Footmp2, and legion_ls is used to verify that the new context has been properly placed:
$ legion_context_create Foo
Creating context "Foo" in parent ".".
New context LOID = "1.01.05.6e0c2..."

$ legion_ls -la
.                             (context)
..                            (context)
Foo                           (context)
$
There are now two different objects which have been given the same name in different contexts, as can be demonstrated with the legion_context_lookup command:
$ legion_context_lookup Foo
1.01.05.6e0c2...

$ legion_context_lookup /tmp/Foo
1.01.66000000...
$

Copying a file object
A Legion file object or a Unix file can be copied to a new, duplicate, Legion file object with the legion_cp command. The example below copies the contents of a Unix file located in the current working directory of our Unix shell and called (logically enough) UnixTextFile, to a new Legion file object called newFileObject. UnixTextFile contains a single line of text:
$ cat UnixTextFile
This is a test, just a test, nothing more.
The -localsource flag will be used to indicate that UnixTextFile can be found in the local file system. The legion_ls command will verify that a new file object has been created.
$ legion_cp -localsource UnixTextFile newFileObject

$ legion_ls -la
.                             (context)
class                         (context)
hosts                         (context)
vaults                        (context)
aFile                          43 bytes
anotherFile                    46 bytes
tty1                                   
tmp                           (context)
tmp2                          (context)
newFileObject                  43 bytes

$
Another flag, -localdest, can be used to indicate that the new file object should be put 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 Legion 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
A local directory tree can be copied from Unix space into context space with the legion_import_tree command. Unix binary files will automatically be copied into 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 contents shows that the directory contains one sub-directory and three files. The subdirectory nextlevel also contains three files.
/legion.practice $ ls -Fa
./	../	nextlevel/	nothing	nothing2	nothing3
$

/legion.practice/nextlevel $ ls -Fa
./	../	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 (click here 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"
$
The legion_ls command can then be used to verify that the new context and file objects were created. Note that Legion copied the contents of the nextlevel subdirectory into a new nextlevel context:
$ legion_ls -la
.                             (context)
class                         (context)
hosts                         (context)
vaults                        (context)
aFile                          43 bytes
anotherFile                    46 bytes
tty1                                   
tmp                           (context)
tmp2                          (context)
newFileObject                  43 bytes
nextlevel                     (context)
nothing                        43 bytes
nothing2                       46 bytes
nothing3                       46 bytes

$ legion_set_context /nextlevel
$ legion_ls -la
nextnothing3                   46 bytes
nextnothing2                   46 bytes
nextnothing                    43 bytes
..                            (context)
.                             (context)
$
We can also use the legion_cat command to verify 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]