From owner-freebsd-hackers  Thu Feb 18 13:58:42 1999
Delivered-To: freebsd-hackers@freebsd.org
Received: from alcanet.com.au (border.alcanet.com.au [203.62.196.10])
	by hub.freebsd.org (Postfix) with ESMTP id A70AC117A0
	for <hackers@FreeBSD.ORG>; Thu, 18 Feb 1999 13:58:20 -0800 (PST)
	(envelope-from peter.jeremy@auss2.alcatel.com.au)
Received: by border.alcanet.com.au id <40350>; Fri, 19 Feb 1999 08:47:45 +1100
Date: Fri, 19 Feb 1999 08:58:07 +1100
From: Peter Jeremy <peter.jeremy@auss2.alcatel.com.au>
Subject: Documenting sysctl knobs
To: hackers@FreeBSD.ORG
Message-Id: <99Feb19.084745est.40350@border.alcanet.com.au>
Sender: owner-freebsd-hackers@FreeBSD.ORG
Precedence: bulk
X-Loop: FreeBSD.ORG

Just to re-open this particular festering sore...

I don't want to pick on Matt Dillon in particular, but a recent commit
of his (dillon 1999/02/18 11:57:33 PST) states:

>  Add two swap tuneables to sysctl:
>  
>  	vm.swap_async_max: 4
>  	vm.swap_cluster_max: 16
>  
>  Recommended values are a cluster size of 8 or 16 pages.  async_max is
>  about right for 1-4 swap devices.  Reduce to 2 if swap is eating too much
>  bandwidth, or even 1 if swap is both eating too much bandwidth and sitting
>  on a slow network (10BaseT).
>  
>  The defaults work well across a broad range of configurations and should
>  normally be left alone.

IMHO, this is the sort of documentation that is needed for all the
tunable sysctl identifiers.  The problem is that (IMHO again), CVS
logs aren't the correct place for it - the information needs to be
available to a sysadmin who doesn't have the CVS archive on-line (and
may not even want to RTSL [*]).  Adding several hundred bytes of text
per identifier to the in-memory kernel image is also not the right
place.  man8/sysctl.8 may be a reasonable place, but it doesn't get
updated (and the logistics involved in having lots of different
people all trying to update a single file virtually guarantee that
updates would be lost).

Physically, the information needs to be in the source code near the
sysctl OID definition - so it gets updated.  It also needs to be
accessible from either man or sysctl(8) - so the sysadmin doesn't need
to rummage thru the source code.

I can immediately think of two solutions:
1) Include the documentation as a parameter to the SYSCTL_OID macro
   (and it's various derivatives).  This parameter gets inserted (as
   text) into an ELF section that's not loaded.  sysctl(8) can locate
   the description by reading it out of the kernel image on disk.
   (The section could also be stripped out to reduce disk space if
   necessary).
2) Mark the documentation is some way (possibly, but not necessarily
   via the SYSCTL_OID macro) so that it can be easily extracted from
   the source by an awk or perl script and turned into a man page
   (or several) - ie there'd be a single automatically generated
   sysctl.oid(7) man page that documented all sysctl identifiers,
   or several man pages, each documenting a group of identifiers.

[*] As a `production OS', it should not be necessary for the sysadmin
    to be intimately familiar with the source code.

Peter


To Unsubscribe: send mail to majordomo@FreeBSD.org
with "unsubscribe freebsd-hackers" in the body of the message