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, typically PXE built into your ethernet 51card, loads a second-stage boot program. 52.It 53The second-stage boot program, typically 'pxeboot', loads modules and 54the kernel and boots the kernel. 55.It 56The kernel NFS mounts the root directory and continues from there. 57.El 58.Pp 59Each of these phases are described in further detail below. 60.Pp 61First the stage-1 bootstrap loads the stage-2 boot program over 62the network. The stage-1 bootstrap typically uses BOOTP or DHCP 63to obtain the filename to load, then uses TFTP to load the file. 64This file is typically called "pxeboot" and should be copied from 65.Pa /boot/pxeboot 66into the tftp directory on the server, which is typically 67.Pa /tftpdir . 68.Pp 69The stage-2 boot program then loads additional modules and the kernel. 70These files may not exist on the DHCP or BOOTP server. You can use the 71.Sy next-server 72option available in DHCP configurations to specify the server holding 73the second stage boot files and kernel. The stage-2 program uses 74NFS or TFTP to obtain these files. By default, NFS is used. 75If you are using pxeboot you can install a version that uses 76TFTP by setting LOADER_TFTP_SUPPORT=YES 77in your 78.Pa /etc/make.conf , 79then recompiling and reinstalling pxeboot via the command listed below. 80It is often necessary to use TFTP here so you can place a custom kernel 81in /tftpdir/. 82If you use NFS and do not have a custom root filesystem for the diskless 83client, the stage-2 boot will load your server's kernel as the kernel for 84the diskless machine, which may not be what you want to have happen. 85.Bd -literal -offset indent 86cd /usr/src/sys/i386/boot 87make clean; make; make install 88cp /boot/pxeboot /tftpdir/ 89.Ed 90.Pp 91In phase 3, the kernel again uses DHCP or BOOTP to acquire 92configuration information, and proceeds to mount the 93root filesystem and start operation. The boot 94scripts recognize a diskless startup and peform 95the actions found in 96.Pa /etc/rc.d/initdiskless 97and 98.Pa /etc/rc.d/diskless . 99In older systems the scripts are located in 100.Pa /etc/rc.diskless1 101and 102.Pa /etc/rc.diskless2 . 103.Sh CONFIGURATION 104In order to run a diskless client, you need the following: 105.Bl -bullet 106.It 107An NFS server which exports a root and /usr partition with 108appropriate permissions. 109The diskless 110scripts work with readonly partitions, as long as root is exported with 111.Fl maproot Ns =0 112so that some system files can be accessed. 113As an example, 114.Pa /etc/exports 115can contain the following lines: 116.Bd -literal -offset indent 117<ROOT> -ro -maproot=0 -alldirs <list of diskless clients> 118/usr -ro -alldirs <list of diskless clients> 119.Ed 120.Pp 121where 122.Aq ROOT 123is the mountpoint on the server of the root partition. 124The script 125.Pa /usr/share/examples/diskless/clone_root 126can be used to create a shared readonly root partition, 127but in many cases you may decide to export 128(again as readonly) the root directory used by 129the server itself. 130.It 131a 132.Tn BOOTP 133or 134.Tn DHCP 135server. 136.Xr bootpd 8 137can be enabled by 138uncommenting the 139.Em bootps 140line in 141.Pa /etc/inetd.conf . 142A sample 143.Pa /etc/bootptab 144can be the following: 145.Bd -literal -offset indent 146 .default:\\ 147 hn:ht=1:vm=rfc1048:\\ 148 :sm=255.255.255.0:\\ 149 :sa=<SERVER>:\\ 150 :gw=<GATEWAY>:\\ 151 :rp="<SERVER>:<ROOT>": 152 153<CLIENT>:ha=0123456789ab:tc=.default 154.Ed 155.Pp 156where 157.Aq SERVER , 158.Aq GATEWAY 159and 160.Aq ROOT 161have the obvious meanings. 162.It 163A properly initialized root partition. 164The script 165.Pa /usr/share/examples/diskless/clone_root 166can help in creating it, using the server's root partition 167as a reference. If you are just starting out you should 168simply use the server's own root directory, 169.Pa / , 170and not try to clone it. 171.Pp 172You often do not want to use the same 173.Pa rc.conf 174or 175.Pa rc.local 176files for the diskless boot as you do on the server. The diskless boot 177scripts provide a mechanism through which you can override various files 178in 179.Pa /etc 180(as well as other subdirectories of root). The scripts provide four 181overriding directories situated in 182.Pa /conf/base , 183.Pa /conf/default , 184.Pa /conf/<broadcast-ip> , 185and 186.Pa /conf/<machine-ip> . 187You should always create 188.Pa /conf/base/etc , 189which will entirely replace the server's 190.Pa /etc 191on the diskless machine. 192You can clone the server's 193.Pa /etc 194here or you can create a special file which tells the diskless boot scripts 195to remount the server's 196.Pa /etc 197onto 198.Pa /conf/base/etc . 199You do this by creating the file 200.Pa /conf/base/etc/diskless_remount 201containing the mount point to use as a basis of the diskless machine's 202.Pa /etc . 203For example, the file might contain: 204.Bd -literal -offset 4n 20510.0.0.1:/etc 206.Ed 207.Pp 208The diskless scripts create memory filesystems to hold the overriden 209directories. Only a 2MB partition is created by default, which may not 210be sufficient for your purposes. To override this you can create the 211file 212.Pa /conf/base/etc/md_size 213containing the size, in 512 byte sectors, of the memory disk to create 214for that directory. 215.Pp 216You then typically provide file-by-file overrides in the 217.Pa /conf/default/etc 218directory. At a minimum you must provides overrides for 219.Pa /etc/fstab , 220.Pa /etc/rc.conf , 221and 222.Pa /etc/rc.local 223via 224.Pa /conf/default/etc/fstab , 225.Pa /conf/default/etc/rc.conf , 226and 227.Pa /conf/default/etc/rc.local . 228.Pp 229Overrides are hierarchical. You can supply network-specific defaults 230in the 231.Pa /conf/<BROADCASTIP>/etc 232directory, where <BROADCASTIP> represents the broadcast IP address of 233the diskless system as given to it via 234.Tn BOOTP . 235The 236.Pa diskless_remount 237and 238.Pa md_size 239features work in any of these directories. 240The configuration feature works on directories other then 241.Pa /etc , 242you simply create the directory you wish to replace or override in 243.Pa /conf/{base,default,<broadcast>,<ip>}/* 244and work it in the same way that you work 245.Pa /etc . 246.Pp 247Since you normally clone the server's 248.Pa /etc 249using the 250.Pa /conf/base/etc/diskless_remount , 251you might wish to remove unneeded files from the memory filesystem. For 252example, if the server has a firewall but you do not, you might wish 253to remove 254.Pa /etc/ipfw.conf . 255You can do this by creating a 256.Pa /conf/base/<DIRECTORY>.remove 257file. For example, 258.Pa /conf/base/etc.remove , 259which contains a list of relative paths that the boot scripts should remove 260from the memory file systems. 261.Pp 262As a minimum, you normally need to have the following in 263.Pa /conf/default/etc/fstab 264.Bd -literal -offset indent 265<SERVER>:<ROOT> / nfs ro 0 0 266<SERVER>:/usr /usr nfs ro 0 0 267proc /proc procfs rw 0 0 268.Ed 269.Pp 270You also need to create a customized version of 271.Pa /conf/default/etc/rc.conf 272which should contain 273the startup options for the diskless client, and 274.Pa /conf/default/etc/rc.local 275which could be empty but prevents the server's own 276.Pa /etc/rc.local 277from leaking onto the diskless system. 278.Pp 279In 280.Pa rc.conf , 281most likely 282you will not need to set 283.Va hostname 284and 285.Va ifconfig_* 286because these will be already set by the startup code. 287Finally, it might be convenient to use a 288.Ic case 289statement using 290.Li `hostname` 291as the switch variable to do machine-specific configuration 292in case a number of diskless clients share the same configuration 293files. 294.It 295The kernel for the diskless clients, which will be loaded using 296NFS or TFTP, should be built with at least the following options: 297.Bd -literal -offset indent 298options BOOTP 299options BOOTP_NFSROOT 300options BOOTP_COMPAT 301.Ed 302.Pp 303In the devices section add: 304.Bd -literal -offset indent 305device md 306.Ed 307.Pp 308If you use the firewall, remember to default to open or your kernel 309will not be able to send/receive the bootp packets. 310.El 311.Sh SECURITY ISSUES 312Be warned that using unencrypted NFS to mount root and user 313partitions may expose information such as 314encryption keys. 315.Sh BUGS 316This manpage is probably incomplete. 317.Pp 318.Fx 319sometimes requires to write onto 320the root partition, so the startup scripts mount MFS 321filesystems on some locations (e.g.\& 322.Pa /etc 323and 324.Pa /var ) , 325while 326trying to preserve the original content. 327The process might not handle all cases. 328.Sh SEE ALSO 329.Xr ethers 5 , 330.Xr exports 5 , 331.Xr bootpd 8 , 332.Xr mountd 8 , 333.Xr nfsd 8 , 334.Xr pxeboot 8 , 335.Xr reboot 8 , 336.Xr tftpd 8 , 337.Xr ports/net/etherboot 338