Bug 34074

Summary: Handbook section 12.3 -- Adding Disks incomplete instructions for using disklabel
Product: Documentation Reporter: Cameron Watters <cameron>
Component: Books & ArticlesAssignee: freebsd-doc (Nobody) <doc>
Status: Closed FIXED    
Severity: Affects Only Me    
Priority: Normal    
Version: Latest   
Hardware: Any   
OS: Any   

Description Cameron Watters 2002-01-20 06:10:02 UTC
      In section 12.3 Adding Disks, there is no mention of the fact that one must run disklabel -W prior to attempting either method of labeling the disk one is adding. While this is mentioned in the manpage for disklabel, the instructions in the handbook give the impression of being a complete step by step to performing this task. However, as according to the man page for disklabel, the disk's driver will simply quietly ignore any requests to write to the disklabel until the above command is performed. So, until one does run disklabel -W, all disklabels fail (even the ones from /stand/sysinstall) and therefor all newfs commands fail...and no where are you told this. The only indicator that there MIGHT be a problem is the fact that the disklabel sequence in /stand/sysinstall will tell you it can't mount your new partition(s) when you attempt to write out the config, HOWEVER, you are specifically instructed to ignore this message in the handbook.

Fix: 

Add a sentence or two explaining the above and instruct the user to run disklabel -W prior to attempting to use either of the two methods given.
Comment 1 hiten pandya 2002-01-22 11:29:46 UTC
Sorry for the bluntness, but, AFAIK, all requests by
/stand/sysinstall are normally completed without any
errors.

The man page, does mention about the -W option, and 
its actions, but I've never found the need to apply
this parameter to disklabel(8).

Does this disklabel(8) issue arise only in certain
conditions?

__________________________________________________
Do You Yahoo!?
Send FREE video emails in Yahoo! Mail!
http://promo.yahoo.com/videomail/
Comment 2 toolhouse12 2002-01-22 17:24:28 UTC
HP> Sorry for the bluntness, but, AFAIK, all requests by
HP> /stand/sysinstall are normally completed without any
HP> errors.

Quoting from the handbook:

"Ignore any errors from Sysinstall  that it could not mount the new
partition."

This, in fact, is exactly what happens. Further, when I actually ran
disklablel -W and THEN ran sysinstall, it didn't give me this error
message.

HP> The man page, does mention about the -W option, and
HP> its actions, but I've never found the need to apply
HP> this parameter to disklabel(8).

I wouldn't have submitted this unless I hadn't tried for an hour to get
the Handbook's instructions to work correctly.

HP> Does this disklabel(8) issue arise only in certain
HP> conditions?

I should clarify that this only happens when using sysinstall on a system
that has already been setup once. As the handbook directs, I was using it
to add additional disks to an existing installation of FreeBSD.

However, that is exactly the activity this portion of the handbook is
trying to cover.

--cameron
Comment 3 darklogik 2002-02-12 03:52:59 UTC
Hello to all involved in this pr, fellow members of the doc team, anyone 
else who is interested  ;)

Tonight, I threw an extra hard disk into my system (4.5) and ran 
sysinstall(8) to configure the drive.  On my 4.5 system, however, the 
'Partition' option is not there.  At least, under the Configure option. 
 I also want to note that, I used:

Configure > Fdisk > Label

although Label fed me some error messages, a simple exit and restart of 
sysinstall(8) and I was back into the label editor.  (Handbook is 
incorrect about the "ignore any errors from sysinstall" because it in 
fact does not write the label, and spits "DEBUG: MakeDev: Unknown 
major/minor for devtype" during the attempted w process, and if you 
ignore, you will not get labels at all)  This time, I obtained no error 
messages when doing the write operation.  After a few diags, I have 
noticed that using the disklabel(8) utility is not required, however, 
you seem to be required to exit sysinstall(8) before you can use the 
Label editor.  The point in case is not that disklabel is required, nor 
that if you use sysinstall(8) apperently you are required to restart 
before using the Label editor, but that the Handbook apperently has 
incorrect information and a patch is required.  When I submit a patch, I 
will also try to accomplish a grammer cleanup on more parts of the 
handbook...  Anyone who has noticed a difference in their use of 
sysinstall(8) for adding drives is requested to come forward and talk 
with me ;)
Comment 4 darklogik 2002-02-12 04:45:35 UTC
Hello to all involved in this pr, fellow members of the doc team, anyone 
else who is interested  [;)]


Tonight, I threw an extra hard disk into my system (4.5) and ran 
sysinstall(8) to configure the drive.  On my 4.5 system, however, the 
'Partition' option is not there.  At least, under the Configure option. 
I also want to note that, I used:

Configure > Fdisk > Label

although Label fed me some error messages, a simple exit and restart of 
sysinstall(8) and I was back into the label editor.  (Handbook is 
incorrect about the "ignore any errors from sysinstall" because it in 
fact does not write the label, and spits "DEBUG: MakeDev: Unknown 
major/minor for devtype" during the attempted w process, and if you 
ignore, you will not get labels at all)  This time, I obtained no error 
messages when doing the write operation.  After a few diags, I have 
noticed that using the disklabel(8) utility is not required, however, 
you seem to be required to exit sysinstall(8) before you can use the 
Label editor.  The point in case is not that disklabel is required, nor 
that if you use sysinstall(8) apperently you are required to restart 
before using the Label editor, but that the Handbook apperently has 
incorrect information and a patch is required.  When I submit a patch, I 
will also try to accomplish a grammer cleanup on more parts of the 
handbook...  Anyone who has noticed a difference in their use of 
sysinstall(8) for adding drives is requested to come forward and talk 
with me please.

--
Tom Rhodes
Comment 5 Jim Mock freebsd_committer freebsd_triage 2002-02-15 20:40:17 UTC
State Changed
From-To: open->closed

Merged with and closed by 34953.  Thanks!