Legion 1.2
Basic User Manual

2.0 Before you start

This manual assumes that you are working on a previously installed, compiled, and running system.1 (See the System Administrator Manual for information on installing, compiling, and starting a new Legion system.) Before going any further, be sure that the system is properly installed and running.

Please note that while your path will change as you move through Legion's binary files, it will not change as you move through context space. We are currently developing a graphic user interface to help users negotiate this space more easily. For the time being, though, you will be working from your command line and typing in commands to run programs and manipulate contexts.

The next few sections deal with setting up the proper environment variables and logging in to a Legion system as a Legion user.

2.1 Preparing the Legion environment

Depending on how your system is set up, you may need to set up your access to your system before you can run Legion commands. This will probably involve running a script such as this:

$ . ~LEGION/setup.sh

or

$ source ~LEGION/setup.csh

The exact syntax will depend on what kind of shell you are using and on where your Legion files are installed. Consult your system administrator for more information.

2.2 Logging in to a Legion system

A user who logs in to a Legion system is identified by a special object called the AuthenticationObject: it contains the user's password, initial implicit parameters (the Legion equivalent of a the Unix "environment"), and other information. AuthenticationObjects are created when a user creates a user id. A set of Legion commands (legion_set_acl, legion_get_acl, legion_passwd, legion_set_implicit_params, and legion_get_implicit_params) can be used to retrieve or change this information (see the Legion Reference Manual or the man pages for a discussion of how to use these commands). When an authenticated user runs a Legion process a certificate confirming his or her identify is passed along to verify that the user has permission to run the process. This certificate is created and signed by the user's AuthenticationObject.

AuthenticationObjects must be permanent in order to be useful. If an AuthenticationObject is destroyed, its associated LOID, which identifies the user to the rest of the system, is lost. There is no way to generate an identical LOID for a new AuthenticationObject.

2.2.1 Logging in as a user

In order to log in to the system, you will need a user id, which can be created by either the user or system administrator. You can then log in, with the legion_login command. The system will then request your password and check it with your AuthenticationObject, which verifies your identity and security privileges.

There are two different ways to use this command.

  1. You can run the command with just the user id or with no arguments at all. The legion_login process will put you in a new sub-shell, and will continue to run. Any processes that you start from within this shell will be accompanied by a copy of your AuthenticationObject's certificate. This method is explained below in "Log in as a new user."
  2. Or, the legion_login command can set the necessary environment variables so that, instead of running a shell, you can tell legion_login to execute a specific command (similar to the behavior of Unix rsh). The syntax for this is:
  3. legion_login [-l userloid | user_id] [-e command]
    You can add another Legion command as an argument and the legion_login process will securely obtain your certificate from your AuthenticationObject and pass it along. This is useful if you need to certify your identity for a specific process and you do not wish to operate in a legion_login sub-shell.

Note that even if your system doesn't require user ids to gain access to Legion, using legion_login has a side benefit in that command-line tools run faster in a user id shell.

2.2.2 Create a new user ID

If you do not already have a user id, you can create one. Normally, the system administrator creates user ids and simultaneously enters them in the groups that have appropriate security rights on the system. If you create your own id you may not have the necessary permissions to enter the id in such groups and use the system resources that the groups control. However, your new user id will otherwise function normally and can be used to protect your resources from other users of the system.

A user name is simply an entry in context space for an AuthenticationObject. You can create users with the legion_create_user command. To create user "bob" in the current context, enter:

$ legion_create_user bob

To create the bob entry elsewhere, enter:

$ legion_create_user /my/path/bob

The command will prompt for a password for the new user. Note that the context where the user name is placed has nothing to do with whether that user can access anything in that context space.

2.2.3 Log in as a new user

To log in as the new user "bob," enter

$ legion_login bob
Password: xxxx
$

You do not need to include the user id as a parameter, if you prefer:

$ legion_login 
Legion login: bob
Password: xxxx
$

Note that your working context will not change when you enter the new shell, but your access privileges are different. Objects created in bob's shell will by default require bob's access privileges to use them.

To exit from bob's shell, enter exit:

$ exit
exit
$

While logged in, you can change your password and other parameters of your environment. The password may be changed with legion_passwd. Note that in this release you must specify the user whose password you are changing, even if it is yourself:

$ legion_passwd bob
New Legion password: xxxx
Retype new password: xxxx
$

To change your implicit parameters, which can be used to control the behavior of security as well as other Legion tools and objects, use the legion_set_implicit_params tools documented in the reference manual. The access permissions of existing objects can be changed with legion_set_acl (please see also "Using security features," in the System Administrator Manual).


1.It is actually not always necessary to have a Legion system running in order to use Legion: some Legion hosts can run in "consumer mode." Consumer mode hosts do not require the full set of Legion system binaries to be installed and running; a subset of binaries can access a Legion system that runs on different remote hosts, and can potentially even use that system to execute parts of Legion programs. A consumer mode host cannot itself be used to carry out parts of Legion programs unless those programs are started directly on that host by mechanisms outside of Legion (for example, from a shell running on the host's operating system). Back


Back to Getting Started sectional index

Back to Basic User Manual Table of Contents