[REVIEW REQUEST]: rctl section

[Warren Block]

On Fri, 1 Feb 2013, Tom Rhodes wrote:

> Long time, no chat.  It's been awhile, so I would like to get some
> review on this section.  In this case, I have used some generic
> results (testing them with a forkbomb, smart, I know) and I would
> like to get some pre-commit feedback.  Thanks in advance to anyone
> who loans me a few moments of their time!

Nice to hear from you!  Comments inline below.

> Index: security/chapter.xml
> ===================================================================
> --- chapter.xml (revision 40807)
> +++ chapter.xml (working copy)
> @@ -97,6 +97,11 @@
>        <para>Have an idea of what Process Accounting is and how to
>          enable it on &os;.</para>
>       </listitem>
> +
> +      <listitem>
> +       <para>Understand what the resource limits database and
> +         how to utilize it to excerpt more control over users.</para>

s/what//
s/excerpt/exert/.  "how to utilize it to control user resources" might 
be better.

> +      </listitem>
>     </itemizedlist>
>
>     <para>Before reading this chapter, you should:</para>
> @@ -4149,4 +4154,116 @@
>        pages.</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>

s/limits/Limits/
textproc/igor can check these.


> +
> +    <indexterm>
> +      <primary>Resource limits</primary>
> +    </indexterm>
> +
> +    <para>For years, &os; has made use of a resource limits
> +      database controlled through a flat file

s/file/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

I want to say that the comma after "single" is not needed, but that's 
not quite right.  Maybe if "more constrained" was hyphenated.

> +      an additional label added, the resource database needs to be
> +      built using <command>cap_mkdb</command>, along with edits to
> +      the <filename>/etc/master.passwd</filename> file.  In

How about just "edits to <filename>/etc/master.passwd</filename>."? 
textproc/igor checks for these; the FDP style guide advises avoid the 
redundancy.

> +      addition, the password database will also need rebuilt using

"will also need rebuilt" could be colloquial.  "Must be rebuilt" would 
work.

> +      <command>pwd_mkdb</command>.  This multi-step process could be
> +      very time consuming depending on how many users must be
> +      singled out.</para>

For cap_mkdb and pwd_mkdb, man entities may be better.  I've been trying 
to use <command> when talking specifically about using the command, and 
man entities when talking about the whole application.  Here it's a 
little fuzzy.  The man entities give the user a link to the man page, 
though.

> +    <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 the following lines to

Suggestion: "these" instead of "the following".  (We have way too many 
of "the following" already; the reader can see that it is following, 
because it is.)

> +      <filename>GENERIC</filename>, or the custom kernel
> +      configuration file, and rebuild.:</para>
> +
> +    <programlisting>options         RACCT
> +options         RCTL</programlisting>
> +
> +    <para>Due to the nature of this configuration file, the
> +      entire system will need rebuilt.  See <xref

Aha!  That really is a colloquialism.  But how about "the kernel must be 
rebuilt."?

> +      linkend="kernelconfig"/>, which will provide instructions for

The diff may distort it, but I think that line needs to be indented 
another level (still inside the xref tag).  textproc/igor checks for 
these, too.

> +      this process.  Once this is complete, the <command>rctl</command>

s/the//

> +      may be used to set rules for the system.</para>
> +
> +    <para>Rule syntax is simple, controlled through the use of
> +      a subject, a subject-id, resource, and action.  Take the

Those terms should probably be marked up.  Maybe <emphasis> tags around 
them?

> +      following example rule:</para>
> +
> +    <programlisting>user:trhodes:maxproc:deny=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,

<literal> around "maxproc" also.

> +      max number of processes, which is considered the action.

"is considered" by what?  Would just "is" be adequate?  And I think it's 
not an action, but a resource.

> +      The action here is set to deny, which blocks any new

<literal> around "deny".

> +      processes from being created.

Wait, what does "10/user" mean?

> +      Other actions could be

s/be/be to/

> +      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

That comma should be a full stop.

> +      will unfortunately block me 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; could be used to prevent

s/could/can/ (active)

> +      a jail from exceeding a memory limit.  This rule could be

s/could/can/ (active)

> +      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 the <filename>/etc/rctl.conf</filename> file.  The

"added to <filename>/etc/rctl.conf</filename>."

> +      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,
> +      the following command may be issued:</para>

How about "this command" instead of "the following command"?

> +    <screen>&prompt.root; <userinput>rctl -r user:trhodes</userinput></screen>
> +
> +    <para>Many other resources exist which could be used to excerpt

s/could/can/ (active)
s/excerpt/exert/

> +      additional control over subjects.

Not really sure what that means.  Is "subjects" a technical term, or 
does it just mean "things"?  If so, how about "<command>rctl</command> 
can control many resources."

> +      See the manual page for
> +      <command>rctl</command> to learn about them.</para>

"See &man.rctl.8; to learn about them.</para>"

> +  </sect1>
> </chapter>

Thank you!