1resource_controls(5)  Standards, Environments, and Macros resource_controls(5)
2
3
4

NAME

6       resource_controls  -  resource controls available through project data‐
7       base
8

DESCRIPTION

10       The resource controls facility is configured through the project  data‐
11       base.  See project(4). You can set and modify resource controls through
12       the following utilities:
13
14           o      prctl(1)
15
16           o      projadd(1M)
17
18           o      projmod(1M)
19
20           o      rctladm(1M)
21
22
23       In a program, you use setrctl(2) to set resource control values.
24
25
26       In addition to the preceding  resource  controls,  there  are  resource
27       pools, accessible through the pooladm(1M) and poolcfg(1M) utilities. In
28       a program, resource pools can be manipulated through the  libpool(3LIB)
29       library.
30
31
32       The following are the resource controls are available:
33
34       process.max-address-space
35
36           Maximum amount of address space, as summed over segment sizes, that
37           is available to this process, expressed as a number of bytes.
38
39
40       process.max-core-size
41
42           Maximum size of a core file created by this process, expressed as a
43           number of bytes.
44
45
46       process.max-cpu-time
47
48           Maximum  CPU time that is available to this process, expressed as a
49           number of seconds.
50
51
52       process.max-data-size
53
54           Maximum heap memory available to this process, expressed as a  num‐
55           ber of bytes.
56
57
58       process.max-file-descriptor
59
60           Maximum  file descriptor index available to this process, expressed
61           as an integer.
62
63
64       process.max-file-size
65
66           Maximum  file  offset  available  for  writing  by  this   process,
67           expressed as a number of bytes.
68
69
70       process.max-msg-messages
71
72           Maximum  number  of  messages on a message queue (value copied from
73           the resource control at msgget() time), expressed as an integer.
74
75
76       process.max-msg-qbytes
77
78           Maximum number of bytes of  messages  on  a  message  queue  (value
79           copied  from the resource control at msgget() time), expressed as a
80           number of bytes.
81
82
83       process.max-port-events
84
85           Maximum allowable number of events per event port, expressed as  an
86           integer.
87
88
89       process.max-sem-nsems
90
91           Maximum  number  of semaphores allowed per semaphore set, expressed
92           as an integer.
93
94
95       process.max-sem-ops
96
97           Maximum number of  semaphore  operations  allowed  per  semop  call
98           (value   copied  from  the  resource  control  at  semget()  time).
99           Expressed as an integer, specifying the number of operations.
100
101
102       process.max-stack-size
103
104           Maximum stack memory segment available to this  process,  expressed
105           as a number of bytes.
106
107
108       project.cpu-caps
109
110           Maximum  amount  of  CPU resources that a project can use. The unit
111           used is the percentage of a single CPU that can be used by all user
112           threads  in  a  project.  Expressed as an integer. The cap does not
113           apply to  threads  running  in  real-time  scheduling  class.  This
114           resource control does not support the syslog action.
115
116
117       project.cpu-shares
118
119           Number  of  CPU  shares  granted to a project for use with the fair
120           share scheduler (see FSS(7)). The unit used is the number of shares
121           (an  integer).  This  resource  control does not support the syslog
122           action.
123
124
125       project.max-contracts
126
127           Maximum number of contracts allowed in a project, expressed  as  an
128           integer.
129
130
131       project.max-crypto-memory
132
133           Maximum  amount of kernel memory that can be used for crypto opera‐
134           tions. Allocations in the kernel for  buffers  and  session-related
135           structures are charged against this resource control.
136
137
138       project.max-locked-memory
139
140           Total  amount  of physical memory locked by device drivers and user
141           processes (including D/ISM), expressed as a number of bytes.
142
143
144       project.max-lwps
145
146           Maximum number of  LWPs  simultaneously  available  to  a  project,
147           expressed as an integer.
148
149
150       project.max-msg-ids
151
152           Maximum  number  of  message  queue  IDs  allowed  for  a  project,
153           expressed as an integer.
154
155
156       project.max-port-ids
157
158           Maximum allowable number of event ports, expressed as an integer.
159
160
161       project.max-sem-ids
162
163           Maximum number of semaphore IDs allowed for a project, expressed as
164           an integer.
165
166
167       project.max-shm-ids
168
169           Maximum  number  of  shared  memory  IDs  allowed  for  a  project,
170           expressed as an integer.
171
172
173       project.max-shm-memory
174
175           Total amount of shared memory allowed for a project, expressed as a
176           number of bytes.
177
178
179       project.max-tasks
180
181           Maximum  number  of  tasks  allowable in a project, expressed as an
182           integer.
183
184
185       project.pool
186
187           Binds a specified resource pool with a project.
188
189
190       rcap.max-rss
191
192           The total amount of physical memory, in bytes, that is available to
193           processes in a project.
194
195
196       task.max-cpu-time
197
198           Maximum  CPU  time  that  is  available  to  this task's processes,
199           expressed as a number of seconds.
200
201
202       task.max-lwps
203
204           Maximum number of LWPs simultaneously available to this task's pro‐
205           cesses, expressed as an integer.
206
207
208
209       The following zone-wide resource controls are available:
210
211       zone.cpu-cap
212
213           Sets  a limit on the amount of CPU time that can be used by a zone.
214           The unit used is the percentage of a single CPU that can be used by
215           all  user threads in a zone. Expressed as an integer. When projects
216           within the capped zone have their own caps, the minimum value takes
217           precedence.  This  resource  control  does  not  support the syslog
218           action.
219
220
221       zone.cpu-shares
222
223           Sets a limit on the number of fair share scheduler (FSS) CPU shares
224           for  a  zone.  CPU shares are first allocated to the zone, and then
225           further subdivided among projects within the zone as  specified  in
226           the  project.cpu-shares  entries.  Expressed  as  an  integer. This
227           resource control does not support the syslog action.
228
229
230       zone.max-locked-memory
231
232           Total amount of physical locked memory available to a zone.
233
234
235       zone.max-lwps
236
237           Enhances resource isolation by preventing too many LWPs in one zone
238           from affecting other zones. A zone's total LWPs can be further sub‐
239           divided among projects within the zone within  the  zone  by  using
240           project.max-lwps entries. Expressed as an integer.
241
242
243       zone.max-msg-ids
244
245           Maximum  number  of message queue IDs allowed for a zone, expressed
246           as an integer.
247
248
249       zone.max-sem-ids
250
251           Maximum number of semaphore IDs allowed for a zone, expressed as an
252           integer.
253
254
255       zone.max-shm-ids
256
257           Maximum  number  of shared memory IDs allowed for a zone, expressed
258           as an integer.
259
260
261       zone.max-shm-memory
262
263           Total amount of shared memory allowed for a zone,  expressed  as  a
264           number of bytes.
265
266
267       zone.max-swap
268
269           Total  amount  of swap that can be consumed by user process address
270           space mappings and tmpfs mounts for this zone.
271
272
273
274       See zones(5).
275
276   Units Used in Resource Controls
277       Resource controls can be expressed as in units of  size  (bytes),  time
278       (seconds),  or as a count (integer). These units use the strings speci‐
279       fied below.
280
281         Category             Res Ctrl      Modifier  Scale
282                              Type String
283         -----------          -----------   --------  -----
284         Size                 bytes         B         1
285                                            KB        2^10
286                                            MB        2^20
287                                            GB        2^30
288                                            TB        2^40
289                                            PB        2^50
290                                            EB        2^60
291
292         Time                 seconds       s         1
293                                            Ks        10^3
294                                            Ms        10^6
295                                            Gs        10^9
296                                            Ts        10^12
297                                            Ps        10^15
298                                            Es        10^18
299
300         Count                integer       none      1
301                                            K         10^3
302                                            M         10^6
303                                            G         10^9
304                                            T         10^12
305                                            P         10^15
306                                            Es        10^18
307
308
309
310       Scaled values can be used with resource controls. The following example
311       shows a scaled threshold value:
312
313         task.max-lwps=(priv,1K,deny)
314
315
316
317       In the project file, the value 1K is expanded to 1000:
318
319         task.max-lwps=(priv,1000,deny)
320
321
322
323       A second example uses a larger scaled value:
324
325         process.max-file-size=(priv,5G,deny)
326
327
328
329       In the project file, the value 5G is expanded to 5368709120:
330
331         process.max-file-size=(priv,5368709120,deny)
332
333
334
335       The  preceding  examples use the scaling factors specified in the table
336       above.
337
338
339       Note that  unit  modifiers  (for  example,  5G)  are  accepted  by  the
340       prctl(1),  projadd(1M),  and  projmod(1M) commands. You cannot use unit
341       modifiers in the project database itself.
342
343   Resource Control Values and Privilege Levels
344       A threshold value on a resource control constitutes a  point  at  which
345       local  actions can be triggered or global actions, such as logging, can
346       occur.
347
348
349       Each threshold value on a resource control must be  associated  with  a
350       privilege level. The privilege level must be one of the following three
351       types:
352
353       basic
354
355           Can be modified by the owner of the calling process.
356
357
358       privileged
359
360           Can be modified by  the  current  process  (requiring  sys_resource
361           privilege) or by prctl(1) (requiring proc_owner privilege).
362
363
364       system
365
366           Fixed for the duration of the operating system instance.
367
368
369
370       A  resource  control  is  guaranteed to have one system value, which is
371       defined by the system, or resource provider. The  system  value  repre‐
372       sents  how much of the resource the current implementation of the oper‐
373       ating system is capable of providing.
374
375
376       Any number of privileged values can be  defined,  and  only  one  basic
377       value  is  allowed.  Operations that are performed without specifying a
378       privilege value are assigned a basic privilege by default.
379
380
381       The privilege level for a resource control  value  is  defined  in  the
382       privilege field of the resource control block as RCTL_BASIC, RCTL_PRIV‐
383       ILEGED, or RCTL_SYSTEM. See setrctl(2) for more  information.  You  can
384       use  the  prctl command to modify values that are associated with basic
385       and privileged levels.
386
387
388       In specifying the privilege level of privileged, you can use the abbre‐
389       viation priv. For example:
390
391         task.max-lwps=(priv,1K,deny)
392
393
394   Global and Local Actions on Resource Control Values
395       There  are two categories of actions on resource control values: global
396       and local.
397
398
399       Global actions apply to resource control values for every resource con‐
400       trol  on  the  system. You can use rctladm(1M) to perform the following
401       actions:
402
403           o      Display the global state of active system resource controls.
404
405           o      Set global logging actions.
406
407
408       You can disable or enable the global logging action  on  resource  con‐
409       trols.  You can set the syslog action to a specific degree by assigning
410       a severity level, syslog=level. The possible settings for level are  as
411       follows:
412
413           o      debug
414
415           o      info
416
417           o      notice
418
419           o      warning
420
421           o      err
422
423           o      crit
424
425           o      alert
426
427           o      emerg
428
429
430       By default, there is no global logging of resource control violations.
431
432
433       Local  actions  are taken on a process that attempts to exceed the con‐
434       trol value. For each threshold value that is placed on a resource  con‐
435       trol,  you  can associate one or more actions. There are three types of
436       local actions: none, deny, and signal=. These three actions are used as
437       follows:
438
439       none
440
441           No  action  is  taken  on  resource  requests for an amount that is
442           greater than the threshold. This action is  useful  for  monitoring
443           resource  usage without affecting the progress of applications. You
444           can also enable a global message that displays  when  the  resource
445           control is exceeded, while, at the same time, the process exceeding
446           the threshhold is not affected.
447
448
449       deny
450
451           You can deny resource requests for an amount that is  greater  than
452           the  threshold.  For example, a task.max-lwps resource control with
453           action deny causes a fork() system call to fail if the new  process
454           would exceed the control value. See the fork(2).
455
456
457       signal=
458
459           You  can  enable  a  global signal message action when the resource
460           control is exceeded. A signal is  sent  to  the  process  when  the
461           threshold value is exceeded. Additional signals are not sent if the
462           process consumes additional resources. Available signals are listed
463           below.
464
465
466
467       Not  all  of  the actions can be applied to every resource control. For
468       example, a process cannot exceed the number of CPU shares  assigned  to
469       the  project  of  which it is a member. Therefore, a deny action is not
470       allowed on the project.cpu-shares resource control.
471
472
473       Due to implementation restrictions, the global properties of each  con‐
474       trol can restrict the range of available actions that can be set on the
475       threshold value. (See rctladm(1M).) A list of available signal  actions
476       is  presented  in  the following list. For additional information about
477       signals, see signal(3HEAD).
478
479
480       The following are the signals available to resource control values:
481
482       SIGABRT
483
484           Terminate the process.
485
486
487       SIGHUP
488
489           Send a hangup signal. Occurs when carrier drops on  an  open  line.
490           Signal sent to the process group that controls the terminal.
491
492
493       SIGTERM
494
495           Terminate the process. Termination signal sent by software.
496
497
498       SIGKILL
499
500           Terminate the process and kill the program.
501
502
503       SIGSTOP
504
505           Stop the process. Job control signal.
506
507
508       SIGXRES
509
510           Resource  control  limit  exceeded.  Generated  by resource control
511           facility.
512
513
514       SIGXFSZ
515
516           Terminate the process. File size limit exceeded. Available only  to
517           resource   controls   with   the   RCTL_GLOBAL_FILE_SIZE   property
518           (process.max-file-size). See rctlblk_set_value(3C).
519
520
521       SIGXCPU
522
523           Terminate the process. CPU time limit exceeded. Available  only  to
524           resource    controls    with   the   RCTL_GLOBAL_CPUTIME   property
525           (process.max-cpu-time). See rctlblk_set_value(3C).
526
527
528   Resource Control Flags and Properties
529       Each resource control on the system has a  certain  set  of  associated
530       properties.  This set of properties is defined as a set of flags, which
531       are associated with all controlled instances of that  resource.  Global
532       flags  cannot  be  modified,  but  the  flags can be retrieved by using
533       either rctladm(1M) or the setrctl(2) system call.
534
535
536       Local flags define the default behavior and configuration  for  a  spe‐
537       cific threshold value of that resource control on a specific process or
538       process collective. The local flags for  one  threshold  value  do  not
539       affect  the  behavior  of  other  defined threshold values for the same
540       resource control. However, the global flags  affect  the  behavior  for
541       every  value  associated  with a particular control. Local flags can be
542       modified, within the constraints supplied by their corresponding global
543       flags, by the prctl command or the setrctl system call. See setrctl(2).
544
545
546       For  the  complete list of local flags, global flags, and their defini‐
547       tions, see rctlblk_set_value(3C).
548
549
550       To determine system behavior when a threshold value  for  a  particular
551       resource  control  is  reached, use rctladm to display the global flags
552       for the resource control . For  example,  to  display  the  values  for
553       process.max-cpu-time, enter:
554
555         $ rctladm process.max-cpu-time
556         process.max-cpu-time  syslog=off [ lowerable no-deny cpu-time inf seconds ]
557
558
559
560       The global flags indicate the following:
561
562       lowerable
563
564           Superuser  privileges are not required to lower the privileged val‐
565           ues for this control.
566
567
568       no-deny
569
570           Even when threshold values are exceeded, access to the resource  is
571           never denied.
572
573
574       cpu-time
575
576           SIGXCPU  is  available  to  be  sent  when threshold values of this
577           resource are reached.
578
579
580       seconds
581
582           The time value for the resource control.
583
584
585
586       Use the prctl command to display  local  values  and  actions  for  the
587       resource control. For example:
588
589         $ prctl -n process.max-cpu-time $$
590             process 353939: -ksh
591             NAME    PRIVILEGE    VALUE    FLAG   ACTION              RECIPIENT
592          process.max-cpu-time
593                  privileged   18.4Es    inf   signal=XCPU                 -
594                  system       18.4Es    inf   none
595
596
597
598       The max (RCTL_LOCAL_MAXIMAL) flag is set for both threshold values, and
599       the inf (RCTL_GLOBAL_INFINITE) flag is defined for this  resource  con‐
600       trol.  An  inf  value  has  an  infinite  quantity.  The value is never
601       enforced. Hence, as configured,  both  threshold  quantities  represent
602       infinite values that are never exceeded.
603
604   Resource Control Enforcement
605       More than one resource control can exist on a resource. A resource con‐
606       trol can exist at each containment  level  in  the  process  model.  If
607       resource  controls  are  active  on the same resource at different con‐
608       tainer levels, the smallest  container's  control  is  enforced  first.
609       Thus,  action is taken on process.max-cpu-time before task.max-cpu-time
610       if both controls are encountered simultaneously.
611

ATTRIBUTES

613       See attributes(5) for a description of the following attributes:
614
615
616
617
618       ┌─────────────────────────────┬─────────────────────────────┐
619ATTRIBUTE TYPE         ATTRIBUTE VALUE        
620       ├─────────────────────────────┼─────────────────────────────┤
621       │Interface Stability          │Evolving                     │
622       └─────────────────────────────┴─────────────────────────────┘
623

SEE ALSO

625       prctl(1),  pooladm(1M),  poolcfg(1M),  projadd(1M),  projmod(1M),  rct‐
626       ladm(1M), setrctl(2), rctlblk_set_value(3C), libpool(3LIB), project(4),
627       attributes(5), FSS(7)
628
629
630       System Administration Guide:  Virtualization Using the Solaris  Operat‐
631       ing System
632
633
634
635SunOS 5.11                        2 Jul 2007              resource_controls(5)
Impressum