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