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