.\" $NetBSD: netboot,v 1.24 2004/09/10 12:59:03 wiz Exp $ .\" .\" Copyright (c) 1999-2004 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. .\" . .(enum Introduction .Pp To netboot a \*M, you must configure one or more servers to provide information and files to your \*M (the .Sq client ). If you are using .Nx (any architecture) on your netboot server(s), the information provided here should be sufficient to configure everything. Additionally, you may wish to look at the .Xr diskless 8 manual page and the manual pages for each daemon you'll be configuring. If the server(s) are another operating system, you should consult the NetBSD Diskless HOW-TO, which will walk you through the steps necessary to configure the netboot services on a variety of platforms. .Lk http://www.NetBSD.org/Documentation/network/netboot/ .if !\n[hp700]:\n[next68k] \{\ .Pp You may either netboot the installer so you can install onto a locally attached disk, or you may run your system entirely over the network. .\} .Pp .ie \n[evbppc] \{\ Briefly, the netboot process involves discovery, kernel and file system stages. In the first stage, the client discovers information about where to find the kernel image. Once the kernel is loaded, it starts executing. .\} .el \{\ Briefly, the netboot process involves discovery, bootstrap, kernel and file system stages. In the first stage, the client discovers information about where to find the bootstrap program. Next, it downloads and executes the bootstrap program. .ie \n[hp700] \{\ The server contains one large file (a LIF file system) with the bootloader and the kernel. The bootstrap program simply loads the kernel from the LIF image. .\} .el \{\ The bootstrap program goes through another discovery phase to determine where the kernel is located. The bootstrap program tries to mount the NFS share containing the kernel. .\} Once the kernel is loaded, it starts executing. .\} .ie !\n[hp700]:\n[next68k] \{\ For RAM disk kernels, it mounts the RAM disk file system and begins executing the installer from the RAM disk. For normal (non-RAM disk) kernels, the .\} .el The kernel tries to mount the NFS share that had the kernel and starts executing .if !\n[hp700]:\n[next68k] the installation tools or .Xr init 8 . .if \n[hp300] \{\ All supported \*M systems use HP's proprietary RMP (the .Xr rbootd 8 daemon) for the first discovery stage and bootstrap download stages. The bootstrap program uses DHCP for its discovery stage. .\} .if \n[hp700] \{\ Early \*M systems use HP's proprietary RMP (the .Xr rbootd 8 daemon) for the discovery stage, bootstrap download, and kernel download stages. Later \*M systems use BOOTP for the discovery stage and TFTP for the bootstrap and kernel download. .\} .if \n[evbppc]:\n[macppc]:\n[next68k] \{\ All \*M systems use BOOTP for the discovery stage. .\} .if \n[sparc] \{\ All \*M systems except JavaStations with OpenFirmware PROM use a combination of RARP and BOOTP for the discovery stage. In the past, these systems used RARP and BOOTPARAMS. JavaStations booting from OpenFirmware use DHCP. .\} .if \n[sparc64] \{\ All \*M systems use a combination of RARP and DHCP for the discovery stage. .\} .if !\n[hp300]:\n[hp700] \{\ TFTP is used in the bootstrap phase to download .if \n[macppc] \{\ the bootstrap program, .Pa ofwboot.xcf . .\} .if \n[next68k] \{\ the bootstrap program, .Pa boot . .\} .if \n[sparc] \{\ the bootstrap program, .Pa boot.net , which has been linked to a file name appropriate to the client's architecture and IP address as described in the TFTP section below. JavaStations with OpenFirmware need a special bootstrap program, .Pa bootjs.net , which is a version of boot.net in ELF format. It is not linked to the IP address. .\} .if \n[sparc64] \{\ the bootstrap program, .Pa ofwboot.net , which has been linked to a file name appropriate to the client's IP address as described in the TFTP section below. .\} .if \n[evbppc] \{\ the kernel via the on-board Ethernet card by the firmware. Thus, .Nx support for the on-board card is not needed in this step. For NFS mounting a file system on the other hand, .Nx support for the Ethernet card is needed, and the on-board one will not suffice; you have to provide a second Ethernet card supported by .Nx "" . .\} .\} \" ! !\n[hp300]:\n[hp700] .if !\n[evbppc]:\n[hp700] \{\ NFS is used in both the kernel and file system stages to download the kernel, and to access files on the file server. .\} \" !\n[evbppc] .Pp We will use .Sq Li "CC:CC:CC:CC:CC:CC" as the MAC address (ethernet hardware address) of your netboot client machine. You should have determined this address in an earlier stage. In this example, we will use .Sq Li 192.168.1.10 as the IP address of your client and .Sq Li client.test.net as its name. We will assume you're providing all of your netboot services on one machine called .Sq Li server.test.net with the client's files exported from the directory .Pa /export/client/root . You should, of course, replace all of these with the names, addresses, and paths appropriate to your environment. .Pp You should set up each netboot stage in order (i.e. discovery, bootstrap, kernel, and then file system) so that you can test them as you proceed. .if \n[hp700] \{\ .Pp If your system uses RMP to netboot, you must set up .Xr rbootd 8 but can skip .Xr dhcpd 8 and .Xr tftpd 8 . If your system uses BOOTP to netboot, then you must set up .Xr dhcpd 8 and .Xr tftpd 8 but can skip .Xr rbootd 8 . .\} .Pp .It .if \n[hp300]:\n[hp700] \{\ .Xr rbootd 8 .Pp Get .if \n[hp300] .Pa SYS_UBOOT .if \n[hp700] .Pa SYSNBSD from the .Pa installation/misc directory of the distribution. .Pp .(disp .No # Ic "mkdir -p /usr/mdec/rbootd" .if \n[hp300] .No # Ic "cp SYS_UBOOT /usr/mdec/rbootd" .if \n[hp700] .No # Ic "cp SYSNBSD /usr/mdec/rbootd" .No # Ic "chmod -R a+rX /usr/mdec/rbootd" .disp) .Pp Create .Pa /etc/rbootd.conf with the following line: .(disp .if \n[hp300] CC:CC:CC:CC:CC:CC SYS_UBOOT .if \n[hp700] CC:CC:CC:CC:CC:CC SYSNBSD .disp) .Pp You will need to start the .Ic rbootd . If it's already running, you will need to restart it to force it to re-read its configuration file. If the server is running .Nx , you can achieve this with: .Pp .(disp .No # Ic "/etc/rc.d/rbootd restart" .disp) .Pp .It .\} \" ! \n[hp300]:\n[hp700] .if \n[evbppc]:\n[hp300]:\n[hp700]:\n[macppc]:\n[next68k]:\n[sparc]:\n[sparc64] \{\ .ie !\n[hp300] \{\ .Xr dhcpd 8 in .Xr bootpd 8 compatible mode .Pp .\} .el \{\ .Xr dhcpd 8 .Pp The bootstrap program uses DHCP to discover the location of the kernel. .\} Put the following lines in your .Pa /etc/dhcpd.conf (see .Xr dhcpd.conf 5 and .Xr dhcp-options 5 for more information): .(disp ddns-update-style none; # Do not use any dynamic DNS features # allow bootp; # Allow bootp requests, thus the dhcp server # will act as a bootp server. # authoritative; # master DHCP server for this subnet # subnet 192.168.1.0 netmask 255.255.255.0 { # Which network interface to listen on. # The zeros indicate the range of addresses # that are allowed to connect. } group { # Set of parameters common to all clients # in this "group". # option broadcast-address 192.168.1.255; option domain-name "test.net"; option domain-name-servers dns.test.net; option routers router.test.net; option subnet-mask 255.255.255.0; # # An individual client. # host client.test.net { hardware ethernet CC:CC:CC:CC:CC:CC; fixed-address 192.168.1.10; # # Name of the host (if the fixed address # doesn't resolve to a simple name). # option host-name "client"; .if !\n[hp300] \{\ .if \n[evbppc] \{\ # # Name of the kernel image to download via tftp. # Note: Plain (ELF) kernels won't work, you # have to use the corresponding *.img file. # filename "netbsd-INSTALL_WALNUT.img" .\} # # Name of the bootloader or kernel # to download via tftp. .if \n[sparc] \{\ # # Only needed for JavaStations with OpenFirmware! # filename "bootjs.net"; .\} .if \n[hp700] \{\ # filename "SYSNBSD"; .\} .ie \n[macppc] \{\ # filename "ofwboot.xcf"; .\} .el \{\ .if \n[next68k] \{\ # filename "boot"; .\} \" \n[next68k] .\} \" \n[macppc] .\} \" !\n[hp300] # # The path on the NFS server. # option root-path "/export/client/root"; .if \n[next68k] \{\ # #next68k machines require non-RFC1048 BOOTP # always-reply-rfc1048 false; .\} # # If your DHCP server is not your NFS server, supply the # address of the NFS server. Since we assume you run everything # on one server, this is not needed. .if \n[macppc] \{\ # # macppc machines will look for their bootloader, # ofwboot.xcf, on the next-server as well. .\} # # next-server server.test.net; } #you may paste another "host" entry here for additional #clients on this network } .disp) .if \n[sparc] \{\ Note that for JavaStations booting from OpenFirmware you do not need the .(disp allow bootp; .disp) statement, since this machines use real DHCP. .\} .Pp You will need to make sure that the .Pa dhcpd.leases file exists. .Pp .(disp .No # Ic "touch /var/db/dhcpd.leases" .disp) .Pp You will need to start the .Ic dhcpd . If it's already running, you will need to restart it to force it to re-read its configuration file. If the server is running .Nx , you can achieve this with: .Pp .(disp .No # Ic "/etc/rc.d/dhcpd restart" .disp) .Pp .\} \" ! \n[evbppc]:\n[hp300]:\n[hp700]:\n[macppc]:\n[next68k]:\n[sparc]:\n[sparc64] .if \n[sparc]:\n[sparc64] \{\ .Pp .It .Xr rarpd 8 .Pp .if \n[sparc] \{\ Note: no .Nm rarpd is needed to boot OpenFirmware based JavaStations. .Pp .\} Create an .Pa /etc/ethers file with the following line: .Pp .(disp CC:CC:CC:CC:CC:CC client .disp) .Pp Add your client to the server's .Pa /etc/hosts file: .Pp .(disp 192.168.1.10 client .disp) .Pp You will need to start the .Ic rarpd . If it's already running, you will need to restart it to force it to re-read its configuration file. If the server is running .Nx , you can achieve this with: .Pp .(disp .No # Ic "/etc/rc.d/rarpd restart" .disp) .Pp .\} \" ! \n[sparc]:\n[sparc64] .if !\n[hp300] \{\ .Pp .It .Xr tftpd 8 .Pp The default configuration of the TFTP server is to run in a .Xr chroot 8 environment in the .Pa /tftpboot directory. Thus, the first order of business is to create this directory: .(disp .No # Ic "mkdir -p /tftpboot" .disp) .Pp Next, edit .Pa /etc/inetd.conf and uncomment the line with the TFTP daemon: .(disp tftp dgram udp wait root /usr/libexec/tftpd tftpd -l -s /tftpboot .disp) .Pp Now, restart .Xr inetd 8 . If the server is running .Nx , you can achieve this with: .Pp .(disp .No # Ic "/etc/rc.d/inetd restart" .disp) .Pp Now, you need to copy the .ie \n[evbppc] kernel .el bootloader for your \*M machine to .Pa /tftpboot . .if \n[hp700] \{\ Get .Pa SYSNBSD from the .Pa installation directory of the distribution. .(disp .No # Ic "cp SYSNBSD /tftpboot" .disp) .\} .if \n[macppc] \{\ Get .Xr ofwboot.xcf 8 from the .Pa installation directory of the distribution. .(disp .No # Ic "cp ofwboot.xcf /tftpboot" .disp) .\} .if \n[next68k] \{\ Get .Pa boot from the .Pa installation directory of the distribution. .(disp .No # Ic "cp boot /tftpboot" .disp) .\} .if \n[sparc]:\n[sparc64] \{\ Get .if \n[sparc] .Pa boot.net .if \n[sparc64] .Pa ofwboot.net from the .Pa installation/netboot directory of the distribution. .(disp .if \n[sparc] .No # Ic "cp boot.net /tftpboot" .if \n[sparc64] .No # Ic "cp ofwboot.net /tftpboot" .disp) .Pp Now, you need to link .if \n[sparc] .Pa boot.net .if \n[sparc64] .Pa ofwboot.net to the filename that your \*M will look for. It will look for a filename composed of the machine's IP address .if \n[sparc] \{\ (in hexadecimal) followed by the machine's architecture, separated by a period. For example, a sun4c machine which has been assigned IP address 192.168.1.10, will make a TFTP request for .Pa C0A8010A.SUN4C . .\} .if \n[sparc64] \{\ (in hexadecimal). For example, a machine which has been assigned IP address 192.168.1.10, will make a TFTP request for .Pa C0A8010A . .\} .Pp You can use .Xr bc 1 to help calculate the filename: .(disp .No # Ic bc .Ic obase=16 .Ic 192 C0 .Ic 168 A8 .Ic 1 1 .Ic 10 A .Ic quit .No # Ic "cd /tftpboot" .if \n[sparc] .No # Ic "ln -s boot.net C0A8010A.SUN4C" .if \n[sparc64] .No # Ic "ln -s ofwboot.net C0A8010A" .disp) .Pp .\} \" \n[sparc]:\n[sparc64] .if \n[sparc] \{\ For OpenFirmware based JavaStations you use the file .Pa bootjs.net and do not create a symlink for the IP address. This machines do full DHCP autoconfiguration, so the bootstrap filename is provided by the DHCP server. .Pp .\} Just to be sure, let's make everything readable. .(disp .No # Ic "chmod -R a+rX /tftpboot" .disp) .Pp Sometimes, the .Xr arp 8 table gets messed up, and the TFTP server can't communicate with the client. In this case, it will write a log message (via .Xr syslogd 8 ) to .Pa /var/log/messages saying: .Sq Li "tftpd: write: Host is down" . If this is the case, you may need to force the server to map your client's ethernet address to its IP address: .(disp .No # Ic "arp -s client CC:CC:CC:CC:CC:CC" .disp) .\} \" ! !\n[hp300] .Pp .It .Xr nfsd 8 , .Xr mountd 8 , and .Xr rpcbind 8 .ie !\n[evbppc] \{\ .Pp Now your system should be able to load the bootstrap program and start looking for the kernel. .\} .el \{\ .Pp You can either boot a kernel, or the RAM disk-based installer .Pa binary/kernel/netbsd-INSTALL.img.gz . In the first case you'll also need an NFS-mounted userland. .\} Let's set up the NFS server. Create the directory you are exporting for the netboot client: .Pp .(disp .No # Ic "mkdir -p /export/client/root" .disp) .Pp Put the following line in .Pa /etc/exports to enable NFS sharing: .Pp .(disp .No "/export/client/root -maproot=root client.test.net" .disp) .Pp If your server is currently running an NFS server, you only need to restart .Xr mountd 8 . Otherwise, you need to start .Xr rpcbind 8 and .Xr nfsd 8 . If the server is running .Nx , you can achieve this with: .Pp .(disp .No # Ic "/etc/rc.d/rpcbind start" .No # Ic "/etc/rc.d/nfsd start" .No # Ic "/etc/rc.d/mountd restart" .disp) .Pp .It .Nx kernel .if !\n[next68k]:\n[hp700] and installation tools .Pp .if !\n[evbppc]:\n[hp700] \{\ Now, if you place a kernel named .Pa netbsd in .Pa /export/client/root your client should boot the kernel. .\} \" !\n[evbppc]:\n[hp700] .if \n[hp300] \{\ If you are netbooting the installer, you can use either the traditional miniroot-based installer .Pa installation/miniroot/miniroot.fs.gz or the experimental RAM disk-based installer .Pa binary/kernel/netbsd-RAMDISK.gz . .Pp To use the miniroot-based installer, mount the miniroot file system on your netboot server. This procedure does .Em not work on any operating system other than .Nx . You'll also need to either set up a new NFS share point or an FTP server for the distribution files, as they won't fit inside the miniroot file system. .Pp .(disp .No # Ic "gunzip miniroot.fs.gz" .No # Ic "vnconfig -c /dev/vnd0c /path/to/miniroot.fs" .No # Ic "mount -o ro /dev/vnd0c /export/client/root" .No # Ic "ls /export/client/root" .profile dist/ install.md mnt/ sbin/ usr/ bin/ etc/ install.sub mnt2/ tmp/ var/ dev/ install* kern/ netbsd* upgrade* .disp) .Pp If there are no files present in your exported directory, then something is wrong. .Pp To use the RAM disk-based installer, uncompress and rename the kernel. Also, copy the distribution files to the client's root directory. .Pp .(disp .No # Ic "cp *tgz /export/client/root" .No # Ic "gunzip netbsd-RAMDISK.gz" .No # Ic "mv netbsd-RAMDISK /export/client/root/netbsd" .disp) .Pp If you are running your \*M diskless, simply use .Pa binary/kernel/netbsd-GENERIC.gz . .\} \" \n[hp300] .if \n[hp700] \{\ You do not need to place a kernel in .Pa /export/client/root since the kernel is contained inside .Pa SYSNBSD . .\} .if \n[macppc] \{\ If you are netbooting the installer, use .Pa binary/kernel/netbsd-GENERIC_MD.gz (this has the installation tools in a RAM disk). Also, copy the distribution files to the client's root directory. .Pp .(Note Some combinations of Open Firmware version and .Pa ofwboot.xcf version have trouble loading compressed kernels. If you have trouble loading a kernel, try uncompressing it with .Xr gunzip 1 .Note) .Pp .(disp .No # Ic "cp *tgz /export/client/root" .No # Ic "gunzip netbsd-GENERIC_MD.gz" .No # Ic "mv netbsd-GENERIC_MD /export/client/root/netbsd" .disp) .Pp If you are running your \*M diskless, simply use .Pa binary/kernel/netbsd-GENERIC.gz . .\} .if \n[next68k] \{\ Use .Pa binary/kernel/netbsd-GENERIC.gz . .Pp .(disp .No # Ic "gunzip netbsd-GENERIC.gz" .No # Ic "mv netbsd-GENERIC /export/client/root/netbsd" .disp) .\} .if \n[sparc]:\n[sparc64] \{\ Use .Pa binary/kernel/netbsd-GENERIC.gz ) . .Pp .(disp .No # Ic "gunzip netbsd-GENERIC.gz" .No # Ic "mv netbsd-GENERIC /export/client/root/netbsd" .disp) .Pp If you are netbooting the installer, copy the distribution files to the client's root directory and extract the tools from .if \n[sparc] .Pa installation/netboot/rootfs.tgz . .if \n[sparc64] .Pa installation/misc/instfs.tgz . .Pp .(disp .No # Ic "cp *tgz /export/client/root" .No # Ic "cd /export/client/root" .if \n[sparc] .No # Ic "tar -xpzf rootfs.tgz" .if \n[sparc64] .No # Ic "tar -xpzf instfs.tgz" .disp) .\} .if \n[evbppc] \{\ If you are netbooting the installer, use .Pa binary/kernel/netbsd-INSTALL_WALNUT.img.gz (this has the installation tools in a RAM disk). Also, copy the distribution files to the client's root directory. .Pp .(disp .No # Ic "cp *tgz /export/client/root" .No # Ic "gunzip netbsd-INSTALL.img.gz" .No # Ic "mv netbsd-INSTALL.img /export/client/root/netbsd" .disp) .Pp If you are running your \*M diskless, simply use .Pa binary/kernel/netbsd.img-WALNUT.gz . .\} .It Client file system .Pp .ie !\n[hp700]:\n[next68k] \{\ You can skip this step if you do not plan to run your client diskless after installation. Otherwise, you .\} .el You need to extract and set up the client's installation of .Nx . The Diskless HOW-TO describes how to provide better security and save space on the NFS server over the procedure listed here. .Lk http://www.NetBSD.org/Documentation/network/netboot/nfs.html .(bullet -compact Extracting distribution sets .Pp .(disp .No # Ic "cd /export/client/root" .No # Ic "tar -xpzf /path/to/files/base.tgz" .No # Ic "tar -xpzf /path/to/files/etc.tgz" .disp) .Pp Continue with the other non-essential distribution sets if desired. .Pp .It Set up swap .Pp .(disp .No # Ic "mkdir /export/client/root/swap" .No # Ic "dd if=/dev/zero of=/export/client/swap bs=4k count=4k" .No # Ic "echo '/export/client/swap -maproot=root:wheel client.test.net' | cat \*>\*> /etc/exports" .No # Ic "/etc/rc.d/mountd restart" .disp) This creates a 16 MB swap file and exports it to the client. .Pp .It Create device nodes .Pp .(disp .No # Ic "cd /export/client/root/dev" .No # Ic "./MAKEDEV all" .disp) .Pp This procedure only works on .Nx hosts. .Pp .It Set up the client's .Xr fstab 5 .Pp Create a file in .Pa /export/client/root/etc/fstab with the following lines: .Pp .(disp server:/export/client/swap none swap sw,nfsmntpt=/swap server:/export/client/root / nfs rw 0 0 .disp) .Pp .It Set up the client's .Xr rc.conf 5 .Pp Edit .Pa /export/client/root/etc/rc.conf .(disp rc_configured=YES hostname="client" defaultroute="192.168.1.1" nfs_client=YES auto_ifconfig=NO net_interfaces="" .disp) .Pp Make sure rc does not reconfigure the network device since it will lose its connection to the NFS server with your root file system. .Pp .It Set up the client's .Xr hosts 5 file. .Pp Edit .Pa /export/client/root/etc/hosts .Pp .(disp ::1 localhost 127.0.0.1 localhost 192.168.1.10 client.test.net client 192.168.1.5 server.test.net server .disp) .bullet) .Pp .It Setting up the server daemons .Pp .ie !\n[hp700]:\n[next68k] If you want .el You need these services to start up every time you boot your server, make sure the following lines are present in your .Pa /etc/rc.conf : .(disp .if \n[hp300]:\n[hp700] \{\ rbootd=YES rbootd_flags="" .\} .if \n[hp300]:\n[hp700]:\n[macppc]:\n[next68k]:\n[sparc]:\n[sparc64] \{\ dhcpd=YES dhcpd_flags="-q" .\} .if \n[sparc]:\n[sparc64] \{\ rarpd=YES rarpd_flags="-a" .\} nfs_server=YES # enable server daemons mountd=YES rpcbind=YES rpcbind_flags="-l" # -l logs libwrap .disp) .Pp .if !\n[hp300] \{\ Also, you'll need to make sure the .Pa tftpd line in .Pa /etc/inetd.conf remains uncommented. .\} .enum)