docs/99804: [PATCH] Handbook "Config" chapter maxusers info outdated

[Kevin Kinsey]

>Number:         99804
>Category:       docs
>Synopsis:       [PATCH] Handbook "Config" chapter maxusers info outdated
>Confidential:   no
>Severity:       non-critical
>Priority:       medium
>Responsible:    freebsd-doc
>State:          open
>Quarter:        
>Keywords:       
>Date-Required:
>Class:          update
>Submitter-Id:   current-users
>Arrival-Date:   Wed Jul 05 16:00:35 GMT 2006
>Closed-Date:
>Last-Modified:
>Originator:     Kevin Kinsey
>Release:        FreeBSD 6.1-STABLE i386
>Organization:
DaleCo, S.P.
>Environment:
System: FreeBSD archangel.daleco.biz 6.1-STABLE FreeBSD 6.1-STABLE #2: Sat May 27 07:15:18 CDT 2006 root at archangel.daleco.biz:/usr/obj/backup/src/sys/GENERIC i386


>Description:

	Handbook reference 11.13.1.1 "kern.maxfiles" only seems to refer to
	pre-4.5 behavior in regard to "kern.maxusers" (e.g., it doesn't mention
	this at all, only the older "maxusers" kernel option).  This was creating
	a slight problem for a user this morning on the questions@ list.

	Also, since it is outdated, it doesn't agree with tuning(7).  I've used
	material from that manpage to produce the included patch.

>How-To-Repeat:

	Read the section above at:
http://www.freebsd.org/doc/en_US.ISO8859-1/books/handbook/configtuning-kernel-limits.html

	... and then try to find the "maxusers" option in your 6.X kernel config file ;-)

>Fix:

	Warning: IANAE on this (or much about kernels or SGML), but would this 
	patch (against EN) help, at least for the immediate future?

===== START =====

--- chapter.sgml.orig	Wed Jul  5 10:16:56 2006
+++ chapter.sgml	Wed Jul  5 10:29:51 2006
@@ -2022,8 +2022,8 @@
 	  require many thousands of file descriptors, depending on the
 	  kind and number of services running concurrently.</para>
 
-	<para><varname>kern.maxfile</varname>'s default value is
-	  dictated by the <option>maxusers</option> option in your
+	<para>In older FreeBSD releases, <varname>kern.maxfile</varname>'s default
+	  value is dictated by the <option>maxusers</option> option in your
           kernel configuration file.  <varname>kern.maxfiles</varname> grows
           proportionally to the value of <option>maxusers</option>.  When
           compiling a custom kernel, it is a good idea to set this kernel
@@ -2033,7 +2033,19 @@
           connected at once, the resources needed may be similar to a
           high-scale web server.</para>
 
-	<para>The system will auto-tune
+        <para>As of FreeBSD 4.5, <varname>kern.maxusers</varname> is automatically 
+	  sized at boot based on the amount of memory available in the system, and may be
+	  determined at run-time by inspecting the value of the read-only 
+	  <varname>kern.maxusers</varname> sysctl.  Some sites will require larger or
+	  smaller values of kern.maxusers and may set it as a loader tunable; values of 
+	  64, 128, and 256 are not uncommon.  We do not recommend going above 256 unless 
+	  you need a huge number of file descriptors; many of the tunable values set to 
+	  their defaults by kern.maxusers may be individually overridden at boot-time or 
+	  run-time in /boot/loader.conf (see /boot/defaults/loader.conf for some hints) or
+	  as described elsewhere in this document.  Systems older than FreeBSD 4.4 must 
+	  set this value via the kernel config(8) option <option>maxusers</option> instead.</para>
+
+	<para>In older releases, the system will auto-tune
 	  <literal>maxusers</literal> for you if you explicitly set it to
 	  <literal>0</literal><footnote>
 	    <para>The auto-tuning algorithm sets


===== END ======

Sincerely, 

Kevin Kinsey
>Release-Note:
>Audit-Trail:
>Unformatted: