svn commit: r41641 - projects/ISBN_1-57176-407-0/en_US.ISO8859-1/books/handbook/security

[Tom Rhodes]

Author: trhodes
Date: Fri May 17 17:27:33 2013
New Revision: 41641
URL: http://svnweb.freebsd.org/changeset/doc/41641

Log:
  Add a section on rctl(8).
  
  Requested by:	someone (bcr?  dru?)

Modified:
  projects/ISBN_1-57176-407-0/en_US.ISO8859-1/books/handbook/security/chapter.xml

Modified: projects/ISBN_1-57176-407-0/en_US.ISO8859-1/books/handbook/security/chapter.xml
==============================================================================
--- projects/ISBN_1-57176-407-0/en_US.ISO8859-1/books/handbook/security/chapter.xml	Fri May 17 17:26:20 2013	(r41640)
+++ projects/ISBN_1-57176-407-0/en_US.ISO8859-1/books/handbook/security/chapter.xml	Fri May 17 17:27:33 2013	(r41641)
@@ -89,6 +89,11 @@
 	<para>What Process Accounting is and how to enable it on
 	  &os;.</para>
       </listitem>
+
+      <listitem>
+	<para>Understand the resource limits database and
+	  how to utilize it to control user resources.</para>
+      </listitem>
     </itemizedlist>
 
     <para>Before reading this chapter, you should:</para>
@@ -3691,4 +3696,119 @@ VII. References <co id="co-ref"/></progr
 	&man.lastcomm.1;, &man.acct.5;, and &man.sa.8;.</para>
     </sect2>
   </sect1>
+
+  <sect1 id="security-resourcelimits">
+    <sect1info>
+      <authorgroup>
+       <author>
+         <firstname>Tom</firstname>
+         <surname>Rhodes</surname>
+         <contrib>Contributed by </contrib>
+       </author>
+      </authorgroup>
+    </sect1info>
+
+    <title>Resource Limits</title>
+
+    <indexterm>
+      <primary>Resource limits</primary>
+    </indexterm>
+
+    <para>For years, &os; has used a resource limits
+      database controlled through a flat file,
+      <filename>/etc/login.conf</filename>.  While it has
+      been discussed previously and is still supported, it
+      is not the most optimal method of controlling resources.
+      The flat file requires users to be divided into various
+      group labels known as classes, which require changes not
+      only to this flat file but also the password database.
+      Potentially a single, more constrained user would require
+      an additional label added, the resource database needs to be
+      built using <command>cap_mkdb</command>, edits made to
+      the <filename>/etc/master.passwd</filename> file.  In
+      addition, the password database must be rebuilt using
+      <command>pwd_mkdb</command>.  This multi-step process could be
+      very time consuming depending on how many users must be
+      singled out.</para>
+
+    <para>A new command in &os;, &man.rctl.8;, allows for a more
+      fine grained method of controlling resources limits for
+      users.  This command will support much more than users,
+      it will also set resource constraints on processes, jails,
+      and the original login class.  These advanced features
+      provide administrators and users with methods to control
+      resources through the command line and set rules on
+      system initialization using a configuration
+      file.</para>
+
+    <para>To enable this feature, add these lines to
+      <filename>GENERIC</filename>, or the custom kernel
+      configuration file, and rebuild.:</para>
+
+    <programlisting>options         RACCT
+options         RCTL</programlisting>
+
+    <para>The entire system will need rebuilt.  See <xref
+        linkend="kernelconfig"/>, which will provide instructions for
+      the process.  Once this is complete, the <command>rctl</command>
+      may be used to set rules for the system.</para>
+
+    <para>Rule syntax is simple, controlled through the use of
+      a <emphasis>subject</emphasis>, a <emphasis>subject-id</emphasis>,
+      <emphasis>resource</emphasis>, and <emphasis>action</emphasis>.
+      Take the following example rule:</para>
+
+    <programlisting>user:trhodes:<literal>maxproc</literal>:<literal>deny</literal>=10/user</programlisting>
+
+    <para>This rule shows a basic premise of a rule, here the
+      subject is <literal>user</literal> and the subject-id
+      is <literal>trhodes</literal>.  The maxproc is, of course,
+      max number of processes, which is considered the action.
+      The action here is set to <literal>deny</literal>, which blocks
+      any new processes from being created.  In the previous example,
+      the user, <literal>trhodes</literal> will be constrained
+      to <literal>10</literal> (ten) processes and no greater.
+      Other actions are available and could be log to the console,
+      pass a notification to &man.devd.8;, or
+      send a sigterm to the process.</para>
+
+    <para>Some care must be taken while adding rules.  The one above
+      will unfortunately block my user from doing the most simple tasks
+      after I have logged in and executed a <command>screen</command>
+      session.  When a resource limit has been hit, an error will
+      be printed, as in this example:</para>
+
+    <screen>&prompt.user; <userinput>man test</userinput>
+    /usr/bin/man: Cannot fork: Resource temporarily unavailable
+eval: Cannot fork: Resource temporarily unavailable</screen>
+
+    <para>For another example, &man.rctl.8; can be used to prevent
+      a jail from exceeding a memory limit.  This rule could be
+      written as:</para>
+
+    <screen>&prompt.root; <userinput>rctl -a jail:httpd:memoryuse:deny=2G/jail</userinput></screen>
+
+    <para>Rules may also persist across reboots if they have been
+      added to <filename>/etc/rctl.conf</filename> file.  The
+      format is a rule, without the preceding command.  For example,
+      the previous rule could be added like the following:</para>
+
+    <programlisting># Block jail from using more than 2G memory:
+jail:httpd:memoryuse:deny=2G/jail</programlisting>
+
+    <para>To remove a rule, just ask <command>rctl</command> to
+      remove it from the list:</para>
+
+    <screen>&prompt.root; <userinput>rctl -r user:trhodes:maxproc:deny=10/user</userinput></screen>
+
+    <para>The manual page shows a method for removing all rules;
+      however, if removing all rules for a single user is required,
+      this command may be issued:</para>
+
+    <screen>&prompt.root; <userinput>rctl -r user:trhodes</userinput></screen>
+
+    <para>Many other resources exist which can be used to excert
+      additional control over various <literal>subjects</literal>.
+      See &man.rctl.8; to learn about them.</para>
+  </sect1>
 </chapter>