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. Check with your system administrator if you are unsure.

Please note that while your local file path will change as you move through Legion's binary files, it will not change as you move through context space. Legion offers a graphical user interface (GUI--see See The GUI ) to help you negotiate this space more easily. We will start looking at context space in the GUI to give you a better idea of the individual components of context space and then go to the command line and look at context-related commands that can be used to run programs and manipulate Legion objects.

Before anything else, you must set up the proper environment variables and log in to a Legion system as a Legion user.

2.1 Preparing your Legion environment

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

$ . ~LEGION/setup.sh


$ 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. Your system may have different requirements: consult your system administrator for more information.

2.2 Logging in to a Legion system

If your system administrator has enabled Legion's security features, you must have a user id and log in to Legion before you can start working. Your system's log in procedure may differ from what is laid out here: please see your system administrator for exact instructions. The default system requires that all users have user ids and passwords. This allows Legion to keep track of your objects and to know what kind of user privileges you have. It also prevents malicious users from interfering with your objects or gaining illicit access to your system.

When you log in to a Legion system you are identified by a special object called the AuthenticationObject : this object contains your password, initial implicit parameters (the Legion equivalent of a the Unix "environment"), and other information. AuthenticationObjects are created when you create a user id. A set of Legion commands can be used to retrieve or change this information (see section See Security in the Legion Reference Manual for these commands). When an authenticated user runs a Legion process a certificate confirming his or her identify is passed along to verify that this person has permission to run the process. This certificate is created and signed by your AuthenticationObject (if your AuthenticationObject is destroyed, you will have to get a new user id).

2.2.1 Logging in as a user

You need a user id before you can log in. Ask your system administrator if you do not have one. You can then log in with the legion_login command. The system will request your password and verify your identity and your security privileges.

Note that there are two ways to use the legion_login command.

  1. 1. You can use it to log in: run the command with just your user id, as in the example above, 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 in more detail below.

To log in with the user id bob , you could enter:

$ legion_login /users/bob
Password: xxxx

Or, you could run legion_login without the user id as a parameter:

$ legion_login
Legion login: /users/bob
Password: xxxx

Notice that in both cases you need to use the full path name ( /users/bob ). To exit from bob 's shell, type exit .

Objects created in your shell will be owned by you and only you will be able to use them.

      1. 2. Or, instead of starting a sub-shell you can use legion_login with the -e flag to execute a specific command with your log in privileges. This option uses your AuthenticationObject to certify your identity for only that specific process (this is similar to the behavior of Unix rsh ).

For example, to use legion_login to execute legion_cat on object bob , enter:

$ legion_login /users/nemo -e legion_cat \ -c /home/nemo/bob
Password: xxxx
Bob's here.
2.2.2 About object permissions

If your system administrator has enabled Legion security, the objects that you create while logged in cannot be used by any other users. If you wish to share your objects you will need to give other users permission to read, write, or execute objects. The legion_change_permissions command lets you do this. The syntax is:

legion_change_permissions [+-rwx] [-v]
[-help] <group/user context path>
<target context path>

You can use the [ r ], [ w ], or [ x ] flags to add [ + ] or remove [ - ] read, write, or execute permissions on objects. So, if you wanted to allow user bob to be able to read your file object foo , you would enter:

$ legion_change_permissions +r /users/bob foo

This lets bob "read" your object foo . Please see See legion_change_permissions in the Reference Manual for full documentation of this command.

2.2.3 Checking your log in status

If you can't remember whether or not you are logged in or which user id you are using, run the legion_whoami command. Your output will look something like this:

$ legion_whoami

This means that you are logged in as user nemo . If you are not logged in or your system administrator has not enabled security there will be no output.

While logged in, you can change your password and other parameters of your environment. The password may be changed with the legion_passwd command. Note that you must include your user name:

$ legion_passwd /users/nemo
New Legion password: xxxx
Retype new password: xxxx
Password changed.

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).