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 274The 275.Nm 276scripts create memory file systems to hold the overriden 277directories. 278Only a 2MB partition is created by default, which may not 279be sufficient for your purposes. 280To override this, you can create the 281file 282.Pa /conf/base/etc/md_size 283containing the size, in 512 byte sectors, of the memory disk to create 284for that directory. 285.Pp 286You then typically provide file-by-file overrides in the 287.Pa /conf/default/etc 288directory. 289At a minimum, you must provide overrides for 290.Pa /etc/fstab , /etc/rc.conf , 291and 292.Pa /etc/rc.local 293via 294.Pa /conf/default/etc/fstab , /conf/default/etc/rc.conf , 295and 296.Pa /conf/default/etc/rc.local . 297.Pp 298Overrides are hierarchical. 299You can supply network-specific defaults 300in the 301.Pa /conf/ Ns Ao Ar BROADCASTIP Ac Ns Pa /etc 302directory, where 303.Aq Ar BROADCASTIP 304represents the broadcast IP address of 305the 306.Nm 307system as given to it via 308.Tn BOOTP . 309The 310.Pa diskless_remount 311and 312.Pa md_size 313features work in any of these directories. 314The configuration feature works on directories other then 315.Pa /etc , 316you simply create the directory you wish to replace or override in 317.Pa /conf/{base,default,<broadcast>,<ip>}/* 318and work it in the same way that you work 319.Pa /etc . 320.Pp 321Since you normally clone the server's 322.Pa /etc 323using the 324.Pa /conf/base/etc/diskless_remount , 325you might wish to remove unneeded files from the memory file system. 326For example, 327if the server has a firewall but you do not, you might wish 328to remove 329.Pa /etc/ipfw.conf . 330You can do this by creating a 331.Pa /conf/base/ Ns Ao Ar DIRECTORY Ac Ns Pa .remove 332file. 333For example, 334.Pa /conf/base/etc.remove , 335which contains a list of relative paths that the boot scripts should remove 336from the memory file systems. 337.Pp 338As a minimum, you normally need to have the following in 339.Pa /conf/default/etc/fstab 340.Bd -literal -offset indent 341<SERVER>:<ROOT> / nfs ro 0 0 342<SERVER>:/usr /usr nfs ro 0 0 343proc /proc procfs rw 0 0 344.Ed 345.Pp 346You also need to create a customized version of 347.Pa /conf/default/etc/rc.conf 348which should contain 349the startup options for the 350.Nm 351client, and 352.Pa /conf/default/etc/rc.local 353which could be empty but prevents the server's own 354.Pa /etc/rc.local 355from leaking onto the 356.Nm 357system. 358.Pp 359In 360.Pa rc.conf , 361most likely 362you will not need to set 363.Va hostname 364and 365.Va ifconfig_* 366because these will be already set by the startup code. 367Finally, it might be convenient to use a 368.Ic case 369statement using 370.Li `hostname` 371as the switch variable to do machine-specific configuration 372in case a number of 373.Nm 374clients share the same configuration 375files. 376.It 377The kernel for the 378.Nm 379clients, which will be loaded using 380.Tn NFS 381or 382.Tn TFTP , 383should be built with at least the following options: 384.Pp 385.D1 Cd "options BOOTP" 386.D1 Cd "options BOOTP_NFSROOT" 387.D1 Cd "options BOOTP_COMPAT" 388.Pp 389In the devices section add: 390.Pp 391.D1 Cd "device md" 392.Pp 393If you use the firewall, remember to default to 394.Dq open , 395or your kernel 396will not be able to send/receive the 397.Tn BOOTP 398packets. 399.El 400.Sh SECURITY ISSUES 401Be warned that using unencrypted 402.Tn NFS 403to mount root and user 404partitions may expose information such as 405encryption keys. 406.Sh BUGS 407This manpage is probably incomplete. 408.Pp 409.Fx 410sometimes requires to write onto 411the root partition, so the startup scripts mount MFS 412file systems on some locations (e.g.\& 413.Pa /etc 414and 415.Pa /var ) , 416while 417trying to preserve the original content. 418The process might not handle all cases. 419.Sh SEE ALSO 420.Xr ethers 5 , 421.Xr exports 5 , 422.Xr bootpd 8 , 423.Xr mountd 8 , 424.Xr nfsd 8 , 425.Xr pxeboot 8 , 426.Xr reboot 8 , 427.Xr tftpd 8 428.Pp 429.Pa ports/net/etherboot 430