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 pages1; 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 /
class
home
hosts
impls
vaults
$ 

If you use a context as a parameter, you will see a list of its contents:

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

You can also use wildcards to look for a naming pattern. For example, to look for context names containing "foo" you would enter:

$ legion_ls \*foo\* 

Please note that you must escape the "*" character.

There are several flags for this command (not all of which will be discussed here -- see page 29 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. Objects of unknown type will be listed as (object) and faulty objects will be listed as (not available). The -a flag will list "hidden" objects, i.e. those objects whose name begin with a "." character.

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

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

5.1.2 Look up LOIDs

There are two ways to look up LOIDs, both using legion_ls. The output in both cases will be a "dotted hex" LOID.2 If you want to look up an individual object's LOID, use its context name as a parameter.

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

You can see a group of LOIDs with the -L flag. The -L flag will lists LOIDs associated with the context's entries.

$ legion_ls -L /
Fooclass 1.35fe7c3d.07..000001fc0a7838d45ed
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...
$ 

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 Change 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 Check your current working context

You can use the legion_pwd command (similar to Unix pwd) to verify your current working context.

$ legion_pwd
/tmp
$ 

5.2 Naming objects

5.2.1 Give an object extra context names

You can give an object extra context names with legion_ln (similar to the Unix ln command). Please note that the object must already have a context name. If it doesn't, use legion_context_add to assign it a name (below).

You can place the new name in any context you wish, regardless of where the object's existing name(s) are placed. The example below puts the bootstrap vault object's new name, Foo, in the current working context, even though the object's existing name (/vaults/BootstrapVault) is in the /vaults context.

$ legion_ln /vaults/BootstrapVault Foo

$ legion_ls
Foo
$ 

The two names both point to the same object and thus to the same LOID:

$ legion_ls -L Foo
1.01.07.01000000.000001fc0a1213a4cab754ec019
$

$ legion_ls -L /vaults/BootstrapVault
1.01.07.01000000.000001fc0a1213a4cab754ec019
$ 

Either name can be used to manipulate the object.

5.2.2 Assign 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 use the object's full LOID as a parameter. In the example below, the name neo is assigned to a LOID.

$ legion_context_add 1.3933cb3f.07.01000000.000001fc0a
94f51928f25f57690d7e47fc3f93ff1dc8f5616f1e606def8bb44b
0538a45ffc07f9e1ae612f455e5dbd6cb6bade7105eeebf2c7f061
79b6bbb8826cfdf90f neo 

5.2.3 Change an object's context path

An object can be given a different context path with the legion_mv command (similar to the Unix mv command). For example, to move an object named Foo to the name Bar you would enter:

$ legion_mv Foo Bar 

Whatever object Bar is now pointing to has the same LOID or physical location as before. This command only affects context names. The name Foo is automatically removed from the current context path, but not from any other path. Any other use of the name Foo will be left alone.

5.2.4 List context names

There are two commands that list an object's context names, legion_list_names and legion_ls. Both produce a list of all context names pointing to your object. If you don't know any names but do know the object's LOID, use legion_list_names with the -l flag:

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

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 context names:

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

You can also use legion_ls with the -A flag. However, you must use a context name as an argument:

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

5.2.5 Remove 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...)
$ 

You can use wildcards to remove groups of names or obects. I.e., to remove all context names starting with "Foo" you would enter:

$ legion_rm Foo\* 

Please note that you must escape the "*" character.

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 Use the same name in different contexts

As discussed in section 4.3, the same context name in different context paths can point to different Legion objects.

In this example, legion_ln assigns the name Bar to object Foo.

$ legion_ln Foo Bar 

Notice that Bar goes in the current context. We can assign the same name to object Foo2 in the tmp context:

$ legion_ln Foo2 /tmp/Bar 

That means that the name Bar is used in two different contexts to point to two different objects, Foo and Foo2. If you prefer, you can use the same name in different context paths to refer to the same object:

$ legion_ln Foo Bar
$ legion_ln Foo /tmp/Bar 

Bar and /tmp/Bar now both point to Foo.

5.3 Moving between local files and contexts

5.3.1 Copying

Use the legion_cp command to copy the contents of a local file into a Legion BasicFileObject and vice cersa as well as to copy between BasicFileObjects. Note that if you copy new material into a previously existing BasicFileObject the new material will write over the old contents. This command only works with BasicFileObjects.

5.3.1.1 Copy a local file to a Legion file object

The example below copies the contents of the Unix file UnixTextFile.txt from the local directory to a new Legion BasicFileObject called newFileObject.

$ legion_cp -localsrc UnixTextFile.txt newFileObject 

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

5.3.1.2 Copy a Legion file object to a local file

You can use the -localdest flag to copy from a Legion file to a local file. To copy the contents of Legion file object Foo to a local file called UnixTextFile.txt, you would enter:

$ legion_cp -localdest Foo UnixTextFile.txt 

Note that if UnixTextFile.txt already existed, Legion would overwrite the old contents.

5.3.1.3 Copy a Legion file object to another 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 

5.3.1.4 Using wildcards

You can use wildcards in the source parameter to copy a group of files into Legion context space. The example below copies all files that start with "Foo" from the local directory into the /home/myContext context.

$ legion_cp -localsrc Foo\* /home/myContext 

Please note that you must escape the "*" character with a "\".

The new file objects are assigned the same names as the local files. E.g., if Foo\* yields Foo1 and Foo2, the duplicate file objects will be Foo1 and Foo2.

You cannot use wildcards in your destination path.

5.3.2 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
Here are the contents of FileObject.
$ 

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

5.3.4 File sharing: temporarily link files to context space

The legion_export_dir command allows a complete local directory tree to be temporarily linked to Legion context space. 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 again.

For example, to export local_directory_Foo, you would enter something like this:

$ legion_export_dir local_directory_Foo \ 
   /home/myContext/Bar 

Legion creates a new context called /Bar, which is linked to local_directory_Foo. This is a read-only context: any changes that you make to /Bar, such as changing or removing context names, will not be reflected in local_directory_Foo (and vice versa). For best results, do not make any changes to either the directory or the context. You should also delete /Bar (with legion_rm) when you are finished.

To pause the command, press ^-C. To resume using the exported files, re-execute the command, specifying the same local directory path and context path. If you try to use your exported files and directories while the command is paused you will get 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. E.g.,

$ legion_rm -r /home/myContext/Bar 

1.Man page usage is man <command name>: ask your system administrator if you are unsure about using man pages on your system. You can also go to <http://legion.virginia.edu/legion_man.html> to see on-line versions of the Legion man pages. back

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

Directory of Legion 1.7 Manuals
[Home] [General] [Documentation] [Software]
[Testbeds] [Et Cetera] [Map/Search]

Free JavaScripts provided by The JavaScript Source

legion@Virginia.edu
http://legion.virginia.edu/