From owner-svn-src-all@FreeBSD.ORG Sun Feb 23 20:07:31 2014 Return-Path: Delivered-To: svn-src-all@freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:1900:2254:206a::19:1]) (using TLSv1 with cipher ADH-AES256-SHA (256/256 bits)) (No client certificate requested) by hub.freebsd.org (Postfix) with ESMTPS id 0D801922; Sun, 23 Feb 2014 20:07:31 +0000 (UTC) Received: from svn.freebsd.org (svn.freebsd.org [IPv6:2001:1900:2254:2068::e6a:0]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by mx1.freebsd.org (Postfix) with ESMTPS id DE88010D3; Sun, 23 Feb 2014 20:07:30 +0000 (UTC) Received: from svn.freebsd.org ([127.0.1.70]) by svn.freebsd.org (8.14.8/8.14.8) with ESMTP id s1NK7Ukj005657; Sun, 23 Feb 2014 20:07:30 GMT (envelope-from bdrewery@svn.freebsd.org) Received: (from bdrewery@localhost) by svn.freebsd.org (8.14.8/8.14.8/Submit) id s1NK7Um2005656; Sun, 23 Feb 2014 20:07:30 GMT (envelope-from bdrewery@svn.freebsd.org) Message-Id: <201402232007.s1NK7Um2005656@svn.freebsd.org> From: Bryan Drewery Date: Sun, 23 Feb 2014 20:07:30 +0000 (UTC) To: src-committers@freebsd.org, svn-src-all@freebsd.org, svn-src-stable@freebsd.org, svn-src-stable-10@freebsd.org Subject: svn commit: r262385 - stable/10/usr.bin/rctl X-SVN-Group: stable-10 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit X-BeenThere: svn-src-all@freebsd.org X-Mailman-Version: 2.1.17 Precedence: list List-Id: "SVN commit messages for the entire src tree \(except for " user" and " projects" \)" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Sun, 23 Feb 2014 20:07:31 -0000 Author: bdrewery Date: Sun Feb 23 20:07:30 2014 New Revision: 262385 URL: http://svnweb.freebsd.org/changeset/base/262385 Log: MFC r261934: Rework rctl(8) manpage Approved by: bapt (mentor, implicit) Modified: stable/10/usr.bin/rctl/rctl.8 Directory Properties: stable/10/ (props changed) Modified: stable/10/usr.bin/rctl/rctl.8 ============================================================================== --- stable/10/usr.bin/rctl/rctl.8 Sun Feb 23 20:04:29 2014 (r262384) +++ stable/10/usr.bin/rctl/rctl.8 Sun Feb 23 20:07:30 2014 (r262385) @@ -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 n 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. -.Pp -A filter is a rule for which one of more fields other than per is left empty. +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 +.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 j .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.