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