amd64/128524: No geom documentation for loading gjournal

[Joe Kelsey]

>Number:         128524
>Category:       amd64
>Synopsis:       No geom documentation for loading gjournal
>Confidential:   no
>Severity:       serious
>Priority:       high
>Responsible:    freebsd-amd64
>State:          open
>Quarter:        
>Keywords:       
>Date-Required:
>Class:          doc-bug
>Submitter-Id:   current-users
>Arrival-Date:   Sat Nov 01 21:00:11 UTC 2008
>Closed-Date:
>Last-Modified:
>Originator:     Joe Kelsey
>Release:        FreeBSD 7.1-PRERELEASE amd64
>Organization:
Joseph M. Kelsey
>Environment:
System: FreeBSD zircon.zircon.seattle.wa.us 7.1-PRERELEASE FreeBSD 7.1-PRERELEASE #26: Mon Oct 27 20:08:55 PDT 2008 root at zircon.zircon.seattle.wa.us:/usr/obj/usr/src/sys/ZIRCON amd64

>Description:
	I am trying to use gjournal on two different disk drives and
	have been frustrated over the lack of documentation.

	To start with, there is no explanation over why certain commands
	are necessary.  For instance, what does the "gjournal load"
	command do?  The man page says that the geom command documents
	it.  However, none of the actual "load" commands are necessary
	in the standard 7.x kernel build, since everything is loaded by
	default.

	However, for some unknowable reason, you actually have to issue
	the gjournal load command in order to actually cause the various
	.journal devices to magically appear.  This is especially true
	at boot time.  This is in spite of the fact that
	geom_journal_load is not documented anywhere, relying on someone
	just guessing that it will cause the right thing to happen.

	Why do I need to do this?  How does this whole thing interact
	with labels?  Why do I sometimes get label devices with, for
	example, labels1a.journal and sometimes label?  What sequence of
	events causes the label to move from /dev/label/ufs to /dev/ufs
	to other palces?  How to I actually control it?

	Another problem occurs when you want to experiment with
	journalling.  As soon as you get one method of journalling
	started, you can never change it because the journal stuff will
	never let go.  For instance, I wanted to reformat my disk to try
	different ways of setting up partitions on the drive to
	effectively support journalling.  What are the recommended sizes
	to use for the data versus journal provider?  Should I do a
	newfs on both?  I have setteled on 10% for journal and the rest
	for data with no actual file system on the journal provider.

	However it took a long time to repartition the disk drive since
	the stupid journal would not let go of the drive.   I had to
	boot into single user without loading the journal stuff in order
	to actually have disklabel -e work correctly.  There needs to be
	a reliable way to cause the journalling to let go of the device
	in order to actually accomplish something.
>How-To-Repeat:
	Run gjournal without doing gjournal load.  Look at the various
	things that do not happen correctly.
>Fix:

	The latest handbook on my disk is different from the handbook on
	freebsd.org.  Why is that?



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