System Administration Guide: Virtualization Using the Solaris Operating System

Chapter 3 Administering Projects and Tasks

This chapter describes how to use the project and task facilities of Solaris resource management.

The following topics are covered.

For an overview of the projects and tasks facilities, see Chapter 2, Projects and Tasks (Overview).


Note –

If you are using these facilities on a Solaris system with zones installed, only processes in the same zone will be visible through system call interfaces that take process IDs when these commands are run in a non-global zone.


Administering Projects and Tasks (Task Map)

Task 

Description 

For Instructions 

View examples of commands and options used with projects and tasks. 

Display task and project IDs, display various statistics for processes and projects that are currently running on your system. 

Example Commands and Command Options

Define a project. 

Add a project entry to the /etc/project file and alter values for that entry.

How to Define a Project and View the Current Project

Delete a project. 

Remove a project entry from the /etc/project file.

How to Delete a Project From the /etc/project File

Validate the project file or project database.

Check the syntax of the /etc/project file or verify the uniqueness of the project name and project ID against the external naming service.

How to Validate the Contents of the /etc/project File

Obtain project membership information. 

Display the current project membership of the invoking process. 

How to Obtain Project Membership Information

Create a new task. 

Create a new task in a particular project by using the newtask command.

How to Create a New Task

Associate a running process with a different task and project. 

Associate a process number with a new task ID in a specified project. 

How to Move a Running Process Into a New Task

Add and work with project attributes. 

Use the project database administration commands to add, edit, validate, and remove project attributes. 

Editing and Validating Project Attributes

Example Commands and Command Options

This section provides examples of commands and options used with projects and tasks.

Command Options Used With Projects and Tasks

ps Command

Use the ps command with the -o option 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

id Command

Use the id command with the -p option 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)

pgrep and pkill Commands

To match only processes with a project ID in a specific list, use the pgrep and pkill commands with the -J option:


# pgrep -J projidlist
# pkill -J projidlist

To match only processes with a task ID in a specific list, use the pgrep and pkill commands with the -T option:


# pgrep -T taskidlist
# pkill -T taskidlist

prstat Command

To display various statistics for processes and projects that are currently running on your system, use the prstat command with the -J option:


% 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
 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, use the prstat command with the -T option:


% prstat -T
   PID USERNAME  SIZE   RSS STATE  PRI NICE      TIME  CPU PROCESS/NLWP
 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	

Note –

The -J and -T options cannot be used together.


Using cron and su With Projects and Tasks

cron Command

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. The at and batch commands also capture the current project ID, which ensures that the project ID is restored when running an at job.

su Command

The su command joins the target user's default project by creating a new task, as part of simulating a login.

To switch the user's default project by using the su command, type the following:


# su user

Administering Projects

ProcedureHow to Define a Project and View the Current Project

This example shows how to use the projadd command to add a project entry and the projmod command to alter that entry.

  1. Become superuser or assume an equivalent role.

  2. View the default /etc/project file on your system by using projects -l.


    # projects -l
    system:0::::
    user.root:1::::
    noproject:2::::
    default:3::::
    group.staff:10::::system
            projid : 0
            comment: ""
            users  : (none)
            groups : (none)
            attribs: 
    user.root
            projid : 1
            comment: ""
            users  : (none)
            groups : (none)
            attribs: 
    noproject
            projid : 2
            comment: ""
            users  : (none)
            groups : (none)
            attribs: 
    default
            projid : 3
            comment: ""
            users  : (none)
            groups : (none)
            attribs: 
    group.staff
            projid : 10
            comment: ""
            users  : (none)
            groups : (none)
            attribs: 
  3. Add a project with the name booksite. Assign the project to a user who is named mark with project ID number 4113.


    # projadd -U mark -p 4113 booksite
    
  4. View the /etc/project file again.


    # projects -l
    system
            projid : 0
            comment: ""
            users  : (none)
            groups : (none)
            attribs: 
    user.root
            projid : 1
            comment: ""
            users  : (none)
            groups : (none)
            attribs: 
    noproject
            projid : 2
            comment: ""
            users  : (none)
            groups : (none)
            attribs: 
    default
            projid : 3
            comment: ""
            users  : (none)
            groups : (none)
            attribs: 
    group.staff
            projid : 10
            comment: ""
            users  : (none)
            groups : (none)
            attribs: 
    booksite
            projid : 4113
            comment: ""
            users  : mark
            groups : (none)
            attribs: 
  5. Add a comment that describes the project in the comment field.


    # projmod -c `Book Auction Project' booksite
    
  6. View the changes in the /etc/project file.


    # projects -l
    system
            projid : 0
            comment: ""
            users  : (none)
            groups : (none)
            attribs: 
    user.root
            projid : 1
            comment: ""
            users  : (none)
            groups : (none)
            attribs: 
    noproject
            projid : 2
            comment: ""
            users  : (none)
            groups : (none)
            attribs: 
    default
            projid : 3
            comment: ""
            users  : (none)
            groups : (none)
            attribs: 
    group.staff
            projid : 10
            comment: ""
            users  : (none)
            groups : (none)
            attribs: 
    booksite
            projid : 4113
            comment: "Book Auction Project"
            users  : mark
            groups : (none)
            attribs: 
See Also

To bind projects, tasks, and processes to a pool, see Setting Pool Attributes and Binding to a Pool.

ProcedureHow to Delete a Project From the /etc/project File

This example shows how to use the projdel command to delete a project.

  1. Become superuser or assume an equivalent role.

  2. Remove the project booksite by using the projdel command.


    # projdel booksite
    
  3. Display the /etc/project file.


    # projects -l
    system
            projid : 0
            comment: ""
            users  : (none)
            groups : (none)
            attribs: 
    user.root
            projid : 1
            comment: ""
            users  : (none)
            groups : (none)
            attribs: 
    noproject
            projid : 2
            comment: ""
            users  : (none)
            groups : (none)
            attribs: 
    default
            projid : 3
            comment: ""
            users  : (none)
            groups : (none)
            attribs: 
    group.staff
            projid : 10
            comment: ""
            users  : (none)
            groups : (none)
            attribs: 
  4. Log in as user mark and type projects to view the projects that are assigned to this user.


    # su - mark
    # projects
    default

How to Validate the Contents of the /etc/project File

If no editing options are given, the projmod command validates the contents of the project file.

To validate a NIS map, type the following:


# ypcat project | projmod -f —

To check the syntax of the /etc/project file, type the following:


# projmod -n

How to Obtain Project Membership Information

Use the id command with the -p flag to display the current project membership of the invoking process.


$ id -p
uid=100(mark) gid=1(other) projid=3(default)

ProcedureHow to Create a New Task

  1. Log in as a member of the destination project, booksite in this example.

  2. Create a new task in the booksite project by using the newtask command with the -v (verbose) option to obtain the system task ID.


    machine% 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.

  3. View the current project membership of the invoking process.


    machine% id -p
    uid=100(mark) gid=1(other) projid=4113(booksite)

    The process is now a member of the new project.

ProcedureHow to Move a Running Process Into a New Task

This example shows how to associate a running process with a different task and new project. To perform this action, you must either be superuser, or be the owner of the process and be a member of the new project.

  1. Become superuser or assume an equivalent role.


    Note –

    If you are the owner of the process or a member of the new project, you can skip this step.


  2. Obtain the process ID of the book_catalog process.


    # pgrep book_catalog
    	8100
  3. 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.

  4. Confirm the task to process ID mapping.


    # pgrep -T 17
    	8100

Editing and Validating Project Attributes

You can use the projadd and projmod project database administration commands to edit project attributes.

The -K option specifies a replacement list of attributes. Attributes are delimited by semicolons (;). If the -K option is used with the -a option, the attribute or attribute value is added. If the -K option is used with the -r option, the attribute or attribute value is removed. If the -K option is used with the -s option, the attribute or attribute value is substituted.

ProcedureHow to Add Attributes and Attribute Values to Projects

Use the projmod command with the -a and -K options to add values to a project attribute. If the attribute does not exist, it is created.

  1. Become superuser or assume an equivalent role.

  2. Add a task.max-lwps resource control attribute with no values in the project myproject. A task entering the project has only the system value for the attribute.


    # projmod -a -K task.max-lwps myproject
    
  3. You can then add a value to task.max-lwps in the project myproject. The value consists of a privilege level, a threshold value, and an action associated with reaching the threshold.


    # projmod -a -K "task.max-lwps=(priv,100,deny)" myproject
    
  4. Because resource controls can have multiple values, you can add another value to the existing list of values by using the same options.


    # projmod -a -K "task.max-lwps=(priv,1000,signal=KILL)" myproject
    

    The multiple values are separated by commas. The task.max-lwps entry now reads:


    task.max-lwps=(priv,100,deny),(priv,1000,signal=KILL)

ProcedureHow to Remove Attribute Values From Projects

This procedure uses the values:


task.max-lwps=(priv,100,deny),(priv,1000,signal=KILL)
  1. Become superuser or assume an equivalent role.

  2. To remove an attribute value from the resource control task.max-lwps in the project myproject, use the projmod command with the -r and -K options.


    # projmod -r -K "task.max-lwps=(priv,100,deny)" myproject
    

    If task.max-lwps has multiple values, such as:


    task.max-lwps=(priv,100,deny),(priv,1000,signal=KILL)

    The first matching value would be removed. The result would then be:


    task.max-lwps=(priv,1000,signal=KILL)

ProcedureHow to Remove a Resource Control Attribute From a Project

To remove the resource control task.max-lwps in the project myproject, use the projmod command with the -r and -K options.

  1. Become superuser or assume an equivalent role.

  2. Remove the attribute task.max-lwps and all of its values from the project myproject:


    # projmod -r -K task.max-lwps myproject
    

ProcedureHow to Substitute Attributes and Attribute Values for Projects

To substitute a different value for the attribute task.max-lwps in the project myproject, use the projmod command with the -s and -K options. If the attribute does not exist, it is created.

  1. Become superuser or assume an equivalent role.

  2. Replace the current task.max-lwps values with the new values shown:


    # projmod -s -K "task.max-lwps=(priv,100,none),(priv,120,deny)" myproject
    

    The result would be:


    task.max-lwps=(priv,100,none),(priv,120,deny)

ProcedureHow to Remove the Existing Values for a Resource Control Attribute

  1. Become superuser or assume an equivalent role.

  2. To remove the current values for task.max-lwps from the project myproject, type:


    # projmod -s -K task.max-lwps myproject