unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (SunOS-5.10)
Page:
Section:
Apropos / Subsearch:
optional field

resource_controls(5)  Standards, Environments, and Macros resource_controls(5)



NAME
       resource_controls  -  resource controls available through project data-
       base

SYNOPSIS
       resource controls

DESCRIPTION
       The resource controls facility is configured through the project  data-
       base.  See project(4). You can set and modify resource controls through
       the following utilities:

         o  prctl(1)

         o  projadd(1M)

         o  projmod(1M)

         o  rctladm(1M)


       In a program, you use setrctl(2) to set resource control values.

       In addition to the preceding  resource  controls,  there  are  resource
       pools, accessible through the pooladm(1M) and poolcfg(1M) utilities. In
       a program, resource pools can be manipulated through the  libpool(3LIB)
       library.

       The  following  are  the  resource  controls  available  in the current
       release of the Solaris operating system.

       project.cpu-shares

           Number of CPU shares granted to a project for  use  with  the  fair
           share  scheduler  (see  FSS(7)).   The  unit  used is the number of
           shares (an integer).



       project.max-device-locked-memory

           Total amount of locked memory allowed, expressed  as  a  number  of
           bytes.



       project.max-port-ids

           Maximum allowable number of event ports, expressed as an integer.



       project.max-shm-ids

           Maximum  number  of  shared  memory  IDs  allowed  for  a  project,
           expressed as an integer.



       project.max-sem-ids

           Maximum number of semaphore IDs allowed for a project, expressed as
           an integer.



       project.max-msg-ids

           Maximum  number  of  message  queue  IDs  allowed  for  a  project,
           expressed as an integer.



       project.max-shm-memory

           Total amount of shared memory allowed for a project, expressed as a
           number of bytes.



       project.max-lwps

           Maximum  number  of  LWPs  simultaneously  available  to a project,
           expressed as an integer.



       project.max-tasks

           Maximum number of tasks allowable in a  project,  expressed  as  an
           integer.



       project.max-contracts

           Maximum  number  of contracts allowed in a project, expressed as an
           integer.



       project.pool

           Binds a specified resource pool with a project.



       task.max-cpu-time

           Maximum CPU time  that  is  available  to  this  task's  processes,
           expressed as a number of seconds.



       task.max-lwps

           Maximum number of LWPs simultaneously available to this task's pro-
           cesses, expressed as an integer.



       process.max-cpu-time

           Maximum CPU time that is available to this process, expressed as  a
           number of seconds.



       process.max-file-descriptor

           Maximum  file descriptor index available to this process, expressed
           as an integer.



       process.max-file-size

           Maximum  file  offset  available  for  writing  by  this   process,
           expressed as a number of bytes.



       process.max-core-size

           Maximum size of a core file created by this process, expressed as a
           number of bytes.



       process.max-data-size

           Maximum heap memory available to this process, expressed as a  num-
           ber of bytes.



       process.max-stack-size

           Maximum  stack  memory segment available to this process, expressed
           as a number of bytes.



       process.max-address-space

           Maximum amount of address space, as summed over segment sizes, that
           is available to this process, expressed as a number of bytes.



       process.max-port-events

           Maximum  allowable number of events per event port, expressed as an
           integer.



       process.max-sem-nsems

           Maximum number of semaphores allowed per semaphore  set,  expressed
           as an integer.



       process.max-sem-ops

           Maximum  number  of  semaphore  operations  allowed  per semop call
           (value  copied  from  the  resource  control  at  semget()   time).
           Expressed as an integer, specifying the number of operations.



       process.max-msg-qbytes

           Maximum  number  of  bytes  of  messages  on a message queue (value
           copied from the resource control at msgget() time), expressed as  a
           number of bytes.



       process.max-msg-messages

           Maximum  number  of  messages on a message queue (value copied from
           the resource control at msgget() time), expressed as an integer.



       process.min-crypto-sessions

           Number of sessions in fixed-sized session table when /dev/crypto is
           opened;  value  can  only  be  changed  by  a  privileged  process.
           Expressed as an integer, specifying the number of sessions.



       process.add-crypto-sessions

           Number of additional sessions when session table is full and larger
           table  is allocated. Expressed as an integer, specifying the number
           of additional sessions.



       process.max-crypto-sessions

           Maximum number of sessions in session  table;  value  can  only  be
           changed  by privileged process. Expressed as an integer, specifying
           the number of sessions.



       process.crypto-buffer-limit

           Number of bytes allocated for copying of user data;  sizes  of  all
           buffers allocated for copying are added together and result checked
           against this resource control; limit applies to  each  instance  of
           /dev/crypto;  value  can  only  be  changed  by privileged process.
           Expressed as a number of bytes.



       In the current release, there are the following zone-wide resource con-
       trols:

       zone.cpu-shares

           Sets a limit on the number of fair share scheduler (FSS) CPU shares
           for a zone. CPU shares are first allocated to the  zone,  and  then
           further  subdivided  among projects within the zone as specified in
           the project.cpu-shares entries. Expressed as an integer.



       zone.max-lwps

           Enhances resource isolation by preventing too many LWPs in one zone
           from affecting other zones. A zone's total LWPs can be further sub-
           divided among projects within the zone within  the  zone  by  using
           project.max-lwps entries. Expressed as an integer.



       See zones(5).

   Units Used in Resource Controls
       Resource  controls  can  be expressed as in units of size (bytes), time
       (seconds), or as a count (integer). These units use the strings  speci-
       fied below.

       Category             Res Ctrl      Modifier  Scale
                            Type String
       -----------          -----------   --------  -----
       Size                 bytes         B         1
                                          KB        2^10
                                          MB        2^20
                                          GB        2^30
                                          TB        2^40
                                          PB        2^50
                                          EB        2^60

       Time                 seconds       s         1
                                          Ks        10^3
                                          Ms        10^6
                                          Gs        10^9
                                          Ts        10^12
                                          Ps        10^15
                                          Es        10^18

       Count                integer       none      1
                                          K         10^3
                                          M         10^6
                                          G         10^9
                                          T         10^12
                                          P         10^15
                                          Es        10^18


       Scaled values can be used with resource controls. The following example
       shows a scaled threshold value:

       task.max-lwps=(priv,1K,deny)


       In the project file, the value 1K is expanded to 1000:

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


       A second example uses a larger scaled value:

       process.max-file-size=(priv,5G,deny)


       In the project file, the value 5G is expanded to 5368709120:

       process.max-file-size=(priv,5368709120,deny)


       The preceding examples use the scaling factors specified in  the  table
       above.

       Note  that  unit  modifiers  (for  example,  5G)  are  accepted  by the
       prctl(1), projadd(1M), and projmod(1M) commands. You  cannot  use  unit
       modifiers in the project database itself.

   Resource Control Values and Privilege Levels
       A  threshold  value  on a resource control constitutes a point at which
       local actions can be triggered or global actions, such as logging,  can
       occur.

       Each  threshold  value  on a resource control must be associated with a
       privilege level. The privilege level must be one of the following three
       types:

       basic

           Can be modified by the owner of the calling process.



       privileged

           Can be modified only by privileged (superuser) callers.



       system

           Fixed for the duration of the operating system instance.



       A  resource  control  is  guaranteed to have one system value, which is
       defined by the system, or resource provider. The  system  value  repre-
       sents  how much of the resource the current implementation of the oper-
       ating system is capable of providing.

       Any number of privileged values can be  defined,  and  only  one  basic
       value  is  allowed.  Operations that are performed without specifying a
       privilege value are assigned a basic privilege by default.

       The privilege level for a resource control  value  is  defined  in  the
       privilege field of the resource control block as RCTL_BASIC, RCTL_PRIV-
       ILEGED, or RCTL_SYSTEM. See setrctl(2) for more  information.  You  can
       use  the  prctl command to modify values that are associated with basic
       and privileged levels.

       In specifying the privilege level of privileged, you can use the abbre-
       viation priv. For example:

       task.max-lwps=(priv,1K,deny)


   Global and Local Actions on Resource Control Values
       There  are two categories of actions on resource control values: global
       and local.

       Global actions apply to resource control values for every resource con-
       trol  on  the  system. You can use rctladm(1M) to perform the following
       actions:

         o  Display the global state of active system resource controls.

         o  Set global logging actions.


       You can disable or enable the global logging action  on  resource  con-
       trols.  You can set the syslog action to a specific degree by assigning
       a severity level, syslog=level. The possible settings for level are  as
       follows:

         o  debug

         o  info

         o
            notice

         o  warning

         o  err

         o  crit

         o  alert

         o  emerg


       By default, there is no global logging of resource control violations.

       Local  actions  are taken on a process that attempts to exceed the con-
       trol value. For each threshold value that is placed on a resource  con-
       trol,  you  can associate one or more actions. There are three types of
       local actions: none, deny, and signal=.  These three actions  are  used
       as follows:

       none

           No  action  is  taken  on  resource  requests for an amount that is
           greater than the threshold. This action is  useful  for  monitoring
           resource  usage without affecting the progress of applications. You
           can also enable a global message that displays  when  the  resource
           control is exceeded, while, at the same time, the process exceeding
           the threshhold is not affected.



       deny

           You can deny resource requests for an amount that is  greater  than
           the  threshold.  For example, a task.max-lwps resource control with
           action deny causes a fork() system call to fail if the new  process
           would exceed the control value. See the fork(2).



       signal=

           You  can  enable  a  global signal message action when the resource
           control is exceeded. A signal is  sent  to  the  process  when  the
           threshold value is exceeded. Additional signals are not sent if the
           process  consumes  additional  resources.   Available  signals  are
           listed below.



       Not  all  of  the actions can be applied to every resource control. For
       example, a process cannot exceed the number of CPU shares  assigned  to
       the  project  of  which it is a member. Therefore, a deny action is not
       allowed on the project.cpu-shares resource control.

       Due to implementation restrictions, the global properties of each  con-
       trol can restrict the range of available actions that can be set on the
       threshold value. (See rctladm(1M).)  A list of available signal actions
       is  presented  in  the following list. For additional information about
       signals, see signal(3HEAD).

       The following are the signals available to resource control values:

       SIGABRT

           Terminate the process.



       SIGHUP

           Send a hangup signal. Occurs when carrier drops on  an  open  line.
           Signal sent to the process group that controls the terminal.



       SIGTERM

           Terminate the process. Termination signal sent by software.



       SIGKILL

           Terminate the process and kill the program.



       SIGSTOP

           Stop the process. Job control signal.



       SIGXRES

           Resource  control  limit  exceeded.  Generated  by resource control
           facility.



       SIGXFSZ

           Terminate the process. File size limit exceeded. Available only  to
           resource   controls   with   the   RCTL_GLOBAL_FILE_SIZE   property
           (process.max-file-size). See rctlblk_set_value(3C).



       SIGXCPU

           Terminate the process. CPU time limit exceeded. Available  only  to
           resource    controls    with   the   RCTL_GLOBAL_CPUTIME   property
           (process.max-cpu-time). See rctlblk_set_value(3C).



   Resource Control Flags and Properties
       Each resource control on the system has a  certain  set  of  associated
       properties.  This set of properties is defined as a set of flags, which
       are associated with all controlled instances of that  resource.  Global
       flags  cannot  be  modified,  but  the  flags can be retrieved by using
       either rctladm(1M) or the getrctl(2) system call.

       Local flags define the default behavior and configuration  for  a  spe-
       cific threshold value of that resource control on a specific process or
       process collective. The local flags for  one  threshold  value  do  not
       affect  the  behavior  of  other  defined threshold values for the same
       resource control. However, the global flags  affect  the  behavior  for
       every  value  associated  with a particular control. Local flags can be
       modified, within the constraints supplied by their corresponding global
       flags, by the prctl command or the setrctl system call. See setrctl(2).

       For  the  complete list of local flags, global flags, and their defini-
       tions, see rctlblk_set_value(3C).

       To determine system behavior when a threshold value  for  a  particular
       resource  control  is  reached, use rctladm to display the global flags
       for the resource control . For  example,  to  display  the  values  for
       process.max-cpu-time, enter:

       $ rctladm process.max-cpu-time
       process.max-cpu-time  syslog=off [ lowerable no-deny cpu-time inf seconds ]


       The global flags indicate the following:

       lowerable

           Superuser  privileges are not required to lower the privileged val-
           ues for this control.



       no-deny

           Even when threshold values are exceeded, access to the resource  is
           never denied.



       cpu-time

           SIGXCPU  is  available  to  be  sent  when threshold values of this
           resource are reached.



       seconds

           The time value for the resource control.



       Use the prctl command to display  local  values  and  actions  for  the
       resource control. For example:

       $ prctl -n process.max-cpu-time $$
           process 353939: -ksh
           NAME    PRIVILEGE    VALUE    FLAG   ACTION              RECIPIENT
        process.max-cpu-time
                privileged   18.4Es    inf   signal=XCPU                 -
                system       18.4Es    inf   none


       The max (RCTL_LOCAL_MAXIMAL) flag is set for both threshold values, and
       the inf (RCTL_GLOBAL_INFINITE) flag is defined for this  resource  con-
       trol.  An  inf  value  has  an  infinite  quantity.  The value is never
       enforced. Hence, as configured,  both  threshold  quantities  represent
       infinite values that are never exceeded.

   Resource Control Enforcement
       More than one resource control can exist on a resource. A resource con-
       trol can exist at each containment  level  in  the  process  model.  If
       resource  controls  are  active  on the same resource at different con-
       tainer levels, the smallest  container's  control  is  enforced  first.
       Thus,  action is taken on process.max-cpu-time before task.max-cpu-time
       if both controls are encountered simultaneously.

ATTRIBUTES
       See attributes(5) for a description of the following attributes:


       tab()    allbox;    cw(2.750000i)|     cw(2.750000i)     lw(2.750000i)|
       lw(2.750000i).  ATTRIBUTE TYPEATTRIBUTE VALUE Interface StabilityEvolv-
       ing


SEE ALSO
       prctl(1),  pooladm(1M),  poolcfg(1M),  projadd(1M),  projmod(1M),  rct-
       ladm(1M), setrctl(2), rctlblk_set_value(3C), libpool(3LIB), project(4),
       attributes(5), FSS(7)

       System Administration Guide: N1 Grid Containers,  Resource  Management,
       and Solaris Zones



SunOS 5.10                        6 Dec 2004              resource_controls(5)