From 2b432f7183d02f03facd741cab32ad8785f324db Mon Sep 17 00:00:00 2001 From: Chern Lee Date: Sat, 13 Oct 2001 01:39:02 +0000 Subject: [PATCH] Completely update the Diskless Operation section. Submitted by: Jean-Francois Dockes --- .../handbook/advanced-networking/chapter.sgml | 686 ++++++++++++------ 1 file changed, 460 insertions(+), 226 deletions(-) diff --git a/en_US.ISO8859-1/books/handbook/advanced-networking/chapter.sgml b/en_US.ISO8859-1/books/handbook/advanced-networking/chapter.sgml index 13d93298fa..15ab572d27 100644 --- a/en_US.ISO8859-1/books/handbook/advanced-networking/chapter.sgml +++ b/en_US.ISO8859-1/books/handbook/advanced-networking/chapter.sgml @@ -1097,256 +1097,490 @@ Exports list on foobar: - Martin - Renters - Contributed by + Jean-François + Dockès + Updated by Diskless Operation diskless workstation - netboot.com/netboot.rom - allow you to boot your FreeBSD machine over the network and run FreeBSD - without having a disk on your client. Under 2.0 it is now possible to - have local swap. Swapping over NFS is also still supported. - Supported Ethernet cards include: Western Digital/SMC 8003, 8013, - 8216 and compatibles; NE1000/NE2000 and compatibles (requires - recompile) + A FreeBSD machine can boot over the network and operate without a + local disk, using file systems mounted from an NFS server. No system + modification is necessary, beyond standard configuration files. + Such a system is easy to set up because all the necessary elements + are readily available: + + + There are at least two possible methods to load the kernel over + the network: + + + PXE: Intel's Preboot Execution + Environment system is a form of smart boot ROM built into some + networking cards or motherboards. See &man.pxeboot.8; for more + details. + + + The etherboot + port (/usr/ports/net/etherboot) + produces ROM-able code to boot kernels over the network. The code + can be either burnt into a boot PROM on a network card, or loaded + from a local floppy (or hard) disk drive, or from a running + MS-DOS system. Many network cards are supported. + + + + + + A sample script + (/usr/local/share/examples/clone_root) eases + the creation and maintenance of the workstation's root filesystem + on the server. The script will probably require a little + customization but it will get you started very quickly + + + + Standard system startup files exist in /etc + to detect and support a diskless system startup. + + + Swapping, if needed, can be done either to an NFS file or to + a local disk + + + + There are many ways to set up diskless workstations. Many + elements are involved, and most can be customized to suit local + taste. The following will describe the setup of a complete system, + emphasising simplicity and compatibility with the + standard FreeBSD startup scripts. The system described has the + following characteristics: + + + + The diskless workstations use a shared + read-only root filesystem, and a shared + read-only /usr. + The root file system is a copy of a + standard FreeBSD root (typically the server's), with some + configuration files overriden by ones specific to diskless + operation or, possibly, to the workstation they belong to. + The parts of the root which have to be + writable are overlayed with &man.mfs.8; filesystems. Any changes + will be lost when the system reboots. + + + The kernel is loaded by etherboot + , using DHCP (or BOOTP) and TFTP. + + + + As described, this system is insecure. It should + live in a protected area of a network, and be untrusted by + other hosts. + + + Setup Instructions - - - - Find a machine that will be your server. This machine will - require enough disk space to hold the FreeBSD 2.0 binaries and - have bootp, tftp and NFS services available. Tested - machines: - - - HP-UX - - HP9000/8xx running HP-UX 9.04 or later (pre 9.04 does not - work) - - Solaris - - Sun/Solaris 2.3. (you may need to get bootp) - - - - - Set up a bootp server to provide the client with IP address, gateway, - netmask. - - diskless:\ - :ht=ether:\ - :ha=0000c01f848a:\ - :sm=255.255.255.0:\ - :hn:\ - :ds=192.1.2.3:\ - :ip=192.1.2.4:\ - :gw=192.1.2.5:\ - :vm=rfc1048: - + + Configuring DHCP/BOOTP - TFTP - bootp - - Set up a TFTP server (on same machine as bootp server) to - provide booting information to client. The name of this file is - cfg.X.X.X.X (or - /tftpboot/cfg.X.X.X.X, - it will try both) where X.X.X.X is the - IP address of the client. The contents of this file can be any - valid netboot commands. Under 2.0, netboot has the following - commands: + There are two protocols that are commonly used to boot a + workstation that retrieves its configuration over the network: BOOTP + and DHCP. They are used at several points in the workstation + bootstrap: + + etherboot uses + DHCP (by default) or BOOTP (needs a configuration option) to + find the kernel. (PXE uses DHCP). + + The kernel uses BOOTP to locate the NFS + root. + + - - - - - help - print help list - - - - ip - - print/set client's IP address - - - - server - - print/set bootp/tftp server address - - - - netmask - - print/set netmask - + It is possible to configure a system to use only BOOTP. + The &man.bootpd.8; server program is included in the + base FreeBSD system. - - hostname name - print/set hostname - - - - kernel - - print/set kernel name - - - - rootfs - - print/set root filesystem - - - - swapfs - - print/set swap filesystem - - - - swapsize - - set diskless swapsize in KBytes - - - - diskboot - boot from disk - - - - autoboot - continue boot process - - - - trans - | - turn transceiver on|off - - - - flags - - set boot flags - - - - - - A typical completely diskless config file might contain: + However, DHCP has a number of advantages over BOOTP (nicer + configuration files, possibility of using PXE, plus many others + not directly related to diskless operation), and we shall describe + both a pure BOOTP, and a BOOTP+DHCP configuration, with an + emphasis on the latter, which will use the ISC DHCP software + package. - rootfs 192.1.2.3:/rootfs/myclient -swapfs 192.1.2.3:/swapfs -swapsize 20000 -hostname myclient.mydomain + + Configuration using ISC DHCP - A config file for a machine with local swap might contain: + The isc-dhcp server can answer + both BOOTP and DHCP requests. - rootfs 192.1.2.3:/rootfs/myclient -hostname myclient.mydomain - + As of release 4.4, isc-dhcp is not part of the base + system. You will first need to install the + /usr/ports/net/isc-dhcp3 port or the + corresponding package. Please refer to + for general information about ports and packages. - - Ensure that your NFS server has exported the root (and swap if - applicable) filesystems to your client, and that the client has - root access to these filesystems A typical - /etc/exports file on FreeBSD might look - like: - - /rootfs/myclient -maproot=0:0 myclient.mydomain -/swapfs -maproot=0:0 myclient.mydomain + Once isc-dhcp is installed, it + needs a configuration file to run, (normally named + /usr/local/etc/dhcpd.conf). Here follows + a commented example: - And on HP-UX: + + default-lease-time 600; + max-lease-time 7200; + authoritative; - /rootfs/myclient -root=myclient.mydomain -/swapfs -root=myclient.mydomain - - - - NFS - swapping over - - - If you are swapping over NFS (completely diskless - configuration) create a swap file for your client using - dd. If your swapfs - command has the arguments /swapfs and - the size 20000 as in the example above, the swapfile for - myclient will be called - /swapfs/swap.X.X.X.X - where X.X.X.X is the client's IP - address, e.g.: - - &prompt.root; dd if=/dev/zero of=/swapfs/swap.192.1.2.4 bs=1k count=20000 - - Also, the client's swap space might contain sensitive - information once swapping starts, so make sure to restrict read - and write access to this file to prevent unauthorized - access: - - &prompt.root; chmod 0600 /swapfs/swap.192.1.2.4 - + option domain-name "mydom.com"; + option domain-name-servers 192.168.4.1; + option routers 192.168.4.1; - - Unpack the root filesystem in the directory the client will - use for its root filesystem (/rootfs/myclient - in the example above). - - - - On HP-UX systems: The server should be running HP-UX 9.04 - or later for HP9000/800 series machines. Prior versions do not - allow the creation of device files over NFS. - + subnet 192.168.4.0 netmask 255.255.255.0 { + use-host-decl-names on; + option subnet-mask 255.255.255.0; + option broadcast-address 192.168.4.255; + + host margaux { + hardware ethernet 01:23:45:67:89:ab; + fixed-address margaux.mydom.com; + next-server 192.168.4.4; + filename "/tftpboot/kernel.diskless"; + option root-path "192.168.4.4:/data/misc/diskless"; + } + } + + + + This option tells + dhcpd to send the value in the + host declarations as the hostname for the + diskless host. An alternate way would be to add an + option host-name + margaux inside the + host declarations. + - - When extracting /dev in - /rootfs/myclient, beware that some - systems (HPUX) will not create device files that FreeBSD is - happy with. You may have to go to single user mode on the - first bootup (press control-c during the bootup phase), cd - /dev and do a sh ./MAKEDEV - all from the client to fix this. - - - + The + next-server directive designates + the TFTP server (the default is to use the same host as the + DHCP server). + + + The + filename directive defines the file that + etherboot will load as a + kernel. + PXE appears to prefer a relative file + name, and it loads pxeboot, not the + kernel (option filename + "pxeboot"). + + + + + The + root-path option defines the path to + the root filesystem, in usual NFS notation + + - - Run netboot.com on the client or make an - EPROM from the netboot.rom file - - - - - - Using Shared <filename>/</filename> and <filename>/usr</filename> - Filesystems + + + Configuration using BOOTP + + Here follows an equivalent bootpd + configuration. This would be found in + /etc/bootptab. + + Please note that etherboot must + be compiled with the non-default option + NO_DHCP_SUPPORT in order to use BOOTP, and that PXE + needs DHCP. The only obvious advantage of + bootpd is that it exists in the base system. + + + .def100:\ + :hn:ht=1:sa=192.168.4.4:vm=rfc1048:\ + :sm=255.255.255.0:\ + :ds=192.168.4.1:\ + :gw=192.168.4.1:\ + :hd="/tftpboot":\ + :bf="/kernel.diskless":\ + :rp="192.168.4.4:/data/misc/diskless": + + margaux:ha=0123456789ab:tc=.def100 + + + + + + Preparing a boot program with + <application>Etherboot</application> + + Etherboot's Web + site contains + + extensive documentation mainly intended for Linux + systems, but nonetheless containing useful information. The following + will just outline how you would use + etherboot on a FreeBSD system. + + You must first install - and possibly compile - the + etherboot package. The + etherboot port can normally be found in + /usr/ports/net/etherboot. If the ports tree is + installed on your system, just typing make in + this directory should take care of everything. Else refer to + for information about ports and + packages. + + For our setup, we shall use a boot floppy. For other methods + (PROM, or dos program), please refer to the + etherboot documentation. + + To make a boot floppy, insert a floppy in the drive on the + machine where you installed etherboot, + then change your current directory to the src + directory in the etherboot tree and + type: + + + &prompt.root; gmake bin32/devicetype.fd0 + + + devicetype depends on the type of + the ethernet card in the diskless workstation. Refer to the + NIC file in the same directory to determine the + right devicetype. + + + + + + Configuring the TFTP and NFS servers + + You need to enable tftpd on the TFTP + server: + + + Create a directory from which tftpd + will serve the files, ie: /tftpboot + + + + Add this line to your + /etc/inetd.conf: + + tftp dgram udp wait nobody /usr/libexec/tftpd tftpd /tftpboot + + It appears that at least some PXE versions wants + the TCP version of TFTP. In this case, add a second line, + replacing dgram udp with stream + tcp + + + + Tell inetd to reread its configuration + file: + &prompt.root; kill -HUP `cat /var/run/inetd.pid` + + + + You can place the tftpboot directory anywhere on the server, but, + of course, the actual location, the value in + inetd.conf, and the value in + dhcpd.conf must be consistent ! + + You also need to enable NFS service and export the + appropriate filesystem on the NFS server + + + + Add this to /etc/rc.conf: + nfs_server_enable="YES" + + + + Export the filesystem where the diskless root directory + is located by adding the following to + /etc/exports (adjust the volume mount + point and workstation name!): + /data/misc -alldirs -ro margaux + + + Tell mountd to reread its configuration + file. If you actually needed to configure NFS service at step + 1, you probably want to reboot instead. + &prompt.root; kill -HUP `cat /var/run/mountd.pid` + + + + + + + Building a diskless kernel + + Create a kernel configuration file for the diskless client + with the following options (in addition to the usual + ones): + + + options BOOTP # Use BOOTP to obtain IP address/hostname + options BOOTP_NFSROOT # NFS mount root filesystem using BOOTP info + options BOOTP_COMPAT # Workaround for broken bootp daemons. + + + You may also want to use BOOTP_NFSV3 and + BOOTP_WIRED_TO (refer to LINT). + + Build the kernel (See ), + and copy it to the tftp directory, under the name listed + in dhcpd.conf + + + + + + Preparing the root filesystem + + You need to create a root filesystem for the diskless + workstations, in the location listed as + root-path in + dhcpd.conf. + + The easiest way to do this is to use the + /usr/share/examples/diskless/clone_root + shell script. This script needs customization, at least to adjust the + place where the filesystem will be created (the + DEST variable). + + Refer to the comments at the top of the script for + instructions. They explain how the base filesystem is built, + and how files may be selectively overriden by versions specific + to diskless operation, to a subnetwork, or to an individual + workstation. They also give examples for the diskless + /etc/fstab and + /etc/rc.conf + + The README files in + /usr/share/examples/diskless contain a lot + of interesting background information, but, together with the + other examples in the diskless directory, + they actually document a configuration method which is distinct + from the one used by clone_root and + /etc/rc.diskless[12], which is a little + confusing. Use them for reference only, except if you prefer + the method that they describe, in which case you will need + customized rc scripts + + As of FreeBSD version 4.4-RELEASE, there is a small + incompatibility between the clone_root + script and the /etc/rc.diskless1 + script. Please refer to PR + + conf/31200 for the small adjustment needed in + clone_root. + Also see PR + conf/29870 + about a small adjustment needed in + /etc/rc.diskless2. + + + + + Configuring swap + + If needed, it is possible to do swapping over NFS, to a file + on the server. The exact bootptab or + dhcpd.conf options are a little mysterious + and poorly documented. Anyway, here is what worked for me, using + isc-dhcp 3.0rc11. + + Add the following lines to + dhcpd.conf: + + # Global section + option swap-path code 128 = string; + option swap-size code 129 = integer 32; + + host margaux { + ... # Standard lines, see above + option swap-path "192.168.4.4:/netswapvolume/netswap"; + option swap-size 64000; + } + + The idea is that, at least for a FreeBSD client, + DHCP/BOOTP option code 128 is the path to the NFS swap file, + and option code 129 is the swap size in kilobytes. Older + versions of dhcpd allowed a syntax of + option option-128 "..., which does not + seem to work any more. + /etc/bootptab would use the + following syntax instead: + T128="192.168.4.4:/netswapvolume/netswap":T129=64000 + + + + + On the NFS swap file server, create the swap + file(s) + + &prompt.root; mkdir /netswapvolume/netswap + &prompt.root; cd /netswapvolume/netswap + &prompt.root; dd if=/dev/zero bs=1024 count=64000 of=swap.192.168.4.6 + &prompt.root; chmod 0600 swap.192.168.4.6 + + 192.168.4.6 is the IP address + for the diskless client + + + + On the NFS swap file server, add the following line to + /etc/exports + + /netswapvolume -maproot=0:10 -alldirs margaux + + Then tell mountd to reread the exports file, as above. + + + + + + + Miscellaneous issues + + + + Running with a read-only <filename>/usr</filename>If the diskless workstation is configured to run X, you + will have to adjust the xdm configuration file, which puts + the error log on /usr by default. + + + Using a non-FreeBSD server + + When the server for the root filesystem is not running FreeBSD, + you will have to create the root file system on a + FreeBSD machine, then copy it to its destination, using + tar or cpio. + In this situation, it seems that there are sometimes + problems with the special files in /dev, + because of differing minor/major number integer sizes. It seems + that a solution to this problem is to run MAKEDEV on a FreeBSD + machine, in a directory mounted through NFS from the final + server. + + + + - Although this is not an officially sanctioned or supported way - of doing this, some people report that it works quite well. If - anyone has any suggestions on how to do this cleanly, please tell - &a.doc;. - - - - Compiling Netboot for Specific Setups - - Netboot can be compiled to support NE1000/2000 cards by changing - the configuration in - /sys/i386/boot/netboot/Makefile. See the - comments at the top of this file.