Re: Issues with FFS vs UFS name in applications and documentation

[Giles Lean <giles.lean%pobox.com@localhost>]

Hi Luke et al,

> There are various issues in how we refer to FFS versus UFS
> and the different versions (FFSv1, FFSv2), and this causes
> confusion and potential failure.

The confusion is not simply in NetBSD; in at least one
commercial Unix vendor's source their version of the code has
"ufs" in file names and some internal documentation, and is
known by a different name externally.

Was/is the reason not to call anything "UFS" avoidance of the
"UNIX" trademark, I wonder?  (Not that it really matters.)

> 1.  In general, there is inconsistenct of "UFS" and "FFS",
>     including version variations such as "UFS1" versus "FFSv1",
>     within documentation, command names, command output, (etc.)

Inconsistency is bad.  NetBSD is a *BSD; the "FFS" name(s) are
more obvious than the "UFS" name IMHO.

>     The source code organisation in src/sys/ufs implies a common
>     code-base called "ufs", with more specific implimentations
>     of "ffs" (Berkeley Fast File System), "ext2fs" (Linux ext2),
>     "lfs" (Berkeley Log-structured File System), (etc.)

Ick.  Without looking at that code, I wonder how that came about?
Is there much code shared?  (Yes, I imagine between FFSv1 and FFSv2,
not sure about the others.)

Perhaps the motivation that these were/are all "local" "Unix"
file systems and thus have "similar" semantics?

"local" in quotes because "local" might now be fibre channel,
or a removable drive, or remote via iSCSI, or a user land
implementation, or ...

"Unix" and "similar" in quotes 'cos as we all know not all
those listed file systems have /quite/ the same semantics.

I'm not sure that you want to do anything about the source
tree, other than perhaps document what is where.  Unless/until
something more supportive of file renaming than CVS is used, I
imagine "cleaning" this up would cause as much harm as good.

>     Given existing tool names (newfs_ffs, ...), I argue 
>     that we should just standardize on referring to the
>     file system as "ffs" in both command name and command output.

+1

> 2.  installboot(8) doesn't have the ability to confirm that the
>     primary bootstrap (/usr/mdec/bootxx_FOO) matches the underlying
>     file system that is being installbooted to.

Be nice to see that solved, and I'll bet anything that low level
is going to run into machine dependent issues as you suspect.
No suggestions. :-)

> 3.  The dumpfs(8) manual doesn't adequately describe the differences
>     between the different FFS versions (including the various
>     file system levels of FFSv1), nor adequately explain the fields
>     in the output of the command.
>     This is partly related to point 5 below.

Or indeed that it doesn't work on CD9660 (with/without extensions),
UDF, and other (ext2 etc?) file systems, so far as I know:

  $ uname -mr
  4.0_STABLE i386
  $ dumpfs -F -s ubuntu-8.10-desktop-i386.iso
  dumpfs: ubuntu-8.10-desktop-i386.iso: could not find superblock, skipped

> 4.  The dumpfs(8) output can be confusing when attempting to determine
>     if a file system is FFSv2 (so that /usr/mdec/bootxx_ffsv2
>     is to be installboot(8)ed.)
> ...
>     At first glance of the latter without the former for reference,
>     a user will see "sblock FFSv2" and mistakenly assume that
>     /usr/mdec/bootxx_ffsv2 is the primary bootstrap to install.
>     (This is incorrect, and will result in an unbootable system.)

"Ouch".

Problems that can show up a long time after the action that
caused them, and at inopportune times (e.g. right after a
kernel panic, power outage, or maintenance) are nasty.

Back when I worked for a Unix vendor, I'd have had no
hesitation in classing that sort of defect as "serious" or
"critical".  (And if it was introduce in a proposed new
release, I'd have been tempted to put a shipstopper flag on
it.)

> 5.  fsck_ffs(8) doesn't describe the "fslevel 5" value of dumpfs(8).

<whistles innocently />

> 6.  newfs(8) -O <filesystem-format> uses different values than
>     fsck_ffs(8) -c <fslevel>
>     This isn't a big deal, although an explanation of the relationship
>     between the two in newfs(8) may be helpful.

The file system related commands have always been a bit
inconsistent.

At least on some systems (maybe only historically) newfs would
call mkfs, and then we got multiple file system types and it
got uglier with newfs calling newfs_XXX for each file system
type and pass through mechanisms to pass unknown arguments to
the *_XXX version of the command to allow for file system
types not provided by the OS vendor (e.g. VxFS from
Veritas/Symantec if you didn't buy it from your OS vendor).

I'd be reluctant to change the commands: they're used in
recovery and maintenance situations, the last sort of time you
want a command's usage to change under you but up to date and
accurate documentation is always good.  (Especially when /usr
is part of / and you can read it, but these web and wireless
days you can find the manual page anyway, probably. :-)

> 7.  We lack a ffs(7) manual page.  FreeBSD has ffs(7) which may
>     be a useful starting point.

+1 (but I haven't read the FreeBSD manual page.)

Perhaps slightly off topic, or perhaps relevant:

OS X has ffs(3), but that's for handing bit strings and is not
related to file systems in any way.  There is a fs(5) manual
page on OS X but it's unclear to me whether it is up to date
for HFS+.  (References to 4.2BSD are not encouraging in that
context; it may only be accurate for FFSv1. Who knows?)

> 8.  Installation documentation, sysinst, NetBSD guide (etc.)
>     will all need updating depending upon the result of this.

+1

Cheers,

Giles

P.S. All "IMHO"; accuracy not guaranteed; and I'm not in a
position to offer much if any help in implementing any changes
that are agreed to be a Good Thing.

P.P.S. If the on-disk formats for NetBSD FFSv1 and FFSv2 are
different to the other *BSDs (and I suspect they are, 'cos
NetBSD at least allows either endian file systems) that
probably wants to be made explicit in the documentation, too.