1.\"- 2.\" Copyright (c) 2009 Edward Tomasz Napierala 3.\" All rights reserved. 4.\" 5.\" Redistribution and use in source and binary forms, with or without 6.\" modification, are permitted provided that the following conditions 7.\" are met: 8.\" 1. Redistributions of source code must retain the above copyright 9.\" notice, this list of conditions and the following disclaimer. 10.\" 2. Redistributions in binary form must reproduce the above copyright 11.\" notice, this list of conditions and the following disclaimer in the 12.\" documentation and/or other materials provided with the distribution. 13.\" 14.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 15.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 16.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 17.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR THE VOICES IN HIS HEAD BE 18.\" LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 19.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 20.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 21.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 22.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 23.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 24.\" POSSIBILITY OF SUCH DAMAGE. 25.\" 26.\" $FreeBSD$ 27.\" 28.Dd May 28, 2017 29.Dt RCTL 8 30.Os 31.Sh NAME 32.Nm rctl 33.Nd display and update resource limits database 34.Sh SYNOPSIS 35.Nm 36.Op Fl h 37.Op Fl n 38.Op Ar filter Ar ... 39.Nm 40.Fl a 41.Ar rule Ar ... 42.Nm 43.Fl l 44.Op Fl h 45.Op Fl n 46.Ar filter Ar ... 47.Nm 48.Fl r 49.Ar filter Ar ... 50.Nm 51.Fl u 52.Op Fl h 53.Ar filter Ar ... 54.Sh DESCRIPTION 55When called without options, the 56.Nm 57command writes currently defined RCTL rules to standard output. 58.Pp 59If a 60.Ar filter 61argument is specified, only rules matching the filter are displayed. 62The options are as follows: 63.Bl -tag -width indent 64.It Fl a Ar rule 65Add 66.Ar rule 67to the RCTL database. 68.It Fl l Ar filter 69Display rules applicable to the process defined by 70.Ar filter . 71Note that this is different from showing the rules when called without 72any options, as it shows not just the rules with subject equal to that 73of process, but also rules for the user, jail, and login class applicable 74to the process. 75.It Fl r Ar filter 76Remove rules matching 77.Ar filter 78from the RCTL database. 79.It Fl u Ar filter 80Display resource utilization for a subject 81.Po 82.Sy process , 83.Sy user , 84.Sy loginclass 85or 86.Sy jail 87.Pc 88matching the 89.Ar filter . 90.It Fl h 91"Human-readable" output. 92Use unit suffixes: Byte, Kilobyte, Megabyte, 93Gigabyte, Terabyte and Petabyte. 94.It Fl n 95Display user IDs numerically rather than converting them to a user name. 96.El 97.Pp 98Modifying rules affects all currently running and future processes matching 99the rule. 100.Sh RULE SYNTAX 101Syntax for a rule is subject:subject-id:resource:action=amount/per. 102.Pp 103.Bl -tag -width "subject-id" -compact -offset indent 104.It subject 105defines the kind of entity the rule applies to. 106It can be either 107.Sy process , 108.Sy user , 109.Sy loginclass , 110or 111.Sy jail . 112.It subject-id 113identifies the 114.Em subject . 115It can be a process ID, user name, numerical user ID, login class name from 116.Xr login.conf 5 , 117or jail name. 118.It resource 119identifies the resource the rule controls. 120See the 121.Sx RESOURCES 122section below for details. 123.It action 124defines what will happen when a process exceeds the allowed 125.Em amount . 126See the 127.Sx ACTIONS 128section below for details. 129.It amount 130defines how much of the resource a process can use before 131the defined 132.Em action 133triggers. 134Resources which limit bytes may use prefixes from 135.Xr expand_number 3 . 136.It per 137defines what entity the 138.Em amount 139gets accounted for. 140For example, rule "loginclass:users:vmem:deny=100M/process" means 141that each process of any user belonging to login class "users" may allocate 142up to 100MB of virtual memory. 143Rule "loginclass:users:vmem:deny=100M/user" would mean that for each 144user belonging to the login class "users", the sum of virtual memory allocated 145by all the processes of that user will not exceed 100MB. 146Rule "loginclass:users:vmem:deny=100M/loginclass" would mean that the sum of 147virtual memory allocated by all processes of all users belonging to that login 148class will not exceed 100MB. 149.El 150.Pp 151A valid rule has all those fields specified, except for 152.Em per , 153which defaults 154to the value of 155.Em subject . 156.Pp 157A filter is a rule for which one of more fields other than 158.Em per 159is left empty. 160For example, a filter that matches every rule could be written as ":::=/", 161or, in short, ":". 162A filter that matches all the login classes would be "loginclass:". 163A filter that matches all defined rules for 164.Sy maxproc 165resource would be 166"::maxproc". 167.Sh SUBJECTS 168.Bl -column -offset 3n "pseudoterminals" ".Sy username or numerical User ID" 169.It Sy process Ta numerical Process ID 170.It Sy user Ta user name or numerical User ID 171.It Sy loginclass Ta login class from 172.Xr login.conf 5 173.It Sy jail Ta jail name 174.El 175.Sh RESOURCES 176.Bl -column -offset 3n "pseudoterminals" 177.It Sy cputime Ta "CPU time, in seconds" 178.It Sy datasize Ta "data size, in bytes" 179.It Sy stacksize Ta "stack size, in bytes" 180.It Sy coredumpsize Ta "core dump size, in bytes" 181.It Sy memoryuse Ta "resident set size, in bytes" 182.It Sy memorylocked Ta "locked memory, in bytes" 183.It Sy maxproc Ta "number of processes" 184.It Sy openfiles Ta "file descriptor table size" 185.It Sy vmemoryuse Ta "address space limit, in bytes" 186.It Sy pseudoterminals Ta "number of PTYs" 187.It Sy swapuse Ta "swap space that may be reserved or used, in bytes" 188.It Sy nthr Ta "number of threads" 189.It Sy msgqqueued Ta "number of queued SysV messages" 190.It Sy msgqsize Ta "SysV message queue size, in bytes" 191.It Sy nmsgq Ta "number of SysV message queues" 192.It Sy nsem Ta "number of SysV semaphores" 193.It Sy nsemop Ta "number of SysV semaphores modified in a single semop(2) call" 194.It Sy nshm Ta "number of SysV shared memory segments" 195.It Sy shmsize Ta "SysV shared memory size, in bytes" 196.It Sy wallclock Ta "wallclock time, in seconds" 197.It Sy pcpu Ta "%CPU, in percents of a single CPU core" 198.It Sy readbps Ta "filesystem reads, in bytes per second" 199.It Sy writebps Ta "filesystem writes, in bytes per second" 200.It Sy readiops Ta "filesystem reads, in operations per second" 201.It Sy writeiops Ta "filesystem writes, in operations per second" 202.El 203.Sh ACTIONS 204.Bl -column -offset 3n "pseudoterminals" 205.It Sy deny Ta deny the allocation; not supported for 206.Sy cputime , 207.Sy wallclock , 208.Sy readbps , 209.Sy writebps , 210.Sy readiops , 211and 212.Sy writeiops 213.It Sy log Ta "log a warning to the console" 214.It Sy devctl Ta "send notification to" 215.Xr devd 8 216using 217.Sy system 218= "RCTL", 219.Sy subsystem 220= "rule", 221.Sy type 222= "matched" 223.It sig* e.g. 224.Sy sigterm ; 225send a signal to the offending process. 226See 227.Xr signal 3 228for a list of supported signals 229.It Sy throttle Ta "slow down process execution"; only supported for 230.Sy readbps , 231.Sy writebps , 232.Sy readiops , 233and 234.Sy writeiops . 235.El 236.Pp 237Not all actions are supported for all resources. 238Attempting to add a rule with an action not supported by a given resource will 239result in error. 240.Sh EXIT STATUS 241.Ex -std 242.Sh EXAMPLES 243Prevent user "joe" from allocating more than 1GB of virtual memory: 244.Dl Nm Fl a Ar user:joe:vmemoryuse:deny=1g 245.Pp 246Remove all RCTL rules: 247.Dl Nm Fl r Ar \&: 248.Pp 249Display resource utilization information for jail named "www": 250.Dl Nm Fl hu Ar jail:www 251.Pp 252Display all the rules applicable to process with PID 512: 253.Dl Nm Fl l Ar process:512 254.Pp 255Display all rules: 256.Dl Nm 257.Pp 258Display all rules matching user "joe": 259.Dl Nm Ar user:joe 260.Pp 261Display all rules matching login classes: 262.Dl Nm Ar loginclass: 263.Sh SEE ALSO 264.Xr rctl 4 , 265.Xr rctl.conf 5 266.Sh HISTORY 267The 268.Nm 269command appeared in 270.Fx 9.0 . 271.Sh AUTHORS 272.An -nosplit 273The 274.Nm 275was developed by 276.An Edward Tomasz Napierala Aq Mt trasz@FreeBSD.org 277under sponsorship from the FreeBSD Foundation. 278.Sh BUGS 279Limiting 280.Sy memoryuse 281may kill the machine due to thrashing. 282.Pp 283The 284.Sy readiops 285and 286.Sy writeiops 287counters are only approximations. 288Like 289.Sy readbps 290and 291.Sy writebps , 292they are calculated in the filesystem layer, where it is difficult 293or even impossible to observe actual disk device operations. 294.Pp 295The 296.Sy writebps 297and 298.Sy writeiops 299resources generally account for writes to the filesystem cache, 300not to actual devices. 301