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

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

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:
  4. -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.
    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.,
  6. $ chgrp legion-group /etc/LegionUsers
    where legion-group is the group that the system administrator's account belongs to).

  7. 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.,
  8. $ chgrp legion-group /etc/LegionUsers
    where legion-group is the group that the system administrator's account belongs to).

  9. 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.
  10. Restart inetd by running killall -HUP inetd.
  11. 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.

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 section 11.3.1) on the host.

$ legion_starthost -B PCDUnixHost PCD.host.DNS.name \
  /vaults/vault_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.

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.

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

The host object is named in the <host object LOID> or <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. (This command does not create a new Legion user id: use the legion_create_user command to create an id if necessary.)

Suppose that you want to map an account for user john on a PCD host object called myPCDhost. John's Unix user id is unixJohn and his Legion user id is john. If you were to enter:

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

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 not be owned by a single Legion user (i.e., by john). It will be a generic (i.e., guest) mapping: if any Legion user who does not already have a mapping runs a process on myPCDhost they will run under a generic account that is not currently in use, such as the unixJohn account. If John runs a process on myPCDhost the process will execute on a generic 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.

legion_remove_host_account
{-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.

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

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

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 (section 12.1). 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:

export LEGION_HOST_BIN=PCDUnixHost

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

Free JavaScripts provided by The JavaScript Source

legion@Virginia.edu
http://legion.virginia.edu/