Legion 1.4
System Administrator Manual


3.0 Starting & shutting down Legion

If you have downloaded the source code, you must compile the system before you can start it. Once the system is running, Legion can be safely shut down and restarted without a loss of state. The restart procedure is different from the procedure discussed here, and will be explained in a later section (see System restart).

3.1 First time start-up procedure

There are three steps in this procedure: configure the system with legion_setup_state, start it with legion_startup, and, finally, initialize it with legion_initialize. Note that, while the sample start-up below uses a single host for convenience, you are not required to use the same host for all three steps. Technically, there are two hosts used for the whole procedure, the start-up host and the bootstrap host (Figure 1), but you can carry out all three steps on a single host. In either case, Legion binary executable files must be installed on any hosts used for Legion procedures. The host that you select during legion_setup_state and that contains the basic Legion classes is the start-up host. The start-up host must always be used to run legion_startup. The bootstrap host is used to boot the system and is the first host object added to the system. It will contain the first pieces of the new system (the first contexts and instances of the classes). You do not have to run legion_initialize on the same host on which you run legion_setup_state and legion_startup.

Figure 1: Start-up and Bootstrap hosts

3.1.1 Configure the system

You must first choose a start-up host. This is the machine from which the main system will be started and shut down.1 The LegionClass object (the root of the Legion binding mechanism and the parent class of many metaclasses) will be placed here. The $LEGION_OPR/LegionClass.config file will be created on this host. This file contains the LegionClass object address, which must be globally known to all Legion objects. The file must be available when other objects are started in the system.

Next, set up the initial state for core Legion system objects. Legion system objects are persistent, and can save and restore their own state. Some of these objects must have their state initialized before they run for the first time. After the initial start-up, these objects will manage their own state and configuration, if the system is properly maintained.

Enter the following command to configure the system:

$ legion_setup_state

This program will return your start-up host name, a port number for the LegionClass object, and a time. If you do not want to use the default settings, use the -i flag to run the command in an interactive mode. Your output will look something like this:

$ legion_setup_state
Creating OPR directory /home/xxx/OPR/.
Saving LegionClass configuration file: /home/xxx/OPR/LegionClass.config
LegionClass host name   = your.startup.host.name
LegionClass port number = 7899
LegionClass timestamp   = 898198093
$

The script creates the $LEGION_OPR directory and several sub-directories, populating them with initial states for several core system objects. The timestamp sets the starting time for the system: Legion objects use a timestamp to guarantee each object's unique identity. The current time is measured in seconds since Jan. 1, 1970.

3.1.2 Start up the system

The legion_startup script provides prompts asking whether or not to start each component. It's best to answer "yes to all" (Y). The verbose option allows you to see more detailed information, as the script works, about debugging. (This can be large amounts of information, so use this option only if you are searching for a problem.) To start the main core system objects, enter

$ legion_startup

Legion will start several classes on your host. Your output will look something like this

$ legion_startup
Starting meta-class object: LegionClass
Continue (y=yes, Y=yes to all, n=no, N=no to all, v=verbose, 
      V=verbose all)? Y
Starting meta-class object: BootstrapMetaClass
Starting class object: BindingAgentClass
Starting class object: CommandLineClass
Starting class object: UnixHostClass
Starting class object: UnixVaultClass
Starting class object: UnixImplementationClass
Starting class object: UnixImplementationCacheClass
Starting class object: ContextClass
$

This indicates that the major class objects were started: LegionClass is the top-level metaclass and is the parent of every other object in the system; BootstrapMetaClass is the class object for the bootstrap class objects, which are those class objects that have instances that need to get created in the initialization phase. These are UnixHostClass, UnixVaultClass, UnixImplementationClass, and UnixImplementationCacheClass. BindingAgentClass is the parent of binding objects, the CommandLineClass is the parent of command-line objects, UnixHostClass is the parent of Unix host objects, UnixVaultClass is the parent of Unix vault objects, UnixImplementationClass is the parent of implementation objects,2 UnixImplementationCacheClass is the parent of implementation cache objects (see Implementation model for information about implementation objects and caches), and ContextClass is the parent of context space-related objects.

3.1.3 Initialize the system

Like legion_startup, the legion_initialize script will provide prompts asking whether or not to perform each task, and it is generally best to use the "yes to all" option (Y). To initialize Legion, enter

$ legion_initialize

Your output will look something like this:

$ legion_initialize
Creating host object BootstrapHostObject on 
	"your.bootstrap.host.name"
Continue (y=yes, Y=yes to all, n=no, N=no to all, v=verbose, 
	V=verbose all)? Y
Configuring wellknown binaries for host "1.01.07.0100..."
Creating vault object BootstrapVaultObject on 
	"your.bootstrap.host.name"
Setting BootstrapHost and BootstrapVault restrictions
Added 1 host(s) to vault's compatibility set
Added 1 vault(s) to host's compatibility set
Creating an ImplementationCache
Creating an implementation (ContextObject) for ContextClass
Creating the root context object
Be sure to
        source /home/xxxx/OPR/legion_context_env.csh
or
        . /home/xxxx/OPR/legion_context_env.sh
before starting anything else from the command line.
Deactivating BootstrapHostObject
Creating an implementation (MetaClassObject) for LegionClass
Creating the VanillaMetaClass
Creating an implementation (ClassObject) for VanillaMetaClass
Creating an implementation (BindingAgent) for BindingAgentClass
Creating the sub-context "/class" for classes
Creating the sub-context "/hosts" for hosts
Creating the sub-context "/vaults" for vaults
Creating the sub-context "/home" for users
Adding "LegionClass" to the class context
Adding "VanillaMetaClass" to the class context
Adding "BootstrapMetaClass" to the class context
Creating BasicFileClass
Creating an implementation (BasicFileObject) for BasicFileClass
Creating ttyObjectClass
Creating an implementation (ttyObject) for ttyObjectClass
Creating JobProxyClass
Creating an implementation (JobProxyObject) for JobProxyClass
Creating BatchQueueMetaClass
Creating an implementation (BatchQueueClassObject) for 
	BatchQueueMetaClass
Creating StatTreeClass
Creating an implementation (StatTreeObject) for StatTreeClass
Creating AuthenticationObject class and implementation
Creating implementation (AuthenticationObject) for 
	AuthenticationObjectClass
Adding "UnixHostClass" to the class context
Adding "UnixVaultClass" to the class context
Adding "BindingAgentClass" to the class context
Adding "CommandLineClass" to the class context
Adding "ContextClass" to the class context
Adding "UnixImplementationClass" to the class context
Adding "UnixImplementationCacheClass" to the class context
Creating an implementation (StatelessProxyClassObject) for 
	StatelessProxyMetaClass
Adding "StatelessClasses" to the class context
Adding "BootstrapHost" to the hosts context
Adding the alias "your.bootstrap.host.name" for BootstrapHost to the 
	hosts context
Adding "BootstrapVault" to the vaults context
$

This rather lengthy output shows the system creating and tagging the key ingredients of a new system. The first line,

Creating host object BootstrapHostObject on 
	"your.current.host.name"
Continue (y=yes, Y=yes to all, n=no, N=no to all, v=verbose, V=verbose 
	all)? Y
Configuring wellknown binaries for host "1.01.07.0100..."

shows the system creating the BootstrapHostObject on your current host. Whatever host you run legion_initialize on will be considered the bootstrap host. Again, note that you do not need to run legion_initialize on the start-up host, although the system's initial context space, instances, and instance tags will be placed on your current host.

Next, a bootstrap vault object is automatically created on your current host.

Creating vault object BootstrapVaultObject on
	"your.bootstrap.host.name"
Setting BootstrapHost and BootstrapVault restrictions
Added 1 host(s) to vault's compatibility set
Added 1 vault(s) to host's compatibility set

This guarantees that the bootstrap host object has an compatible vault object. In Legion, a host object must have an compatible vault object. The bootstrap host and vaults are marked as compatible so that the system can maintain the state of all parts of the system. A host and vault are considered compatible when each can "see" the other. (For more information on host-vault pairing, see About host-vault pairs.)

The system then creates objects which will represent and manage the implementation cache (used to allow Legion processes to take place in different architectures) and context space.

Creating an ImplementationCache
Creating an implementation (ContextObject) for ContextClass
Creating the root context object

These are instances of the ContextClass, UnixImplementationClass, and UnixImplementationCacheClass created in the legion_startup script.

The next piece of information is simply a reminder to set the environment variables before running any commands (see section Setting up the user environment for information on setting the user environment).

Be sure to
        source /home/xxxx/OPR/legion_context_env.csh
or
        . /home/xxxx/OPR/legion_context_env.sh
before starting anything else from the command line.

Then the bootstrap host object is deactivated.

Deactivating BootstrapHostObject

Note, however, that it is immediately reactivated: it is shut down and restarted as part of the initialization process.

The next few lines concern the creation of implementation objects (objects that allow Legion processes to take place in different architecture) for core object management (see Implementation model for information on the Legion implementation model).

Creating an implementation (MetaClassObject) for LegionClass
Creating the VanillaMetaClass
Creating an implementation (ClassObject) for VanillaMetaClass
Creating an implementation (BindingAgent) for BindingAgentClass

More implementation objects are created as the process creates new object classes. The basic elements of context space are also created:

Creating the sub-context "/class" for classes
Creating the sub-context "/hosts" for hosts
Creating the sub-context "/vaults" for vaults
Creating the sub-context "/home" for users
Adding "LegionClass" to the class context
Adding "VanillaMetaClass" to the class context
Adding "BootstrapMetaClass" to the class context
Creating BasicFileClass
Creating an implementation (BasicFileObject) for BasicFileClass
Creating ttyObjectClass
Creating an implementation (ttyObject) for ttyObjectClass
Creating JobProxyClass
Creating an implementation (JobProxyObject) for JobProxyClass
Creating BatchQueueMetaClass
Creating an implementation (BatchQueueClassObject) for 
	BatchQueueMetaClass
Creating StatTreeClass
Creating an implementation (StatTreeObject) for StatTreeClass
Creating AuthenticationObject class and implementation
Creating implementation (AuthenticationObject) for 
	AuthenticationObjectClass
Adding "UnixHostClass" to the class context
Adding "UnixVaultClass" to the class context
Adding "BindingAgentClass" to the class context
Adding "CommandLineClass" to the class context
Adding "ContextClass" to the class context
Adding "UnixImplementationClass" to the class context
Adding "UnixImplementationCacheClass" to the class context
Adding "StatelessProxyMetaClass" to the class context
Creating an implementation (StatelessProxyClassObject) for 
	StatelessProxyMetaClass
Adding "StatelessClasses" to the class context
Adding "BootstrapHost" to the hosts context
Adding the alias "your.bootstrap.host.name" for BootstrapHost to the 
	hosts context
Adding "BootstrapVault" to the vaults context

Note that two context names are added to the /hosts context: BootstrapHost and your.bootstrap.host.name, but only one name, BootstrapVault, is added to the /vaults context. Both BootstrapHost and your.bootstrap.host.name refer to the Bootstrap host object, which is managing the machine used as your bootstrap host (Figure 2). This object will manage a portion of the persistent storage mechanism for the Bootstrap host (please see Host and vault objects in the Basic User Manual for information on Legion hosts and vaults). The /impls context contains names of the default implementation objects (see Implementation model). These can all be viewed with the context commands (listed at the appendix of this manual, and described in detail in the Reference Manual), once the system has been completely started.

Figure 2: Context space of a newly initialized Legion system

3.1.4 Set the environment

Source the script that sets up environment variables for using the context space.

ksh or sh users type:

$ . $LEGION_OPR/legion_context_env.sh

csh users type:

$ source $LEGION_OPR/legion_context_env.csh

You must source this script in each shell in which you plan to run Legion commands, including the shell in which you ran legion_initialize. Otherwise you will not be able to run Legion utilities or commands.

3.1.5 Choose your security setting

If you wish to enable Legion security, you must run the legion_init_security command now. Please note that Legion will run with or without the security features, but if you do not enable security none of your processes will be protected. If you don't enable it, you can simply start working in the system. Note, though, that you cannot turn on these features later. The legion_init_security command will not run properly unless you run it immediately after initializing the system.

If you decide to use the features, you will be given a system administrator user id called admin. This user id has root privileges in the system: it can create new users, modify security settings, etc. It also has ownership of all objects in the new system. Note, however, that admin does not own any other users' objects.

To enable security, enter:

$ legion_init_security

Several events take place when you run this command, and we will discuss each in turn. First, a new context, called /users, is placed in the root context.

Creating the context "/users" to contain user-objects
Creating context "users" in parent "/".
New context LOID = "1.3622260c.05.08000000.000001fc..."

The admin user is then created and given the context path /users/admin. You will also be asked to create a password. You will have to enter it three times. You can change it later, with legion_passwd (see Changing user passwords).

Creating the initial system-admin user object, "/users/admin"
Please select a Legion password for "/users/admin":
New Legion password: xxxx
Retype password: xxxx
1.3622260c.6b000000.01000000.000001fc0c...
Please enter the Legion password for "/users/admin" to continue:
Password: xxxx

Legion then assigns ownership of all existing objects to admin.

Changing ownership of all objects to "/users/admin"
1.3622260c.01..000001fc0cbe1846763f895a...
1.3622260c.02..000001fc0b3b16eb8b2dde29...
[...etc.]
Changed ownership of 43 objects.

Then it creates and sets access control list (ACLs) for all existing objects.

Creating initial ACLs files for all core objects in
	/home/xxxx/OPR/init_acls
Creating ACL for /class/AuthenticationObjectClass class
Creating ACL for /class/BasicFileClass class
[...etc.]

Several new contexts are created and placed in the root context.

Creating context "tmp" in parent "/".
New context LOID = "1.362dabd6.05.09000000.000001fc..."
Creating context "etc" in parent "/".
New context LOID = "1.362dabd6.05.0a000000.000001fc..."
Creating context "mpi" in parent "/".
New context LOID = "1.362dabd6.05.0b000000.000001fc..."
Creating context "programs" in parent "/mpi".
New context LOID = "1.362dabd6.05.0c000000.000001fc..."
Creating context "instances" in parent "/mpi".
New context LOID = "1.362dabd6.05.0d000000.000001fc..."
Creating context "pvm" in parent "/".
New context LOID = "1.362dabd6.05.0e000000.000001fc..."
Creating context "tasks" in parent "/pvm".
New context LOID = "1.362dabd6.05.0f000000.000001fc..."
Done creating acl files

Then it sets the ACLs for all existing objects.

Setting ACL for /class/AuthenticationObjectClass class
Setting ACL for /class/BasicFileClass class
[...etc.]
All acls set.
$

You must now log in as admin. Note that you need to include the /users path.

$ legion_login /users/admin
Password: xxxx
$

At this point, security has been enabled and is running. You can create new user ids, create new host or vault objects, execute remote programs, etc. The contents of your context space will now look something like this:

Figure 3: Context space of a typical new secure Legion system

3.2 System shutdown

Legion can be safely shut down without a loss of state in system objects. Creators of user object classes can choose whether or not to maintain the state of their objects.

Issue the shutdown command from the bootstrap host:

$ legion_shutdown

This may take several minutes. Be patient, and do not try to quit the process with ^C. When completed, the entire system, with the notable exception of extra hosts and vaults that were started separately (see Host and vault objects in the Basic User Manual), will be deactivated.

Please note that the shutdown procedure will be unable to delete objects that it does not have permission for. If you have only created one user (i.e., /users/admin), run shutdown while logged in. Otherwise you will need to clean up after the system by hand.

3.3 System restart

Once a system has been safely shut down, it can be restarted without repeating the configuration and first-time initialization process. If the system was not safely shut down, you cannot restart it but must start again with the configuration and start-up procedure. If you did not have a safe shutdown, be sure to remove the $LEGION_OPR directory and to kill any extraneous Legion processes (use ps to check this).

For a normal system restart, check to be sure that environment variables are properly set. If necessary, run

(ksh or sh users)

export LEGION=<Legion root dir path>
export LEGION_OPR=<Legion OPR root dir path>
. $LEGION/bin/legion_env.sh
. $LEGION_OPR/legion_context_env.sh

(csh users)

setenv LEGION <Legion root dir path>
setenv LEGION_OPR <Legion OPR root dir path>
source $LEGION/bin/legion_env.csh
source $LEGION_OPR/legion_context_env.csh

Go to the start-up host and run the start-up command.

$ legion_startup

Do not rerun legion_initialize. The objects created when you first ran it still exist in the system, since they are in an inert state until the system is restarted. They will be reactivated and their state reloaded as necessary.


1.Once fully operational, Legion does not shut down and restart automatically: the system is intended to stay up. back

2.Again, this may confuse some users, since neither the UnixImplementationClass nor the UnixImplementationCacheClass are in fact Unix implementations, but are specific to your platform. back


Back to System Administrator Manual Table of Contents