10.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.5 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.

10.1 Adding a PCD host object

Before you start up a PDC host object, you must be logged into the host as a root user. You must also start the process control daemon, if it is not already running. You can install a daemon with inetd (explained below).

The daemon is able to carry out the following operations:

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 /etc/services:
  2. legion_host	4000/tcp	# Legion procControlD
  3. Add the following line to /etc/inetd.conf, replacing the "/home/legion-admin/OPR" argument with the home directory of the local Legion administrator:
  4. legion_host stream tcp nowait root /etc/procControl-d
    procControl-d -m /etc/LegionUsers -c /etc/LegionClients 
    -s /home/legion-admin/OPR
  5. Create the 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 0600.
  6. Create the file /etc/LegionClients. List the user-ids that will be able to connect to the daemon. This should probably contain a single user-id: that of the Legion administrator for the site. This file must be owned by root and have mode 0600.
  7. Copy the executable program procControl-d into /etc/procControl-d. 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.

To start up a PCD host object on a PCD host run legion_starthost with the -B flag (see legion_starthost flags) on the host.

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

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.

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

10.2.1 Adding a new account

The legion_add_host_account command adds one or more accounts to a PCD host object's list of available accounts.

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

The user's Unix user id is named in the <Unix user id> parameter. The host object is named in the {-l <host object LOID> | -c <host object context path>} parameter. The user's Legion user id can be given in the [-l <owner LOID> | -c <owner context path>] parameter: this designates the ownership of the <Unix user id>, so that when that user creates processes on the host object the processes will automatically run under that Unix user id. If this parameter is left empty, the user will be treated as a guest user.

Suppose that you want to add an account for user john on a PCD host object called myPCDhost. John has Unix user id unixJohn. If you were to enter:

$ legion_add_host_account -c /hosts/myPCDhost unixJohn \
  -c /users/john

A new user account called unixJohn would be created and user john would be its owner. When John (logged in as user john) asks to runs a process on myPCDhost, the PCD demon will automatically it execute on his unixJohn account. If, on the other hand, you did not name John as the account owner:

$ legion_add_host_account -c /hosts/myPCDhost unixJohn

the new user account unixJohn will be created but John will not own the account. If John runs a process on myPCDhost the process will execute on a guest account, not the unixJohn account.

10.2.2 Removing an account

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

{-l <host object LOID> | -c <host object context path>}
<user id>

As with legion_add_host_account, the <user id> parameter is the user's Unix user id. If no host is named in the [-l <host object LOID> | -c <host object context path>] parameter your current host object is the default.

10.2.3 Viewing available accounts

The legion_list_host_accounts command lists the available accounts on a host object.

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

If no host object argument is provided, your current host object will be used as a default.

10.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 the 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 6, 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 in Adding a PCD host object, 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 whichever local Unix users 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 The host object's log, 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.

Back to System Administrator Manual Table of Contents

Directory of Legion 1.5 Manuals