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