Section 7.6. Interfaces for Resource Controls

7.6. Interfaces for Resource Controls

We first examine the project database entries required to support the resource control functionality for login (or project binding in general). Additionally, we give a grammar for the attribute field of the project database. We then define the new system calls required to support the rctls functionality.

7.6.1. Project Name-Service Attributes

The final field of the project database is defined as part of the projects and tasks infrastructure as an open-ended series of delimited name-value pairs. The resource control framework defines a collection of name-value pairs and defines rules for future attribute names in this space. The following collection of examples illustrate the convention.

The names of a name-value pair are restricted to letters, digits, the underscore, and the period, which is used as a separator between the categories and subcategories of the rctl. The first character of an attribute name must be a letter. The attribute name is case sensitive, following standard UNIX conventions.

The right-hand side of the assignment, being the value, can be structured with commas and parentheses (for precedence). Since a semicolon separates name-value pairs, it is not legal within a value definition. And since a colon separates project fields, it too is not legal within a value definition.

entity.structured.attr=alpha,(beta,gamma) 

7.6.2. Attributes Originating within Solaris

The attribute namespace uses the form [entity].[control name] to encode these limits. Valid entities are task, process, and project.

Solaris facilities using rctls must acquire valid control names from a governance body, which will own the rctl namespace. A listing of the valid resource controls available with the base operating system is presented in the manual page for rctladm(1M).

7.6.3. Grammar for Attributes

A grammar restricting the attribute namespace is given below.

attribute list : attribute [ ; attribute list ] attribute : name [ = structured value list ] name : [ stock symbol , ] symbol character sequence structured value list : value, structured value list value : valid character sequence -- ( structured value list ) 

7.6.4. Interpretation of rctl Attributes

By default, the specification of a resource control in the project database as a simple key-value pair defines the privileged resource control and local action for the entity being constructed (through login/PAM or setproject). Thus,

task.max.lwps=(PRIVILEGED,32,signal=SIGXRES) 

translates to a call of the form

rctlblk.t *blk = malloc(rctlblk.size()); ... rctlblk.set.privilege(blk, RCPRIV.PRIVILEGED); rctlblk.set.local.action(blk, RCTL.LOCAL.SIGNAL, SIGXRES); rctlblk.set.value(blk, 32); if (setrctl("task.max.lwps", NULL, blk, RCTL.REPLACE) == -1 && errno == ESRCH) {         if (setrctl("task.max-lwps", NULL, blk, RCTL.INSERT) == -1)                 /* log error message */ } 

(If the SIGXRES specification and the parentheses were omitted, then the local action would be set to RCTL_LOCAL_NOACTION.)

To specify more general attributes, the project database allows the setting of a series of resource control values by connecting a set of triplets in a comma-separated list:

task.max-lwps=(BASIC,24,none),(PRIVILEGED,32,signal=SIGXRES,deny) 

which translates to a call sequence of the form

/* allocate blk and blk2 */ rctlblk.set.privilege(blk, RCPRIV.BASIC); rctlblk.set.local.action(blk, RCTL.LOCAL.NOACTION, 0); rctlblk.set.value(blk, 24); rctlblk.set.privilege(blk2, RCPRIV.PRIVILEGED); rctlblk.set.local.action(blk2, RCTL.LOCAL.DENY -- RCTL.LOCAL.SIGNAL, SIGXRES); rctlblk.set.value(blk2, 32); if (setrctl("task.max.lwps", NULL, blk, RCTL.REPLACE) == -1 && errno == ESRCH) {         if (setrctl("task.max-lwps", NULL, blk, RCTL.INSERT) == -1)                 /* log error message */                 ... if (setrctl("task.max.lwps", NULL, blk2, RCTL.REPLACE) == -1 &&                         errno == ESRCH) {                 if (setrctl("task.max-lwps", NULL, blk2, RCTL.INSERT) == -1)                 /* log error message */                 ... 

The following is an example of a series of resource controls for process.maxcpu-time:

process.max-cpu-time=(PRIVILEGED,30,signal=SIGXCPU), (PRIVILEGED,40,signal=SIGTERM),(PRIVILEGED,50,signal=SIGKILL) 

In this example, the resource value is seconds of CPU time. By configuring three actions in this way, when a process exceeds 30 seconds of CPU time it is sent a SIGXCPU. If the process ignores that and continues to run, then after exceeding 40 seconds of CPU time it is sent a SIGTERM. At this point any sensible process should terminate. If it does continue to run, we resort to a SIGKILL after 50 seconds of CPU time.

# projadd -K 'process.max-cpu-time=(privileged,30,signal=SIGXCPU),'\ > '(privileged,40,signal=SIGTERM),(privileged,50,signal=SIGKILL)' cpulimit # newtask -p cpulimit sh #  trap 'echo "got XCPU: \c"; date' XCPU #  trap 'echo "got TERM: \c"; date' TERM # echo "Started : \c"; date; while :; do :; done Started : Sat Feb 18 18:27:19 EST 2006 got XCPU: Sat Feb 18 18:27:49 EST 2006 got TERM: Sat Feb 18 18:27:59 EST 2006 Killed 

7.6.5. An Example /etc/project

A simple example of a files-based project database is given below. Given the /etc/group file

sol9$ grep beatles /etc/group beatles::1000:paul,george,ringo 

we can define a simple set of projects.

system:0:::: user.root:1:::: noproject:2:::: group.beatles:1000::::task.max-lwps=256 user.paul:2000::::task.max-lwps=512;process.max-core-size=0 user.george:2002::::process.max-cpu-seconds=1000 user.ringo:2003::::task.max-cpu-seconds=3000 

Note that the absence of the default project prevents any of the defined users from escaping their default group or group.beatles to a project with greater resources.

7.6.6. System Calls and Private Kernel Interfaces

The setrctl(2), getrctl(2), setrctl(2), and getrctl(2) system calls allow the values on rctls for various entities in the system to be established or retrieved. Because of the variable number of resource control values, these system calls use an opaque structure, the resource control block whose members are set with the rctlblk routines of "rctlblk Manipulation Routines" on the next page and provide an iteration-based interface.

Private subcodes on the rctlsys system call will enable the rctladm(1M) command and the rctl_walk(3C) library function described below. A similar private subcode on the task or project system call enables the project_walk(3PROJECT) function. All the rctl registration and implementation functions internal to the kernel are Consolidation Private.

7.6.7. Library Functions

Five library functions are described in this section: setproject, project_walk, rctl_walk, getproject, and rctlblk_size.

Table 7.7. Library Functions for rctls

Interface	Description
setproject(3PROJECT)	setproject() provides a simplified interface to bind the current process to the specified project with all pertinent rctl settings as recorded in the project database. Invocation of setproject() includes a call to settaskid(2), implying that the calling process must possess root privilege for the operation to succeed.
project_walk(3PROJECT)	The project_walk() function provides a mechanism for an application to visit, with a callback function provided by the application, each project active on the system.
rctl_walk(3C)	The rctl_walk() function allows the application to have a callback function invoked for each active resource control on the system.
The getprojent() Derived Family of Library Calls	The following calls already support the attributes field of the project database: getprojent(3PROJECT) fgetprojent(3PROJECT) getprojbyname(3PROJECT) getprojbyid(3PROJECT) geTDefaultproj(3PROJECT) The key-value pair management functions of libsecdb(3LIB) can be used to manipulate the field after a project entry is retrieved. The name service calls themselves are not modified by this project.
rctlblk Manipulation Routines	These interfaces are provided to keep the contents and layout of the resource control block opaque. A sizing routine, rctlblk_size(3C), is provided so that applications will maintain binary compatibility in the face of enhancements to the resource control block.