1.\" Copyright (c) 1994 Gordon W. Ross, Theo de Raadt 2.\" Updated by Luigi Rizzo, Robert Watson 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 January 10, 2004 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 file systems 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.Bl -enum 48.It 49The stage-1 bootstrap, typically PXE built into your Ethernet 50card, loads a second-stage boot program. 51.It 52The second-stage boot program, typically 53.Xr pxeboot 8 , 54loads modules and 55the kernel, and boots the kernel. 56.It 57The kernel 58.Tn NFS 59mounts the root directory and continues from there. 60.El 61.Pp 62Each of these phases are described in further detail below. 63.Pp 64First, the stage-1 bootstrap loads the stage-2 boot program over 65the network. 66The stage-1 bootstrap typically uses 67.Tn BOOTP 68or 69.Tn DHCP 70to obtain the filename to load, then uses 71.Tn TFTP 72to load the file. 73This file is typically called 74.Pa pxeboot , 75and should be copied from 76.Pa /boot/pxeboot 77into the 78.Tn TFTP 79directory on the server, which is typically 80.Pa /tftpdir . 81.Pp 82The stage-2 boot program then loads additional modules and the kernel. 83These files may not exist on the 84.Tn DHCP 85or 86.Tn BOOTP 87server. 88You can use the 89.Ic next-server 90option available in 91.Tn DHCP 92configurations to specify the server holding 93the second stage boot files and kernel. 94The stage-2 program uses 95.Tn NFS 96or 97.Tn TFTP 98to obtain these files. 99By default, 100.Tn NFS 101is used. 102If you are using 103.Xr pxeboot 8 , 104you can install a version that uses 105.Tn TFTP 106by setting 107.Li LOADER_TFTP_SUPPORT=YES 108in your 109.Pa /etc/make.conf , 110then recompiling and reinstalling 111.Xr pxeboot 8 112via the command listed below. 113It is often necessary to use 114.Tn TFTP 115here so you can place a custom kernel 116in 117.Pa /tftpdir/ . 118If you use 119.Tn NFS 120and do not have a custom root file system for the 121.Nm 122client, the stage-2 boot will load your server's kernel as the kernel for 123the 124.Nm 125machine, which may not be what you want to have happen. 126.Bd -literal -offset indent 127cd /usr/src/sys/boot/i386 128make clean; make; make install 129cp /boot/pxeboot /tftpdir/ 130.Ed 131.Pp 132In phase 3, the kernel acquires IP networking configuration in one 133of two ways, and then proceeds to mount the root file system and start 134operation. 135If the phase 2 loader supports passing network configuration to the 136kernel using the kernel environment, then the kernel will configure 137the network interface using that information. 138Otherwise, it must use 139.Tn DHCP 140or 141.Tn BOOTP 142to acquire 143configuration information. 144The boot 145scripts recognize a 146.Nm 147startup and perform 148the actions found in 149.Pa /etc/rc.d/initdiskless 150and 151.Pa /etc/rc.d/diskless . 152On older systems, the scripts are located in 153.Pa /etc/rc.diskless1 154and 155.Pa /etc/rc.diskless2 . 156.Sh CONFIGURATION 157In order to run a 158.Nm 159client, you need the following: 160.Bl -bullet 161.It 162An 163.Tn NFS 164server which exports a root and 165.Pa /usr 166partitions with appropriate permissions. 167The 168.Nm 169scripts work with read-only partitions, as long as root is exported with 170.Fl maproot Ns =0 171so that some system files can be accessed. 172As an example, 173.Pa /etc/exports 174can contain the following lines: 175.Bd -literal -offset indent 176<ROOT> -ro -maproot=0 -alldirs <list of diskless clients> 177/usr -ro -alldirs <list of diskless clients> 178.Ed 179.Pp 180where 181.Aq ROOT 182is the mount point on the server of the root partition. 183The script 184.Pa /usr/share/examples/diskless/clone_root 185can be used to create a shared read-only root partition, 186but in many cases you may decide to export 187(again as read-only) the root directory used by 188the server itself. 189.It 190A 191.Tn BOOTP 192or 193.Tn DHCP 194server. 195.Xr bootpd 8 196can be enabled by 197uncommenting the 198.Dq Li bootps 199line in 200.Pa /etc/inetd.conf . 201A sample 202.Pa /etc/bootptab 203can be the following: 204.Bd -literal -offset indent 205 .default:\\ 206 hn:ht=1:vm=rfc1048:\\ 207 :sm=255.255.255.0:\\ 208 :sa=<SERVER>:\\ 209 :gw=<GATEWAY>:\\ 210 :rp="<SERVER>:<ROOT>": 211 212<CLIENT>:ha=0123456789ab:tc=.default 213.Ed 214.Pp 215where 216.Aq SERVER , 217.Aq GATEWAY 218and 219.Aq ROOT 220have the obvious meanings. 221.It 222A properly initialized root partition. 223The script 224.Pa /usr/share/examples/diskless/clone_root 225can help in creating it, using the server's root partition 226as a reference. 227If you are just starting out, you should 228simply use the server's own root directory, 229.Pa / , 230and not try to clone it. 231.Pp 232You often do not want to use the same 233.Pa rc.conf 234or 235.Pa rc.local 236files for the 237.Nm 238boot as you do on the server. 239The 240.Nm 241boot 242scripts provide a mechanism through which you can override various files 243in 244.Pa /etc 245(as well as other subdirectories of root). 246The scripts provide four 247overriding directories situated in 248.Pa /conf/base , 249.Pa /conf/default , 250.Pa /conf/<broadcast-ip> , 251and 252.Pa /conf/<machine-ip> . 253You should always create 254.Pa /conf/base/etc , 255which will entirely replace the server's 256.Pa /etc 257on the 258.Nm 259machine. 260You can clone the server's 261.Pa /etc 262here or you can create a special file which tells the 263.Nm 264boot scripts 265to remount the server's 266.Pa /etc 267onto 268.Pa /conf/base/etc . 269You do this by creating the file 270.Pa /conf/base/etc/diskless_remount 271containing the mount point to use as a basis of the 272.Nm 273machine's 274.Pa /etc . 275For example, the file might contain: 276.Pp 277.Dl 10.0.0.1:/etc 278.Pp 279Alternatively, if the server contains several independent roots, the file 280might contain: 281.Pp 282.Dl 10.0.0.1:/usr/diskless/4.7-RELEASE/etc 283.Pp 284This would work, but if you copied 285.Pa /usr/diskless/4.7-RELEASE 286to 287.Pa /usr/diskless/4.8-RELEASE 288and upgraded the installation, you would need to modify the 289.Pa diskless_remount 290files to reflect that move. 291To avoid that, paths in 292.Pa diskless_remount 293files beginning with 294.Pa / 295have the actual path of the client's root prepended to them so the file 296could instead contain: 297.Pp 298.Dl /etc 299.Pp 300The 301.Nm 302scripts create memory file systems to hold the overridden 303directories. 304Only a 2MB partition is created by default, which may not 305be sufficient for your purposes. 306To override this, you can create the 307file 308.Pa /conf/base/etc/md_size 309containing the size, in 512 byte sectors, of the memory disk to create 310for that directory. 311.Pp 312You then typically provide file-by-file overrides in the 313.Pa /conf/default/etc 314directory. 315At a minimum, you must provide overrides for 316.Pa /etc/fstab , /etc/rc.conf , 317and 318.Pa /etc/rc.local 319via 320.Pa /conf/default/etc/fstab , /conf/default/etc/rc.conf , 321and 322.Pa /conf/default/etc/rc.local . 323.Pp 324Overrides are hierarchical. 325You can supply network-specific defaults 326in the 327.Pa /conf/ Ns Ao Ar BROADCASTIP Ac Ns Pa /etc 328directory, where 329.Aq Ar BROADCASTIP 330represents the broadcast IP address of 331the 332.Nm 333system as given to it via 334.Tn BOOTP . 335The 336.Pa diskless_remount 337and 338.Pa md_size 339features work in any of these directories. 340The configuration feature works on directories other then 341.Pa /etc , 342you simply create the directory you wish to replace or override in 343.Pa /conf/{base,default,<broadcast>,<ip>}/* 344and work it in the same way that you work 345.Pa /etc . 346.Pp 347Since you normally clone the server's 348.Pa /etc 349using the 350.Pa /conf/base/etc/diskless_remount , 351you might wish to remove unneeded files from the memory file system. 352For example, 353if the server has a firewall but you do not, you might wish 354to remove 355.Pa /etc/ipfw.conf . 356You can do this by creating a 357.Pa /conf/base/ Ns Ao Ar DIRECTORY Ac Ns Pa .remove 358file. 359For example, 360.Pa /conf/base/etc.remove , 361which contains a list of relative paths that the boot scripts should remove 362from the memory file systems. 363.Pp 364As a minimum, you normally need to have the following in 365.Pa /conf/default/etc/fstab 366.Bd -literal -offset indent 367<SERVER>:<ROOT> / nfs ro 0 0 368<SERVER>:/usr /usr nfs ro 0 0 369proc /proc procfs rw 0 0 370.Ed 371.Pp 372You also need to create a customized version of 373.Pa /conf/default/etc/rc.conf 374which should contain 375the startup options for the 376.Nm 377client, and 378.Pa /conf/default/etc/rc.local 379which could be empty but prevents the server's own 380.Pa /etc/rc.local 381from leaking onto the 382.Nm 383system. 384.Pp 385In 386.Pa rc.conf , 387most likely 388you will not need to set 389.Va hostname 390and 391.Va ifconfig_* 392because these will be already set by the startup code. 393Finally, it might be convenient to use a 394.Ic case 395statement using 396.Li `hostname` 397as the switch variable to do machine-specific configuration 398in case a number of 399.Nm 400clients share the same configuration 401files. 402.It 403The kernel for the 404.Nm 405clients, which will be loaded using 406.Tn NFS 407or 408.Tn TFTP , 409must include support for the NFS client: 410.Pp 411.D1 Cd "options NFSCLIENT" 412.D1 Cd "options NFS_ROOT" 413.Pp 414If you are using a boot mechanism that does not pass network configuration 415to the kernel using the kernel environment, you will also need to include 416the following options: 417.Pp 418.D1 Cd "options BOOTP" 419.D1 Cd "options BOOTP_NFSROOT" 420.D1 Cd "options BOOTP_COMPAT" 421.Pp 422.Em Note : 423the PXE environment does not require these options. 424.Pp 425The 426.Nm 427booting environment relies on memory-backed file systems to 428support temporary local storage in the event that the root file system 429is mounted read-only; as such, it is necessary to add the following 430to the device section of the kernel configuration: 431.Pp 432.D1 Cd "device md" 433.Pp 434If you use the firewall, remember to default to 435.Dq open , 436or your kernel 437will not be able to send/receive the 438.Tn BOOTP 439packets. 440.El 441.Sh SECURITY ISSUES 442Be warned that using unencrypted 443.Tn NFS 444to mount root and user 445partitions may expose information such as 446encryption keys. 447.Sh BUGS 448This manpage is probably incomplete. 449.Pp 450.Fx 451sometimes requires to write onto 452the root partition, so the startup scripts mount MFS 453file systems on some locations (e.g.\& 454.Pa /etc 455and 456.Pa /var ) , 457while 458trying to preserve the original content. 459The process might not handle all cases. 460.Sh SEE ALSO 461.Xr ethers 5 , 462.Xr exports 5 , 463.Xr bootpd 8 , 464.Xr mountd 8 , 465.Xr nfsd 8 , 466.Xr pxeboot 8 , 467.Xr reboot 8 , 468.Xr tftpd 8 469.Pp 470.Pa ports/net/etherboot 471