Rework rctl(8) manpage
- Note that kernel options are required - Shift parameters around in SYNOPSIS to make it more clear that there are different modes - For all literal symbols such as 'process' or 'loginclass' or 'wallclock', etc, make them into bold symbols with .Sy - For each subject:subject-id:etc: use .Em to underline to make it more clear they relate to the rule syntax - Document how devd(8) support works - Move RSS warning to BUGS and replace RSS with 'memoryuse' since 'RSS' is not defined in the manpage - Add more examples around listing existing rules - Make rule syntax into a list to improve readability - Add a list of subjects and their corresponding subject-id same as RESOURCES/ACTIONS have lists - Note that rctl(8) takes affect on all current and future processes - Note that amount can take human numbers - Add reference to login.conf(5) in few places login class is mentioned Reviewed by: trasz Approved by: bapt (mentor) MFC after: 1 week
This commit is contained in:
Bryan Drewery
parent
4360b89b6d
commit
c0a04e017b
@ -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.
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user