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 September 28, 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 , 150.Pa /etc/rc.d/resolv , 151.Pa /etc/rc.d/tmp , 152and 153.Pa /etc/rc.d/var . 154On early 5.x releases, the functions of latter three scripts where 155implemented in 156.Pa /etc/rc.d/diskless . 157On older systems, the scripts are located in 158.Pa /etc/rc.diskless1 159and 160.Pa /etc/rc.diskless2 . 161.Sh CONFIGURATION 162In order to run a 163.Nm 164client, you need the following: 165.Bl -bullet 166.It 167An 168.Tn NFS 169server which exports a root and 170.Pa /usr 171partitions with appropriate permissions. 172The 173.Nm 174scripts work with read-only partitions, as long as root is exported with 175.Fl maproot Ns =0 176so that some system files can be accessed. 177As an example, 178.Pa /etc/exports 179can contain the following lines: 180.Bd -literal -offset indent 181<ROOT> -ro -maproot=0 -alldirs <list of diskless clients> 182/usr -ro -alldirs <list of diskless clients> 183.Ed 184.Pp 185where 186.Aq ROOT 187is the mount point on the server of the root partition. 188The script 189.Pa /usr/share/examples/diskless/clone_root 190can be used to create a shared read-only root partition, 191but in many cases you may decide to export 192(again as read-only) the root directory used by 193the server itself. 194.It 195A 196.Tn BOOTP 197or 198.Tn DHCP 199server. 200.Xr bootpd 8 201can be enabled by 202uncommenting the 203.Dq Li bootps 204line in 205.Pa /etc/inetd.conf . 206A sample 207.Pa /etc/bootptab 208can be the following: 209.Bd -literal -offset indent 210 .default:\\ 211 hn:ht=1:vm=rfc1048:\\ 212 :sm=255.255.255.0:\\ 213 :sa=<SERVER>:\\ 214 :gw=<GATEWAY>:\\ 215 :rp="<SERVER>:<ROOT>": 216 217<CLIENT>:ha=0123456789ab:tc=.default 218.Ed 219.Pp 220where 221.Aq SERVER , 222.Aq GATEWAY 223and 224.Aq ROOT 225have the obvious meanings. 226.It 227A properly initialized root partition. 228The script 229.Pa /usr/share/examples/diskless/clone_root 230can help in creating it, using the server's root partition 231as a reference. 232If you are just starting out, you should 233simply use the server's own root directory, 234.Pa / , 235and not try to clone it. 236.Pp 237You often do not want to use the same 238.Pa rc.conf 239or 240.Pa rc.local 241files for the 242.Nm 243boot as you do on the server. 244The 245.Nm 246boot 247scripts provide a mechanism through which you can override various files 248in 249.Pa /etc 250(as well as other subdirectories of root). 251The scripts provide four 252overriding directories situated in 253.Pa /conf/base , 254.Pa /conf/default , 255.Pa /conf/<broadcast-ip> , 256and 257.Pa /conf/<machine-ip> . 258You should always create 259.Pa /conf/base/etc , 260which will entirely replace the server's 261.Pa /etc 262on the 263.Nm 264machine. 265You can clone the server's 266.Pa /etc 267here or you can create a special file which tells the 268.Nm 269boot scripts 270to remount the server's 271.Pa /etc 272onto 273.Pa /conf/base/etc . 274You do this by creating the file 275.Pa /conf/base/etc/diskless_remount 276containing the mount point to use as a basis of the 277.Nm 278machine's 279.Pa /etc . 280For example, the file might contain: 281.Pp 282.Dl 10.0.0.1:/etc 283.Pp 284Alternatively, if the server contains several independent roots, the file 285might contain: 286.Pp 287.Dl 10.0.0.1:/usr/diskless/4.7-RELEASE/etc 288.Pp 289This would work, but if you copied 290.Pa /usr/diskless/4.7-RELEASE 291to 292.Pa /usr/diskless/4.8-RELEASE 293and upgraded the installation, you would need to modify the 294.Pa diskless_remount 295files to reflect that move. 296To avoid that, paths in 297.Pa diskless_remount 298files beginning with 299.Pa / 300have the actual path of the client's root prepended to them so the file 301could instead contain: 302.Pp 303.Dl /etc 304.Pp 305The 306.Nm 307scripts create memory file systems to hold the overridden 308directories. 309Only a 2MB partition is created by default, which may not 310be sufficient for your purposes. 311To override this, you can create the 312file 313.Pa /conf/base/etc/md_size 314containing the size, in 512 byte sectors, of the memory disk to create 315for that directory. 316.Pp 317You then typically provide file-by-file overrides in the 318.Pa /conf/default/etc 319directory. 320At a minimum, you must provide overrides for 321.Pa /etc/fstab , /etc/rc.conf , 322and 323.Pa /etc/rc.local 324via 325.Pa /conf/default/etc/fstab , /conf/default/etc/rc.conf , 326and 327.Pa /conf/default/etc/rc.local . 328.Pp 329Overrides are hierarchical. 330You can supply network-specific defaults 331in the 332.Pa /conf/ Ns Ao Ar BROADCASTIP Ac Ns Pa /etc 333directory, where 334.Aq Ar BROADCASTIP 335represents the broadcast IP address of 336the 337.Nm 338system as given to it via 339.Tn BOOTP . 340The 341.Pa diskless_remount 342and 343.Pa md_size 344features work in any of these directories. 345The configuration feature works on directories other then 346.Pa /etc , 347you simply create the directory you wish to replace or override in 348.Pa /conf/{base,default,<broadcast>,<ip>}/* 349and work it in the same way that you work 350.Pa /etc . 351.Pp 352Since you normally clone the server's 353.Pa /etc 354using the 355.Pa /conf/base/etc/diskless_remount , 356you might wish to remove unneeded files from the memory file system. 357For example, 358if the server has a firewall but you do not, you might wish 359to remove 360.Pa /etc/ipfw.conf . 361You can do this by creating a 362.Pa /conf/base/ Ns Ao Ar DIRECTORY Ac Ns Pa .remove 363file. 364For example, 365.Pa /conf/base/etc.remove , 366which contains a list of relative paths that the boot scripts should remove 367from the memory file systems. 368.Pp 369As a minimum, you normally need to have the following in 370.Pa /conf/default/etc/fstab 371.Bd -literal -offset indent 372<SERVER>:<ROOT> / nfs ro 0 0 373<SERVER>:/usr /usr nfs ro 0 0 374proc /proc procfs rw 0 0 375.Ed 376.Pp 377You also need to create a customized version of 378.Pa /conf/default/etc/rc.conf 379which should contain 380the startup options for the 381.Nm 382client, and 383.Pa /conf/default/etc/rc.local 384which could be empty but prevents the server's own 385.Pa /etc/rc.local 386from leaking onto the 387.Nm 388system. 389.Pp 390In 391.Pa rc.conf , 392most likely 393you will not need to set 394.Va hostname 395and 396.Va ifconfig_* 397because these will be already set by the startup code. 398Finally, it might be convenient to use a 399.Ic case 400statement using 401.Li `hostname` 402as the switch variable to do machine-specific configuration 403in case a number of 404.Nm 405clients share the same configuration 406files. 407.It 408The kernel for the 409.Nm 410clients, which will be loaded using 411.Tn NFS 412or 413.Tn TFTP , 414must include support for the NFS client: 415.Pp 416.D1 Cd "options NFSCLIENT" 417.D1 Cd "options NFS_ROOT" 418.Pp 419If you are using a boot mechanism that does not pass network configuration 420to the kernel using the kernel environment, you will also need to include 421the following options: 422.Pp 423.D1 Cd "options BOOTP" 424.D1 Cd "options BOOTP_NFSROOT" 425.D1 Cd "options BOOTP_COMPAT" 426.Pp 427.Em Note : 428the PXE environment does not require these options. 429.Pp 430The 431.Nm 432booting environment relies on memory-backed file systems to 433support temporary local storage in the event that the root file system 434is mounted read-only; as such, it is necessary to add the following 435to the device section of the kernel configuration: 436.Pp 437.D1 Cd "device md" 438.Pp 439If you use the firewall, remember to default to 440.Dq open , 441or your kernel 442will not be able to send/receive the 443.Tn BOOTP 444packets. 445.El 446.Sh SECURITY ISSUES 447Be warned that using unencrypted 448.Tn NFS 449to mount root and user 450partitions may expose information such as 451encryption keys. 452.Sh SEE ALSO 453.Xr ethers 5 , 454.Xr exports 5 , 455.Xr bootpd 8 , 456.Xr mountd 8 , 457.Xr nfsd 8 , 458.Xr pxeboot 8 , 459.Xr reboot 8 , 460.Xr tftpd 8 461.Pp 462.Pa ports/net/etherboot 463.Sh BUGS 464This manpage is probably incomplete. 465.Pp 466.Fx 467sometimes requires to write onto 468the root partition, so the startup scripts mount MFS 469file systems on some locations (e.g.\& 470.Pa /etc 471and 472.Pa /var ) , 473while 474trying to preserve the original content. 475The process might not handle all cases. 476