share/man/man8/diskless.8

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