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