5.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 pages; and the Legion web site has on-line tutorials and a quick guide to all commands (<http://legion.virginia.edu/documentation.html>). Finally, you can type
$ <command name> -help
to see a command's full usage.
Please note that the sample outputs in this section may not match your own. Your system administrator may have customized your system's context space or limited what parts you can see. If you think there's something wrong, please consult your system administrator.
5.1 Viewing contexts
5.1.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:
$ legion_ls /
To view subcontexts, use a context as an argument:
$ legion_ls /hosts
There are several flags for this command, not all of which will be discussed here (see page 26 in the Reference Manual for a discussion of all legion_ls flags).
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 /
Foofile 43 bytes
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 /
You can use this command to get specific information about an individual object by using the object's context name as an argument.
5.1.2 Looking up LOIDs
You can look up LOIDs with legion_ls and the -L flag. The -L flag will lists LOIDs associated with the context's entries. The output will be a "dotted hex" LOID.
$ legion_ls -L /
You can look up an individual object's LOID by using its context name as a parameter.
$ legion_ls -L /hosts/BootstrapHost
5.1.3 Create a new context
You can create new contexts with the legion_context_create command. It is similar to the Unix mkdir command. If you do not specify a path, the new context will be placed in the current context.
$ legion_context_create /tmp
5.1.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
5.1.5 Verify the current working context
You can use the legion_pwd command (similar to Unix pwd) to verify your current working context. The sample below indicates that we are in the /tmp context.
5.2.1 Alternate names for 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
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
$ legion_ls -L /hosts/BootstrapHost
Either name can be used to manipulate the object.
5.2.2 Assigning a context name to a LOID
The legion_context_add command maps a new context name to a LOID. 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.38e67781.07.01000000.000001fc0
5.2.3 Renaming an object
An object can be renamed with the legion_mv command (similar to the Unix mv command). The object's LOID and physical location is not changed. In the example below, the object that was named Foo is now named Bar.
$ legion_mv Foo Bar
The name Foo is automatically removed. This process only affects the object in this specific context path: any other use of the name Foo, whether in this user's or any other user's context space, will be unchanged.
5.2.4 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...
If you already know an object's name, you can 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 /hosts/BootstrapHost
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
5.2.5 Removing names and objects
You can remove (i.e., destroy) context names and objects with legion_rm. 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 removes a context and all of its contents.
5.2.6 Using the same name in different contexts
As discussed in section 4.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
5.3 Moving between local files and contexts
5.3.1 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.
5.3.2 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.
5.3.3 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.
5.3.4 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 25 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"
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 /
nothing 43 bytes
nothing2 46 bytes
nothing3 46 bytes
$ legion_ls -la /nextlevel
nextnothing3 46 bytes
nextnothing2 46 bytes
nextnothing 43 bytes
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.
5.3.5 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:
Verbose mode. Prints information about which files and directories the command is currently exporting.
Specify the context path of the file object class. 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.
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.
Catch and print Legion exceptions.
Print command syntax and exit.