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. 66Operation in 67this phase depends on the design of the boot program. 68Typically, the boot program uses the 69.Tn BOOTP 70or 71.Tn DHCP 72protocol to get the client's IP address and other boot 73information, including but not limited to 74the IP addresses of the NFS server, router and nameserver, 75and the name of the kernel to load. 76Then the kernel is loaded, either directly using NFS 77(as it is the case for etherboot and netboot), 78or through an intermediate loader called pxeboot and 79loaded using TFTP or NFS. 80.Pp 81In phase 3, the kernel uses again DHCP or BOOTP to acquire 82configuration information, and proceeds to mount the 83root filesystem and start operation. 84Some specific actions performed during the startup 85of a diskless system are listed in 86.Pa /etc/rc.diskless1 87and 88.Pa /etc/rc.diskless2 89.Sh CONFIGURATION 90In order to run a diskless client, you need the following: 91.Bl -bullet 92.It 93an NFS server which exports a root and /usr partition with 94appropriate permissions. 95The 96.Pa rc.diskless{1,2} 97scripts work with readonly partitions, as long as root is exported with 98.Fl maproot Ns =0 99so that some system files can be accessed. 100As an example, 101.Pa /etc/exports 102can contain the following lines: 103.Bd -literal -offset indent 104<ROOT> -maproot=0 -alldirs <list of diskless clients> 105/usr -alldirs <list of diskless clients> 106.Ed 107.Pp 108where 109.Aq ROOT 110is the mountpoint on the server of the root partition. 111The script 112.Pa /usr/share/examples/diskless/clone_root 113can be used to create a shared readonly root partition, 114but in same cases you can also decide to export 115(again as readonly) the root directory used by 116the server itself. 117.It 118a 119.Tn BOOTP 120or 121.Tn DHCP 122server. 123.Xr bootpd 8 124can be enabled by 125uncommenting the 126.Em bootps 127line in 128.Pa /etc/inetd.conf . 129A sample 130.Pa /etc/bootptab 131can be the following: 132.Bd -literal -offset indent 133 .default:\\ 134 hn:ht=1:vm=rfc1048:\\ 135 :sm=255.255.255.0:\\ 136 :sa=<SERVER>:\\ 137 :gw=<GATEWAY>:\\ 138 :rp="<SERVER>:<ROOT>": 139 140<CLIENT>:ha=0123456789ab:tc=.default 141.Ed 142.Pp 143where 144.Aq SERVER , 145.Aq GATEWAY 146and 147.Aq ROOT 148have the obvious meanings. 149.It 150On the root partition, create the directory 151.Pa /conf/default/etc , 152and populate it with a copy of the contents of 153.Pa /etc . 154The files and subdirectories within 155.Pa /conf/default/etc 156are used to bootstrap the diskless environment's 157.Pa /etc 158memory filesystem. 159Be sure and copy the entirety of 160.Pa /etc , 161and not just overrides. 162.It 163Additionally, one may supply per-network or per-host overrides for 164files in 165.Pa /etc 166by creating and populating the directories 167.Pa /conf/${i}/etc , 168where 169.Va i 170can be either the subnet broadcast address for the client, or the IP 171address of the client. 172.Pp 173Files are copied from the above directories into 174.Pa /etc 175(overriding the previous content of 176.Pa /etc ) 177starting from the most generic one by 178.Pa /etc/rc.diskless1 , 179before the main part of 180.Pa /etc/rc 181(including reading 182.Pa rc.conf ) 183is run. 184.Pp 185As a minimum, you normally need to have the following in 186.Pa /conf/default/etc/fstab 187.Bd -literal -offset indent 188<SERVER>:<ROOT> / nfs ro 0 0 189<SERVER>:/usr /usr nfs ro 0 0 190proc /proc procfs rw 0 0 191.Ed 192.Pp 193and also a customized version of 194.Pa /conf/default/etc/rc.conf 195which should contain 196the startup options for the diskless client. 197.Pp 198Most likely 199you will not need to set 200.Va hostname 201and 202.Va ifconfig_* 203because these will be already set by the startup code. 204You will also probably need to set 205.Va local_startup Ns = Ns Qq 206so that the server's 207local startup files will not be used. 208.Pp 209While an 210.Xr md 4 Ns -backed 211file system is mounted on 212.Pa /var 213by the startup scripts, 214some sites may want to disable the saving of entropy by setting 215.Va entropy_dir Ns = Ns Qq Li NO 216in 217.Pa /etc/defaults/rc.conf . 218.Pp 219Finally, it might be convenient to use a 220.Ic case 221statement using 222.Li `hostname` 223as the switch variable to do machine-specific configuration 224in case a number of diskless clients share the same configuration 225files. 226.It 227build a kernel whose config file (e.g.\& 228.Pa /sys/i386/conf/DISKLESS ) 229has at least the following options and devices: 230.Bd -literal -offset indent 231device md 232options BOOTP 233options BOOTP_NFSROOT 234options BOOTP_COMPAT 235.Ed 236.Pp 237If you use the firewall, remember to default to open or your kernel 238will not be able to send/receive the bootp packets. 239.El 240.Sh SECURITY ISSUES 241Be warned that using unencrypted NFS to mount root and user 242partitions may expose information such as 243encryption keys. 244.Sh BUGS 245This manpage is probably incomplete. 246.Pp 247.Fx 248sometimes requires to write onto 249the root partition, so the startup scripts create and mount 250.Xr md 4 Ns -backed 251filesystems on some locations (e.g.\& 252.Pa /etc 253and 254.Pa /var ) , 255while 256trying to preserve the original content. 257The process might not handle all cases. 258.Sh SEE ALSO 259.Xr md 4 , 260.Xr ethers 5 , 261.Xr exports 5 , 262.Xr bootpd 8 , 263.Xr mountd 8 , 264.Xr nfsd 8 , 265.Xr pxeboot 8 , 266.Xr reboot 8 , 267.Xr tftpd 8 , 268.Xr ports/net/etherboot 269