NetBSD/cobalt Restore CD HOWTO

This document attempts to explain how to create and use a NetBSD Restore CD/USB for Cobalt Qube/Raq devices. It was originally written by Alex Pelts and posted to the port-cobalt mailinglist, then updated by Izumi Tsutsui for the newer 5.0 restorecd script.

 BSD daemon

Introduction

What is a Cobalt Qube/Raq and what is a Restore CD/USB?

Hardware and Software Requirements

Installation with the Restore CD/USB

Steps to create new Restore CD/USB

Restore CD/USB Internals

Credits

Introduction

Disclaimer

The author does not accept any liability for your use of this document. It is possible that your use of this document will render your computer useless, damage your hardware, software, break your window or your relationship with a loved one. Use the contents of this document at your own risk. This document is just the authors opinion on how to use hardware and software mentioned herein.

You have been warned.

Copyright Information

This document is copyrighted (c) 2005 Alex Pelts and also copyrighted (c) 2008, 2009, 2010, 2011, 2012, 2013, 2014, 2018, 2020 Izumi Tsutsui, and distributed under the terms of the OpenContent License (OPL). The full text of the license can be found at https://www.opencontent.org/openpub/ .

What is a Cobalt Qube/Raq and what is a Restore CD/USB?

What is a Cobalt Qube/Raq?

The Cobalt Qube/Raq is a server appliance. To put it simply, they are just computers without keyboard and monitor and without the ability to attach one. There are several versions of Qubes and Raqs in existence, older MIPS based and newer AMD-K6 based. This document covers only MIPS based server appliances. Further in the document both appliances will be referred to as "Qube". There are differences between the Qube and the Raq but for the purpose of this document they are irrelevant.

What is a Restore CD?

Because the Qube does not have an easy way to attach a monitor, a keyboard and most importantly a CDROM drive, there is no easy way to install a new operating system on it. This is where the Restore CD comes in. The Qube has the ability to boot an operating system over the network. A Restore CD provides the environment allowing the Qube to boot an operating system and perform an unattended install of the operating system onto hard drive. An original Linux Restore CD was provided with the device. ISO image of this CD can still be downloaded from Sun's web site.

Based on the original Cobalt Restore CD, Dennis Chernoivanov created a NetBSD Restore CD for versions 1.6 and 1.6.1. He then published the scripts he used to create CD and he also updated the script for 3.0 release and 3.99.xx -current. After that his restorecd script has been updated and improved by Izumi Tsutsui for 4.0 and 5.0_BETA.

This document describes how to use a Restore CD on installation and how to create a Restore CD for version 5.0 (and later) from scratch.

What is a Restore USB?

Restore USB is a bootable disk image which has almost identical functions with Restore CD but is intended to be burned into USB memory sticks for modern USB bootable PCs without CD/DVD drives.

Hardware and Software Requirements

Hardware Requirements to use Restore CD/USB

To create and use Restore CD/USB you will need following hardware:

  • MIPS based Qube or RaQ with at least 1GB hard drive installed.
  • x86 based PC or Laptop with NetBSD supported Ethernet adapter and bootable CDROM drive (for Restore CD), or bootable USB interface and 600MiB or larger USB memory stick (for Restore USB).
  • Crossover Ethernet cable or hub with two straight cables.
  • RS232 Serial cable could be very helpful to diagnose problems.
  • CD Recorder to create your final CD (for Restore CD).

Software Requirements to create Restore CD/USB

To create Restore CD/USB you will need following software:

  • POSIX-compliant systems which are capable to build NetBSD from sources. Any of the following should work - NetBSD, FreeBSD, Linux, Cygwin etc.
  • wget or rsync to retrieve all new installation binary and source sets.
  • Typical unix tools including awk, basename, cat, chmod, cp, dirname, echo, gzip, ln, mkdir, mv, patch, pwd, rm, sed, sh, tar, and touch etc. These usually come with your OS.
  • More commands to build NetBSD toolchains, including make, cc (or gcc), as, ld, and cmp (required by configure scripts) etc. Usually these also come with your OS.

Installation with the Restore CD/USB

Installation Overview

The installation instructions below will in order perform the following steps:

  1. Write the Restore CD/USB to CD-R media or USB memory stick using some utilities.
  2. Boot the assisting PC from the RestoreCD/USB media. This will enable a dhcp server on the PC and other services which the server appliance will need during installation.
  3. (re)boot the Cobalt server appliance in a state where it is prepared to retrieve the Restore CD/USB contents via network
  4. Re-initialize the Cobalt server appliance from the assisting PC's Restore CD/USB

Note an article “Install NetBSD on a Vintage Computer” in DesignSpark has detailed descriptions about installation of NetBSD/cobalt 9.0 using this Cobalt RestoreCD/USB.

YouTube video “Install NetBSD/cobalt 5.1_RC2 using restorecd” is also available for a visual example.

How to Use Your Restore CD/USB

Warning: THIS INSTALLATION WILL DESTROY THE EXISTING CONTENTS OF YOUR COBALT HARDDISK DRIVE. Ensure you have sufficient backups before starting the installation if you need.

Note: on the other hand, Restore CD/USB don't use harddisk on the i386 server at all (it works even if the server has no hard drive).

  1. Write the Restore CD/USB image to CD-R media or USB memory stick using some utilities. On NetBSD, you can use cdrecord tool in cdrtools package for ISO, or dd(1) for USB image. To write a USB image on Microsoft Windows, you can use Rawrite32 tool.

  2. Connect your i386 server to your cobalt using ether a crossover cable or hub/switch.

    Note: for security reason, it's recommended not to connect any other machines than your i386 server and cobalt appliance on the same network.

  3. Check your i386 server's manuals to see how to boot from its CDROM drive (or its USB storage device), then boot it from the Restore CD (or the Restore USB memory). If “login:” prompt appears the i386 server is ready for installation and no further settings are required on the server.

    As noted during boot process, it is recommended to check an instruction document prepared as /instructions.txt on the server's image.

    Note: if your machine has some trouble during boot around ACPI, try alternative kernel settings as shown on the boot menu.

  4. Turn on the cobalt appliance while simultaneously pressing and holding down both the left (<) and right (>) arrow buttons on the LCD console to boot cobalt via network.

  5. Continue holding down both the left (<) and right (>) arrow buttons until “Net booting” appears on the LCD display, 

    Net booting

    then release the buttons.

  6. Wait until the box boots up. Note most boot processes are shown on the LCD display: 

    NetBSD/cobalt
Bootloader


    Loading:
nfs:netbsd


    NetBSD/cobalt
Starting up...


    [Starting up]
  Create /dev/*


    [Starting up]
  > network

    If it's ready, “restorecd ready” message and IP address assigned by the i386 server appear on the LCD screen: 

    restorecd ready
[10.0.0.150]

    Note: if you need remote login access for recovery without restoring, you can login to your cobalt from the i386 server via network at this point.

  7. To start restorecd operation, push and hold the “Select” button two seconds to enable paneld menu. Once the menu appears on the LCD display, select “Restore” menu by the Select button, 

    select:
  Restore

    select “Y” (which is default) by the arrow buttons on the confirm menu, 

    Start restore?
  [Y]es / [N]o

    and then push the “Enter” button to start installation.

    Warning: again, whole disk contents on the cobalt appliance will be destroyed once installation is started.

    During installation, whole procedure will appear on the LCD display and serial console. 

    Disk Setup:
  Reset disk


    Disk Setup:
  Format root


    System install:
  base.tgz

    Warning: please note that the installation process may take a while (about 10 minutes on Qube2). Do not interrupt it until it is finished.

  8. Once all part of installation are complete, the cobalt box will be rebooted automatically. 

    Installed OK:
  Rebooting...

    Wait until the cobalt appliance boots up from the hard drive. 

    NetBSD/cobalt
Bootloader


    Loading:
wd0a:netbsd


    NetBSD/cobalt
Starting up...


    [Starting up]
  > dhcpcd

    Finally, the box host name and IP address (that are assigned by the i386 server running restorecd) should appear on the LCD screen. 

    q-150.netbsd.org 
  [10.0.0.150]

    This indicates installation success.

  9. BE AWARE that a newly installed box is left in a highly insecure state.

    (9.1 and later versions) Root access via sshd(8) without password from your i386 server is permitted. This is done to allow you to login into the fresh box in order to make necessary configuration changes.

    (9.0 and prior versions only) All ttys are open by default and allow root access over the network. Also, telnet and rlogin ports are open. This is done to allow you to login into the fresh box in order to make necessary configuration changes.

    Please do not forget to bring your cobalt appliance to a secure state before connecting it to an open network:

    • set root password by passwd(1)
    • (9.1 and later versions) remove the following lines in /etc/sshd/sshd_config to disable root access via sshd(8). 
      # !!! Temporary settings for the initial setup of Cobalt RestoreCD/USB. !!!
# !!! Remove these lines after your own setup is complete. !!!
AllowUsers root@10.0.0.254
PermitRootLogin yes
PermitEmptyPasswords yes
AuthenticationMethods none
UsePam no
IgnoreUserKnownHosts yes
# !!! End of Cobalt RestoreCD/USB settings !!!
    • (9.0 and prior versions only) remove all pseudo terminal (pts/[0-9]*) lines from /etc/ttys, or remove “secure” field from such pseudo terminals
    • (9.0 and prior versions only) comment out telnet and rlogin lines in /etc/inetd.conf if you don't really want to enable those services by default (it might be better to use sshd(8))
    • add new users with user(8) etc.
    • put users who need root access via su(1) in the “wheel” group by editing the /etc/group file

    See the afterboot(8) man page for more details.

  10. Check afterboot(8) for further settings. Some of the information is not applicable to the cobalt, but will give you some background information on configuring NetBSD in general. The NetBSD Guide also provides helpful information.

    Warning: a freshly installed cobalt box is configured as a DHCP client, i.e. it tries to obtain its IP address over the network from a DHCP server, for initial setup with the i386 server running restorecd. To disable this after your own settings are complete, change /etc/rc.conf to contain “dhcpcd=NO” line.

Troubleshooting

If you have any trouble and your cobalt doesn't boot up to the multi user, you can still use the Restore CD/USB for recovery. As mentioned in the previous section, netboot environment with the Restore CD/USB provide remote login capability without reinstalling, so you can check and fix contents in your hard drive etc. without serial console.

To debug any problems with the Restore CD/USB operation itself you will need a serial cable. Cobalt machines use standard DB9 male connector and NetBSD Serial Port Primer page might help to prepare it. Attach this cable to your Qube's serial port and to your computer. Now you can run a terminal program and monitor the installation progress.

Qube2700 does not have serial port so there is not much you can do. About the only thing is to extract hard disk from Qube, attach it to a PC or a newer Qube2. Examine the failed install and try to figure out what went wrong. If you are brave enough, you could also try to build optional serial interface.

Installation using sysinst based install kernel

While Restore CD/USB provide fully automated installation by default, it also contains the sysinst based install RAMDISK kernel which is the traditional installation method on NetBSD. If you have a working serial console, you can also boot the sysinst based install kernel without difficult netboot server settings.

To use the RAMDISK based install kernel, you need to specify sysinst based kernel at the bootloader's prompt.

  1. Setup your i386 server and boot your Cobalt via network with arrow buttons as mentioned in How to Use Your Restore CD/USB section.

  2. If bootloader is properly loaded via network, you can see the following bootloader prompt on your serial console: 

    >> NetBSD/cobalt 9.2 Bootloader, Revision 1.0 (Wed May 12 13:15:55 UTC 2021) [@0x80f00000]
>> Model:               Cobalt Qube 2
>> Memory:              65536 k
>> PROM boot string:    root=/dev/nfs nfsroot=/nfsroot nfsaddrs=bootp
Boot [nfs:netbsd]:

  3. Enter netbsd.sysinst to load the sysinst based RAMDISK kernel on the prompt: 

    Boot [nfs:netbsd]: netbsd.sysinst

  4. The RAMDISK kernel will be loaded as the following: 

    Loading: nfs:netbsd.sysinst
8400656+116800 [267824+262389]=0x8a13fc
Starting at 0x80001000

[   1.0000000] Copyright (c) 1996, 1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005,
[   1.0000000]     2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013, 2014, 2015, 2016, 2017,
[   1.0000000]     2018, 2019, 2020 The NetBSD Foundation, Inc.  All rights reserved.
[   1.0000000] Copyright (c) 1982, 1986, 1989, 1991, 1993
[   1.0000000]     The Regents of the University of California.  All rights reserved.

[   1.0000000] NetBSD 9.2 (RAMDISK) #0: Wed May 12 13:15:55 UTC 2021
[   1.0000000]	mkrepro@mkrepro.NetBSD.org:/usr/src/sys/arch/cobalt/compile/RAMDISK
 :

  5. On "Terminal type? [vt100]" prompt, just hit Enter. On the next "(I)nstall, (S)hell or (H)alt ?" menu, select "i": 

     :
erase ^H, werase ^W, kill ^U, intr ^C, status ^T
Terminal type? [vt100] 
Erase is backspace.
(I)nstall, (S)hell or (H)alt ? i

    then you see messages by sysinst.

  6. For further sysinst installation, refer Example installation section in the NetBSD guide.

    Note there are several NetBSD/cobalt specific or Restore CD/USB specific settings:

    1. NetBSD/cobalt sysinst supports only English messages, so selecting language and keyboard menu are not applicable.

    2. On MBR partitions menu, select "b: Use the entire disk". If you want to edit MBR partition manually, make sure to prepare Linux Ext2fs boot partition required by the firmware.

    3. On Disklabel partitions menu, select "a: Set sizes of NetBSD partitions" and change partition or swap size if necessary. Note Ext2fs boot partition is prepared automatically, but please don't change it in the disklabel editor.

    4. On Choosing the installation media, you can only use Install from NFS, which is prepared on your i386 server by the Restore CD/USB. Before setting Host and Base directory, you also need to configure network as mentioned in Install via FTP section.

      • Use the default "tlp0" for network interface device.
      • Use the default "autoselect" for media type.
      • Select "a: Yes" on "Perform DHCP autoconfiguration?" prompt to use DHCP.
      • Don't try to setup IPv6 configuration because Restore CD/USB don't support it.

      On the NFS install screen, use the following settings:

      • Use "10.0.0.254" for NFS host, which is the default IP address used on the your i386 server running Restore CD/USB.
      • Use "/nfsroot" for base directory, where the NFS root is stored on the Restore CD/USB.
      • No need to change set directory from the default, since Restore CD/USB have set files in the default path.

Upgrading installed system

Unfortunately Restore CD/USB don't support automated upgrading installed system, but you can still try to update your system manually as described in the Updating an existing system from a current snapshot section in the Tracking NetBSD-current document.

If you have a working serial console, you can also try to boot sysinst(8) based RAMDISK kernel in the distribution for menu based upgrading. To boot RAMDISK kernel, you can just put netbsd-RAMDISK.gz kernel in the root directory on your working system and choose it on the bootloader prompt. For the actual procedure of upgrading by sysinst, see Upgrading NetBSD section in the NetBSD guide for details.

If you have any trouble on upgrading, you can still use Restore CD/USB as a rescue disk as mentioned in the Troubleshooting section.

Steps to create new Restore CD/USB

Prepare fetch command

The restorecd script requires wget or rsync to fetch necessary NetBSD release files for Restore CD/USB. If you are using a NetBSD host you can install them via Packages Collection by the following commands:

# PKG_PATH=https://cdn.NetBSD.org/pub/pkgsrc/packages/NetBSD/amd64/9.2/All	# use appropriate port and version for your build host
# export PKG_PATH
# pkg_add -v wget
# pkg_add -v rsync

Download restorecd script

Download the NetBSD Restore CD script and extract it. It is located on github.

Edit Makefile

The restorecd script includes a simple Makefile to create Restore CD/USB, but there is no automated “configure” mechanism so you might have to modify the Makefile for your host system and environments.

  • Modify WGET= or RSYNC= lines per where these commands are installed on your host: 
    WGET?=		/usr/pkg/bin/wget
#WGET=		/usr/bin/wget
#WGET=		/usr/local/bin/wget

RSYNC?= 	/usr/pkg/bin/rsync
#RSYNC= 	/usr/bin/rsync
#RSYNC= 	/usr/local/bin/rsync
  • If you will use daily snapshot binaries to build restorecd, check Summary of daily snapshot builds page and modify DAILY_DIR?= line to point an appropriate daily directory: 
    DAILY_DIR?=	202002220040Z
  • If you use mirror sites rather than ftp.NetBSD.org or rsync.NetBSD.org, set your mirror host to FTP_HOST= line for wget: 
    FTP_HOST?=	ftp.NetBSD.org
#FTP_HOST=	ftp.jp.NetBSD.org
#FTP_HOST=	ftp7.jp.NetBSD.org
    or RSYNC_HOST= line for rsync: 
    RSYNC_HOST?=	rsync.NetBSD.org
#RSYNC_HOST=	rsync.jp.NetBSD.org
RSYNC_PREFIX?=

#RSYNC_HOST=	rsync3.jp.NetBSD.org
#RSYNC_PREFIX=	pub/
    If your rsync mirror have different module names from rsync.NetBSD.org (i.e. its rsync URL has trailing directory path after the hostname), you also have to adjust RSYNC_PREFIX= line.
  • If you use rsync, you have to change the following lines: 
    ${DONE_FETCH}:
	${MKDIR} -p ${DOWNLOADDIR}
#	${MAKE} fetch_wget
	${MAKE} fetch_rsync
	${TOUCH} ${DONE_FETCH}
    i.e. comment out “${MAKE} fetch_wget” line and uncomment “${MAKE} fetch_rsync” line.

Creating your new Restore CD/USB

Once your fetch command and Makefile are prepared, just type “make”.

This will take some time to execute and after it is finished you will have a file “cd.tmp/restorecd.iso” which is your new Restore CD image, and also a file “usb.tmp/restoreusb.img” as a new Restore USB image.

You can burn this Restore CD image onto a CD using any software that can record ISO images. On UNIX like OSes you can use cdrecord, on Windows use Nero Burning Rom or any other ISO image compatible software. To write the Restore USB disk image to USB memory stick, you can use dd command on UNIX like OSes. On Windows, you can use Rawrite32 utility.

Congratulations! Enjoy your custom NetBSD Restore CD/USB.

Restore CD/USB Internals

What restorecd script does?

Makefile in the restorecd script does the following ops:

  • fetch release binary sets (both for i386 and cobalt) and source sets (necessary files are listed in restorecd-fetch.lst file)
  • extract whole source sets
  • build toolchains for NetBSD/cobalt, to prepare makefs(8), installboot(8), and disklabel(8) commands (required to create ISO/USB images and make it bootable) and to rebuild paneld binary and its manual pages
  • extract cobalt binary sets and build paneld binary and man pages
  • invoke “restorecd” script to build the actual Restore CD ISO image and Restore USB FFS image

The script of “restorecd” performs the following ops:

  • check if the system has necessary commands
  • prepare files for i386 server (which will appear in root of the images) by extracting binary sets with misc local modifications
  • prepare files for cobalt client (which will appear in /nfsroot in the images) from binary sets, rebuilt paneld binary and some local files for Restore CD/USB operations
  • copy binary set files for cobalt into /nfsroot/cobalt and /nfsroot/mipsel for installation
  • create a bootable ISO image by makefs(8) in the NetBSD toolchain
  • also create a bootable FFS image by makefs(8), installboot(8), and disklabel(8) commands in the toolchain

See the Makefile and restorecd script for more details.

Note several settings used in the restorecd script depend on the default behaviors and settings of each NetBSD command and kernel, so they might have to be updated for the future NetBSD-current.

How does the Restore CD/USB work?

  • The i386 server uses ISO9660 file system for root file system on the Restore CD. The GENERIC kernel now recognizes CDROM drive as a booted device so there is no special settings for it.
  • Of course ISO9660 file system on CDROM is read-only, so several directories which require write permission are prepared using MFS.
    • Device nodes in /dev is prepared by init(8) as well as RAMDISK kernels on installation media.
    • All files under the /var directory are stored in /altvar in the CDROM, and they are copied to MFS mounted /var directory once it's ready. It's handled by the custom /etc/rc.d/mfsmount rc.d(8) script.
    • The /etc directory is a bit tricky. Some files (like /etc/rc) are required right after root file system is mounted so we can't use the same way with the /var directory. Instead, restorecd uses “union” option of mount(8) command to write some necessary files in /etc dir. For named(8), chroot settings are used for some write ops. Some more other rc.d(8) scripts are modified to handle this read-only quirk.
  • On Restore USB, the i386 server uses normal FFS for root file system but it's mounted read only to use the same settings as the Restore CD.
  • The cobalt client uses NFS for root file system during installation. The NFS exported directory is /nfsroot on the i386 server and of course it's also read-only, so the similar mechanism with the i386 server mentioned above is used on the cobalt client.
  • The i386 server searches available network interfaces from output of ifconfig(8) command with -l option. If there are multiple interfaces the first one is used. You have to use userconf(4) at the boot to disable unwanted interfaces, or modify the custom data/i386/etc/rc.d/netconfig rc.d(8) script on building restorecd.
  • Actual installation operations are described in the install-core.sh found in /nfsroot/cobalt/install/script directory, or data/cobalt/install/script directory in the restorecd script tree. They are not same procedure with the default sysinst(8) installation.
  • The installer create the following partitions:
    • two times as physical memory for swap
    • 20% (10% if disk size is smaller then 2Gbytes) of the available disk space for /var
    • 5% of the available disk space (or 500Mbytes if it's larger than that) for /tmp
    • 10Mbytes for ext2fs partition to store bootloader
    • rest for the NetBSD root partition
  • The installer also put custom files from data/cobalt/install/files directory in the restorecd script tree for the following operations:
    • fstab(5) file for the above default partitions
    • paneld(8) binary and its config files under /etc
    • patched ttys(5) and inetd.conf(5) (9.0 and prior versions) or sshd_config(5) (9.1 and later versions) for initial root login
    • patched rc(8) and rc.d(8) scripts to show boot process to the LCD display

Credits

Authors

This document was originally written and contributed to the NetBSD Project by Alex Pelts . The Create and Install sections are updated for 5.0_BETA restorecd and the Internals section is added by Izumi Tsutsui .

Other credits

Thanks to Dennis Chernoivanov for creating the original NetBSD Restore CD upon which this work is based and the original instructions.txt document which the Install section is based on, and also thanks to Havard Eidnes for improving the instructions.txt document. Of course many thanks to numerous people from the port-cobalt mailing list, who helped me to test this CD.

Document revision history

  • 2005-03-11 -- original version announced on the port-cobalt mailing list.
  • 2005-03-13 -- original import into NetBSD's htdocs CVS module with minor english and grammar fixes.
  • 2008-11-18 -- updated for newer 5.0_BETA restorecd script.
  • 2009-04-20 -- Add some note about upgrading.
  • 2009-04-30 -- updated for 5.0 release.
  • 2009-08-29 -- Add a section about installation using sysinst kernel.
  • 2010-02-19 -- updated for 5.0.2 release.
  • 2010-09-18 -- reorder sections, add a link to YouTube video, update some examples.
  • 2010-11-19 -- updated for 5.1 release.
  • 2012-02-14 -- updated for 5.1.2 release, and also add descriptions about a brandnew Restore USB.
  • 2012-12-08 -- updated for 5.2 release.
  • 2013-10-20 -- updated for 5.2.1 release.
  • 2014-02-02 -- updated for 5.2.2 release.
  • 2018-02-17 -- A test version for 7.1.1 release.
  • 2018-04-01 -- updated for 7.1.2 release.
  • 2018-07-22 -- updated for 8.0 release.
  • 2020-02-29 -- updated for 9.0 release.
  • 2020-10-24 -- updated for 9.1 release, with changes to use sshd(8) login rather than rlogind(8).
  • 2021-08-07 -- updated for 9.2 release.
All other changes can be seen from the cvsweb interface.