Legion 1.4
System Administrator Manual

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.4 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 the legion_starthost command with the -B flag (please see More about legion_starthost for information about the legion_starthost flags) on the host. The output should look something like this:

Note that a PCD host object will behave very much like a normal Unix host object and that most users do not need to even know whether or not their processes are running on one or the other. PCD host objects are designed to help system administrators protect their resources and their users.

$ legion_starthost -B PCDHostObject PCD.host.DNS.name /vaults/vault.DNS.name
Creating a Legion host object with the following attributes:
	Host	= "PCD.host.DNS.name"
	Context name	= "/hosts/new.host.DNS.name"
	$LEGION	= "/home/xx/Legion"
	$LEGION_OPR	= "/home/xx/OPR"
	$LEGION_OPA	= "/home/xx/OPR/PCD.host.DNS.name.OPA"
	Architecture	= "linux"
	User id	= "xx"
	Binary path	= "/home/xx/Legion/bin/linux/PCDUnixHost"
	Compatible vaults  = "vaults/BootstrapVault"
Transferring configuration files to "xx@PCD.host.DNS.name:/home/xx/OPR"
Creating an instance of "/class/UnixHostClass"
Adding "/hosts/new.host.DNS.name" to the host list for
Added 1 host(s) to vault's compatibility set
Adding "vaults/BootstrapVault" to the vault list for
Added 1 vault(s) to host's compatibility set
Configuring well-known binaries for "/hosts/PCD.host.DNS.name"

There are, however, three Legion commands designed 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. The usage of these commands is below.

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

So, suppose that you want to add an account for Legion user john on a PCD host object called myPCDhost. John has Unix user id abcd47. If you were to enter:

$ legion_add_host_account -c /hosts/myPCDhost abcd47 -l /user/john

A new user account called abcd47 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 abcd47 account. If, on the other hand, you enter:

$ legion_add_host_account -c /hosts/myPCDhost abcd47

A new user account, called abcd47, would be created, but John does not own it. If John (logged in as user john) runs a process on myPCDhost, the PCD will execute it on a guest account.

10.1.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.1.3 Viewing the list of available account

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

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

The host object can be listed in the [-l <host object LOID> | -c <host object context path>] parameter, or, if this parameter is left empty, the current host object will be used as a default.

10.2 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 (step 4 in Figure 6), 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.

PDCs 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