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: src/share/man/man8/diskless.8,v 1.6.2.9 2003/01/25 18:56:44 dillon Exp $ 28.\" $DragonFly: src/share/man/man8/diskless.8,v 1.6 2006/07/22 23:52:23 swildner Exp $ 29.\" 30.Dd April 18, 2001 31.Dt DISKLESS 8 32.Os 33.Sh NAME 34.Nm diskless 35.Nd booting a system over the network 36.Sh DESCRIPTION 37The ability to boot a machine over the network is useful for 38.Em diskless 39or 40.Em dataless 41machines, or as a temporary measure while repairing or 42re-installing filesystems on a local disk. 43This file provides a general description of the interactions between 44a client and its server when a client is booting over the network. 45.Sh OPERATION 46When booting a system over the network, there are three 47phases of interaction between client and server: 48.Pp 49.Bl -enum -compact 50.It 51The stage-1 bootstrap loads a boot program, from 52.It 53The boot program loads a kernel. 54.It 55The kernel does NFS mounts for root. 56.El 57.Pp 58Each of these phases are described in further detail below. 59.Pp 60In phase 1, the stage-1 bootstrap code loads a boot program, 61which is typically able to control the network card. 62The boot program can be stored in the BIOS, in a BOOT ROM 63located on the network card (PXE, etherboot, netboot), 64or come from a disk unit (e.g. etherboot or netboot). 65.Pp 66In phase 2, the boot program loads a kernel. 67Operation in 68this phase depends on the design of the boot program. 69Typically, the boot program uses the 70.Tn BOOTP 71or 72.Tn DHCP 73protocol to get the client's IP address and other boot 74information, including but not limited to 75the IP addresses of the NFS server, router and nameserver, 76and the name of the kernel to load. 77Then the kernel is loaded, either directly using NFS 78(as it is the case for etherboot and netboot), 79or through an intermediate loader called pxeboot and 80loaded using TFTP or NFS. 81.Pp 82In phase 3, the kernel again uses DHCP or BOOTP to acquire 83configuration information, and proceeds to mount the 84root filesystem and start operation. The boot 85scripts recognize a diskless startup and peform 86the actions found in 87.Pa /etc/rc.d/initdiskless 88and 89.Pa /etc/rc.d/diskless . 90In older systems the scripts are located in 91.Pa /etc/rc.diskless1 92and 93.Pa /etc/rc.diskless2 . 94.Sh CONFIGURATION 95In order to run a diskless client, you need the following: 96.Bl -bullet 97.It 98An NFS server which exports a root and /usr partition with 99appropriate permissions. 100The diskless 101scripts work with readonly partitions, as long as root is exported with 102.Fl maproot Ns =0 103so that some system files can be accessed. 104As an example, 105.Pa /etc/exports 106can contain the following lines: 107.Bd -literal -offset indent 108<ROOT> -ro -maproot=0 -alldirs <list of diskless clients> 109/usr -ro -alldirs <list of diskless clients> 110.Ed 111.Pp 112where 113.Aq ROOT 114is the mountpoint on the server of the root partition. 115The script 116.Pa /usr/share/examples/diskless/clone_root 117can be used to create a shared readonly root partition, 118but in many cases you may decide to export 119(again as readonly) the root directory used by 120the server itself. 121.It 122a 123.Tn BOOTP 124or 125.Tn DHCP 126server. 127.Xr bootpd 8 128can be enabled by 129uncommenting the 130.Em bootps 131line in 132.Pa /etc/inetd.conf . 133A sample 134.Pa /etc/bootptab 135can be the following: 136.Bd -literal -offset indent 137 .default:\\ 138 hn:ht=1:vm=rfc1048:\\ 139 :sm=255.255.255.0:\\ 140 :sa=<SERVER>:\\ 141 :gw=<GATEWAY>:\\ 142 :rp="<SERVER>:<ROOT>": 143 144<CLIENT>:ha=0123456789ab:tc=.default 145.Ed 146.Pp 147where 148.Aq SERVER , 149.Aq GATEWAY 150and 151.Aq ROOT 152have the obvious meanings. 153.It 154A properly initialized root partition. 155The script 156.Pa /usr/share/examples/diskless/clone_root 157can help in creating it, using the server's root partition 158as a reference. If you are just starting out you should 159simply use the server's own root directory, 160.Pa / , 161and not try to clone it. 162.Pp 163You often do not want to use the same 164.Pa rc.conf 165or 166.Pa rc.local 167files for the diskless boot as you do on the server. The diskless boot 168scripts provide a mechanism through which you can override various files 169in 170.Pa /etc 171(as well as other subdirectories of root). The scripts provide four 172overriding directories situated in 173.Pa /conf/base , 174.Pa /conf/default , 175.Pa /conf/(broadcast-ip) , 176and 177.Pa /conf/(machine-ip) . 178You should always create 179.Pa /conf/base/etc , 180which will entirely replace the server's 181.Pa /etc 182on the diskless machine. 183You can clone the server's 184.Pa /etc 185here or you can create a special file which tells the diskless boot scripts 186to remount the server's 187.Pa /etc 188onto 189.Pa /conf/base/etc . 190You do this by creating the file 191.Pa /conf/base/etc/diskless_remount 192containing the mount point to use as a basis of the diskless machine's 193.Pa /etc . 194For example, the file might contain: 195.Bd -literal -offset 4n 19610.0.0.1:/etc 197.Ed 198.Pp 199The diskless scripts create memory filesystems to hold the overriden 200directories. Only a 2MB partition is created by default, which may not 201be sufficient for your purposes. To override this you can create the 202file 203.Pa /conf/base/etc/md_size 204containing the size, in 512 byte sectors, of the memory disk to create 205for that directory. 206.Pp 207You then typically provide file-by-file overrides in the 208.Pa /conf/default/etc 209directory. At a minimum you must provides overrides for 210.Pa /etc/fstab , 211.Pa /etc/rc.conf , 212and 213.Pa /etc/rc.local 214via 215.Pa /conf/default/etc/fstab , 216.Pa /conf/default/etc/rc.conf , 217and 218.Pa /conf/default/etc/rc.local . 219.Pp 220Overrides are hierarchical. You can supply network-specific defaults 221in the 222.Pa /conf/<BROADCASTIP>/etc 223directory, where <BROADCASTIP> represents the broadcast IP address of 224the diskless system as given to it via 225.Tn BOOTP . 226The 227.Pa diskless_remount 228and 229.Pa md_size 230features work in any of these directories. 231The configuration feature works on directories other then 232.Pa /etc , 233you simply create the directory you wish to replace or override in 234.Pa /conf/{base,default,<broadcast>,<ip>}/* 235and work it in the same way that you work 236.Pa /etc . 237.Pp 238As a minimum, you normally need to have the following in 239.Pa /conf/default/etc/fstab 240.Bd -literal -offset indent 241<SERVER>:<ROOT> / nfs ro 0 0 242<SERVER>:/usr /usr nfs ro 0 0 243proc /proc procfs rw 0 0 244.Ed 245.Pp 246You also need to create a customized version of 247.Pa /conf/default/etc/rc.conf 248which should contain 249the startup options for the diskless client, and 250.Pa /conf/default/etc/rc.local 251which could be empty but prevents the server's own 252.Pa /etc/rc.local 253from leaking onto the diskless system. 254.Pp 255In 256.Pa rc.conf , 257most likely 258you will not need to set 259.Va hostname 260and 261.Va ifconfig_* 262because these will be already set by the startup code. 263Finally, it might be convenient to use a 264.Ic case 265statement using 266.Li `hostname` 267as the switch variable to do machine-specific configuration 268in case a number of diskless clients share the same configuration 269files. 270.It 271The kernel for the diskless clients, which will be loaded using 272NFS or TFTP, should be built with at least the following options: 273.Pp 274.D1 Cd options MFS 275.D1 Cd options BOOTP 276.D1 Cd options BOOTP_NFSROOT 277.D1 Cd options BOOTP_COMPAT 278.Pp 279If you use the firewall, remember to default to open or your kernel 280will not be able to send/receive the bootp packets. 281.El 282.Sh SECURITY ISSUES 283Be warned that using unencrypted NFS to mount root and user 284partitions may expose information such as 285encryption keys. 286.Sh SEE ALSO 287.Xr ethers 5 , 288.Xr exports 5 , 289.Xr bootpd 8 , 290.Xr mountd 8 , 291.Xr nfsd 8 , 292.Xr pxeboot 8 , 293.Xr reboot 8 , 294.Xr tftpd 8 , 295.Xr ports/net/etherboot 296.Sh BUGS 297This manpage is probably incomplete. 298.Pp 299.Dx 300sometimes requires to write onto 301the root partition, so the startup scripts mount MFS 302filesystems on some locations (e.g.\& 303.Pa /etc 304and 305.Pa /var ) , 306while 307trying to preserve the original content. 308The process might not handle all cases. 309