As in Unix space, users move around context space with command-line utilities, 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 more easily. There are a variety of resources available for learning The Reference Manual lists all commands and instructions for using them, and man pages for all commands are included in new Legion systems (ask your system administrator if you are unsure how to use man pages). The Legion web site has on-line tutorials and postscript documents that provide information about context space and legion commands (http://legion.virginia.edu). In this manual, an alphabetical list of all commands and their syntax is in the "Alphabetical list of Legion commands" and a subject list is in the "Subject listing of Legion commands."
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. The root context of a new system will look something like this:
$ legion_context_list . class hosts vaults home $
$ legion_context_list . class hosts vaults home Foofile Fooclass Fooobject $
To view sub-contexts (similar to sub-directories), the name of a context1 is used an as argument:
$ 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 contexts and file objects contained in the current context.
$ legion_ls . class hosts vaults home Foofile $
$ legion_ls -a . class hosts vaults home Foofile Fooclass Fooobject $
$ legion_ls -l . (context) class (context) hosts (context) vaults (context) home (context) Foofile 43 bytes $ $ legion_ls -la . (context) class (context) hosts (context) vaults (context) home (context) Foofile 43 bytes Fooclass (class) Fooobject $
$ legion_ls -L . 1.01.05.01000000.00000...2 class 1.01.05.02000000.00000... hosts 1.01.05.03000000.00000... vaults 1.01.05.04000000.00000... home 1.01.05.05000000.00000... Foofile 1.01.66000000.02000000.00000... $
$ legion_ls -la /class . (context) .. (context) LegionClass (class) VanillaMetaClass (class) BootstrapMetaClass (class) BasicFileClass (class) ttyObjectClass (class) JobProxyClass (class) BatchQueueMetaClass (class) StatTreeClass (class) AuthenticationObjectClass (class) UnixHostClass (class) UnixVaultClass (class) BindingAgentClass (class) CommandLineClass (class) ContextClass (class) UnixImplementationClass (class) UnixImplementationCacheClass (class) StatelessProxyMetaClass (class) StatelessClasses (context) $
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.01000000.000001fc0a8e60138a9... $
$ legion_context_create /tmp Creating context "tmp" in parent "/". New context LOID = "1.01.05.07000000.000001fc0d02..." $
$ legion_set_context /tmp
The sub-context tmp is now the current working 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.
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 "Assigning a context name to a LOID") to assign a name 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 (rather than the hosts context, where the object's original context name BootstrapHost is located).
$ legion_ln /hosts/BootstrapHost Foo $ legion_ls -la . (context) .. (context) Foo $
An object's alternate context names can be in different contexts: BootstrapHost is in the hosts context, and Foo is in the current context. Both names refer to the same LOID and either one can be used to control the object.
$ legion_context_lookup Foo 1.01.07.01000000.000001fc0a8e60138a9... $ $ legion_context_lookup /hosts/BootstrapHost 1.01.07.01000000.000001fc0a8e60138a9... $
The legion_context_add command maps an object's LOID to a context name. It can be used to assign a name to a previously unnamed object or to assign an extra name to a previously named object. Either way you need to provide the object's full LOID as an argument.
$ legion_context_add 1.01.66000000.05... newName
$ 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.
$ legion_rm Bar
$ legion_context_remove Bar
Neither of these commands, as used in these two examples, will affect the associated object: removing a context name does not destroy the object. If you wish to destroy or deactivate the object use the legion_rm command with, respectively, the -destroy or -deactivate flags.
The legion_destroy_object command, on the other hand, destroys the object but not its context name(s). This command should therefore not be used with objects that have context names, unless the names are then removed with either legion_rm or legion_context_remove.
As discussed in "Organizing context space," the same context name can be used to refer to different Legion objects. For example, the name Foo can be assigned to two different objects in two different contexts, the current working context and the tmp context.
$ legion_ln 1.01.05.6e0c2... Foo
$ legion_ln 1.01.66000... /tmp/Foo
$ legion_ln 1.01.05.6e0c2... Foo $ legion_ln 1.01.05.6e0c2... /tmp/Foo
The contents of a local file can be copied to a new 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 -localsource UnixTextFile.txt newFileObject
$ legion_cp newFileObject newFileObject_copy
$ legion_cp -localdest newFileObject anotherTextFile.txt
$ legion_cat newFileObject This is a test, just a test, nothing more. $
The contents of a local directory tree can be copied from local file space into context space with the legion_import_tree command. The contents of Unix binary files will automatically be 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 users 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" $
$ legion_ls -la . (context) class (context) hosts (context) vaults (context) home (context) nextlevel (context) nothing 43 bytes nothing2 46 bytes nothing3 46 bytes $ legion_ls -la /nextlevel nextnothing3 46 bytes nextnothing2 46 bytes nextnothing 43 bytes .. (context) . (context) $
$ 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. Full path syntax can be used as well as relative path syntax in all Legion commands.Back
2. In this and some of the following examples the entire LOID is not reproduced, in the interests of space and readability.Back