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