Add rctl(8), the utility to manage rctl rules.

Sponsored by:	The FreeBSD Foundation
Reviewed by:	kib (earlier version)

1 files changed, 200 insertions, 0 deletions

diff --git a/usr.bin/rctl/rctl.8 b/usr.bin/rctl/rctl.8
new file mode 100644
index 0000000..dc9b36d
--- /dev/null
+++ b/usr.bin/rctl/rctl.8
@@ -0,0 +1,200 @@
+.\"-
+.\" Copyright (c) 2009 Edward Tomasz Napierala
+.\" All rights reserved.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice, this list of conditions and the following disclaimer in the
+.\"    documentation and/or other materials provided with the distribution.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
+.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR THE VOICES IN HIS HEAD BE
+.\" LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+.\" POSSIBILITY OF SUCH DAMAGE.
+.\"
+.\" $FreeBSD$
+.\"
+.Dd February 13, 2011
+.Dt RCTL 8
+.Os
+.Sh NAME
+.Nm rctl
+.Nd display and update resource limits database
+.Sh SYNOPSIS
+.Nm
+.Op Fl h
+.Op Fl n
+.Op Ar filter
+.Nm
+.Fl a
+.Op Ar rule
+.Nm
+.Op Fl h
+.Op Fl n
+.Fl l
+.Op Ar filter
+.Nm
+.Fl r
+.Op Ar filter
+.Nm
+.Op Fl h
+.Fl u
+.Op Ar filter
+.Sh DESCRIPTION
+When called without options, the
+.Nm
+command writes currently defined RCTL rules to standard output.
+.Pp
+If a
+.Ar filter
+argument is specified, only rules matching the filter are displayed.
+The options are as follows:
+.Bl -tag -width indent
+.It Fl a Ar rule
+Add
+.Ar rule
+to the RCTL database.
+.It Fl l Ar filter
+Display rules applicable to the process defined by
+.Ar filter .
+.It Fl r Ar filter
+Remove rules matching
+.Ar filter
+from the RCTL database.
+.It Fl u Ar filter
+Display resource usage for a subject (process, user, login class
+or jail) matching the
+.Ar filter .
+.It Fl h
+"Human-readable" output.
+Use unit suffixes: Byte, Kilobyte, Megabyte,
+Gigabyte, Terabyte and Petabyte.
+.It Fl n
+Display user IDs numerically rather than converting them to a user name.
+.Pp
+.Sh RULE SYNTAX
+Syntax for a rule is subject:subject-id:resource:action=amount/per.
+.Pp
+Subject defines the kind of entity the rule applies to.
+It can be either process, user, login class, or jail.
+.Pp
+Subject ID identifies the subject.  It can be user name,
+numerical user ID, login class name, jail name, or numerical jail ID.
+.Pp
+Resource identifies the resource the rule controls.
+.Pp
+Action defines what will happen when a process exceeds the allowed amount.
+.Pp
+Amount defines how much of the resource a process can use before
+the defined action triggers.
+.Pp
+The per field defines what entity the amount gets accounted for.
+For example, rule "loginclass:users:vmem:deny=100M/process" means
+that each process of any user belonging to login class "users" may allocate
+up to 100MB of virtual memory.
+Rule "loginclass:users:vmem:deny=100M/user" would mean that for each
+user belonging to the login class "users", the sum of virtual memory allocated
+by all the processes of a that user will not exceed 100MB.
+Rule "loginclass:users:vmem:deny=100M/loginclass" would mean that the sum of
+virtual memory allocated by all processes of all users belonging to that login
+class will not exceed 100MB.
+.Pp
+Valid rule has all those fields specified, except for the per, which defaults
+to the value of subject.
+.Pp
+A filter is a rule for which one of more fields other than per is left empty.
+For example, a filter that matches every rule could be written as ":::=/",
+or, in short, ":".
+A filter that matches all the login classes would be "loginclass:".
+A filter that matches all defined rules for nproc resource would be
+"::nproc".
+.Pp
+.Sh RESOURCES
+.Bl -column -offset 3n "msgqqueued"
+.It cpu		CPU time, in milliseconds
+.It fsize	maximum file size, in bytes
+.It data	data size, in bytes
+.It stack	stack size, in bytes
+.It core	core dump size, in bytes
+.It rss		resident set size, in bytes
+.It memlock	locked memory, in bytes
+.It nproc	number of processes
+.It nofile	file descriptor table size
+.It sbsize	memory consumed by socket buffers, in bytes
+.It vmem	address space limit, in bytes
+.It npts	number of PTYs
+.It swap	swap usage, in bytes
+.It nthr	number of threads
+.It msgqqueued	number of queued SysV messages
+.It msgqsize	SysV message queue size, in bytes
+.It nmsgq	number of SysV message queues
+.It nsem	number of SysV semaphores
+.It nsemop	number of SysV semaphores modified in a single semop(2) call
+.It nshm	number of SysV shared memory segments
+.It shmsize	SysV shared memory size, in bytes
+.It wallclock	wallclock time, in milliseconds
+.It pctcpu	%cpu time
+.El
+.Pp
+.Sh ACTIONS
+.Bl -column -offset 3n "msgqqueued"
+.It deny	deny the allocation; not supported for cpu and wallclock
+.It log		log a warning to the console
+.It devctl	send notification to
+.Xr devd 8
+.It sig*	e.g. sigterm; send a signal to the offending process
+.El
+.Pp
+See
+.Xr signal 3
+for a list of supported signals.
+.Pp
+Not all actions are supported for all resources.
+Attempt to add rule with action not supported by a given resouce will result
+in error.
+.Pp
+Note that limiting RSS may kill the machine due to thrashing.
+.Pp
+.Sh EXIT STATUS
+.Ex -std
+.Sh EXAMPLES
+.Dl rctl -a user:joe:vmem:deny=1g
+.Pp
+Prevent user "joe" from allocating more than 1GB of virtual memory.
+.Pp
+.Dl rctl -r :
+.Pp
+Remove all RCTL rules.
+.Pp
+.Dl rctl -hu jail:5
+.Pp
+Display resource usage information for jail with JID 5.
+.Pp
+.Dl rctl -l process:512
+.Pp
+Display all the rules applicable to process with PID 512.
+.Sh SEE ALSO
+.Xr jailstat 8 ,
+.Xr userstat 8
+.Sh HISTORY
+The
+.Nm
+command appeared in
+.Fx 9.0.
+.Sh AUTHORS
+.An -nosplit
+The
+.Nm
+command was written by
+.An Edward Tomasz Napierala Aq trasz@FreeBSD.org .