NetBSD/mac68k Installation Guide

Overview

Note: If you are upgrading an earlier NetBSD system to version 1.3, see the Upgrade HOWTO[2].

This document is geared toward users with a fair amount of MacOS experience, and a limited amount of Un*x experience (Unix, NetBSD, Solaris, Linux, NextStep, and many other similar systems are lumped together as "Un*x"). Beyond the initial installation, this document contains only a few references to other pages and books.

Instructions for setting up a Jaz drive for use with NetBSD can be found in the Jaz HOWTO[3].

About this document

Acknowledgements

• The NetBSD 1.3 Installation Sheet[4]
• The NetBSD port-mac68k Mailing List Archives[5]

However, any mistakes found here are my own. Please let me know if you have any questions or improvements.

Disclaimer

Getting Started

About NetBSD/mac68k

• It is not necessary to completely replace MacOS with NetBSD. In fact, you must keep a functional MacOS system on your boot drive. Linux and Xenix users are familiar with the "dual boot" concept, although it's optional for them.
• To boot NetBSD, you must first boot MacOS, and then run the Booter program. This gracefully terminates MacOS and starts NetBSD. You can automatically start NetBSD while starting MacOS, however.
• MacOS and NetBSD have different file systems (methods of storing files on disks). Currently, there are only limited file transfer capabilities between the two file systems.
• Once you start NetBSD, you are running Un*x on your Mac hardware. This is as much a "real" Un*x as is Linux -- Macs running NetBSD are in daily use as research platforms, Web servers, and learning tools. Many applications running on Linux or other Un*x platforms can be easily ported to NetBSD.

Hardware requirements

To actually do much compiling or anything more interesting than booting, at least 8MB of RAM and more disk space [than 40MB] is recommended. About 75MB will be necessary to install all of the NetBSD 1.3 binary system distribution sets (note that this does not count swap space!). An [additional] 25MB or so is needed for the binary X11 distribution sets.

A system with 16MB of RAM and 200MB of hard drive space will be adequate for anything short of recompiling the entire operating system (in this case, assign roughly 500MB of disk space). (Compiling Emacs requires a significant percentage of the world's storage media, but it too can be done.)

The following systems have additional hardware requirements:

• Mac II: requires a full memory management unit (MMU).
• Mac IIsi, LCII: a floating point processor (FPU) is strongly recommended, but no longer absolutely necessary.
• Any system with a 68LC040 processor (many Performas, some Quadras): Certain processors work, others do not. Of those that work, any software that requires floating point will probably have errors. This will be fixed eventually; you could also replace the processor with a 68040.

Highly recommended reading

• NetBSD Installation Sheet[4]
• Colin Wood's documents[6] on the MacBSD site. Especially read the FAQ, meta-FAQ, and list of supported systems. The general info page is also recommended.

If your system does not appear in the list of supported systems, you may still be able to install a "current" (development) version of NetBSD instead of the 1.3 release version. Search the mailing list archives[5] for discussions about your system before giving up.

Installation Procedures

Choosing a Kernel

Ideally, the kernel should be able to automatically detect connected peripherals and configure itself accordingly. In reality, a "generic" kernel covers the majority of situations while other kernels are available for special (but not uncommon) situations. These situations include support for systems not in the current "supported" list.

Pre-compiled kernels are available at the main NetBSD site[7]. Select a kernel as follows:

If you have adequate hard drive space, you should consider recompiling your kernel to tailor it to your system requirements (once you have NetBSD installed and running on your Mac, of course). This results in a smaller, and often faster, kernel. See the kernel HOWTO[8] for instructions.

After you have installed MacBSD with a pre-compiled custom kernel, you may notice that commands such as ps and w terminate with an error. This happens when the kernel is out of sync with these commands. Compiling a new kernel is the easiest way to solve that problem.

Preparing the Mac

Now that your data is safe, you're ready to start.

Tools

• mkfs 1.45 (creates a NetBSD file system)
• Installer 1.1g (installs archives from MacOS files onto the NetBSD file system)
• Booter 1.11 (starts NetBSD from the MacOS)

In addition, you need a hard drive utility to partition and format the hard drive. FWB Hard Drive Toolkit (HDT), LaCie SilverLining, and several others are suitable.

If you need a freeware solution:

• The Apple HD SC utility can be patched[10] to work with drives other than Apple's.
• APS Disk Tools used to be available as APS273.sit.hqx on A/UX archive sites. However, it has been determined to be a commercial product and has been withdrawn from most sites. (Do any sites still have it? Only Archie knows.)

Sizing partitions

• swap partition (40MB)
• NetBSD root partition (50MB)
• /usr partition (200MB)
• /var partition (100MB)
• /home partition (130MB)

A guideline for determining swap -- too often misstated as a rule -- is to double the RAM installed in your machine and use that figure to determine swap space. You can actually run NetBSD with no swap, but the system will lock up if you run out of RAM.

You can use more than one hard drive for NetBSD, and you can share a hard drive between NetBSD and MacOS partitions. Part of your job as a system administrator is to find an efficient allocation of disk resources.

Preparing the hard drive

Tips:

• If you want to create more than two or three partitions, and your software does not cooperate, use the software's A/UX partitioning scheme and allow it to create eschatology or autorecovery partitions. You will convert them next.
• If you can determine how many blocks make up one cylinder on your drive, size the partitions so they take up entire cylinders. Otherwise, sectors in each partition will be unallocated (essentially wasted).

Important: Several formatters, including Apple HD SC, have a bug that writes erroneous data to the partition map. This may show up when you run older versions of mkfs; you may not see the last partition. Version 1.45 of mkfs can detect and fix this problem automatically. Another way to work around this problem is to make the last partition a MacOS partition (it can be very small if you don't need more MacOS space).

Creating the NetBSD filesystems

1. Start the mkfs application. Mkfs polls the SCSI bus, displays the devices it finds, then presents a dialog with the devices it found.
2. Select the appropriate hard drive and click OK. Mkfs displays a list of partitions available.
3. If you need to change a partition type (for example, from MacOS to NetBSD), select the partition then click the CHANGE button. Select the new type and click OK. When you finish, you should have the following:
   • At least one "NetBSD Root" or "NetBSD Root&Usr" partition
   • One "NetBSD Swap" partition
   • Other partitions should be "NetBSD Usr" (or "MacOS") types.
4. Format each NetBSD partition, except for the swap partition. Follow these steps:
   • Select the partition to format.
   • Click the FORMATbutton. Mkfs presents a list of hard drive and filesystem parameters.
   • Look over the parameters and make any corrections, if necessary. For most drives, the defaults shown are usually reasonable and can be accepted as-is.
   • Click OK. Mkfs gives you one last chance to back out; click Format if you want to proceed.

Downloading the binaries

Get the following files from the NetBSD FTP site[7]:

• base.tgz (the binaries needed for minimal support)
• etc.tgz (system configuration files)

Remember to specify binary mode for the file transfers.

If you have adequate hard drive space, download the other files in this directory as well -- comp.tgz, man.tgz, misc.tgz, text.tgz, and games.tgz. All these files, including the base.tgz and etc.tgz tarballs, take up about 15MB on the hard drive.

The files whose names start with x are for the X11 windowing system. These tarballs require about 9MB more.

Note: These files are called "tarballs" in the NetBSD community, because they are gzip'ed tar (archive) files.

How NetBSD names partitions

• Each time you boot NetBSD, it scans the Mac's SCSI bus for disk drives. The drive at the lowest SCSI address in the system is assigned the name /dev/sd0 -- regardless of whether its SCSI address is 0 and whether that drive has a NetBSD partition or not. The second SCSI drive is named /dev/sd1 and so on. (NetBSD recognizes CD-ROM and tape drives and assigns them different device names. However, NetBSD/mac68k does not recognize IDE hard drives at this time.)
• Disk drives consist of one or more partitions, and NetBSD typically names them as follows:
  • a - root partition
  • b - swap partition
  • c - entire drive
  • d - MacOS driver partition
  • g - first usr partition (typically mounted at /usr)
  • e, f, h - successive usr partitions (can be mounted anywhere; these are often mounted at /var, /tmp, /home, and so on)

For example, if the hard drive at SCSI ID 0 is dedicated to MacOS, and you have a hard drive (or Zip/Jaz/other removeable) at ID 5 for NetBSD, the NetBSD drive might be assigned the following device names:

• /dev/sd1a - NetBSD root partition
• /dev/sd1b - swap partition
• /dev/sd1c - entire disk
• /dev/sd1d - MacOS driver partition
• /dev/sd1g - first usr partition
• /dev/sd1e - next root or usr partition, if configured
• /dev/sd1f, /dev/sd1h - other NetBSD usr partitions, if configured

SCSI devices are named as follows:

• sd - SCSI disk drive
• st - tape drive
• ss - scanner
• se - SCSI Ethernet controller
• ch - tape (and possibly CD-ROM) changer
• uk - unknown device

Installing the system

1. Place the Installer application and the tarballs in the same folder.
2. Start the Installer application. The Installer scans the SCSI bus and presents you with a list of available devices.
3. Select the appropriate hard drive -- the one with your NetBSD filesystems on it -- and click OK. Installer mounts the "root" partition.
4. Select "Build Devices" from the File menu. This creates the standard list of devices in the /dev directory.
5. Select "Mini Shell" from the File menu. A > prompt appears in the Installer window.
6. Type disklabel at the prompt and press Return. This shows you the device names that NetBSD has assigned to your partitions. Note the names of your root partition and any usr partitions; you will need these.
7. Create empty directories for use as mount points. For example, create the /usr directory with the command:

        mkdir /usr

8. Mount user partitions at the appropriate mount points. For example, if your NetBSD drive is the second drive in the SCSI chain, mount the first user partition with the command:

        mount /dev/sd1g /usr

   Note: The root partition is already mounted at /. Do not mount the swap partition.
9. When you have all partitions mounted correctly, create the filesystem table /etc/fstab with the following command:

        fstab force

   This creates a table that NetBSD uses to automatically mount all your partitions when you boot the system.
10. Type quit to exit the mini-shell.
11. Select "Install" from the File menu. The Installer presents you with the list of available tarballs. Select at least the kernel (typically GENERIC), base, and etc files -- you can install the rest later (for example, if you have to make room on your MacOS drive for them). If you have all the tarballs handy, go ahead and install them all. This will take some time, and you will see occasional "file exists" messages when the Installer tries to create a directory that already exists. You can ignore these messages.
12. When the installation is complete, quit the Installer.

If you have problems

Once again, make sure you downloaded the tarballs in binary mode. Everybody makes this mistake at least once.

Most problems with the Installer can be fixed by increasing its "Preferred Memory" size in its Get Info dialog. Version 1.1 has a default of 3000KB; try increasing this to 6000KB if possible.

If you continue to have problems, copy down any error messages and email a cry for help to the port-mac68k mailing list[11].

The Moment of Truth

• Open the Memory control panel and make sure 32-bit addressing is turned on. If your system is one of those listed as "dirty" in the Machine Status Page[1], you need the Mode32 extension[12] installed (download this extension and reboot if necessary).
• Use the Monitors control panel to put your Mac in black&white mode for best results (Booter versions 1.11 and newer can do this for you).
• Boot MacOS with extensions OFF (except for Mode32 on systems that require it). This is not strictly necessary on many systems, but is required for others.

You are now ready to boot NetBSD. Quit any open MacOS applications (or at least save any work) before proceeding. The booting process shuts down MacOS.

Configuring the Booter

1. Select Booting... from the Options menu and configure the system as follows:
   • No env dumps, Don't disable VBL interrupts, Enabled (next to the Root SCSI ID text box) and Auto-size RAM on, all other checkboxes OFF.
   • GMT Bias: the time, in minutes, that the Mac system clock is offset from GMT. For example, Eastern Daylight Time (US) would be -240.
   • Kernel location: NetBSD/mac
   • Kernel name: netbsd
   • Partition name, Miniroot: leave blank
   • Root SCSI ID: The SCSI ID of the hard drive that contains the root NetBSD partition.
   • RAM (MB): Set automatically; do not change this value unless you know it's wrong.
2. Now select Startup... from the Options menu and configure this dialog as follows:
   • All checkboxes OFF
   • Debug level: 0
3. Select Monitors... from the Options menu and verify that the Change Monitor Depth and B&W settings are enabled. This sets the Mac to black & white before booting, the safest and fastest setting. You can change this later if you wish.
4. If your Mac requires a serial console, or you want to use one, select Serial Ports... from the Options menu and configure the serial ports as necessary for your setup. If your printer port is used for a LocalTalk connection, you should check the LocalTalk connected to Printer Port box as well.
5. Select Save Options from the File menu, then quit the Booter. This step is necessary for the Booter to save your configuration.
6. Start the Booter again, select Booting... from the Options menu, and check the Single User box. (This is not strictly necessary, but is helpful if fsck needs to clean up your partitions the first time you boot.)
7. Click OK to close the dialog box, then select Boot Now from the Options menu. The Booter window displays a few messages, then the entire screen clears; the top line should say "Preserving xxxx bytes..." where xxxx is some number. If you see this and other messages, you are now running NetBSD.

If your system hangs, or the console displays "kernel panic," make sure you have done the steps at the beginning of this section.

Eventually, if you booted in single-user mode, you should see a # prompt; this indicates that NetBSD is ready to take commands. (If you did not boot single-user, you should see a login prompt -- type root to log in.) If you saw any messages like filesystem corrupt, run fsck, you should run fsck on the indicated partitions. For example, type

     fsck /dev/sd1g

to clean up the user partition. The system will ask you whether you want to fix each error it finds; answer y each time.

After all the partitions are in proper order, press [Ctrl]-D to exit single-user mode. NetBSD automatically mounts your partitions in their proper places, then presents you with a login prompt. Log in as root the first time.

The rc.conf error

To fix this, edit the /etc/rc.conf file and configure the network parameters as needed. Then, change the line reading rc_configured=NO to rc_configured=YES. If you are familiar with what other parameters need to be changed, make those changes as well. Save the file and type reboot at the prompt.

Now what?

Now that you (we hope!) have a working NetBSD system, you need to create your normal login account, set up files in /etc, and generally have a good time playing system administrator. Rob Windsor's Life After Installing NetBSD[13] page covers most of these topics (although it may be slightly outdated). The FAQ pages[14] cover other basic information. Happy Un*x'ing!