Legion Quick Guide: Starting a new system

Legion quick guide
Starting a new system

This is a guide to starting a new Legion system. It more or less summarizes the instructions in the System Administrator manual. We suggest, though, that you at least skim the relevant sections of the Basic User and System Administrator manuals before starting a new system.

Table of Contents

1. Before you start

2. Start a system

2.1. To start a single host Legion system

2.2. To start a multihost Legion system

2.2.1. Set up

2.2.2. Create a new vault

2.2.3. Create a new host

2.2.4. Adding new users

2.2.5. Working in the new net

2.3. To create a multidomain net

2.4. To add virtual hosts

Other on-line tutorials & documentation

1. Before you start

Before you start a new Legion system, be sure that you consider what type of set-up will best suit your needs. Primary considerations are:

What kind of system will you be using? How many machines do you anticipate using? Do you only use local hosts or do you also use remote machines? Possible configurations might include:

A single host system: one Legion machine using its own resources (figure 1). This is the simplest system.

Figure 1: Single host system

A multihost system: multiple Legion hosts linked together and sharing resources (figure 2). This can include homogeneous and heterogeneous platforms, as well as non-Legion machines. The machines do not need to be in physical proximity.

Figure 2: Multihost system

A multidomain system: multiple Legion domains connected together and sharing resources (figure 3).

Figure 3: Multidomain system

Will you be using Legion security? This is an important consideration, since a secure Legion system cannot be cleanly shut down and restarted. If you are using security, you should decide who will be the "admin" (the system administrator). The system should be started up by the administrator, since he or she will have special privileges on the core objects created in the new system. (These privileges do not extend to other users' objects, however.)

What kind of host objects will you be using? Options include:

Basic host object: it resides on its host and manages and guards its host's resources. This is the template for the other host objects.

See "Host and vault objects" in the Basic User manual for discussion of basic host objects. In the System Administrator manual, section 11.0 discusses host-vault pairings and adding new hosts.

PCD host object: it resides on its host, manages and guards its host's resources, and uses a process control daemon to regulate ownership of all Legion processes executed on that host. You can use a PCD host as your bootstrap host, but the start-up procedure will be slightly different.

The daemon requires root privileges to start and to run. The PCD host object is useful if outside users will be running processes on your host, but can only be used if Legion security is enabled. Each user's processes will be tracked and accounted for. For more information, please see "Process control daemon host objects" in the System Administrator manual.

Batch queue host object: it resides on its host, manages and guards its host's resources, and submits Legion jobs to the local queueing system.

This is the best choice for hosts that use a queue management system, although the PCD host object is more secure and has better accounting. For more information, please see "Batch queue host objects" in the System Administrator manual.

Virtual host object: it resides on a different host, represents and guards its host's resources, but does not run normal Legion objects. A virtual host cannot be used a bootstrap host: it can only be added to an already running system.

A virtual host object is used for running Legion jobs on unsupported platforms. The host object resides on a supported platform and runs native jobs with standard Legion tools on the target host machine. It can be used for scheduling, resource selection, and transparent execution on the target machine. For more information, please see "Virtual hosts" in the System Administrator manual.

2. Start a system

Assuming that you have already downloaded and compiled the desired platform source code, you should run through the following checklist:

Is /bin/ksh is installed in your system? Several Legion scripts look for ksh and will send error messages if they can not find it.
Be sure that the user environment is properly set. You must check this each time you open a new shell or login to use Legion, so we suggest that you edit your .profile or .login file. We also suggest using $LEGION/.../OPR for the OPR root directory path (unless you are starting a PCDUnixHost object). The necessary lines are shown below.

ksh or sh users:

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

csh users:

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

2.1 To start a single host Legion system.

Choose a machine to be the bootstrap host and run the following:

$ legion_setup_state
$ legion_startup
$ legion_initialize
$ $LEGION_OPR/setup.{sh | csh}
$ legion_init_security
$ legion_login /users/admin

If you do not wish to use security, do not run legion_init_security and legion_login. However, please note that you cannot change your mind later on and enable security after you've been working in the system. Security must be turned on immediately after starting a new system.

If you are starting up on a PCD host, the process is slightly different. Before you run legion_initialize, you need to set the LEGION_HOST_BIN variable. So, the procedure looks like this:

$ LEGION_HOST_BIN=PCDUnixHost
$ legion_setup_state
$ legion_startup
$ legion_initialize
$ $LEGION_OPR/setup.{sh | csh}
$ legion_init_security
$ legion_login /users/admin

2.2 To start a multihost Legion system.

You will need to select a bootstrap host and start up Legion as outlined above and then add new host objects on the desired machines. HOWEVER, you must be able to run rsh/ssh on the bootstrap host as well as on the target hosts from the bootstrap host without having to enter a password. You can set up an .rhosts file for rsh or an authorized_keys file for ssh to accomplish this: see the rsh and ssh man pages for further information.

2.2.1 Set up

You'll need to set the proper environment variable on the bootstrap host and the remote host(s) so that you can run Legion commands on a remote host using rsh or ssh.

For sh, ksh, or bash:

LEGION_RSH=<rsh|ssh>
LEGION_RCP=<rcp|scp>
export LEGION_RSH LEGION_RCP

For csh:

setenv LEGION_RSH <rsh|ssh>
setenv LEGION_RCP <rcp|scp>

Set these variables on the bootstrap host before you start the new system (i.e., before you run legion_startup). Please note that you only need to follow these steps on the bootstrap host: you will need to install the Legion binaries on any other machines that you add to your system, but you do not need to start more Legion systems.

To add additional hosts and users, copy the $LEGION_OPR/setup.[sh | csh] scripts to a globally accessible location. Hosts can share an NFS-mounted Legion tree, but for best results you should place the OPRs on a local disk.

2.2.2 Create a new vault

If the new host will not be compatible with your existing vaults, create a new vault object with the legion_startvault command.

$ legion_startvault -L <path_to_Legion> -O <path_to_OPR> -U <user> \
  -A <arch> <host_name>

2.2.3 Create a new host

Use the legion_starthost command to create a new host object on the desired host.

$ legion_starthost -L <path_to_Legion> -O <path_to_OPR> -U <user> \
  -A <arch> <new_host_name> /vaults/vault-<new_host_name>

If you are creating a PCD host object, enter:

$ legion_starthost -L <path_to_Legion> -O <path_to_OPR> -U <user> \
  -A <arch> -B PCDUnixHost <new_host_name> /vaults/vault-<new_host_name>

If you are creating a batch queue host object, enter:

$ legion_starthost -L <path_to_Legion> -O <path_to_OPR> \
  -U <user> -A <arch> -B BatchQueueHost <new_host_name>
  /vaults/vault-<new_host_name>
$ legion_update_attributes -c /hosts/<new_host_name> \
  -a "host_queue_type('<Queue_type>')"

Note that you need to update the host object's attributes to include the host's queue type.

If the new host has a new architecture, you now need to add implementations of the core objects for the new architecture. Log in to the new machine and run the following:

$ source <path_to_globally_visable_setup_script>/setup.[sh | csh]
$ legion_login /users/admin
[run legion_login only if you have enabled Legion security]
$ legion_init_arch

Repeat these steps for each additional host. We suggest that you customize these steps and write a script to simplify the process, especially if you need to bring up a big net.

2.2.4 Adding new users

To add users to a secure net, run:

$ legion_create_user <new_user_name>

If you are working on a PCD host, follow up with these steps:

$ for i in `legion_ls /hosts'
$ do
$ legion_add_host_account -c /hosts/$i <unix_id> /users/<new_user_name>
$ done

You will need to wait an hour for new user account(s) to be available.

2.2.5 Working in the new net

Users can work in an insecure net by entering:

$ source <path_to_globally_visable_setup_script>/setup.[sh | csh]

User can work in a secure net by entering:

$ source <path_to_globally_visable_setup_script>/setup.[sh | csch]
$ legion_login /users/<user_name>
$ legion_cd /home/<user_name>

Please note that neither of these will open a separate shell.

2.3 To create a multidomain net

This involves connecting two or more Legion system together. A Legion system is known as a domain, since it is self-contained and can run independently. Multiple domains can be combined to create a larger virtual machine. Each domain maintains its own independence and rules but objects can communicate with and call upon the services of objects in connected domains. A multidomain net is created by making the domains' LegionClass objects aware of one another and connecting the binding trees of the domains together. For a longer discussion of this subject, please see the System Administrator manual.

2.4 To add virtual hosts

Virtual hosts all you to use resources on unsupported platforms. A special host object called a virtual host object represents the unsupported host (known as the virtual host), resides on a Legion host and represents the unsupported host's resources. The virtual host object can then run native jobs with standard Legion tools. This allows transparent, simplified scheduling and remote execution on the unsupported target machine via Legion mechanisms.

Start with a working Legion system, either single host or multihost. Log in to one of the hosts in the system and create a normal host object on one of the system's hosts (not the virtual host). This host, known as the physical host, must be able to start jobs on the virtual host (via a queueing system, ssh, etc.). Then set the virtual host architecture for the new host object. Then configure the virtual run scripts for the virtual host.

$ legion_starthost -N /hosts/<virtual_host_name> /vaults/<compatible_vault>
$ legion_set_varch -c /hosts/<virtual_host_name>
$ legion_set_vrun -c /hosts/<virtual_host_name> <path_for_scripts>

Please see the System Administrator manual for a more complete discussion of this topic.

	Click on the to go to the page.
	Logging in to a running Legion system Introduction to Legion context space Context-related commands Legion tty objects Running a PVM code in Legion Running a Legion MPI code Running native MPI code		Quick list of all 1.7 Legion commands Usage of all 1.7 Legion commands FAQs for running programs in Legion Starting a new Legion system Legion security Legion host and vault objects Adding host and vault objects Brief descriptions of all on-line tutorials