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