12.0 Process control daemon host objects

In a normal host object all objects run under the same Unix user id, making it difficult to isolate and account for different objects: in other words, if an outside user runs processes on your host, his processes will run under the same Unix user id as your processes. To solve this problem, Legion 1.6.x lets you create a second type of Unix host object, a process control daemon (PCD) host object. A PCD host object uses the services of a daemon, which executes as root in order to provide the host object with controlled access to a limited set of privileged operations. That is, the daemon oversees the host object's processes, regulating ownership of each process. This daemon must be started by someone with root privileges on the host (i.e. a system administrator). Typically, the PCD is configured to start through inetd.

Legion users who have Unix accounts on the host are tracked by their Unix user ids and guest users can be assigned a temporary Unix guest account user id. The PCD host object assigns guest user status to outside users and tracks each process's owner. This prevents malicious users from interfering with other users' processes.

12.1 Adding a PCD host object

12.1.1 Configure the daemon

Before you start up a PCD host object, you must start the process control daemon if it is not already running. You can install a daemon with inetd (explained below). These steps only need to be run once.

The daemon is able to carry out the following operations:

  • Spawn a given process, with a given environment, with a given user id. This user id must be listed in a file of authorized user ids called PCD_readUserFile.
  • Kill a process. The process must be owned by a user listed in the authorized user id file PCD_readUserFile. The implementation of this operation currently depends on the /proc file system.
  • Kill all of a given user's processes. The user must be listed in the authorized user id file PCD_readUserFile.
  • Recursively change directory ownership to a given user. The user id must be listed in the authorized user id file PCD_readUserFile.

If you wish to use a PCD host object as your net's BootstrapHost, the Legion administrator must set LEGION_HOST_BIN=PCDUnixHost in his/her environment before running legion_initialize.

To install the Legion process control daemon on a host, perform the following steps while logged in as root:

  1. Add the following line to your Unix /etc/services file:
  2. legion_host	4000/tcp	# Legion procControlD
  3. You need to set values for procControl-d. This daemon lives on the host: when a Legion user wants to start a process on the host, the PCD host maps the user's Legion user to a Unix user and passes the information to procControl-d, which then creates the requested process under the user's Unix account. It takes the following arguments:
    -m <user file>

    Names a local file containing a list of Unix user accounts that procControl-d can spawn processes under.

    -c <client file>

    Names a local file containing a list of Unix users who have permission to access procControl-d. We recommend that this file contain only the Unix account under which the PCD host is running.

    -s <spawn dir>

    Names a local directory under which the PCD can spawn processes. We recommend that this directory be the same as the host/vault pair's $LEGION_OPR directory.

    -l <core dir>

    Name the local directory under which the PCD will spawn core Legion objects. We recommend that this be the same as the $LEGION/bin directory.

    We recommend that you set all four of these arguments. Add a line to your Unix /etc/inetd.conf file, replacing the "/home/legion-admin/OPR" argument with the location of your OPR directory and "/home/legion-admin/Legion/bin" argument with the location of your Legion bin directory.

  4. legion_host stream tcp nowait root /etc/procControl-d procControl-d
    -m /etc/LegionUsers -c /etc/LegionClients -s /home/legion-admin/OPR
    -l /home/legion-admin/Legion/bin
  5. Create the Unix file /etc/LegionUsers. List the user-ids of managed accounts in this files (the user-ids that the daemon will be able to spawn processes as), one user-id per line. This file must be owned by root and have mode 0640 (grant read permissions to the group). Be sure to set the file's group to a group that contains the Legion system administrator. E.g.,
    $ chgrp legion-group /etc/LegionUsers

    where legion-group is the group that the system administrator's account belongs to).

  6. Create the Unix file /etc/LegionClients. List the user-ids that will be able to connect to the daemon. This should probably contain a single user-id: the account that the UnixHostObject is running on. This file must be owned by root and have mode 0640 (grant read permissions to the group). Be sure to set the file's group to a group that contains the Legion system administrator. E.g.,
    $ chgrp legion-group /etc/LegionUsers

    where legion-group is the group that the system administrator's account belongs to).

  7. Copy the executable program procControl-d into /etc/procControl-d (in your Unix directory). This executable file can be obtained from the local Legion administrator. It resides by default in $LEGION/bin/$LEGION_ARCH/procControl-d under the home directory of the Legion administrator. Make sure that /etc/procControl-d has mode 0500.
  8. Restart inetd by running killall -HUP inetd.
  9. Run pcdCheckConfig to make sure that all is well. This binary executable checks that procControl-d has a valid configuration. If the configuration is incorrect the host object will not function.

    It does not need to be run by root, but it does need to be run with read permissions to the /etc/LegionUsers and /etc/LegionClients files. E.g., if these files can be read by a group that includes the Legion system administrator, pcdCheckConfig can be run by the system administrator.

12.1.2 Start the daemon and the host object

You need to be logged in as /users/admin to start up a PCD host object. To start up a PCD host object on a PCD host run legion_starthost with the -B flag (see page 47) on the host.

$ legion_starthost -B PCDUnixHost PCD.host.DNS.name \

This starts the PCD host, which in turn starts the daemon. The daemon checks its configuration to make sure that it is valid (which it should be, if you ran pcdCheckConfig) and establishes a connection with its host. The host object will then report to the host class and run normally.

Note that the example above assumes that you have already started a compatible vault object. We recommend that the vault reside on the PCD host.

Once you have started the PCD host object and (if necessary) the accompanying vault, you must change the following file permissions on the node that is actually running the PCD host.

$LEGION_OPR should be set to 755
$LEGION_OPR/LegionClass.config* should be set to 644
$LEGION_OPR/BootstrapVaultOPR should be set to 777
    (If your bootstrap host is a PCD host)
$LEGION_OPR/<vault_name>.OPA should be set to 777
    (If the bootstrap host is not a PCD host)

These changes should be made by the Legion administrator.

A PCD host object will behave very much like a normal Unix host object, so most users do not need to know whether or not their processes are running on one or the other.

12.2 PCD host commands

There are three Legion commands for PCD host objects: legion_add_host_account, for adding new accounts to the list of available accounts; legion_list_host_accounts, for viewing the list of available accounts; and legion_remove_host_account, for removing an account from the list of available accounts.

12.2.1 Adding a new account

The legion_add_host_account command adds a mapping between a Legion account and a Unix account and adds this mapping to a PCD host object's list of available accounts.

The user's Unix user id is named in the <Unix user id> parameter. The host object is named in the <host object LOID> or <host object context path> parameter.

  -l <host object LOID> | -c <host object context path>}
  {[-f <mapping file name>] |
    [<Unix user id> [-l <owner LOID> | -c <owner context path>]]}
  [-debug] [-help]

The user's Legion user id can be given in the [-l <owner LOID> | -c <owner context path>] parameter or listed in a file: this parameter designates the ownership of the <Unix user id>, so that when a Unix user creates Legion processes on the host object the processes will automatically run under the proper Unix user id. If the Legion id parameter is left empty, the Unix user will be treated as a guest user. This command does not create a new Legion user id: use the legion_create_user command to create an id if necessary.

Alternatively, you can create a local mapping file that contains a list of Unix-Legion account mappings. This file contains a list of Unix user ids (one per line) and any corresponding Legion user ids. There is no limit on the number of mappings that can be listed. If no Legion account is named, the account will be treated as a guest account. Suppose that you want to map three accounts: one guest account, and one each for your Unix users John and Lucy. The mapping file below shows how to do this.

unixLucy	-c /users/lucy
unixJohn	-c /users/john

Of, you could do this from the command line. The examples below map the accounts for a PCD host object called myPCDhost.

$ legion_add_host_account  /hosts/myPCDhost guest
$ legion_add_host_account  /hosts/myPCDhost unixLucy -c /users/lucy
$ legion_add_host_account  /hosts/myPCDhost unixJohn  -c /users/john

In John's case, a mapping for unixJohn would be created on myPCDhost and john would be its owner. When John (logged in to his Legion account) asks to runs a process on myPCDhost, the PCD demon will automatically execute it on his unixJohn account. If, on the other hand, you did not name John as the account owner:

$ legion_add_host_account /hosts/myPCDhost unixJohn

a mapping for unixJohn will be added but it will be a guest mapping. If any Legion user who does not already have a mapping runs a process on myPCDhost he or she will run under a guest account that is not currently in use. If John runs a process on myPCDhost the process will execute on a guest account, not the unixJohn account.

12.2.2 Removing an account

The legion_remove_host_account command removes one or more account mappings from the host object's list of available accounts.

   {-l <host object LOID> | [-c] <host object context path>}
   <user id> [-debug] [-help]

As with legion_add_host_account, the <user id> parameter is the user's Unix user id. If no host is named in the <host object LOID>/<host object context path> parameter, your current host object is the default.

12.2.3 Viewing available accounts

The legion_list_host_accounts command lists the available accounts on a host object. If no host object argument is provided, your current host object will be used as a default.

   [-l <host object LOID> | [-c] <host object context path>]
   [-debug] [-help]

12.3 How the PCD host object works

When an object creation request arrives at a PCD host object as a normal method invocation. The host object checks the request credentials against the user's LOID and the list of groups that are allowed to create objects on the host object. If all is acceptable, the host object selects an account for the new object. Depending on the creation request's credentials, it may choose a local user account or a generic (i.e., guest) account. Accounts are subject to scheduling and resource control (CPU time, memory usage, etc.), so an object's lease on an account, especially a generic account, is limited.

When a class object sends an object creation request to the host object (Figure 7, step 4), it includes the new object's OPA as a parameter. The OPA contains the new object's vault directory (i.e., where the new object's persistent state will be stored), so before starting the creation process the PCD host object must switch the ownership of the new object's vault directory from the vault user id to the newly allocated user id. This switch gives the new object access to its persistent state and protects it against other objects (who will be running under different user ids).

The host object can then start the creation process, which will execute the object on the appropriate account. This involves some privileged operations (listed on page 51, above). The host object does not execute with root permissions: access to privileged operations is encapsulated in the PCD that runs on the host object. The PCD is configured to allow only the host object to have access to these operations. Two of its key functions are permitting the host object to change directory ownership and creating new processes on a designated account only. The PCD limits the accounts in which these two functions can be done to a set designated by the local system administrator. This set includes any generic (guest) Unix accounts and local Unix users that the administrator wishes to add.

PCDs can be used in two ways. First, they can multiplex objects onto multiple user accounts, thus providing a level of protection for user objects and, when combined with user log ins, making it possible to audit a user's actions. Second, they can match an object's effective user id to match the user's Unix user id, making it easier to track user actions. As discussed in section 11.3.2, Legion maintains logs for all host objects in the $OPR directory, and the PCD host object logs will include information about when different Unix users ids were used by Legion users.

12.4 Using a PCD host as your bootstrap host

You can use a PCD host as your bootstrap host. Before you run legion_initialize set the LEGION_HOST_BIN variable:


Directory of Legion 1.6.4 Manuals
[Home] [General] [Documentation] [Software]
[Testbeds] [Et Cetera] [Map/Search]

Free JavaScripts provided by The JavaScript Source