1.\" Copyright (c) 1994 Gordon W. Ross, Theo de Raadt 2.\" Updated by Luigi Rizzo 3.\" All rights reserved. 4.\" 5.\" Redistribution and use in source and binary forms, with or without 6.\" modification, are permitted provided that the following conditions 7.\" are met: 8.\" 1. Redistributions of source code must retain the above copyright 9.\" notice, this list of conditions and the following disclaimer. 10.\" 2. Redistributions in binary form must reproduce the above copyright 11.\" notice, this list of conditions and the following disclaimer in the 12.\" documentation and/or other materials provided with the distribution. 13.\" 3. The name of the author may not be used to endorse or promote products 14.\" derived from this software without specific prior written permission. 15.\" 16.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR 17.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 18.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 19.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, 20.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 21.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 22.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 23.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 24.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF 25.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 26.\" 27.\" $FreeBSD$ 28.\" 29.Dd April 18, 2001 30.Dt DISKLESS 8 31.Os 32.Sh NAME 33.Nm diskless 34.Nd booting a system over the network 35.Sh DESCRIPTION 36The ability to boot a machine over the network is useful for 37.Em diskless 38or 39.Em dataless 40machines, or as a temporary measure while repairing or 41re-installing filesystems on a local disk. 42This file provides a general description of the interactions between 43a client and its server when a client is booting over the network. 44.Sh OPERATION 45When booting a system over the network, there are three 46phases of interaction between client and server: 47.Pp 48.Bl -enum -compact 49.It 50The stage-1 bootstrap loads a boot program, from 51.It 52The boot program loads a kernel. 53.It 54The kernel does NFS mounts for root. 55.El 56.Pp 57Each of these phases are described in further detail below. 58.Pp 59In phase 1, the stage-1 bootstrap code loads a boot program, 60which is typically able to control the network card. 61The boot program can be stored in the BIOS, in a BOOT ROM 62located on the network card (PXE, etherboot, netboot), 63or come from a disk unit (e.g. etherboot or netboot). 64.Pp 65In phase 2, the boot program loads a kernel. Operation in 66this phase depends on the design of the boot program. 67Typically, the boot program uses the 68.Tn BOOTP 69or 70.Tn DHCP 71protocol to get the client's IP address and other boot 72information, including but not limited to 73the IP addresses of the NFS server, router and nameserver, 74and the name of the kernel to load. 75Then the kernel is loaded, either directly using NFS 76(as it is the case for etherboot and netboot), 77or through an intermediate loader called pxeboot and 78loaded using TFTP or NFS. 79.Pp 80In phase 3, the kernel uses again DHCP or BOOTP to acquire 81configuration information, and proceeds to mount the 82root filesystem and start operation. 83Some specific actions performed during the startup 84of a diskless system are listed in 85.Pa /etc/rc.diskless1 86and 87.Pa /etc/rc.diskless2 88.Sh CONFIGURATION 89In order to run a diskless client, you need the following: 90.Bl -bullet 91.It 92an NFS server which exports a root and /usr partition with 93appropriate permissions. 94The 95.Pa rc.diskless{1,2} 96scripts work with readonly partitions, as long as root is exported with 97.Fl maproot Ns =0 98so that some system files can be accessed. 99As an example, 100.Pa /etc/exports 101can contain the following lines: 102.Bd -literal -offset indent 103<ROOT> -maproot=0 -alldirs <list of diskless clients> 104/usr -alldirs <list of diskless clients> 105.Ed 106.Pp 107where 108.Aq ROOT 109is the mountpoint on the server of the root partition. 110The script 111.Pa /usr/share/examples/diskless/clone_root 112can be used to create a shared readonly root partition, 113but in same cases you can also decide to export 114(again as readonly) the root directory used by 115the server itself. 116.It 117a 118.Tn BOOTP 119or 120.Tn DHCP 121server. 122.Xr bootpd 8 123can be enabled by 124uncommenting the 125.Em bootps 126line in 127.Pa /etc/inetd.conf . 128A sample 129.Pa /etc/bootptab 130can be the following: 131.Bd -literal -offset indent 132 .default:\\ 133 hn:ht=1:vm=rfc1048:\\ 134 :sm=255.255.255.0:\\ 135 :sa=<SERVER>:\\ 136 :gw=<GATEWAY>:\\ 137 :rp="<SERVER>:<ROOT>": 138 139<CLIENT>:ha=0123456789ab:tc=.default 140.Ed 141.Pp 142where 143.Aq SERVER , 144.Aq GATEWAY 145and 146.Aq ROOT 147have the obvious meanings. 148.It 149On the root partition, create the directory 150.Pa /conf/default/etc , 151and populate it with a copy of the contents of 152.Pa /etc . 153The files and subdirectories within 154.Pa /conf/default/etc 155are used to bootstrap the diskless environment's 156.Pa /etc 157memory filesystem. 158Be sure and copy the entirety of 159.Pa /etc , 160and not just overrides. 161.It 162Additionally, one may supply per-network or per-host overrides for 163files in 164.Pa /etc 165by creating and populating the directories 166.Pa /conf/${i}/etc , 167where 168.Va i 169can be either the subnet broadcast address for the client, or the IP 170address of the client. 171.Pp 172Files are copied from the above directories into 173.Pa /etc 174(overriding the previous content of 175.Pa /etc ) 176starting from the most generic one by 177.Pa /etc/rc.diskless1 , 178before the main part of 179.Pa /etc/rc 180(including reading 181.Pa rc.conf ) 182is run. 183.Pp 184As a minimum, you normally need to have the following in 185.Pa /conf/default/etc/fstab 186.Bd -literal -offset indent 187<SERVER>:<ROOT> / nfs ro 0 0 188<SERVER>:/usr /usr nfs ro 0 0 189proc /proc procfs rw 0 0 190.Ed 191.Pp 192and also a customized version of 193.Pa /conf/default/etc/rc.conf 194which should contain 195the startup options for the diskless client. 196.Pp 197Most likely 198you will not need to set 199.Va hostname 200and 201.Va ifconfig_* 202because these will be already set by the startup code. 203You will also probably need to set 204.Va local_startup Ns = Ns Qq 205so that the server's 206local startup files will not be used. 207Finally, it might be convenient to use a 208.Ic case 209statement using 210.Li `hostname` 211as the switch variable to do machine-specific configuration 212in case a number of diskless clients share the same configuration 213files. 214.It 215build a kernel whose config file (e.g.\& 216.Pa /sys/i386/conf/DISKLESS ) 217has at least the following options: 218.Bd -literal -offset indent 219options MFS 220options BOOTP 221options BOOTP_NFSROOT 222options BOOTP_COMPAT 223.Ed 224.Pp 225If you use the firewall, remember to default to open or your kernel 226will not be able to send/receive the bootp packets. 227.El 228.Sh SECURITY ISSUES 229Be warned that using unencrypted NFS to mount root and user 230partitions may expose information such as 231encryption keys. 232.Sh BUGS 233This manpage is probably incomplete. 234.Pp 235.Fx 236sometimes requires to write onto 237the root partition, so the startup scripts mount MFS 238filesystems on some locations (e.g.\& 239.Pa /etc 240and 241.Pa /var ) , 242while 243trying to preserve the original content. 244The process might not handle all cases. 245.Sh SEE ALSO 246.Xr ethers 5 , 247.Xr exports 5 , 248.Xr bootpd 8 , 249.Xr mountd 8 , 250.Xr nfsd 8 , 251.Xr pxeboot 8 , 252.Xr reboot 8 , 253.Xr tftpd 8 , 254.Xr ports/net/etherboot 255