MFC r261934:

  Rework rctl(8) manpage

Approved by:	bapt (mentor, implicit)

1 files changed, 135 insertions, 55 deletions

diff --git a/usr.bin/rctl/rctl.8 b/usr.bin/rctl/rctl.8
index 6b2f4da..5df0310 100644
--- a/usr.bin/rctl/rctl.8
+++ b/usr.bin/rctl/rctl.8
@@ -25,7 +25,7 @@
 .\"
 .\" $FreeBSD$
 .\"
-.Dd December 3, 2012
+.Dd February 14, 2014
 .Dt RCTL 8
 .Os
 .Sh NAME
@@ -40,17 +40,24 @@
 .Fl a
 .Op Ar rule
 .Nm
+.Fl l
 .Op Fl h
 .Op Fl n
-.Fl l
 .Op Ar filter
 .Nm
 .Fl r
 .Op Ar filter
 .Nm
-.Op Fl h
 .Fl u
+.Op Fl h
 .Op Ar filter
+.Pp
+.Nm
+requires the kernel to be compiled with:
+.Bd -ragged -offset indent
+.Cd "options RACCT"
+.Cd "options RCTL"
+.Ed
 .Sh DESCRIPTION
 When called without options, the
 .Nm
@@ -77,8 +84,15 @@ 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
+Display resource usage for a subject
+.Po
+.Sy process ,
+.Sy user ,
+.Sy loginclass
+or
+.Sy jail
+.Pc
+matching the
 .Ar filter .
 .It Fl h
 "Human-readable" output.
@@ -87,24 +101,49 @@ Gigabyte, Terabyte and Petabyte.
 .It Fl n
 Display user IDs numerically rather than converting them to a user name.
 .El
+.Pp
+Modifying rules affects all currently running and future processes matching
+the rule.
 .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 a process ID, user name, numerical user ID, login class name,
+.Bl -tag -width "subject-id" -compact -offset indent
+.It subject
+defines the kind of entity the rule applies to.
+It can be either
+.Sy process ,
+.Sy user ,
+.Sy loginclass ,
+or
+.Sy jail .
+.It subject-id
+identifies the
+.Em subject .
+It can be a process ID, user name, numerical user ID, login class name from
+.Xr login.conf 5 ,
 or jail name.
-.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.
+.It resource
+identifies the resource the rule controls.
+See the
+.Sx RESOURCES
+section below for details.
+.It action
+defines what will happen when a process exceeds the allowed
+.Em amount .
+See the
+.Sx ACTIONS
+section below for details.
+.It amount
+defines how much of the resource a process can use before
+the defined
+.Em action
+triggers.
+Resources which limit bytes may use prefixes from
+.Xr expand_number 3 .
+.It per
+defines what entity the
+.Em 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.
@@ -114,58 +153,86 @@ by all the processes of 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.
+.El
 .Pp
-Valid rule has all those fields specified, except for the per, which defaults
-to the value of subject.
+A valid rule has all those fields specified, except for
+.Em per ,
+which defaults
+to the value of
+.Em subject .
 .Pp
-A filter is a rule for which one of more fields other than per is left empty.
+A filter is a rule for which one of more fields other than
+.Em 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 maxproc resource would be
+A filter that matches all defined rules for
+.Sy maxproc
+resource would be
 "::maxproc".
+.Sh SUBJECTS
+.Bl -column -offset 3n "pseudoterminals" ".Sy username or numerical User ID"
+.It Em subject Ta Em subject-id
+.It Sy process Ta numerical Process ID
+.It Sy user Ta user name or numerical User ID
+.It Sy loginclass Ta login class from
+.Xr login.conf 5
+.It Sy jail Ta jail name
+.El
 .Sh RESOURCES
 .Bl -column -offset 3n "pseudoterminals"
-.It cputime Ta "CPU time, in seconds"
-.It datasize Ta "data size, in bytes"
-.It stacksize Ta "stack size, in bytes"
-.It coredumpsize Ta "core dump size, in bytes"
-.It memoryuse Ta "resident set size, in bytes"
-.It memorylocked Ta "locked memory, in bytes"
-.It maxproc Ta "number of processes"
-.It openfiles Ta "file descriptor table size"
-.It vmemoryuse Ta "address space limit, in bytes"
-.It pseudoterminals Ta "number of PTYs"
-.It swapuse Ta "swap usage, in bytes"
-.It nthr Ta "number of threads"
-.It msgqqueued Ta "number of queued SysV messages"
-.It msgqsize Ta "SysV message queue size, in bytes"
-.It nmsgq Ta "number of SysV message queues"
-.It nsem Ta "number of SysV semaphores"
-.It nsemop Ta "number of SysV semaphores modified in a single semop(2) call"
-.It nshm Ta "number of SysV shared memory segments"
-.It shmsize Ta "SysV shared memory size, in bytes"
-.It wallclock Ta "wallclock time, in seconds"
-.It pcpu Ta "%CPU, in percents of a single CPU core"
+.It Em resource
+.It Sy cputime Ta "CPU time, in seconds"
+.It Sy datasize Ta "data size, in bytes"
+.It Sy stacksize Ta "stack size, in bytes"
+.It Sy coredumpsize Ta "core dump size, in bytes"
+.It Sy memoryuse Ta "resident set size, in bytes"
+.It Sy memorylocked Ta "locked memory, in bytes"
+.It Sy maxproc Ta "number of processes"
+.It Sy openfiles Ta "file descriptor table size"
+.It Sy vmemoryuse Ta "address space limit, in bytes"
+.It Sy pseudoterminals Ta "number of PTYs"
+.It Sy swapuse Ta "swap usage, in bytes"
+.It Sy nthr Ta "number of threads"
+.It Sy msgqqueued Ta "number of queued SysV messages"
+.It Sy msgqsize Ta "SysV message queue size, in bytes"
+.It Sy nmsgq Ta "number of SysV message queues"
+.It Sy nsem Ta "number of SysV semaphores"
+.It Sy nsemop Ta "number of SysV semaphores modified in a single semop(2) call"
+.It Sy nshm Ta "number of SysV shared memory segments"
+.It Sy shmsize Ta "SysV shared memory size, in bytes"
+.It Sy wallclock Ta "wallclock time, in seconds"
+.It Sy pcpu Ta "%CPU, in percents of a single CPU core"
 .El
 .Sh ACTIONS
 .Bl -column -offset 3n "pseudoterminals"
-.It deny Ta "deny the allocation; not supported for cpu and wallclock"
-.It log Ta "log a warning to the console"
-.It devctl Ta "send notification to"
+.It Em action
+.It Sy deny Ta deny the allocation; not supported for
+.Sy cpu
+and
+.Sy wallclock
+.It Sy log Ta "log a warning to the console"
+.It Sy devctl Ta "send notification to"
 .Xr devd 8
-.It "sig*	e.g. sigterm; send a signal to the offending process"
-.El
-.Pp
+using
+.Sy system
+= "RCTL",
+.Sy subsystem
+= "rule",
+.Sy type
+= "matched"
+.It sig*	e.g.
+.Sy sigterm ;
+send a signal to the offending process.
 See
 .Xr signal 3
-for a list of supported signals.
+for a list of supported signals
+.El
 .Pp
 Not all actions are supported for all resources.
-Attempt to add rule with action not supported by a given resource will result
-in error.
-.Pp
-Note that limiting RSS may kill the machine due to thrashing.
+Attempting to add a rule with an action not supported by a given resource will
+result in error.
 .Sh EXIT STATUS
 .Ex -std
 .Sh EXAMPLES
@@ -180,6 +247,15 @@ Display resource usage information for jail named "www":
 .Pp
 Display all the rules applicable to process with PID 512:
 .Dl Nm Fl l Ar process:512
+.Pp
+Display all rules:
+.Dl Nm
+.Pp
+Display all rules matching user "joe":
+.Dl Nm Ar user:joe
+.Pp
+Display all rules matching login classes:
+.Dl Nm Ar loginclass:
 .Sh SEE ALSO
 .Xr rctl.conf 5
 .Sh HISTORY
@@ -193,3 +269,7 @@ The
 .Nm
 command was written by
 .An Edward Tomasz Napierala Aq trasz@FreeBSD.org .
+.Sh BUGS
+Limiting
+.Sy memoryuse
+may kill the machine due to thrashing.