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 22, 2011 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 nproc resource would be 121"::nproc". 122.Pp 123.Sh RESOURCES 124.Bl -column -offset 3n "pseudoterminals" 125.It "cputime CPU time, in seconds" 126.It "datasize data size, in bytes" 127.It "stacksize stack size, in bytes" 128.It "coredumpsize core dump size, in bytes" 129.It "memoryuse resident set size, in bytes" 130.It "memorylocked locked memory, in bytes" 131.It "maxproc number of processes" 132.It "openfiles file descriptor table size" 133.It "vmemoryuse address space limit, in bytes" 134.It "pseudoterminals number of PTYs" 135.It "swapuse swap usage, in bytes" 136.It "nthr number of threads" 137.It "msgqqueued number of queued SysV messages" 138.It "msgqsize SysV message queue size, in bytes" 139.It "nmsgq number of SysV message queues" 140.It "nsem number of SysV semaphores" 141.It "nsemop number of SysV semaphores modified in a single semop(2) call" 142.It "nshm number of SysV shared memory segments" 143.It "shmsize SysV shared memory size, in bytes" 144.It "wallclock wallclock time, in seconds" 145.El 146.Pp 147.Sh ACTIONS 148.Bl -column -offset 3n "pseudoterminals" 149.It "deny deny the allocation; not supported for cpu and wallclock" 150.It "log log a warning to the console" 151.It "devctl send notification to" 152.Xr devd 8 153.It "sig* e.g. sigterm; send a signal to the offending process" 154.El 155.Pp 156See 157.Xr signal 3 158for a list of supported signals. 159.Pp 160Not all actions are supported for all resources. 161Attempt to add rule with action not supported by a given resouce will result 162in error. 163.Pp 164Note that limiting RSS may kill the machine due to thrashing. 165.Pp 166.Sh EXIT STATUS 167.Ex -std 168.Sh EXAMPLES 169.Dl rctl -a user:joe:vmemoryuse:deny=1g 170.Pp 171Prevent user "joe" from allocating more than 1GB of virtual memory. 172.Pp 173.Dl rctl -r : 174.Pp 175Remove all RCTL rules. 176.Pp 177.Dl rctl -hu jail:www 178.Pp 179Display resource usage information for jail named "www". 180.Pp 181.Dl rctl -l process:512 182.Pp 183Display all the rules applicable to process with PID 512. 184.Sh SEE ALSO 185.Xr rctl.conf 5 , 186.Xr jailstat 8 , 187.Xr userstat 8 188.Sh HISTORY 189The 190.Nm 191command appeared in 192.Fx 9.0. 193.Sh AUTHORS 194.An -nosplit 195The 196.Nm 197command was written by 198.An Edward Tomasz Napierala Aq trasz@FreeBSD.org . 199