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.
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 workloads: the project and the task.
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 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.
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)).
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.
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.
Operations that change or set identify include logging in to the system, invoking an rcp or rsh command, using ftp, or using su. When an operation involves changing or setting 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. The PAM system is documented in the man pages pam(3PAM), pam.conf(4), and pam_unix(5).
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. The routine then searches subsequent databases.
For more information on /etc/nsswitch.conf, see “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 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 recognized by the system, of the following form:
projname:projid:comment:user-list:group-list:attributes |
The fields are defined as follows.
The name of the project. The name 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.
The project's unique numerical ID (PROJID) within the system. The maximum value of the projid field is UID_MAX (2147483647).
The project's description.
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.
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.
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. The semicolon cannot be used in a value definition. The colon is used to separate project fields. The colon cannot be used in a value definition.
Routines that read this file halt when they encounter a malformed entry. 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.
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).
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 General Reference (Reference)” in System Administration Guide: Naming and Directory Services (DNS, NIS, and LDAP).
With each successful login into a project, a new task that contains the login process is created. 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 process is a member of one task, and each task is associated with one project.
All operations on sessions, such as signal delivery, are also supported on tasks. You can also bind tasks to processor sets and set their scheduling priorities and classes, which modifies all current and subsequent processes in the task.
Tasks are created at login (see login(1)), by cron(1M), by newtask(1), and by setproject(3PROJECT).
The extended accounting facility can provide accounting data for processes that is aggregated at the task level.
Command |
Description |
---|---|
Prints the project membership of a user. |
|
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 modify the task and the project binding for a running process. |
|
Adds a new project entry to the /etc/project file. projadd creates a project entry only on the local system. projadd cannot change information that is supplied by the network name service. |
|
Modifies a project's information on the local system. projmod cannot change information that is supplied by the network name service. However, the command does verify the uniqueness of the project name and project ID against the external name service. |
|
Deletes a project from the local system. projdel cannot change information that is supplied by the network name service. |
Use ps -o to display task and project IDs. For example, to view the project ID, type the following:
# ps -o user,pid,uid,projid USER PID UID PROJID jtd 89430 124 4113 |
Use id -p to print the current project ID in addition to the user and group IDs. If the user operand is provided, the project associated with that user's normal login is printed:
# id -p uid=124(jtd) gid=10(staff) projid=4113(booksite) |
To match only processes with a project ID in a specific list, type the following:
# pgrep -J projidlist # pkill -J projidlist |
To match only processes with a task ID in a specific list, type the following:
# pgrep -T taskidlist # pkill -T taskidlist |
To display various statistics for processes and projects that are currently running on your system, type the following:
% prstat -J PID USERNAME SIZE RSS STATE PRI NICE TIME CPU PROCESS/NLWP 21634 jtd 5512K 4848K cpu0 44 0 0:00.00 0.3% prstat/1 324 root 29M 75M sleep 59 0 0:08.27 0.2% Xsun/1 15497 jtd 48M 41M sleep 49 0 0:08.26 0.1% adeptedit/1 328 root 2856K 2600K sleep 58 0 0:00.00 0.0% mibiisa/11 1979 jtd 1568K 1352K sleep 49 0 0:00.00 0.0% csh/1 1977 jtd 7256K 5512K sleep 49 0 0:00.00 0.0% dtterm/1 192 root 3680K 2856K sleep 58 0 0:00.36 0.0% automountd/5 1845 jtd 24M 22M sleep 49 0 0:00.29 0.0% dtmail/11 1009 jtd 9864K 8384K sleep 49 0 0:00.59 0.0% dtwm/8 114 root 1640K 704K sleep 58 0 0:01.16 0.0% in.routed/1 180 daemon 2704K 1944K sleep 58 0 0:00.00 0.0% statd/4 145 root 2120K 1520K sleep 58 0 0:00.00 0.0% ypbind/1 181 root 1864K 1336K sleep 51 0 0:00.00 0.0% lockd/1 173 root 2584K 2136K sleep 58 0 0:00.00 0.0% inetd/1 135 root 2960K 1424K sleep 0 0 0:00.00 0.0% keyserv/4 PROJID NPROC SIZE RSS MEMORY TIME CPU PROJECT 10 52 400M 271M 68% 0:11.45 0.4% booksite 0 35 113M 129M 32% 0:10.46 0.2% system Total: 87 processes, 205 lwps, load averages: 0.05, 0.02, 0.02 |
To display various statistics for processes and tasks that are currently running on your system, type the following:
% prstat -T PID USERNAME SIZE RSS STATE PRI NICE TIME CPU PROCESS/NLWP 23023 root 26M 20M sleep 59 0 0:03:18 0.6% Xsun/1 23476 jtd 51M 45M sleep 49 0 0:04:31 0.5% adeptedit/1 23432 jtd 6928K 5064K sleep 59 0 0:00:00 0.1% dtterm/1 28959 jtd 26M 18M sleep 49 0 0:00:18 0.0% .netscape.bin/1 23116 jtd 9232K 8104K sleep 59 0 0:00:27 0.0% dtwm/5 29010 jtd 5144K 4664K cpu0 59 0 0:00:00 0.0% prstat/1 200 root 3096K 1024K sleep 59 0 0:00:00 0.0% lpsched/1 161 root 2120K 1600K sleep 59 0 0:00:00 0.0% lockd/2 170 root 5888K 4248K sleep 59 0 0:03:10 0.0% automountd/3 132 root 2120K 1408K sleep 59 0 0:00:00 0.0% ypbind/1 162 daemon 2504K 1936K sleep 59 0 0:00:00 0.0% statd/2 146 root 2560K 2008K sleep 59 0 0:00:00 0.0% inetd/1 122 root 2336K 1264K sleep 59 0 0:00:00 0.0% keyserv/2 119 root 2336K 1496K sleep 59 0 0:00:02 0.0% rpcbind/1 104 root 1664K 672K sleep 59 0 0:00:03 0.0% in.rdisc/1 TASKID NPROC SIZE RSS MEMORY TIME CPU PROJECT 222 30 229M 161M 44% 0:05:54 0.6% group.staff 223 1 26M 20M 5.3% 0:03:18 0.6% group.staff 12 1 61M 33M 8.9% 0:00:31 0.0% group.staff 1 33 85M 53M 14% 0:03:33 0.0% system Total: 65 processes, 154 lwps, load averages: 0.04, 0.05, 0.06 |
The -J and -T options cannot be used together.
The cron command issues a settaskid to ensure that each cron, at, and batch job executes in a separate task, with the appropriate default project for the submitting user. Also, the at and batch commands capture the current project ID and ensure that the project ID is restored when running an at job.
To switch the user's default project, and thus create a new task (as part of simulating a login) type the following:
# su - user |
To retain the project ID of the invoker, issue su without the - flag.
# su user |
This example shows how to use the projadd and projmod commands.
Become superuser.
View the default /etc/project file on your system.
# cat /etc/project system:0:::: user.root:1:::: noproject:2:::: default:3:::: group.staff:10:::: |
Add a project called booksite and assign it to a user named mark with project ID number 4113.
# projadd -U mark -p 4113 booksite |
View the /etc/project file again to see the project addition.
# cat /etc/project system:0:::: user.root:1:::: noproject:2:::: default:3:::: group.staff:10:::: booksite:4113::mark:: |
Add a comment that describes the project in the comment field.
# projmod -c `Book Auction Project' booksite |
View the changes in the /etc/project file.
# cat /etc/project system:0:::: user.root:1:::: noproject:2:::: default:3:::: group.staff:10:::: booksite:4113:Book Auction Project:mark:: |
This example shows how to use the projdel command to delete a project.
Become superuser.
Remove the project booksite by using the projdel command.
# projdel booksite |
Display the /etc/project file.
# cat /etc/project system:0:::: user.root:1:::: noproject:2:::: default:3:::: group.staff:10:::: |
Log in as user mark and type projects to view the projects assigned.
# su - mark # projects default |
Use the id command with the -p flag to view the current project membership of the invoking process.
$ id -p uid=100(mark) gid=1(other) projid=3(default) |
Become superuser.
Create a new task in the booksite project by using the newtask command with the -v (verbose) option to obtain the system task ID.
# newtask -v -p booksite 16 |
The execution of newtask creates a new task in the specified project, and places the user's default shell in this task.
View the current project membership of the invoking process.
# id -p uid=100(mark) gid=1(other) projid=4113(booksite) |
The process is now a member of the new project.
This example shows how to associate a running process with a different task and project. To perform this task, you must either be superuser, or be the owner of the process and be a member of the new project.
Become superuser.
Obtain the process ID of the book_catalog process.
# pgrep book_catalog 8100 |
Associate process 8100 with a new task ID in the booksite project.
# newtask -v -p booksite -c 8100 17 |
The -c option specifies that newtask operate on the existing named process.
Confirm the task to process ID mapping.
# pgrep -T 17 8100 |