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