Document kern.geom.journal.* sysctls.

PR:		docs/130548
Submitted by:	Hywel Mallett <hywel@hmallett.co.uk>
MFC after:	1 week

1 files changed, 102 insertions, 6 deletions

diff --git a/sbin/geom/class/journal/gjournal.8 b/sbin/geom/class/journal/gjournal.8
index eb4f517b1f4d..714f24a2e886 100644
--- a/sbin/geom/class/journal/gjournal.8
+++ b/sbin/geom/class/journal/gjournal.8
@@ -1,4 +1,4 @@
-.\" Copyright (c) 2006-2007 Pawel Jakub Dawidek <pjd@FreeBSD.org>
+.\" Copyright (c) 2006-2009 Pawel Jakub Dawidek <pjd@FreeBSD.org>
 .\" All rights reserved.
 .\"
 .\" Redistribution and use in source and binary forms, with or without
@@ -24,7 +24,7 @@
 .\"
 .\" $FreeBSD$
 .\"
-.Dd April 13, 2008
+.Dd February 17, 2008
 .Dt GJOURNAL 8
 .Os
 .Sh NAME
@@ -223,6 +223,106 @@ gjournal label da0s1d da0s1e && \e
     mount -o async /dev/da0s1d.journal /mnt || \e
     mount /dev/da0s1d /mnt
 .Ed
+.Sh SYSCTLS
+Gjournal adds the sysctl level kern.geom.journal.
+The string and integer information available is detailed below.
+The changeable column shows whether a process with appropriate privilege may
+change the value.
+.Bl -column "accept_immediatelyXXXXXX" integerXXX -offset indent
+.It Sy "sysctl name	Type	Changeable"
+.It "debug	integer	yes"
+.It "switch_time	integer	yes"
+.It "force_switch	integer	yes"
+.It "parallel_flushes	integer	yes"
+.It "accept_immediately	integer	yes"
+.It "parallel_copies	integer	yes"
+.It "record_entries	integer	yes"
+.It "optimize	integer	yes"
+.El
+.Pp
+.Bl -tag -width 6n
+.It Li debug
+Setting a non-zero value enables debugging at various levels.
+Debug level 1 will record actions at a journal level, relating to journal
+switches, metadata updates etc.
+Debug level 2 will record actions at a higher level, relating to the numbers of
+entries in journals, access requests etc.
+Debug level 3 will record verbose detail, including insertion of I/Os to the
+journal.
+.It Li switch_time
+The maximum number of seconds a journal is allowed to remain open before
+switching to a new journal.
+.It Li force_switch
+Force a journal switch when the journal uses more than N% of the free journal space.
+.It Li parallel_flushes
+The number of flush I/O requests to be sent in parallel when flushing the journal to the data provider.
+.It Li accept_immediately
+The maximum number of I/O requests accepted at the same time.
+.It Li parallel_copies
+The number of copy I/O requests to send in parallel.
+.It Li record_entries
+The maximum number of record entries to allow in a single journal.
+.It Li optimize
+Controls whether entries in a journal will be optimized, by combining overlapping I/Os into a single I/O, and reordering the entries in a journal. This can be disabled by setting the sysctl to 0.
+.El
+.Ss cache
+The string and integer information available for the cache level
+is detailed below.
+The changeable column shows whether a process with appropriate
+privilege may change the value.
+.Bl -column "alloc_failuresXXXXXX" integerXXX -offset indent
+.It Sy "sysctl name	Type	Changeable"
+.It "used	integer	no"
+.It "limit	integer	yes"
+.It "divisor	integer	no"
+.It "switch	integer	yes"
+.It "misses	integer	yes"
+.It "alloc_failures	integer	yes"
+.El
+.Pp
+.Bl -tag -width 6n
+.It Li used
+The number of bytes currently allocated to the cache.
+.It Li limit
+The maximum number of bytes to be allocated to the cache.
+.It Li divisor
+Sets the cache size to be used as a proportion of kmem_size. A value of 2 (the default) will cause the cache size to be set to 1/2 of the kmem_size.
+.It Li switch
+Force a journal switch when this percentage of cache has been used.
+.It Li misses
+The number of cache misses, when data has been read, but was not found in the cache.
+.It Li alloc_failures
+The number of times memory failed to be allocated to the cache because the cache limit was hit.
+.El
+.Ss stats
+The string and integer information available for the statistics level
+is detailed below.
+The changeable column shows whether a process with appropriate
+privilege may change the value.
+.Bl -column "skipped_bytesXXXXXX" integerXXX -offset indent
+.It Sy "sysctl name	Type	Changeable"
+.It "skipped_bytes	integer	yes"
+.It "combined_ios	integer	yes"
+.It "switches	integer	yes"
+.It "wait_for_copy	integer	yes"
+.It "journal_full	integer	yes"
+.It "low_mem	integer	yes"
+.El
+.Pp
+.Bl -tag -width 6n
+.It Li skipped_bytes
+The number of bytes skipped.
+.It Li combined_ios
+The number of I/Os which were combined by journal optimization.
+.It Li switches
+The number of journal switches.
+.It Li wait_for_copy
+The number of times the journal switch process had to wait for the previous journal copy to complete.
+.It Li journal_full
+The number of times the journal was almost full, forcing a journal switch.
+.It Li low_mem
+The number of times the low_mem hook was called.
+.El
 .Sh SEE ALSO
 .Xr geom 4 ,
 .Xr geom 8 ,
@@ -237,7 +337,3 @@ utility appeared in
 .Fx 7.0 .
 .Sh AUTHORS
 .An Pawel Jakub Dawidek Aq pjd@FreeBSD.org
-.Sh BUGS
-Documentation for sysctls
-.Va kern.geom.journal.*
-is missing.