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 following topics are covered in this chapter:
To use the projects and tasks facilities, see Chapter 3, Administering Projects and Tasks.
Solaris 10 enhancements include the following:
Scaled value and unit modifier support for resource control values and commands
Improved validation and easier manipulation of the project attributes field
Revised output format and new options for the prctl and projects commands
Ability to set user's default project through the useradd command and modify information by using the usermod and passmgmt commands
In addition to the information contained in this chapter and Chapter 6, Resource Controls (Overview), see the following man pages:
Solaris 10 5/08 enhancements include the addition of a -A option to the projmod command. See Commands Used With Projects and Tasks.
For a complete listing of new Solaris 10 features and a description of Solaris releases, see Oracle Solaris 10 9/10 What’s New.
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 system, you have two additional facilities that can be used to separate and identify workloads: the project and the task. 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.
The controls specified in the project name service database are set on the process, task, and project. Since process and task controls are inherited across fork and settaskid system calls, all processes and tasks that are created within the project inherit these controls. For information on these system calls, see the fork(2) and settaskid(2) man pages.
Based on their project or task membership, running processes can be manipulated with standard Solaris commands. 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 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.
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 be assigned to a default project, the processes that the user launches can be associated with any of the projects of which that user is a member.
To log in to the system, a user must be assigned a default project. A user is automatically a member of that default project, even if the user is not in the user or group list specified in that 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 is documented in the man page getprojent(3C). The system follows ordered steps to determine the default project. 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 the user_attr(4) man page.
If a project with the name user.user-id is present in the project database, then that project is the default project. See the project(4) man page for more information.
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 the passwd file, then that project is the default project. For information on the passwd file, see the passwd(4) man page.
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 the getprojent(3PROJECT) man page for more information.
You can use the following commands with the -K option and a key=value pair to set user attributes in local files :
Modify user information
Set default project for user
Modify user information
Local files can include the following:
If a network naming service such as NIS is being used to supplement the local file with additional entries, these commands cannot change information supplied by the network name service. However, the commands do verify the following against the external naming service database:
Uniqueness of the user name (or role)
Uniqueness of the user ID
Existence of any group names specified
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 file or naming 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.
Updates to entries in the project database, whether to the /etc/project file or to a representation of the database in a network naming service, are not applied to currently active projects. The updates are applied to new tasks that join the project when either the login or the newtask command is used. For more information, see the login(1) and newtask(1) man pages.
Operations that change or set identity include logging in to the system, invoking an rcp or rsh command, using ftp, or using su. When an operation involves changing or setting an identity, 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. For an overview of PAM, see Chapter 17, Using PAM, in System Administration Guide: Security Services.
Resource management supports naming service project databases. The location where the project database is stored is defined in the /etc/nsswitch.conf file. 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, and then search subsequent sources.
For more information about the /etc/nsswitch.conf file, see Chapter 2, The Name Service Switch (Overview), in System Administration Guide: Naming and Directory Services (DNS, NIS, and LDAP) and nsswitch.conf(4).
If you select files as your project database source in the nsswitch.conf file, the login process searches the /etc/project file for project information. See the projects(1) and project(4) man pages for more information.
The project file contains a one-line entry of the following form for each project recognized by the system:
The fields are defined as follows:
The name of the project. The name must be a string that consists of alphanumeric characters, underline (_) characters, hyphens (-), and periods (.). The period, which is reserved for projects with special meaning to the operating system, can only be used in the names of default projects for users. projname cannot contain colons (:) or newline characters.
The project's unique numerical ID (PROJID) within the system. The maximum value of the projid field is UID_MAX (2147483647).
A description of the project.
A comma-separated list of users who are allowed in the project.
Wildcards can be used in this field. An asterisk (*) allows all users to join the project. An exclamation point followed by an asterisk (!*) excludes all users from the project. An exclamation mark (!) followed by a user name excludes the specified user from the project.
A comma-separated list of groups of users who are allowed in the project.
Wildcards can be used in this field. An asterisk (*) allows all groups to join the project. An exclamation point followed by an asterisk (!*) excludes all groups from the project. An exclamation mark (!) followed by a group name excludes the specified group from the project.
A semicolon-separated list of name-value pairs, such as resource controls (see Chapter 6, Resource Controls (Overview)). name is an arbitrary string that specifies the object-related attribute, and value is the optional value for that attribute.
In the name-value pair, names are restricted to letters, digits, underscores, and periods. A period is conventionally used as a separator between the categories and subcategories of the resource control (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.
A semicolon is used to separate name-value pairs. A semicolon cannot be used in a value definition. A colon is used to separate project fields. A colon cannot be used in a value definition.
Routines that read this file halt if they encounter a malformed entry. Any projects that are specified after the incorrect entry are not assigned.
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::
You can also add resource controls and attributes to the /etc/project file:
To add resource controls for a project, see Setting Resource Controls.
To define a physical memory resource cap for a project using the resource capping daemon described in rcapd(1M), see Attribute to Limit Physical Memory Usage for Projects.
To add a project.pool attribute to a project's entry, see Creating the Configuration.
If you are using NIS, you can specify in the /etc/nsswitch.conf file to search the NIS project maps for projects:
project: nis files
The NIS maps, either project.byname or project.bynumber, have the same form as the /etc/project file:
If you are using LDAP, you can specify in the /etc/nsswitch.conf file to search the LDAP project database for projects:
project: ldap files
For more information about LDAP, see Chapter 8, Introduction to LDAP Naming Services (Overview/Reference), in System Administration Guide: Naming and Directory Services (DNS, NIS, and LDAP). For more information about the schema for project entries in an LDAP database, see Solaris Schemas in System Administration Guide: Naming and Directory Services (DNS, NIS, and LDAP).
Each successful login into a project creates a new task that contains the login process. The task is a process collective that represents a set of work over time. A task can also be viewed as a workload component. Each task is automatically assigned a task ID.
All operations on process groups, such as signal delivery, are also supported on tasks. You can also bind a task to a processor set and set a scheduling priority and class for a task, which modifies all current and subsequent processes in the task.
A task is created whenever a project is joined. The following actions, commands, and functions create tasks:
You can create a finalized task by using one of the following methods. All further attempts to create new tasks will fail.
You can use the newtask command with the -F option.
You can set the task.final attribute on a project in the project naming service database. All tasks created in that project by setproject have the TASK_FINAL flag.
The extended accounting facility can provide accounting data for processes. The data is aggregated at the task level.
Man Page Reference
Displays project memberships for users. Lists projects from project database. Prints information on given projects. If no project names are supplied, information is displayed for all projects. Use the projects command with the -l option to print verbose output.
Executes the user's default shell or specified command, placing the execution command in a new task that is owned by the specified project. newtask can also be used to change the task and the project binding for a running process. Use with the -F option to create a finalized task.
Updates information in the password files. Use with the -K key=value option to add to user attributes or replace user attributes in local files.
Adds a new project entry to the /etc/project file. The projadd command creates a project entry only on the local system. projadd cannot change information that is supplied by the network naming service.
Can be used to edit project files other than the default file, /etc/project. Provides syntax checking for project file. Validates and edits project attributes. Supports scaled values.
Modifies information for a project on the local system. projmod cannot change information that is supplied by the network naming service. However, the command does verify the uniqueness of the project name and project ID against the external naming service.
Can be used to edit project files other than the default file, /etc/project. Provides syntax checking for project file. Validates and edits project attributes. Can be used to add a new attribute, add values to an attribute, or remove an attribute. Supports scaled values.
Starting with the Solaris 10 5/08 release, can be used with the -A option to apply the resource control values found in the project database to the active project. Existing values that do not match the values defined in the project file, such as values set manually by the prctlcommand, are removed.
Deletes a project from the local system. projdel cannot change information that is supplied by the network naming service.
Adds default project definitions to the local files. Use with the -K key=value option to add or replace user attributes.
Deletes a user's account from the local file.
Modifies a user's login information on the system. Use with the -K key=value option to add or replace user attributes.