In Unix space you move around directory space with command-line utilities, and Legion provides commands to let you move around in context space. The remainder of this section discusses some basic context-related command line utilities. Most resemble Unix commands in both name and purpose to make them easier to use (e.g., legion_ls, legion_rm).
There are several other sources of information about Legion context space and commands: this manual has an alphabetical list (Alphabetical list of Legion commands) and a subject list (Subject listing of Legion commands) of all commands' syntax; the Reference Manual lists all commands and instructions for using them; the Legion web site has on-line tutorials and postscript documents (<http://legion.virginia.edu>); and the Legion release package includes man pages for all commands.1
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 $
But you might see something different, depending on your individual system:
$ legion_ls / Fooclass Foofile Fooobject class home hosts impls vaults $
To view sub-contexts (similar to sub-directories), use a context's name as argument:2
$ legion_ls /hosts BootstrapHost your.host.DNS.name $
You can use the legion_ls flags to get more specific information. There are eight flags, not all of which are discussed here. Please see legion_ls in the Reference Manual for more information.
You can use the -l and -a flags to get more detailed lists. The -l flag includes objects' 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 legion_ls command will not list the "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..000001fc0a7838d45ed Foofile 1.01.66000000.02000000.00000... Fooobject 1.35fe7c3d.66000000.01000000.00 class 1.01.05.02000000.00000...3 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 also use this command to get specific information about an individual object by using the object's context name as an argument. For example:
$ legion_ls -L Foofile Foofile 1.01.66000000.02000000.00000... $
You can look up an object's LOID with the legion_ls command. 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... $
You can create new contexts 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.07000000.000001fc0d02..." $
The legion_set_context command will change the current working context.
$ legion_set_context /tmp
The sub-context tmp is now the current working context.
This command 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.
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.
You can create alternate names for objects with legion_ln, a command similar to the Unix ln command. Note that this 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 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 (/tmp).
$ legion_ln /hosts/BootstrapHost Foo $ legion_ls Foo $
Note that BootstrapHost and Foo have different context paths but both names point to the same object (a host object in this case) 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.
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
An object can be renamed with the legion_mv command (similar to the Unix mv command). The object keeps the same LOID but gets a different context path name. In the example below, object Foo is renamed Bar.
$ legion_mv Foo Bar
The name Foo is automatically removed from the current context. This process affects only a specific context path: any other use of the name Foo, whether somewhere else in this user's or any other user's context space, will be unchanged.
There are two commands that will show an object's context names: legion_list_names and legion_ls. Note, though, that you must use a context name as an argument for legion_ls, so you'll need to know at least one of the object's names.
Use the legion_ls command with the -A flag to look up an object's other (if any) name[s]:
$ legion_ls -A /hosts/BootstrapHost /hosts/BootstrapHost /hosts/BootstrapHost /hosts/my.host.DNS.name $
The legion_list_names command will list all context paths that have been assigned to a given object. If, for example, you knew an object's LOID but not its context name you could use the -l flag to ask Legion to look up the object's name. The output below asks for the context names that have been assigned to a LOID then shows that this is the BootstrapVault's LOID.
$ 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 $
You can remove (i.e., destroy) context names with legion_rm.
$ legion_rm Foo
Note that destroying a context name does not necessarily destroy its associated object. If there are other names assigned to the object legion_rm will just remove the specified name(s). If there are no other names, however, the object will be destroyed. For example, if you gave Foo an additional name:
$ legion_ln Foo Foo2 $ legion_rm Foo
The name Foo would be removed but the object itself would be unaffected. However, if you then ran:
$ legion_rm Foo2
Both the name and the object would be destroyed, since Foo2 is the only remaining context name. 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.
You can use legion_ls -A to check which names are mapped to an object.
$ legion_ls -A Foo /Foo /Foo /Foo2 $
If you want to remove an entire context, use legion_rm -r: the -r flag recursively destroys a context and all of its contents.
As discussed in Organizing context space, the same context name can be used in different context paths to refer to different Legion objects. For example, the name Foo can be assigned to two different objects in two different contexts.
Below, the name Foo is assigned to a LOID with the legion_ln command. Foo is placed in the current context. The same name, in the tmp context, is then assigned to a different object.
$ legion_ln 1.01.05.6e0c2... Foo $ legion_ln 1.01.66000... /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
You can copy the contents of a local file to a 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 -localsrc UnixTextFile.txt newFileObject
The -localsrc flag indicates that UnixTextFile.txt can be found in the local file system.
Note that if you copy new material into a previously existing file object the new material will write over any old material.
The legion_cp command will also copy the contents of a file object to a new file object.
$ legion_cp FileObject FileObject_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 FileObject anotherTextFile.txt
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. $
You can copy the contents of a local tree from your local file space into your context space with the legion_import_tree command. The contents of local files will be automatically 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 you can specify the directory path and/or the context (see 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" $
Note that Legion copied the contents of the /nextlevel subdirectory into a new sub-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. $
1. Man page usage is man <command name>: ask your system administrator if you are unsure about using man pages on your system.
2. Full path syntax can be used as well as relative path syntax in all Legion commands.
3. In the interests of space and readability, in this and some of the following examples the entire LOID is not reproduced.
Directory of Legion 1.5 Manuals