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 December 3, 2012 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 39.Nm 40.Fl a 41.Op Ar rule 42.Nm 43.Op Fl h 44.Op Fl n 45.Fl l 46.Op Ar filter 47.Nm 48.Fl r 49.Op Ar filter 50.Nm 51.Op Fl h 52.Fl u 53.Op Ar filter 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 usage for a subject (process, user, login class 81or jail) matching the 82.Ar filter . 83.It Fl h 84"Human-readable" output. 85Use unit suffixes: Byte, Kilobyte, Megabyte, 86Gigabyte, Terabyte and Petabyte. 87.It Fl n 88Display user IDs numerically rather than converting them to a user name. 89.El 90.Sh RULE SYNTAX 91Syntax for a rule is subject:subject-id:resource:action=amount/per. 92.Pp 93Subject defines the kind of entity the rule applies to. 94It can be either process, user, login class, or jail. 95.Pp 96Subject ID identifies the subject. 97It can be a process ID, user name, numerical user ID, login class name, 98or jail name. 99.Pp 100Resource identifies the resource the rule controls. 101.Pp 102Action defines what will happen when a process exceeds the allowed amount. 103.Pp 104Amount defines how much of the resource a process can use before 105the defined action triggers. 106.Pp 107The per field defines what entity the amount gets accounted for. 108For example, rule "loginclass:users:vmem:deny=100M/process" means 109that each process of any user belonging to login class "users" may allocate 110up to 100MB of virtual memory. 111Rule "loginclass:users:vmem:deny=100M/user" would mean that for each 112user belonging to the login class "users", the sum of virtual memory allocated 113by all the processes of that user will not exceed 100MB. 114Rule "loginclass:users:vmem:deny=100M/loginclass" would mean that the sum of 115virtual memory allocated by all processes of all users belonging to that login 116class will not exceed 100MB. 117.Pp 118Valid rule has all those fields specified, except for the per, which defaults 119to the value of subject. 120.Pp 121A filter is a rule for which one of more fields other than per is left empty. 122For example, a filter that matches every rule could be written as ":::=/", 123or, in short, ":". 124A filter that matches all the login classes would be "loginclass:". 125A filter that matches all defined rules for maxproc resource would be 126"::maxproc". 127.Sh RESOURCES 128.Bl -column -offset 3n "pseudoterminals" 129.It cputime Ta "CPU time, in seconds" 130.It datasize Ta "data size, in bytes" 131.It stacksize Ta "stack size, in bytes" 132.It coredumpsize Ta "core dump size, in bytes" 133.It memoryuse Ta "resident set size, in bytes" 134.It memorylocked Ta "locked memory, in bytes" 135.It maxproc Ta "number of processes" 136.It openfiles Ta "file descriptor table size" 137.It vmemoryuse Ta "address space limit, in bytes" 138.It pseudoterminals Ta "number of PTYs" 139.It swapuse Ta "swap usage, in bytes" 140.It nthr Ta "number of threads" 141.It msgqqueued Ta "number of queued SysV messages" 142.It msgqsize Ta "SysV message queue size, in bytes" 143.It nmsgq Ta "number of SysV message queues" 144.It nsem Ta "number of SysV semaphores" 145.It nsemop Ta "number of SysV semaphores modified in a single semop(2) call" 146.It nshm Ta "number of SysV shared memory segments" 147.It shmsize Ta "SysV shared memory size, in bytes" 148.It wallclock Ta "wallclock time, in seconds" 149.It pcpu Ta "%CPU, in percents of a single CPU core" 150.El 151.Sh ACTIONS 152.Bl -column -offset 3n "pseudoterminals" 153.It deny Ta "deny the allocation; not supported for cpu and wallclock" 154.It log Ta "log a warning to the console" 155.It devctl Ta "send notification to" 156.Xr devd 8 157.It "sig* e.g. sigterm; send a signal to the offending process" 158.El 159.Pp 160See 161.Xr signal 3 162for a list of supported signals. 163.Pp 164Not all actions are supported for all resources. 165Attempt to add rule with action not supported by a given resouce will result 166in error. 167.Pp 168Note that limiting RSS may kill the machine due to thrashing. 169.Sh EXIT STATUS 170.Ex -std 171.Sh EXAMPLES 172Prevent user "joe" from allocating more than 1GB of virtual memory: 173.Dl Nm Fl a Ar user:joe:vmemoryuse:deny=1g 174.Pp 175Remove all RCTL rules: 176.Dl Nm Fl r Ar \&: 177.Pp 178Display resource usage information for jail named "www": 179.Dl Nm Fl hu Ar jail:www 180.Pp 181Display all the rules applicable to process with PID 512: 182.Dl Nm Fl l Ar process:512 183.Sh SEE ALSO 184.Xr rctl.conf 5 185.Sh HISTORY 186The 187.Nm 188command appeared in 189.Fx 9.0 . 190.Sh AUTHORS 191.An -nosplit 192The 193.Nm 194command was written by 195.An Edward Tomasz Napierala Aq trasz@FreeBSD.org . 196