Fixing the man page for renice

[Frank Leonhardt]

On 06/07/2013 16:28, Glen Barber wrote:
> On Sat, Jul 06, 2013 at 12:24:40PM +0100, Frank Leonhardt wrote:
>> Okay - I've been around here for some time but I haven't actually
>> changed anything. I'm hoping someone will sanity check the following
>> as a reasonable course of action, as I really don't want to mess
>> anything up.
>>
>> I'm reading:
>>
>> http://www.freebsd.org/doc/en/articles/problem-reports/index.html
>>
>> The problem is the man page for renice. Has anyone tried it as the
>> root user in a jail? You can increase the nice value of any process
>> within the jail you like, but you can't decrease it. In other words
>> it behaves as though you were a standard user except you can change
>> other users' processes too.
>>
>> This all seems reasonable as you don't want the root user in their
>> jailed machine pinching CPU time from everyone else. It's probably
>> documented somewhere, but I've only found an old discussion about
>> allowing jailed users to renice anything. It's certinaly not in the
>> first place I'd look - the man page.
>>
>> So, what I've done:
>>
>> I've searched for "renice" in
>> http://www.freebsd.org/cgi/query-pr-summary.cgi?query and not found
>> it listed.
>>
>> I've Googled for things like "renice in jail"
>>
>> I've checked out the behaviour out on running systems I have
>> available to me.
>>
>> I'm about to fill out this form here:
>>
>> http://www.freebsd.org/send-pr.html
>>
>> Should I do anything else first?
>>
> Will you be including a patch?  If so, perhaps sending the patch to this
> list for review might be a good first course of action.  If not, then
> your plan looks good. :)
>
> Glen
>

Thanks Glen - the "patch" business is what's putting me off! I'm sure 
once I've done it, nothing will stop me. Is there a page or *really 
simple* guide to doing it, that assumes nothing?


As to the changes, I'd go from:

      Users other than the super-user may only alter the priority of 
processes
      they own, and can only monotonically increase their ``nice value'' 
within
      the range 0 to PRIO_MAX (20).  (This prevents overriding 
administrative
      fiats.)  The super-user may alter the priority of any process and 
set the
      priority to any value in the range PRIO_MIN (-20) to PRIO_MAX. Useful
      priorities are: 20 (the affected processes will run only when nothing
      else in the system wants to), 0 (the ``base'' scheduling 
priority), any-
      thing negative (to make things go very fast).

to

      Users other than the super-user may only alter the priority of 
processes
      they own, and can only monotonically increase their ``nice value'' 
within
      the range 0 to PRIO_MAX (20).  (This prevents overriding 
administrative
      fiats.)  *** Except when running in a jail,*** the super-user may 
alter the priority of
      any process and set the priority to any value in the range 
PRIO_MIN (-20)
      to PRIO_MAX.  Useful priorities are: 20 (the affected processes 
will run only
     when nothing else in the system wants to), 0 (the ``base'' 
scheduling priority), any-
      thing negative (to make things go very fast).

     ***Within a jail, the super-user may increase the "nice value'' of 
any process belonging
     to a user in the same jail, but may not reduce it, even if they 
originally raised it or
     if the process belongs to them.  The super-user on the system 
hosting a jail
     may manipulate the nice value on any process, regardless of whether 
its jailed.***

I'm tempted to re-write the whole lot, but I'm successfully resisting.

Why is this referring to "super-user", and not "root". I prefer root, 
but if there's a style-guide that says call root "super-user" then fair 
enough. Yes, you could call root something different if you wanted to 
mess with things but I'd guess anyone knowing enough to do that would be 
above being confused by the documentation.

Regards, Frank.