Chapter 6

Projects and Tasks

This chapter discusses the project and task facilities of Solaris resource management. Projects and tasks are used to label workloads and separate them from one another. The project provides a network-wide administrative identifier for related work. The task collects a group of processes into a manageable entity that represents a workload component.

Overview

To optimize workload response, you must first be able to identify the workloads that are running on the system you are analyzing. This information can be difficult to obtain by using either a purely process-oriented or a user-oriented method alone. In the Solaris environment, you have two additional facilities that can be used to separate and identify workload: the project and the task.

Running processes can be manipulated with standard Solaris commands, based on their project or task membership. The extended accounting facility can report on both process usage and task usage, and tag each record with the governing project identifier. This process enables offline workload analysis to be correlated with online monitoring. The project identifier itself can be shared across multiple machines through the project name service database. Thus, the resource consumption of related workloads that run on (or span) multiple machines can ultimately be analyzed across all of the machines.

Projects

The project identifier is an administrative identifier that is used to identify related work. The project identifier can be thought of as a workload tag equivalent to the user and group identifiers. A user or group can belong to one or more projects. These projects can be used to represent the workloads in which the user (or group of users) is allowed to participate. This membership can then be the basis of chargeback that is based on, for example, usage or initial resource allocations. Although a user must have a default project assigned, the processes that the user launches can be associated with any of the projects of which that user is a member.

Determining a User's Default Project

To log in to the system, a user must be assigned a default project.

Because each process on the system possesses project membership, an algorithm to assign a default project to the login or other initial process is necessary. The algorithm to determine a default project consists of four steps. If no default project is found, the user's login (or request to start a process) is denied.

The system sequentially follows these steps to determine a user's default project:

If the user has an entry with a project attribute defined in the /etc/user_attr extended user attributes database, then the value of the project attribute is the default project (see user_attr(4)).
If a project with the name user.user-id is present in the project(4) database, then that project is the default project.
If a project with the name group.group-name is present in the project database, where group-name is the name of the default group for the user (as specified in passwd(4)), then that project is the default project.
If the special project default is present in the project database, then that project is the default project.

This logic is provided by the getdefaultproj() library function (see getprojent(3PROJECT)).

`project` Database

You can store project data in a local file, in a Network Information Service (NIS) project map, or in a Lightweight Directory Access Protocol (LDAP) directory service. The /etc/project database or name service is used at login and by all requests for account management by the pluggable authentication module (PAM) to bind a user to a default project.

Note - Updates to entries in the project database, whether to the /etc/project file or to a representation of the database in a network name service, are not applied to currently active projects. The updates are applied to new tasks that join the project when login(1) or newtask(1) is used.

PAM Subsystem

An operation can involve changing or setting identity, such as logging in to the system, invoking an rcp or rsh command, using ftp, or using su. In those situations, a set of configurable modules is used to provide authentication, account management, credentials management, and session management.

The account management PAM module for projects is documented in the pam_projects(5) man page. The PAM system is documented in the man pages pam(3PAM), pam.conf(4), and pam_unix(5).

Name Service Configuration

Resource management supports the name service project database. The location where the project database is stored is defined in /etc/nsswitch.conf. By default, files is listed first, but the sources can be listed in any order.

project: files [nis] [ldap]

If more than one source for project information is listed, the nsswitch.conf file directs the routine to start searching for the information in the first source listed, then search subsequent databases.

For more information on /etc/nsswitch.conf, see "The Name Service Switch" in System Administration Guide: Naming and Directory Services (DNS, NIS, and LDAP) and nsswitch.conf(4).

Local `project` File Format

If you select files as your project database in nsswitch.conf, the login process searches the /etc/project file for project information (see projects(1) and project(4)). The project file contains a one-line entry for each project that is recognized by the system, of the following form:

projname:projid:comment:user-list:group-list:attributes

The fields are defined as follows.

projname

The name of the project. It must be a string that consists of alphanumeric characters, the underline (_) character, and the hyphen (-). The name must begin with an alphabetic character. projname cannot contain periods (.), colons (:), or newline characters.

projid

The project's unique numerical ID (PROJID) within the system. The maximum value of the projid field is UID_MAX (2147483647).

comment

The project's description.

user-list

A comma-separated list of users who are allowed in the project.

Wildcards can be used in this field. The asterisk (*) allows all users to join the project. The exclamation point followed by the asterisk (!*) excludes all users from the project. The exclamation mark (!) followed by a user name excludes the specified user from the project.

group-list

A comma-separated list of groups of users who are allowed in the project.

Wildcards can be used in this field. The asterisk (*) allows all groups to join the project. The exclamation point followed by the asterisk (!*) excludes all groups from the project. The exclamation mark (!) followed by a group name excludes the specified group from the project.

attributes

A semicolon-separated list of name-value pairs (see Chapter 8, Resource Controls). name is an arbitrary string that specifies the object-related attribute, and value is the optional value for that attribute.
name[=value]

In the name-value pair, names are restricted to letters, digits, underscores, and the period. The period is conventionally used as a separator between the categories and subcategories of the rctl. The first character of an attribute name must be a letter. The name is case sensitive.

Values can be structured by using commas and parentheses to establish precedence. The semicolon is used to separate name-value pairs and cannot be used in a value definition. The colon is used to separate project fields and cannot be used in a value definition.

Note - Routines that read this file halt when they encounter a malformed entry, so any project assignments that are specified after the incorrect entry are not made.

This example shows the default /etc/project file:

system:0:System:::
user.root:1:Super-User:::
noproject:2:No Project:::
default:3::::
group.staff:10::::

This example shows the default /etc/project file with project entries added at the end:

system:0:System:::
user.root:1:Super-User:::
noproject:2:No Project:::
default:3::::
group.staff:10::::
user.ml:2424:Lyle Personal:::
booksite:4113:Book Auction Project:ml,mp,jtd,kjh::

To add resource controls to the /etc/project file, see "Using Resource Controls".

Name Service Configuration for NIS

If you are using NIS, you can specify in the /etc/nsswitch.conf file to search the NIS maps for projects:

project: nis files

The NIS map, either project.byname or project.bynumber, has the same form as the /etc/project file:

projname:projid:comment:user-list:group-list:attributes

For more information, see System Administration Guide: Naming and Directory Services (DNS, NIS, and LDAP).

Directory Service Configuration for LDAP

If you are using LDAP, you can specify in the /etc/nsswitch.conf file to search the LDAP entries for projects.

project: ldap files

For more information, including the schema for project entries in an LDAP database, see "LDAP Schemas (Reference)" in System Administration Guide: Naming and Directory Services (DNS, NIS, and LDAP).