All of the points James has outlined below are well taken.  Though it's
not an official NetBSD project document, my older VAX specific
netbooting howto is referenced by the NetBSD/vax project page, and for
better or worse, it's generally the document that one finds when
searching for information on the internet.  I've moved the original and
have updated all of the existing links at its primary location with a
notice to not use this document since it is no longer maintained.

I'm not very familiar enough with the contents of the official NetBSD
project netbooting instructions, but perhaps that document's maintainer
will take any appropriate to update it to reflect the current state of
things?

And as for the VAX specific installation instructions that are part of
the release notes, their inaccuracies have bothered me for a while too.
They're very PC-centric.  Having never investigated how this install
document is generated, or where its source files are, I'd don't know off
the top of my head how to update it with instructions that are relevant
for VAX systems.  In part, I suspect correcting it has been ignored
because there are such a wide variety of VAX systems available, spanning
25 years of change.  The basic procedures for booting a system from the
console are similiar, but there are probably a few dozen specific ways
to initiate a boot depending on various types of disk devices, tape
devices, and network devices available.  Still, it would be nice to at
least have the install instruction reference reasonable examples.  I'll
see if I can find out more about remedying this for the VAX port in the
1.6.1 release.

-brian.


On Mon, 13 Jan 2003, James K. Lowden wrote:

> I recently put a VAX together and noticed -- it can't be helped -- that
> the docs are out of date and sometimes misleading.  I can fix this, and
> I'd rather do it before I've forgotten or lost interest.  I want to list
> some specific issues, so you can see what I'm talking about (and so I
> don't lose track); then I'd like to ask how best to remedy them.
>
> To begin, http://www.netbsd.org/Documentation/network/netboot/mop.html
> says:
>
> "First, you need to get a copy of the bootloader. This can be found in the
> NetBSD 1.5.3 distribution as:
> ftp://ftp.netbsd.org/pub/NetBSD/NetBSD-1.5.3/vax/installation/netboot/netbsd.ram.gz"
>
> I didn't know what that file was used for.  The document doesn't say.  I
> found a different file, install.ram.gz, which I eventually intuited is the
> install kernel.
>
> http://www.netbsd.org/Documentation/network/netboot/bootpd.html includes:
>
> #/etc/bootptab
> client.test.net:\
>         :ht=ether:\
>         :ha=CCCCCCCCCCCC:\
>         :sm=255.255.255.0:\
>         :lg=192.168.1.5:\
>         :ip=192.168.1.10:\
>         :hn:\
>         :bf=[/tftpboot/]boot.netbsd:\   # see note below
>         :bs=auto:\
>         :rp=/export/client/root/:\
>         :vm=auto:                       # see note below for next hardware
>         :vm=rfc1048:                    # see note below for alpha
> hardware
>
> There's no indication what "CCCCCCCCCCCC" means.  Too, I had to read the
> bootptab man page to know that "[/tftpboot/]" means "this part is
> optional, depending".  I think a clearer typography would use italics for
> placeholders and/or boldface for constants, as jade renders sgml.
>
> Another point of confusion, at least for me, was that
> http://www.netbsd.org/Documentation/network/netboot/tftpd.html
>
> says, "Next, you should copy all of the files necessary for your
> architecture to /tftpboot, as specified in the client
> architecture-specific introduction" but
> http://www.netbsd.org/Documentation/network/netboot/intro.vax.html
>
> doesn't mention what to put in /tftpboot (although it's very helpful with
> the VAX firmware).  Also, at the bottom of that page is a short list of
> links to the rest of the steps, which I found helpful.  But that list is
> missing a link to the tftp setup.
>
> I also got into trouble reading Brian Chase's VAX-netboot-HOWTO.html.
> That document, to which I was frequently referred, is now 5 years old, and
> almost all the specifics have been superseded.  Maybe others are more
> savvy, but had to keep remembering *not* to read it, once I realized it
> was a dead end.  The newcomer will be misled; the old hand can appreciate
> the art.  No criticism intended to Brian, I hope that's clear.
>
> On the plus side, once I got to NFS, it was pretty much clear sailing.
> Prior to the VAX, my whole NFS experience had consisted of one Sun
> workstation netboot installation.  But the NFS steps are very clear, so my
> lack of NFS experience wasn't much of an impediment.  In fact, I wound up
> with a complete diskless installation because I overlooked the link to
> netboot/local.install.html on netboot/nfs.html.  <shrug>
>
> I also want to criticise vax/INSTALL.html.
>
> 1.  Are there really any vaxen with pcmcia cards? IDE disks?
> 2.  "You will be asked if you want to use the entire disk or only part of
> the disk."
> 3.  "To do the upgrade, you must have the boot floppy available."
> 4.  "partition sizes for a full install ... /usr 110 MB".
>
> #4 May be true, but somewhere it should mention that for ftp
> #installations, sysinst pulls all the sets and then starts installing.  My
> #200 MB boot LXT-213S ran out of room using ftp; I put the sets on the NFS
> #server to complete the installation.
>
> For me, what vax/INSTALL.html lacked was a concise recap of what's
> happening, something to serve as a VAX-specific guide to the netboot
> process.  Something like:
>
> Service	 Provides		Filename on server
> -------	 --------------------	-------------------------
> mopd	 bootloader [url]	/tftpboot/mop/MOPBOOT.SYS
> bootpd	 ip address, hostname,	/etc/bootptab
> 	 boot loader filename
> tftpd	 bootloader [url]	/tftpboot/vax/1.6/boot
> nfs	 install kernel [url]	/export/vax/root/netbsd
>
> If each Service were linked back to its netboot page and each Provides
> were linked to the file on ftp.netbsd.org, it would be simpler to navigate
> and get the right stuff.  It would also be unnecessary to keep updating
> links in the netboot pages; they could instead refer to bookmarks in
> INSTALL.html.
>
> Finally, I should mention there's no errata or readme to point out:
>
> 1.  The NetBSD 1.5 mopd is broken.
> 2.  The only working MOP bootload is 1.5.3.  Not prior, not since.
>
> At the very least, there should be a readme that says no one's maintaining
> the readme, referring the reader to the ML archives.
>
> Sorry for the long list.  You only do something once for the first time.
> Soon it becomes obvious what to do, and by then it's too late to see where
> the newcomer can go astray.  In that sense, I'm still ignorant enough to
> be useful.
>
> +++
>
> I've seen messages in the archives indicating a move toward sgml/docbook,
> with which I'm familiar.  Does the netboot document want conversion to
> sgml?  I know how to do that.
>
> I can also update the existing docs in html, per the above remarks.  You
> want diffs against current cvs, new files, what?  You want to stick with
> <i> and <tt> or move to <em> and <kbd>?
>
> --jkl