Date: Fri, 19 Feb 1999 08:58:07 +1100 From: Peter Jeremy <peter.jeremy@auss2.alcatel.com.au> To: hackers@FreeBSD.ORG Subject: Documenting sysctl knobs Message-ID: <99Feb19.084745est.40350@border.alcanet.com.au>
next in thread | raw e-mail | index | archive | help
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
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?99Feb19.084745est.40350>