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