diff options
author | bdrewery <bdrewery@FreeBSD.org> | 2014-02-15 14:56:50 +0000 |
---|---|---|
committer | bdrewery <bdrewery@FreeBSD.org> | 2014-02-15 14:56:50 +0000 |
commit | b38a0800aa6330c763e581ed748fabdd3a3bb03e (patch) | |
tree | 0617d4ceaa6d70f92e8b7be1c6c407cc18070b88 /usr.bin | |
parent | 9c227c867f1701ab7fa4b068112afc17c2fe0eba (diff) | |
download | FreeBSD-src-b38a0800aa6330c763e581ed748fabdd3a3bb03e.zip FreeBSD-src-b38a0800aa6330c763e581ed748fabdd3a3bb03e.tar.gz |
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
Diffstat (limited to 'usr.bin')
-rw-r--r-- | usr.bin/rctl/rctl.8 | 190 |
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. |