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 1Start-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.* 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
Legion first-time system startup complete
Run "legion_initialize"
$

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; those class objects are UnixVaultClass, UnixHostClass, UnixImplementationClass, and UnixImplementationCacheClass.

The new class objects will start instances in the new system: BindingAgentClass parents binding objects, CommandLineClass parents command-line objects, etc.

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

The output shows the system creating and tagging the key ingredients of a new system. It is too long to reproduce in full here, but we'll look at some select actions.

The first line shows the system creating a bootstrap host object on your current host. This object manages the bootstrap host machine.

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

Whichever host you run legion_initialize on will be considered the bootstrap host. Remember 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.

A bootstrap vault object is automatically created on your current host. This guarantees that the bootstrap host object has an compatible vault object. In Legion, a host object must be paired with an compatible vault object (i.e., a vault that it can "see").

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

Implementation objects 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

More implementation objects are created as the process creates new object classes.

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

Two context names are added to the /hosts context (BootstrapHost and your.bootstrap.host.name): both names refer to the Bootstrap host object (see Figure 2) but only one is added to the /vaults context

Figure 2Context space of a newly initialized Legion system

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 a discussion of Legion hosts and vaults). The /impls context contains names of the default implementation objects (see Implementation model). These can all be viewed with context-related commands once the system has been completely started.

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 any Legion utilities or commands.

3.1.5 Choose your security setting

If you wish 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.

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

The /users context holds Legion user ids, starting with admin:

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

This admin is the system administrator's user id: anyone logging in as admin has root privileges. You will have to enter the password three times during the legion_init_security process and when logging in.

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

Legion assigns ownership of all existing objects to admin. Objects created by other users will belong to those users.

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

The access control lists (ACLs) protect objects against unauthorized use. Only an object's creator can use the object, unless the creator specifies otherwise. The initial ACL files allow only the admin to use the core objects.

Creating context "tmp" in parent "/".
New context LOID = "1.362dabd6.05.09000000.000001fc..."
[...etc.]
Done creating acl files

Several new context objects are created and placed in the root context and given ACLs.

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

ACL files are then created for all previously existing objects.

At this point, security has been enabled and is running. You must now log in as admin. Note that you need to include the /users path.

$ legion_login /users/admin
Password: xxxx
$

The contents of your context space will now look something like this:

Figure 3Context 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 one user (i.e., /users/admin), run legion_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 one of the following:

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

3.4 Summary of commands

Starting a new system

  1. First time start-up
  2. $ legion_setup_state
    $ legion_startup
    $ legion_initialize

  3. Set the environment
  4. Start security (if desired)
  5. $ legion_init_security

  6. Login as admin (if security started)
  7. $ legion_login /users/admin

Shutdown

  1. Shut down
  2. $ legion_shutdown

  3. If security was enabled, you'll have to clean up some objects by hand (Legion cannot shut down non-admin objects)

Restart

  1. Restart the system
  2. $ legion_startup

  3. Set environment variables

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


Back to System Administrator Manual Table of Contents

Directory of Legion 1.5 Manuals