sys/boot/i386/zfsboot/zfsboot.8

   1 .\" Copyright (c) 2014 Andriy Gapon <avg@FreeBSD.org>
   2 .\" All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\"
  13 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHORS AND CONTRIBUTORS ``AS IS'' AND
  14 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  15 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  16 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHORS OR CONTRIBUTORS BE LIABLE
  17 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  18 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  19 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  20 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  21 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  22 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  23 .\" SUCH DAMAGE.
  24 .\"
  25 .\" $FreeBSD$
  26 .\"
  27 .Dd September 15, 2014
  28 .Dt ZFSBOOT 8
  29 .Os
  30 .Sh NAME
  31 .Nm zfsboot
  32 .Nd bootcode for ZFS on BIOS-based computers
  33 .Sh DESCRIPTION
  34 .Nm
  35 is used on BIOS-based computers to boot from a filesystem in
  36 a ZFS pool.
  37 .Nm
  38 is installed in two parts on a disk or a partition used by a ZFS pool.
  39 The first part, a single-sector starter boot block, is installed
  40 at the beginning of the disk or partition.
  41 The second part, a main boot block, is installed at a special offset
  42 within the disk or partition.
  43 Both areas are reserved by the ZFS on-disk specification for boot use.
  44 If
  45 .Nm
  46 is installed in a partition, then that partition should be made
  47 bootable using appropriate configuration and boot blocks described in
  48 .Xr boot 8 .
  49 .Sh BOOTING
  50 The
  51 .Nm
  52 boot process is very similar to that of
  53 .Xr gptzfsboot 8 .
  54 One significant difference is that
  55 .Nm
  56 does not currently support the GPT partitioning scheme.
  57 Thus only whole disks and MBR partitions, traditionally referred to as
  58 slices, are probed for ZFS disk labels.
  59 See the BUGS section in
  60 .Xr gptzfsboot 8
  61 for some limitations of the MBR scheme support.
  62 .Sh USAGE
  63 .Nm
  64 supports all the same prompt and configuration file arguments as
  65 .Xr gptzfsboot 8 .
  66 .Sh FILES
  67 .Bl -tag -width /boot/zfsboot -compact
  68 .It Pa /boot/zfsboot
  69 boot code binary
  70 .It Pa /boot.config
  71 parameters for the boot block
  72 .Pq optional
  73 .It Pa /boot/config
  74 alternative parameters for the boot block
  75 .Pq optional
  76 .El
  77 .Sh EXAMPLES
  78 .Nm
  79 is typically installed using
  80 .Xr dd 1 .
  81 To install
  82 .Nm
  83 on the
  84 .Pa ada0
  85 drive:
  86 .Bd -literal -offset indent
  87 dd if=/boot/zfsboot of=/dev/ada0 count=1
  88 dd if=/boot/zfsboot of=/dev/ada0 iseek=1 oseek=1024
  89 .Ed
  90 .Pp
  91 If the drive is currently in use, the GEOM safety will prevent writes
  92 and must be disabled before running the above commands:
  93 .Bd -literal -offset indent
  94 sysctl kern.geom.debugflags=0x10
  95 .Ed
  96 .Pp
  97 .Nm
  98 can also be installed in an MBR slice:
  99 .Bd -literal -offset indent
 100 gpart create -s mbr ada0
 101 gpart add -t freebsd ada0
 102 gpart create -s BSD ada0s1
 103 gpart bootcode -b /boot/boot0 ada0
 104 gpart set -a active -i 1 ada0
 105 dd if=/boot/zfsboot of=/dev/ada0s1 count=1
 106 dd if=/boot/zfsboot of=/dev/ada0s1 iseek=1 oseek=1024
 107 .Ed
 108 .Pp
 109 Note that commands to create and populate a pool are not shown
 110 in the example above.
 111 .Sh SEE ALSO
 112 .Xr dd 1 ,
 113 .Xr boot.config 5 ,
 114 .Xr boot 8 ,
 115 .Xr gptzfsboot 8 ,
 116 .Xr loader 8 ,
 117 .Xr zfsloader 8 ,
 118 .Xr zpool 8
 119 .Sh HISTORY
 120 .Nm
 121 appeared in FreeBSD 7.3.
 122 .Sh AUTHORS
 123 This manual page was written by
 124 .An Andriy Gapon Aq avg@FreeBSD.org .
 125 .Sh BUGS
 126 Installing
 127 .Nm
 128 with
 129 .Xr dd 1
 130 is a hack.
 131 ZFS needs a command to properly install
 132 .Nm
 133 onto a ZFS-controlled disk or partition.