Bug 48101 - [patch] Add documentation on the fixit disk
Summary: [patch] Add documentation on the fixit disk
Status: Open
Alias: None
Product: Documentation
Classification: Unclassified
Component: Documentation (show other bugs)
Version: Latest
Hardware: Any Any
: Normal Affects Only Me
Assignee: freebsd-doc mailing list
URL:
Keywords:
Depends on:
Blocks:
 
Reported: 2003-02-08 22:00 UTC by mwm
Modified: 2018-04-13 23:25 UTC (History)
2 users (show)

See Also:


Attachments

Note You need to log in before you can comment on or make changes to this bug.
Description mwm 2003-02-08 22:00:24 UTC
	There isn't any real documentation on what the fixit disk is
used for anywhere on the FreeBSD site.

Fix: 

The attached patch ands a FAQ entry that serves mostly to list
the reasons one would want to use the Fixit disk, and the other
sources of information that one might find useful when working with
the disk. I'm not sure this is the right place to put the information,
but I couldn't see any better place.

4450a4451,4519
> 
>       <qandaentry>
>         <question id="broken-root">
> 	  <para>My root file system doesn't mount. What do I do now?</para>
> 	</question>
> 
> 	<answer>
>           <para>The fixit disk is used when your systems root file
>           system cannot be mounted read-only at boot time. The sole
>           purpose of the disk is to repair the root file system so you
>           can mount it, and continue the process of bringing up the
>           system from that point.</para>
> 
>           <para>The fixit CDROM has most of the functionality of a
>           complete FreeBSD install. It does not have
>           <filename>/stand</filename>, but <filename>/bin</filename>,
>           <filename>/sbin</filename>, <filename>/usr/bin</filename>
>           and <filename>/usr/sbin</filename> are all there. You
>           should be able to boot this CDROM and go directly to the
>           fixit mode.</para>
> 
>           <para>The fixit floppy has much less functionality. All the
>           tools on it are in <filename>/stand</filename>. In
>           particular, it does not have &man.fsck.8; or &man.newfs.8;,
>           but it does have &man.tar.1; and &man.restore.8;. The fixit
>           floppy is not bootable. You must boot the install floppy,
>           then insert the fixit floppy when so directed.</para>
> 
>           <para>There are three things that can cause your root file
>           system to fail to mount. Each of these has a different
>           solution.</para>
> 
>           <para>First, if your system has slices on the disk holding
>           the root file system, the slice table may be broken. The
>           tool for editing the slice table is &man.fdisk.8;. The
>           format of the data is documented in
>           <filename>/usr/include/sys/disklabel.h</filename>.</para>
> 
>           <para>Second, the disk label may be broken. The tool for
>           editing disk labels is &man.disklabel.8;. The format of the
>           data is documented in
>           <filename>/usr/include/sys/disklabel.h</filename>.</para>
> 
>           <para>Finally, the file system proper may be so badly broken
>           that it can't be mounted. The tool for fixing this is
>           &man.fsck.8;. The format is documented in
>           <filename>/usr/include/ufs/ffs/fs.h</filename>,
>           <filename>/usr/include/ufs/ufs/dinode.h</filename>, and
>           <filename>/usr/include/ufs/ufs/dir.h</filename>.  Of
>           particular interest is the alternate superblock at block 32,
>           so that <command>fsck -b 32
>           <replaceable>disk</replaceable></command> will repair a broken
>           primary superblock. Note that &man.fsck.8; is
>           <emphasis>not</emphasis> on the fixit floppy.</para>
> 
>           <para>Other useful commands are &man.ed.1; and whatever you
>           use to restore from backups. Ed can be used to repair broken
>           configuration files, or to change them to deal with
>           nonfunctional hardware. If you are using a standard system
>           tool for backing up your system, then the ability to restore
>           backups is probably on the fixit disk.</para>
> 
>           <para>It is advisable to use &man.fdisk.8; - if appropriate -
>           to get a copy of your slice tables, and &man.disklabel.8; to get a
>           copy of your disk labels, and save them somewhere
>           safe. Printed copies for the disk your root file system is
>           on should be stored with the backup of the root file system.</para>
> 	</answer>
>       </qandaentry>
How-To-Repeat: 	Try finding that documentation.
Comment 1 Gary W. Swearingen 2003-02-09 02:25:41 UTC
> >           <para>The fixit disk is used when your systems root file
"system's root"
I'm not sure if you mean this paragraph to apply to both floppy and
CDROM.  Isn't the purpose of the CDROM broader than just / repair?
I thought this para was about the floppy until I got to the third para
and became unsure.  If it's about both, "The" should be "A", since "The"
sound like there's only one (kind).  Maybe mention floppy & CDROM here.
> >           system cannot be mounted read-only at boot time. The sole
AFAIK, the FAQ uses only "filesystem" and not "file system". Same below..
> >           purpose of the disk is to repair the root file system so you
> >           can mount it, and continue the process of bringing up the
Better without comma. (The sentence naturally divides before "so".)
> >           <para>The fixit CDROM has most of the functionality of a
> >           complete FreeBSD install. It does not have
> >           <filename>/stand</filename>, but <filename>/bin</filename>,
> >           <filename>/sbin</filename>, <filename>/usr/bin</filename>
Comma at end?
> >           and <filename>/usr/sbin</filename> are all there. You
...
> >           <para>Other useful commands are &man.ed.1; and whatever you
> >           use to restore from backups. Ed can be used to repair broken
"The &man.ed.1 command can"
> > 
> >           <para>It is advisable to use &man.fdisk.8; - if appropriate -
Dare to just advise it:  "Use &man.fdisk.8..."
Or use true weasel words: "Many people use..." or "It's helpful to use...".
Comment 2 Christian Brueffer freebsd_committer 2003-06-13 00:41:33 UTC
Responsible Changed
From-To: freebsd-doc->brueffer

I'll take this
Comment 3 Christian Brueffer freebsd_committer 2005-05-22 15:41:36 UTC
Responsible Changed
From-To: brueffer->freebsd-doc

Throw this back into the pool.
Comment 4 Gabor Pali freebsd_committer 2010-08-22 00:39:50 UTC
Responsible Changed
From-To: freebsd-doc->pgj

Take.
Comment 5 Gabor Pali freebsd_committer 2010-08-27 11:57:28 UTC
State Changed
From-To: open->analyzed

Test change.
Comment 6 Gabor Pali freebsd_committer 2010-08-27 11:58:23 UTC
State Changed
From-To: analyzed->open

Back to open.
Comment 7 Gabor Pali freebsd_committer 2010-11-28 12:28:08 UTC
Responsible Changed
From-To: pgj->freebsd-doc

Back to the pool.
Comment 8 Eitan Adler freebsd_committer freebsd_triage 2012-11-01 23:52:54 UTC
State Changed
From-To: open->closed

while this PR should have been committed some time ago, it wasn't, and 
for that I'm sorry.  In the meantime though the fixit disk is going away 
and is being replaced by the 'shell' option in the new installer.
Comment 9 Eitan Adler freebsd_committer freebsd_triage 2012-11-02 12:28:51 UTC
State Changed
From-To: closed->open

per Mehmet Erol Sanliturk - reopen as this is still an issue (in a 
different form)
Comment 10 Eitan Adler freebsd_committer freebsd_triage 2017-12-31 07:59:59 UTC
For bugs matching the following criteria:

Status: In Progress Changed: (is less than) 2014-06-01

Reset to default assignee and clear in-progress tags.

Mail being skipped
Comment 11 Oleksandr Tymoshenko freebsd_committer freebsd_triage 2018-04-13 23:25:55 UTC
Back to Documentation component, this was mis-categorized as man page issue