NetBSD/distrib/notes/alpha/install

.\"	$NetBSD: install,v 1.20 2000/10/29 14:08:04 lukem Exp $
.\"
.\" Copyright (c) 1999, 2000 The NetBSD Foundation, Inc.
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 3. All advertising materials mentioning features or use of this software
.\"    must display the following acknowledgement:
.\"        This product includes software developed by the NetBSD
.\"        Foundation, Inc. and its contributors.
.\" 4. Neither the name of The NetBSD Foundation nor the names of its
.\"    contributors may be used to endorse or promote products derived
.\"    from this software without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
.\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
.\" POSSIBILITY OF SUCH DAMAGE.
.\"
Installation of
.Nx*M
is now easier than ever!
For the latest news, problem reports, and discussion, join
the port-\*M mailing list by mailing a line saying
.Pp
.Dl subscribe port-\*M
.Pp
to
.Mt majordomo@netsbd.org .
Also, see
.Lk http://www.netbsd.org
for more information.
.Pp
If you encounter any problems, please report them via the mailing list or the
.Xr send-pr 1
program so that they can be fixed for the next release.
.Pp
To install or upgrade
.Nx ,
you need to first boot an installation
program and then interact with the screen-menu program
.Ic sysinst .
The installation program actually consists of the
.Nx
kernel plus an in-memory file system of utility programs.
.Pp
The usual procedure is to write the installation system to a floppy
disk set and then boot from the floppies, however, there
are now six ways to boot the
.Nx*M
installation system! Each approach
loads the exact same installation bits.
The six paths are:
.Pp
.
.(bullet -offset indent
Floppy disk boot
.It
CD boot
.It
Hard Drive Boot
.It
Magnetic Tape Boot
.It
Existing Root FS Boot
.It
Network boot
.bullet)
.
.Pp
In all cases, you need to transfer a
bootable image of the installation system
from the
.Nx
CD or from an ftp site to the chosen media type.
Although booting from floppy is the usual path, the
hard drive boot is useful if you have another operating system (and a spare
drive) already installed, or if you don't mind swapping hard drives from
box to box. CD and tape boots are nice and fast if you have a CD writer
or a tape format in common with another previously installed
.Ul
system. Finally, most versions of SRM can locate the
.Nx
boot program
.Ic netboot
via bootp and download it via tftp,
.Ic netboot
then mounts the root file system
.Pq Pa /
via NFS and loads the kernel.
.Pp
Note that if you are installing or upgrading from a writable media,
the media can be write-protected if you wish.
These systems mount a root image from inside the kernel, and will not
need to write to the media.
If you booted from a floppy, the floppy disk may be removed from
the drive after the system has booted.
.Pp
.
.(bullet
Floppy disk boot
.Pp
The 3.5", 1.44 MB boot floppy set is found under the
.Nx*M
\*V distribution directory in
.Pa \*M/installation/floppy/
as two files called
.Pa disk1of2
and
.Pa disk2of2 .
You need to put these two disk images on two floppy disks.
.Pp
If you have a
.Ul
system handy, you can do this with commands
like the following:
.Pp
.Dl # Ic "dd if=disk1of2 of=/dev/rfd0a bs=18k"
.Dl # Ic "dd if=disk2of2 of=/dev/rfd0a bs=18k"
.Pp
If the
.Ul
system you are using is not a
.Nx
system, you will probably need to replace
.Li /dev/rfd0a
with the name of the floppy device on your particular system.
.Pp
If you have an
.Tn MS-DOS
or
.Tn Windows
system available, you can use
the
.Ic rawrite.exe
utility to transfer the image to a floppy
disk. This utility is provided with the
.Nx Ns /i386
install tools, under
.Pa i386/installation/misc ;
a documentation file,
.Ic rawrite.doc
is available there as well.
.Pp
Once the floppy has been made, you simply need to put it in the
drive and type
.Pp
.Dl \*>\*>\*> Ic "B DVA0"
.Pp
.It
CD boot
.It
Hard Drive boot
.It
Magnetic Tape Boot
.Pp
All three of these media types use the same initial image:
.Pa \&.../installation/diskimage/cdhdtape
The image can be written to a hard drive partition with a command
like:
.Pp
.Dl # Ic "dd if=cdhdtape bs=16k of=/dev/rsd0c"
.Pp
To boot from a magnetic tape device such as
.Tn DAT
or
.Tn DLT ,
it is important
to create the tape image with 512-byte records. Use a command like:
.Pp
.Dl # Ic "dd if=cdhdtape bs=512 of=/dev/rst0"
.Pp
If the host system is not
.Nx ,
the names of the destination devices are likely to be different.
Be sure to use a
.Dq raw partition
device that doesn't skip over labels!
.Pp
The use of CD-R devices varies greatly depending on the host OS
and host software; it isn't possible to give typical instructions here.
.Pp
.It
Existing Root FS Boot
.Pp
The installation subdirectory
.Pa instkernel/
contains
.Pa netbsd.gz ;
this is the same install kernel but without a bootable file system
image wrapped around it. You can perform an complete reinstall
by beginning it as an upgrade, and booting this kernel in the
normal way off the root file system
.Pq Pa /
of a previous installation.
.Pp
The gzipped image can be booted directly; it is not necessary to
uncompress it first.
.Pp
.It
Network Boot
.Pp
Booting
.Nx*M
\*V over a network requires a BOOTP or
DHCP server, a TFTP server and an NFS server. (These are usually
all run on the same machine.) There are three basic stages to
the boot:
.Pp
.
.
.(bullet
\*M console software sends a BOOTP request to get its
own address, the address of the TFTP server and the file to
download. It downloads this file, which is the second stage
bootstrap, via TFTP and then executes it.
.It
The secondary boot program resends the BOOTP request, this
time also locating the NFS server and root path. It mounts the
root path via NFS and reads in and transfers to the kernel:
.Pa /netbsd .
.It
The kernel probes and configures the devices, and then sends
out another BOOTP request so it can find out its address, the NFS
server, and path. It then mounts its root
.Pq Pa /
via NFS and continues.
.bullet)
.
.Pp
You will need to set up servers for BOOTP, TFTP and NFS.
.Pp
If you want to run a full system
from the network, untar the
.Nx
snapshot or distribution
into a directory on your server and NFS export that directory
to the client. Make sure you put a kernel there as well, and
create the device nodes in
.Pa /dev
with
.Ic sh ./MAKEDEV all .
Detailed instructions on netbooting can be found by visiting the
.Nx
\*M platform page:
.Lk http://www.netbsd.org/Ports/\*M
.Pp
At the time of this
release, the URL for the netbooting instructions is:
.Lk http://www.netbsd.org/Documentation/network/netboot/
.Pp
You'll want to map root to
.Li root
(rather than the default
.Li nobody )
when you export your root file system
.Pq Pa / .
A typical
.Pa /etc/exports
line on a
.Nx
system would be:
.Pp
.Dl /usr/export/\*M -maproot=0 myclient.mydom.com
.Pp
One option is to load just the install kernel over the network but then
proceed to a normal disk-based install and disk-based operation.
(Perhaps the \*M doesn't have a floppy drive, or you just don't
want to use a
.Tn Windows
system to make the floppy; we understand.)
.Pp
For this case, you still need to export an NFS root, but
the only thing it needs to have in it is the
.Li instkernel
image from the distribution.
.Pp
The gzipped image can be booted directly; it is not necessary to
uncompress it first.
.Pp
The console will be using TFTP to load the
.Nx
boot program,
so for the TFTP setup, you need to copy the second stage bootstrap,
.Ic netboot ,
into an appropriately named file such as
.Li boot.netbsd.\*M
in the directory used by your TFTP server. If you extracted a full
snapshot, you can get the netboot program from
.Pa /usr/mdec/netboot ;
if not, you can get this from the
.Pa installation/netboot
directory where you found the \*M distribution.
.Pp
For the BOOTP server you need to specify the:
.
.(bullet -compact -offset indent
hardware type (Ethernet)
.It
hardware address (Ethernet MAC address)
.It
IP address of the client
.It
subnet mask of the client
.It
address of of the TFTP/NFS server
.It
name of the second stage bootstrap loaded via TFTP
.It
path to the root for the client (mounted via NFS)
.bullet)
.
.Pp
Here's an example for a
.Ul
system running
.Ic bootpd :
.(disp
myhost.mydom.com:\
	 :ht=ethernet:ha=0000c0391ae4:\e
	 :ip=192.168.1.2:sm=255.255.255.0:\e
	 :sa=192.168.1.1:bf=boot.netbsd.\*M:rp=/usr/export/\*M:
.disp)
.Pp
And here's an example for a
.Ul
system running the ISC
.Ic dhcpd :
.(disp
host axp {
	hardware ethernet 0:0:c0:39:1a:e4;
	fixed-address 192.168.1.2;
	option host-name "myhost.mydom.com";
	filename "boot.netbsd.\*M";
	option root-path "/usr/export/\*M";
	option domain-name-servers 192.168.1.1;
	option broadcast-address 255.255.255.0;
	option domain-name "my.domain";
}
.disp)
.Pp
The only Ethernet device the console on most \*M systems
knows how to boot from is the onboard Ethernet interface or a
.Tn DEC
Tulip (21040, 21041, 21140) PCI Ethernet card. Some
older SMC 100 Mbps cards that use this chip have been known to
work as well. Many older systems will not be able to use the
newer 2.0 stepping of the 21140, however. If your system appears
not to be receiving packets, this may be the problem. (You may
or may not be able to update your firmware to fix this; see
the \*M port pages on www.netbsd.org for more information on
this.) In general, 10 Mb cards from manufacturers other than
.Tn DEC
will work, and 100 Mb cards not from
.Tn DEC
will not.
.Pp
Once you're set up, you should be able to boot with:
.Pp
.Dl \*>\*>\*> Ic "boot -proto bootp ewa0"
.Pp
You should permanently set your protocol to
.Tn BOOTP
with:
.Pp
.Dl \*>\*>\*> Ic "set ewa0_protocols bootp"
.Pp
The 3000 series of Turbochannel systems and certain other models use
.Em old SRM ,
do not have a
.Fl proto
option and use different device names. They also tend to not netboot very
well so you probably don't need to worry about this section. However, if you
want to give it a try, note the following differences:
.(bullet -offset indent
There is no
.Fl proto
argument, or
.Ic ewa0_protocols
variable. Old SRM uses bootp if the device name is given as
.Sy ez0 .
.It
The use of the
.Xr setnetbootinfo 8
program will probably also be necessary, as it is unlikely that an SRM
from that era will properly communicate the ethernet HW address to the
boot program.
.It
Example:
.Pp
.Dl \*>\*>\*> Ic "boot ez0"
.bullet)
.bullet)
.
.
.Pp
.so ../common/sysinst
.
.Ss2 Manual and script-assisted installation
.
All of the installation procedures consist of
putting a label on the disk to provide information on
the sizes and placement of the partitions into which the disk
is divided, putting the boot blocks on the disk, creating the
file systems on the partitions, and unpacking the distribution
tar archives.
.
.
.(enum
Disk prep: label, boot block, and file system setup
.
.
.(tag "AA."
.It "A."
Manual Install from the Shell Prompt
.Pp
The normal installation involves running the install shell script
and interactively configuring the file systems, and then simply
unpacking the tar files into these followed by running MAKEDEV.
.Pp
However, as stated above it is also possible to do the installation yourself
from the shell, and in any case it is helpful to understand
what the install script does. The procedure is:
.Pp
.
.
.(bullet -compact
create
.Pa /etc/disktab ,
see
.Xr disktab 5
.It
run
.Xr disklabel 8 ,
.It
run
.Xr newfs 8
.It
.Xr mount 8
the new root on
.Pa /mnt
.It
cd to
.Pa /usr/mdec
and run
.Xr installboot 8
.bullet)
.
.Pp
If you are reviewing man pages on
.Nx
platforms other than \*M, be sure that when reading
.Xr installboot 8
you read the \*M version by typing:
.Pp
.Dl # Ic man 8 \*M/installboot
.Pp
At this point you need only unpack the distribution sets by running
.Xr tar 1
as described below.
.It B.
.Pa /install
and
.Pa /upgrade
traditional installation scripts
.Pp
The
.Pa install
and
.Pa upgrade
scripts are still there, so by exiting the sysinst program you can type
.Li install
or
.Li upgrade
at the shell prompt and run them as you did in the good old days.
.Pp
You may install
on either a SCSI or an IDE disk; you will be prompted for
the disk to install on. The disks in your system will be numbered
starting at
.Em x Ns Li d0
(where
.Em x
is an
.Sq Li s
for SCSI disks,
.Sq Li w
for IDE disks) based on the SCSI-ID or IDE drive order; if you have
more than one disk, watch the boot messages carefully to see
which ones are probed as which numbers.
.Pp
Once you've selected a disk to install on, you'll be prompted
for the geometry. This is also displayed in the boot messages,
and you'll be given a chance to review the boot messages again
to get the exact figures for the number of cylinders, heads
and sectors.
.Pp
After this you must specify the size of your partitions.
Generally you'll be giving the sizes in cylinders; the install
program will tell you how many bytes there are in each cylinder.
.Pp
The swap partition is the second thing you specify, after the
.Pa /
(root) partition. Regardless of the size of your disk, you'll
want to specify a swap partition that's at least as large as
the amount of RAM you have, and probably not less than 64 MB
in any case.
.Pp
If you have a small disk (under 500 MB), it's probably best to
devote all of the disk (excepting 64 MB or more for the swap)
to the
.Pa /
(root) partition.
.Pp
If you have more space, we recommend devoting at least 32 MB,
and preferably 48 MB, to the
.Pa /
(root) partition.
.Pa /usr
will need 150 MB or so if you're not installing X, 200 MB or so if you
are. A typical organization is 50 MB for
.Pa /
(root), 150-250 MB for
swap, and the remaining space for
.Pa /usr .
With enough swap space configured, you can make
.Pa /tmp
a nice, fast mfs. See
.Xr mount_mfs 8 ,
and note that the mfs will require swap space for
the largest planned amount of
.Pa /tmp
storage. It doesn't return
space when files are deleted, but just keeps it its own freelist
so the swap space required is equal to the highwater mark of
.Pa /tmp
use, plus space required to back up main memory and store inactive images.
.Pp
Once you've specified this information, the install script will
write the disklabel, install boot blocks to make the disk
bootable, initialise the file systems, and mount them all under
.Pa /mnt .
You are now ready to go on to the next step.
.
.tag)
.
.
.It
Configuration: arranging access to the distribution sets
.Pp
After doing the disk and file system setup with either
shell commands or the script assist, you then need only
unpack the distribution sets with the
.Xr tar 1
command.
To do this you will need access from the target host
to the tar files
that contain the operating system in order to extract them to your
disk. This is done via an NFS or FTP transfer over a network,
via a CD-ROM archive, a tape archive, or by preloading an accessible hard
drive with the necesary tar files.
.
.
.(bullet
Preparing to Install from a CD-ROM
.Pp
All you need to do is mount the CD-ROM, which will generally
be device cd0. (The initial boot messages will tell you what
the CD-ROM drive is probed as.) This would be done with:
.Pp
.Dl # Ic "mount -r -t cd9660 /dev/cd0a /mnt2"
.It
Preparing to Install from the Network
.Pp
The first thing you need to do is configure the loopback network
interface, which is done with the command
.Pp
.Dl # Ic "ifconfig lo0 127.0.0.1"
.Pp
Then you will have to configure your Ethernet card. The command
.Pp
.Dl # Ic "ifconfig -l"
.Pp
will give you a list of the network interfaces on your system.
It will show you your ethernet cards first, followed by lo0
(the loopback interface that we configured above), ppp0 (the
PPP interface) and sl0 (the SLIP interface).
.Pp
To configure your ethernet card, type
.Ic ifconfig Ar if Li inet
.Ar addr
.Op Li netmask
.Op Li media Ar media
where
.Ar if
is the network card (interface), almost always
.Li de0 ,
.Ar addr
is the IP address, the optional
.Ar netmask
parameter is the network mask,
and the optional
.Ar media
parameter is one of:
.
.
.Bl -column "10baseT/UTPxx" "T4 twisted pair interfacexx" "100 Mbpsxxxx" \
  -offset indent
.It 10base2 Ta BNC connector Ta 10 Mbps
.It AUI Ta AUI connector Ta 10 Mbps
.It 10baseT/UTP Ta Twisted pair connector Ta 10 Mbps
.It 100baseTX Ta Twisted pair connector Ta 100 Mbps
.It 100baseFX Ta Fibre-optic connector Ta 100 Mbps
.It 100baseT4 Ta T4 twisted pair interface Ta 100 Mbps
.El
.
.
.Pp
If the host you are getting the data files from is not on the
local network, you will also have to configure a gateway into
your system. Do this with
.Pp
.Dl # Ic "route add default \*<gateway-IP-address\*>"
.Pp
One improvement over the good old days is that the resolver is now
present; by configuring
.Pa /etc/resolv.conf
you can get name resolution during any install NFS or FTP operations.
.Pp
Once networking has been configured, you may mount the directory
with the install files via NFS, or download them via FTP.
.Pp
To mount them via nfs, type
.Pp
.Dl # Ic "mount -t nfs \*<hostname:/path/to/nfs/volume\*> /mnt2"
.Pp
If this volume has been exported read-only, you may need the
.Fl r
option to mount.
.Pp
To download the install sets with ftp, create a directory in
which to put them and then use the ftp client to download them.
Mirror sites are listed at:
.Lk http://www.netbsd.org/Sites/net.html
A typical session might be:
.Pp
.Dl # Ic mkdir /mnt/usr/release
.Dl # Ic cd /mnt/usr/release
.Dl # Ic ftp ftp.netbsd.org
.D1 Em "the following commands are given to the" Ic ftp Em "program after logging in"
.Dl ftp> Ic "prompt"
.Dl ftp> Ic "cd /pub/NetBSD/NetBSD-\*V/\*M/binary/sets"
.Dl ftp> Ic "mget *"
.Dl ftp> Ic "quit"
.Pp
Feel free, of course, to leave off the sets that you don't need
if you don't plan to install everything.
.
.bullet)
.
.It
Unpack distribution sets: Extracting the Operating System Files
.
.Pp
Change to the root directory of your hard
drive (which is
.Pa /mnt
if you've used the standard install script
to this point) by typing
.Pp
.Dl # Ic "cd /mnt"
.Pp
For this and the following commands, replace
.Pa /mnt/usr/release/
with the path to your NFS volume or CD-ROM if that's how you
chose to access your install files instead.
.Pp
The sets and kernel are extracted with:
.Pp
.Dl # Ic "cd /mnt"
.Dl # Ic "for i in base kern comp etc games man misc text; do"
.Dl   Ic "\ \ \ \ tar -zxpf /mnt/usr/release/$i.tgz;"
.Dl # Ic "done"
.Pp
or perhaps:
.Pp
.Dl # Ic "cd /mnt"
.Dl # Ic "for i in /mnt/usr/release/*.tgz; do"
.Dl   Ic "\ \ \ \ echo $i"
.Dl   Ic "\ \ \ \ tar -zxpf $i"
.Dl # Ic "done"
.Pp
Now make the device nodes:
.Pp
.Dl # Ic "cd /mnt/dev"
.Dl # Ic "sh ./MAKEDEV all"
.It
Restart your system
.Pp
Unmount the file systems and halt. The exact instructions to
type here will depend on the file systems you created, but
typically the commands are:
.Pp
.Dl # Ic "cd /"
.Dl # Ic "umount /mnt/usr"
.Dl # Ic "umount /mnt"
.Dl # Ic "sync"
.D1 Pq Ic sync Em "is not strictly necessary but it is traditional"
.Dl # Ic "halt"
.Pp
You should now be at the SRM console's
.Li \*>\*>\*>
prompt and can reboot
into the new configuration (possibly after an optional power cycle)
with a command such as:
.Pp
.Dl \*>\*>\*> Ic "boot dka0"
.Pp
This command might be:
.Ic "boot dka100"
if your drive is on ID 1.
You can usually use
.Ic "show device"
to see a full list of bootable
devices in your system. Your system will come up in single-user
mode, ready for you to configure it.
.
.enum)
.
.
.Pp
You can create the floppy needed for installation
under
.Tn MS-DOS
or
.Tn Windows .
Supposing your 1.44 MB floppy
drive is drive A:, and your CD is drive
.Ic E: ,
do the following from an
.Tn MS-DOS
command prompt:
.Pp
.Dl Ic "e:\&"
.Dl Ic "cd \eNetBSD-\*V\einstallation\emisc"
.Dl Ic "rawrite"
.Pp
When asked for a source filename, answer
.Pp
.Dl "\&...\efloppy\edisk1of2
.Pp
When asked for a destination drive answer
.Pp
.Dl \&a
.Pp
(Repeat the procedure for
.Pa installation/floppy/disk2of2 . )