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