6.0 Working in context space

Legion has an assortment of context space command-line utility tools, and this section introduces some basic tools for working with contexts and context space. You'll notice that many resemble Unix commands in both name and purpose, which should make Unix users feel more comfortable. Your local file path will not change as you move through context space. Full path syntax can be used as well as relative path syntax in all Legion commands

There are several other sources of information about Legion context space and commands: an alphabetical list (section A-3.0) and a subject list (section A-4.0) of all commands' syntax are in this manual; the Reference Manual documents all commands; all Legion release packages include man pages1; and the Legion web site has on-line tutorials and a quick guide to all commands (<http://legion.virginia.edu/documentation.html>). Finally, in most cases you can type

$ <command name> -help 

to see a context-related command's full usage.

6.1 View a context's contents

Just as the ls command in Unix lets you view files located in a directory, the legion_ls command shows all objects contained in a context. The root context of a new system will look something like this (your system may look different):

$ legion_ls /
class
home
hosts
impls
vaults
$

To view subcontexts, use a context as an argument:

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

There are several flags for this command, not all of which will be discussed here (see page 22 in the Reference Manual).

You can use the -l and -a flags to get more information about one or more objects. The -l flag displays object type and description.

$ legion_ls -l /
Fooclass	(class)
Foofile		43 bytes
Fooobject	(object)
class		(context)
home	        (context)
hosts		(context)
impls		(context)
vaults		(context)
$

Objects of unknown type will be listed as (object) and faulty objects will be listed as (not available).

The command will not list "hidden" objects, i.e. those objects whose name begin with a "." character (such as "." and "..") unless you use the -a flag.

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

The -L flag will list the LOIDs associated with the context's entries:

$ legion_ls -L /
Fooclass 1.35fe7c3d.07..000001fc0a7838d45ed2
Foofile 1.01.66000000.02000000.00000...
Fooobject 1.35fe7c3d.66000000.01000000.00
class 1.01.05.02000000.00000...
home 1.01.05.05000000.00000...
hosts 1.01.05.03000000.00000...
impls 1.01.05.06000000.0000
vaults 1.01.05.04000000.00000...
$

You can use this command to get specific information about an individual object by using the object's context name as an argument.

6.2 Looking up an object's LOID

You can look up an object's LOID with legion_ls and the -L flag. The output will be a "dotted hex" LOID. You will need to include the object's context space name (its context path) as a parameter.

$ legion_ls -L /hosts/BootstrapHost
1.01.07.01000000.000001fc0a8e60138a9...
$

6.3 Create a new context

You can create new contexts with the legion_context_create command. This is similar to the Unix mkdir command. The output includes the new context's LOID and its parent context.

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

6.4 Changing the working context

The legion_set_context command will change the current working context (it is similar to the Unix cd and chdir commands). It sets an environment variable in the shell in which it has been invoked and is implemented as an alias (as supported by your shell) that sources the script legion_set_context.sh or legion_set_context.csh. The example below sets tmp as the current working context.

$ legion_set_context /tmp

6.5 Checking the current working context

This command is similar to the Unix pwd command. You can use the legion_pwd command to check your current working context. It will print your current context path on the command line. The output below tells you that you are in the tmp context.

$ legion_pwd
/tmp
$

6.6 Assigning alternate names to existing contexts

You 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 a different command, such as legion_context_add (see "Assigning a context name to a LOID"), 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.

$ legion_ln /hosts/BootstrapHost Foo

$ legion_ls
Foo
$

BootstrapHost and Foo have different context paths but both now point to the same object (in this case, the bootstrap host object) and thus to the same LOID:

$ legion_ls -L Foo
1.01.07.01000000.000001fc0a8e60138a9...
$

$ legion_ls -L /hosts/BootstrapHost
1.01.07.01000000.000001fc0a8e60138a9...
$

Either name can be used to manipulate the object.

6.7 Assigning a context name to a LOID

The legion_context_add command maps an object's LOID to a new context name. It can be used to name a previously unnamed object or to assign an extra name to a previously named object. Either way you need to include the object's full LOID as a parameter. In the example below, the name newName is assigned to a LOID.

$ legion_context_add 1.01.66000000.05... newName

6.8 Renaming an object

An object can be renamed with the legion_mv command (similar to the Unix mv command). The object's LOID is not changed, but gets a different context name. In the example below, object Foo is renamed Bar. The name Foo is automatically removed from the current context.

$ legion_mv Foo Bar

This process affects only a specific context path (in this case the working context): if the name Foo is used elsewhere, whether in this user's or any other user's context space, it will be unchanged.

6.9 Listing an object's names

There are two commands that will show an object's context names, legion_list_names and legion_ls.

The legion_list_names command looks up an object's name[s]. If you only know the object's LOID, use it with the -l flag:

$ legion_list_names -l 1.360830b6.07.0100000...
/hosts/BootstrapVault
$

If you already know an object's name you can use the -c flag to see what (if any) other names it has. The example below shows that BootstrapHost has two names, BootstrapHost and my.host.DNS.name:

$ legion_list_names -c /hosts/BootstrapHost
/hosts/BootstrapHost
/hosts/my.host.DNS.name
$

The legion_ls command, used with the -A flag, will also look up an object's name[s]. However, as in previous example, you must use one of the object's context names as an argument:

$ legion_ls -A /hosts/BootstrapHost
/hosts/BootstrapHost
        /hosts/BootstrapHost
        /hosts/my.host.DNS.name
$

6.10 Removing names and objects

You can remove (i.e., destroy) context names and objects with legion_rm. NOTE: If there are no other names assigned to the object, it will be destroyed. If there are other names assigned to the object, legion_rm will just remove the specified name(s). Be sure to check this with either legion_ls or legion_list_names if you are not sure.

For example, if an object has two names, Foo and Foo2, and you remove just the name Foo the object would remain. However, if you then remove Foo2 the object will be destroyed, since there are no other names.

You can use the -v flag to run legion_rm in a verbose setting, which will show you whether objects or just context paths are being destroyed:

$ legion_rm -v foo
Removing context name "foo"
$

$ legion_rm -v foo2
Removing context name "foo2"
Destroying object "foo2" (1.3759173a.690...)
$

If you want to remove an entire context, use the -r flag. It recursively destroys a context and all of its contents.

6.11 Using the same name in different contexts

As discussed in section 5.3, the same context name in different context paths can refer to different Legion objects. Here the name Bar is assigned to object Foo with the legion_ln command. Bar is placed in the current context. The same name, in the tmp context, is then assigned to object Foo2.

$ legion_ln Foo Bar
$ legion_ln Foo2 /tmp/Bar

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

$ legion_ln Foo Bar
$ legion_ln Foo /tmp/Bar

6.12 Copying a local file to a Legion file object

You can copy the contents of a local file to a Legion BasicFileObject with the legion_cp command.

$ legion_cp -localsrc UnixTextFile.txt newFileObject

The -localsrc flag indicates that UnixTextFile.txt can be found in the local file system. Legion first copies the contents of the Unix file UnixTextFile.txt from the local directory to a new Legion BasicFileObject called newFileObject.

Note that if you copy new material into a previously existing BasicFileObject the new material will write over any old material.

6.13 Copying a Legion file object

The legion_cp command will also copy the contents of a BasicFileObject to a new file object.

$ legion_cp Foo Foo_copy

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

$ legion_cp -localdest Foo anotherTextFile.txt

This command only works with BasicFileObjects.

6.14 Viewing a file object's contents

You 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 FileObject
This is a test, just a test, nothing more.
$

Be aware that this command only works with BasicFileObjects. If you try to run it with a class object, for example, you'll get an error:

$ legion_cat /class/UnixHostClass
Can't open "/class/UnixHostClass" for reading.
$

6.15 Importing a local Unix tree

You can copy the contents of a local file tree from your local file space into context space with the legion_import_tree command. The contents of local files will be automatically copied into new Legion BasicFileObjects.

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 tree's contents shows that the tree contains one subdirectory 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 tree and the current Legion context, but you can specify the directory and/or the context paths (see page 21 in 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"
$

Legion copied the contents of the /nextlevel subdirectory into a new context called /nextlevel:

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

$ 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.
$

6.16 Link a directory to context space

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:

-help

Print this help message and exit.

-v

Verbose mode. Prints information about which files and directories the command is currently exporting.

-fc

Specify the context path of the class to use for file objects. This class should be an instance of the metaclass /class/ProxyBindingMetaClass, since the style of file object used by legion_export_dir requires specialized binding services. The default is /class/FileProxyClass.

-cc

Specify the context path of the class to use for context objects. This class should also be an instance of /class/ProxyBindingMetaClass. The default used is /class/ContextProxyClass.

1. Man page usage is man <command name>: ask your system administrator if you are unsure about using man pages on your system. back

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


Back to Basic User Manual Table of Contents
Directory of Legion 1.6 Manuals