share/man/man8/diskless.8

   1 .\" Copyright (c) 1994 Gordon W. Ross, Theo de Raadt
   2 .\" Updated by Luigi Rizzo, Robert Watson
   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$
  28 .\"
  29 .Dd December 10, 2005
  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 file systems 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 .Bl -enum
  48 .It
  49 The stage-1 bootstrap, typically PXE built into your Ethernet
  50 card, loads a second-stage boot program.
  51 .It
  52 The second-stage boot program, typically
  53 .Xr pxeboot 8 ,
  54 loads modules and
  55 the kernel, and boots the kernel.
  56 .It
  57 The kernel
  58 .Tn NFS
  59 mounts the root directory and continues from there.
  60 .El
  61 .Pp
  62 Each of these phases are described in further detail below.
  63 .Pp
  64 First, the stage-1 bootstrap loads the stage-2 boot program over
  65 the network.
  66 The stage-1 bootstrap typically uses
  67 .Tn BOOTP
  68 or
  69 .Tn DHCP
  70 to obtain the filename to load, then uses
  71 .Tn TFTP
  72 to load the file.
  73 This file is typically called
  74 .Pa pxeboot ,
  75 and should be copied from
  76 .Pa /boot/pxeboot
  77 into the
  78 .Tn TFTP
  79 directory on the server, which is typically
  80 .Pa /tftpdir .
  81 .Pp
  82 The stage-2 boot program then loads additional modules and the kernel.
  83 These files may not exist on the
  84 .Tn DHCP
  85 or
  86 .Tn BOOTP
  87 server.
  88 You can use the
  89 .Ic next-server
  90 option available in
  91 .Tn DHCP
  92 configurations to specify the server holding
  93 the second stage boot files and kernel.
  94 The stage-2 program uses
  95 .Tn NFS
  96 or
  97 .Tn TFTP
  98 to obtain these files.
  99 By default,
 100 .Tn NFS
 101 is used.
 102 If you are using
 103 .Xr pxeboot 8 ,
 104 you can install a version that uses
 105 .Tn TFTP
 106 by setting
 107 .Li LOADER_TFTP_SUPPORT=YES
 108 in your
 109 .Xr make.conf 5 ,
 110 then recompiling and reinstalling
 111 .Xr pxeboot 8
 112 via the command listed below.
 113 It is often necessary to use
 114 .Tn TFTP
 115 here so you can place a custom kernel
 116 in
 117 .Pa /tftpdir/ .
 118 If you use
 119 .Tn NFS
 120 and do not have a custom root file system for the
 121 .Nm
 122 client, the stage-2 boot will load your server's kernel as the kernel for
 123 the
 124 .Nm
 125 machine, which may not be what you want to have happen.
 126 .Bd -literal -offset indent
 127 cd /usr/src/sys/boot/i386
 128 make clean; make; make install
 129 cp /boot/pxeboot /tftpdir/
 130 .Ed
 131 .Pp
 132 In phase 3, the kernel acquires IP networking configuration in one
 133 of two ways, and then proceeds to mount the root file system and start
 134 operation.
 135 If the phase 2 loader supports passing network configuration to the
 136 kernel using the kernel environment, then the kernel will configure
 137 the network interface using that information.
 138 Otherwise, it must use
 139 .Tn DHCP
 140 or
 141 .Tn BOOTP
 142 to acquire
 143 configuration information.
 144 The boot
 145 scripts recognize a
 146 .Nm
 147 startup and perform
 148 the actions found in
 149 .Pa /etc/rc.d/initdiskless ,
 150 .Pa /etc/rc.d/resolv ,
 151 .Pa /etc/rc.d/tmp ,
 152 and
 153 .Pa /etc/rc.d/var .
 154 On early 5.x releases, the functions of latter three scripts where
 155 implemented in
 156 .Pa /etc/rc.d/diskless .
 157 On older systems, the scripts are located in
 158 .Pa /etc/rc.diskless1
 159 and
 160 .Pa /etc/rc.diskless2 .
 161 .Sh CONFIGURATION
 162 In order to run a
 163 .Nm
 164 client, you need the following:
 165 .Bl -bullet
 166 .It
 167 An
 168 .Tn NFS
 169 server which exports a root and
 170 .Pa /usr
 171 partitions with appropriate permissions.
 172 The
 173 .Nm
 174 scripts work with read-only partitions, as long as root is exported with
 175 .Fl maproot Ns =0
 176 so that some system files can be accessed.
 177 As an example,
 178 .Pa /etc/exports
 179 can contain the following lines:
 180 .Bd -literal -offset indent
 181 <ROOT> -ro -maproot=0 -alldirs <list of diskless clients>
 182 /usr -ro -alldirs <list of diskless clients>
 183 .Ed
 184 .Pp
 185 where
 186 .Aq ROOT
 187 is the mount point on the server of the root partition.
 188 The script
 189 .Pa /usr/share/examples/diskless/clone_root
 190 can be used to create a shared read-only root partition,
 191 but in many cases you may decide to export
 192 (again as read-only) the root directory used by
 193 the server itself.
 194 .It
 195 A
 196 .Tn BOOTP
 197 or
 198 .Tn DHCP
 199 server.
 200 .Xr bootpd 8
 201 can be enabled by
 202 uncommenting the
 203 .Dq Li bootps
 204 line in
 205 .Pa /etc/inetd.conf .
 206 A sample
 207 .Pa /etc/bootptab
 208 can be the following:
 209 .Bd -literal -offset indent
 210  .default:\\
 211     hn:ht=1:vm=rfc1048:\\
 212     :sm=255.255.255.0:\\
 213     :sa=<SERVER>:\\
 214     :gw=<GATEWAY>:\\
 215     :rp="<SERVER>:<ROOT>":
 216
 217 <CLIENT>:ha=0123456789ab:tc=.default
 218 .Ed
 219 .Pp
 220 where
 221 .Aq SERVER ,
 222 .Aq GATEWAY
 223 and
 224 .Aq ROOT
 225 have the obvious meanings.
 226 .It
 227 A properly initialized root partition.
 228 The script
 229 .Pa /usr/share/examples/diskless/clone_root
 230 can help in creating it, using the server's root partition
 231 as a reference.
 232 If you are just starting out, you should
 233 simply use the server's own root directory,
 234 .Pa / ,
 235 and not try to clone it.
 236 .Pp
 237 You often do not want to use the same
 238 .Pa rc.conf
 239 or
 240 .Pa rc.local
 241 files for the
 242 .Nm
 243 boot as you do on the server.
 244 The
 245 .Nm
 246 boot
 247 scripts provide a mechanism through which you can override various files
 248 in
 249 .Pa /etc
 250 (as well as other subdirectories of root).
 251 .Pp
 252 One difference that you should pay particular attention to is
 253 the value of
 254 .Va local_startup
 255 in
 256 .Pa /etc/defaults/rc.conf .
 257 A typical value for a
 258 .Nm
 259 boot is
 260 .Va mountcritremote ,
 261 however your needs may be different.
 262 .Pp
 263 The scripts provide four
 264 overriding directories situated in
 265 .Pa /conf/base ,
 266 .Pa /conf/default ,
 267 .Pa /conf/<broadcast-ip> ,
 268 and
 269 .Pa /conf/<machine-ip> .
 270 You should always create
 271 .Pa /conf/base/etc ,
 272 which will entirely replace the server's
 273 .Pa /etc
 274 on the
 275 .Nm
 276 machine.
 277 You can clone the server's
 278 .Pa /etc
 279 here or you can create a special file which tells the
 280 .Nm
 281 boot scripts
 282 to remount the server's
 283 .Pa /etc
 284 onto
 285 .Pa /conf/base/etc .
 286 You do this by creating the file
 287 .Pa /conf/base/etc/diskless_remount
 288 containing the mount point to use as a basis of the
 289 .Nm
 290 machine's
 291 .Pa /etc .
 292 For example, the file might contain:
 293 .Pp
 294 .Dl 10.0.0.1:/etc
 295 .Pp
 296 Alternatively, if the server contains several independent roots, the file
 297 might contain:
 298 .Pp
 299 .Dl 10.0.0.1:/usr/diskless/4.7-RELEASE/etc
 300 .Pp
 301 This would work, but if you copied
 302 .Pa /usr/diskless/4.7-RELEASE
 303 to
 304 .Pa /usr/diskless/4.8-RELEASE
 305 and upgraded the installation, you would need to modify the
 306 .Pa diskless_remount
 307 files to reflect that move.
 308 To avoid that, paths in
 309 .Pa diskless_remount
 310 files beginning with
 311 .Pa /
 312 have the actual path of the client's root prepended to them so the file
 313 could instead contain:
 314 .Pp
 315 .Dl /etc
 316 .Pp
 317 The
 318 .Nm
 319 scripts create memory file systems to hold the overridden
 320 directories.
 321 Only a 2MB partition is created by default, which may not
 322 be sufficient for your purposes.
 323 To override this, you can create the
 324 file
 325 .Pa /conf/base/etc/md_size
 326 containing the size, in 512 byte sectors, of the memory disk to create
 327 for that directory.
 328 .Pp
 329 You then typically provide file-by-file overrides in the
 330 .Pa /conf/default/etc
 331 directory.
 332 At a minimum, you must provide overrides for
 333 .Pa /etc/fstab , /etc/rc.conf ,
 334 and
 335 .Pa /etc/rc.local
 336 via
 337 .Pa /conf/default/etc/fstab , /conf/default/etc/rc.conf ,
 338 and
 339 .Pa /conf/default/etc/rc.local .
 340 .Pp
 341 Overrides are hierarchical.
 342 You can supply network-specific defaults
 343 in the
 344 .Pa /conf/ Ns Ao Ar BROADCASTIP Ac Ns Pa /etc
 345 directory, where
 346 .Aq Ar BROADCASTIP
 347 represents the broadcast IP address of
 348 the
 349 .Nm
 350 system as given to it via
 351 .Tn BOOTP .
 352 The
 353 .Pa diskless_remount
 354 and
 355 .Pa md_size
 356 features work in any of these directories.
 357 The configuration feature works on directories other then
 358 .Pa /etc ,
 359 you simply create the directory you wish to replace or override in
 360 .Pa /conf/{base,default,<broadcast>,<ip>}/*
 361 and work it in the same way that you work
 362 .Pa /etc .
 363 .Pp
 364 Since you normally clone the server's
 365 .Pa /etc
 366 using the
 367 .Pa /conf/base/etc/diskless_remount ,
 368 you might wish to remove unneeded files from the memory file system.
 369 For example,
 370 if the server has a firewall but you do not, you might wish
 371 to remove
 372 .Pa /etc/ipfw.conf .
 373 You can do this by creating a
 374 .Pa /conf/base/ Ns Ao Ar DIRECTORY Ac Ns Pa .remove
 375 file.
 376 For example,
 377 .Pa /conf/base/etc.remove ,
 378 which contains a list of relative paths that the boot scripts should remove
 379 from the memory file systems.
 380 .Pp
 381 As a minimum, you normally need to have the following in
 382 .Pa /conf/default/etc/fstab
 383 .Bd -literal -offset indent
 384 <SERVER>:<ROOT> /     nfs    ro 0 0
 385 <SERVER>:/usr   /usr  nfs    ro 0 0
 386 proc            /proc procfs rw 0 0
 387 .Ed
 388 .Pp
 389 You also need to create a customized version of
 390 .Pa /conf/default/etc/rc.conf
 391 which should contain
 392 the startup options for the
 393 .Nm
 394 client, and
 395 .Pa /conf/default/etc/rc.local
 396 which could be empty but prevents the server's own
 397 .Pa /etc/rc.local
 398 from leaking onto the
 399 .Nm
 400 system.
 401 .Pp
 402 In
 403 .Pa rc.conf ,
 404 most likely
 405 you will not need to set
 406 .Va hostname
 407 and
 408 .Va ifconfig_*
 409 because these will be already set by the startup code.
 410 Finally, it might be convenient to use a
 411 .Ic case
 412 statement using
 413 .Li `hostname`
 414 as the switch variable to do machine-specific configuration
 415 in case a number of
 416 .Nm
 417 clients share the same configuration
 418 files.
 419 .It
 420 The kernel for the
 421 .Nm
 422 clients, which will be loaded using
 423 .Tn NFS
 424 or
 425 .Tn TFTP ,
 426 must include support for the NFS client:
 427 .Pp
 428 .D1 Cd "options NFSCLIENT"
 429 .D1 Cd "options NFS_ROOT"
 430 .Pp
 431 If you are using a boot mechanism that does not pass network configuration
 432 to the kernel using the kernel environment, you will also need to include
 433 the following options:
 434 .Pp
 435 .D1 Cd "options BOOTP"
 436 .D1 Cd "options BOOTP_NFSROOT"
 437 .D1 Cd "options BOOTP_COMPAT"
 438 .Pp
 439 .Em Note :
 440 the PXE environment does not require these options.
 441 .Pp
 442 The
 443 .Nm
 444 booting environment relies on memory-backed file systems to
 445 support temporary local storage in the event that the root file system
 446 is mounted read-only; as such, it is necessary to add the following
 447 to the device section of the kernel configuration:
 448 .Pp
 449 .D1 Cd "device md"
 450 .Pp
 451 If you use the firewall, remember to default to
 452 .Dq open ,
 453 or your kernel
 454 will not be able to send/receive the
 455 .Tn BOOTP
 456 packets.
 457 .El
 458 .Sh SECURITY ISSUES
 459 Be warned that using unencrypted
 460 .Tn NFS
 461 to mount root and user
 462 partitions may expose information such as
 463 encryption keys.
 464 .Sh SEE ALSO
 465 .Xr ethers 5 ,
 466 .Xr exports 5 ,
 467 .Xr make.conf 5 ,
 468 .Xr bootpd 8 ,
 469 .Xr mountd 8 ,
 470 .Xr nfsd 8 ,
 471 .Xr pxeboot 8 ,
 472 .Xr reboot 8 ,
 473 .Xr tftpd 8
 474 .Pp
 475 .Pa ports/net/etherboot
 476 .Sh BUGS
 477 This manpage is probably incomplete.
 478 .Pp
 479 .Fx
 480 sometimes requires to write onto
 481 the root partition, so the startup scripts mount MFS
 482 file systems on some locations (e.g.\&
 483 .Pa /etc
 484 and
 485 .Pa /var ) ,
 486 while
 487 trying to preserve the original content.
 488 The process might not handle all cases.