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