From 56f2d3397754ce603217961b02ec83965af862d4 Mon Sep 17 00:00:00 2001 From: avg Date: Tue, 7 Oct 2014 13:35:34 +0000 Subject: MFC r271609: add gptzfsboot.8, zfsboot.8 and zfsloader.8 manual pages --- sys/boot/common/Makefile.inc | 3 + sys/boot/common/zfsloader.8 | 109 +++++++++++++++++++ sys/boot/i386/gptzfsboot/Makefile | 1 + sys/boot/i386/gptzfsboot/gptzfsboot.8 | 193 ++++++++++++++++++++++++++++++++++ sys/boot/i386/zfsboot/Makefile | 1 + sys/boot/i386/zfsboot/zfsboot.8 | 133 +++++++++++++++++++++++ 6 files changed, 440 insertions(+) create mode 100644 sys/boot/common/zfsloader.8 create mode 100644 sys/boot/i386/gptzfsboot/gptzfsboot.8 create mode 100644 sys/boot/i386/zfsboot/zfsboot.8 diff --git a/sys/boot/common/Makefile.inc b/sys/boot/common/Makefile.inc index fab1630..a2dccdf 100644 --- a/sys/boot/common/Makefile.inc +++ b/sys/boot/common/Makefile.inc @@ -73,3 +73,6 @@ CFLAGS+= -DBOOT_PROMPT_123 .endif MAN+= loader.8 +.if ${MK_ZFS} != "no" +MAN+= zfsloader.8 +.endif diff --git a/sys/boot/common/zfsloader.8 b/sys/boot/common/zfsloader.8 new file mode 100644 index 0000000..9bb74a4 --- /dev/null +++ b/sys/boot/common/zfsloader.8 @@ -0,0 +1,109 @@ +.\" Copyright (c) 2014 Andriy Gapon +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd September 15, 2014 +.Dt ZFSLOADER 8 +.Os +.Sh NAME +.Nm zfsloader +.Nd kernel bootstrapping final stage +.Sh DESCRIPTION +.Nm +is an extended variant of +.Xr loader 8 +with added support for booting from ZFS. +This document describes only differences from +.Xr loader 8 . +.Sh ZFS FEATURES +.Nm +supports the following format for specifying ZFS filesystems which +can be used wherever +.Xr loader 8 +refers to a device specification: +.Pp +.Ar zfs:pool/filesystem: +.Pp +where +.Pa pool/filesystem +is a ZFS filesystem name as described in +.Xr zfs 8 . +.Pp +If +.Pa /etc/fstab +does not have an entry for the root filesystem and +.Va vfs.root.mountfrom +is not set, but +.Va currdev +refers to a ZFS filesystem, then +.Nm +will instruct kernel to use that filesystem as the root filesystem. +.Sh ZFS COMMAND EXTENSIONS +.Bl -tag -width Ds -compact +.Pp +.It Ic lsdev Op Fl v +Lists ZFS pools in addition to disks and partitions. +Adding +.Fl v +shows more ZFS pool details in a format that resembles +.Nm zpool Cm status +output. +.Pp +.It Ic lszfs Ar filesystem +A ZFS extended command that can be used to explore the ZFS filesystem +hierarchy in a pool. +Lists the immediate children of the +.Ar filesystem . +The filesystem hierarchy is rooted at a filesystem with the same name +as the pool. +.El +.Sh FILES +.Bl -tag -width /boot/zfsloader -compact +.It Pa /boot/zfsloader +.Nm +itself. +.El +.Sh EXAMPLES +Set the default device used for loading a kernel from a ZFS filesystem: +.Pp +.Bd -literal -offset indent +set currdev=zfs:tank/ROOT/knowngood: +.Ed +.Pp +.Sh SEE ALSO +.Xr gptzfsboot 8 , +.Xr loader 8 , +.Xr zfs 8 , +.Xr zfsboot 8 , +.Xr zfsloader 8 , +.Xr zpool 8 +.Sh HISTORY +The +.Nm +first appeared in +.Fx 7.3 . +.Sh AUTHORS +This manual page was written by +.An Andriy Gapon Aq avg@FreeBSD.org . diff --git a/sys/boot/i386/gptzfsboot/Makefile b/sys/boot/i386/gptzfsboot/Makefile index a9d6ac8..6fdf014 100644 --- a/sys/boot/i386/gptzfsboot/Makefile +++ b/sys/boot/i386/gptzfsboot/Makefile @@ -5,6 +5,7 @@ ${.CURDIR}/../../common FILES= gptzfsboot +MAN= gptzfsboot.8 NM?= nm diff --git a/sys/boot/i386/gptzfsboot/gptzfsboot.8 b/sys/boot/i386/gptzfsboot/gptzfsboot.8 new file mode 100644 index 0000000..400c8c6 --- /dev/null +++ b/sys/boot/i386/gptzfsboot/gptzfsboot.8 @@ -0,0 +1,193 @@ +.\" Copyright (c) 2014 Andriy Gapon +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHORS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHORS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd September 15, 2014 +.Dt GPTZFSBOOT 8 +.Os +.Sh NAME +.Nm gptzfsboot +.Nd GPT bootcode for ZFS on BIOS-based computers +.Sh DESCRIPTION +.Nm +is used on BIOS-based computers to boot from a filesystem in +a ZFS pool. +.Nm +is installed in a +.Cm freebsd-boot +partition of a GPT-partitioned disk with +.Xr gpart 8 . +.Sh IMPLEMENTATION NOTES +The GPT standard allows a variable number of partitions, but +.Nm +only boots from tables with 128 partitions or less. +.Sh BOOTING +.Nm +tries to find all ZFS pools that are composed of BIOS-visible +hard disks or partitions on them. +.Nm +looks for ZFS device labels on all visible disks and in discovered +supported partitions for all supported partition scheme types. +The search starts with the disk from which +.Nm +itself was loaded. +Other disks are probed in BIOS defined order. +After a disk is probed and +.Nm +determines that the whole disk is not a ZFS pool member, then +individual partitions are probed in their partition table order. +Currently GPT and MBR partition schemes are supported. +With the GPT scheme, only partitions of type +.Cm freebsd-zfs +are probed. +The first pool seen during probing is used as a default boot pool. +.Pp +The filesystem specified by the +.Cm bootfs +property of the pool is used as a default boot filesystem. +If the +.Cm bootfs +property is not set, then the root filesystem of the pool is used as +the default. +.Xr zfsloader 8 +is loaded from the boot filesystem. +If +.Pa /boot.config +or +.Pa /boot/config +is present in the boot filesystem, boot options are read from it +in the same way as +.Xr boot 8 . +.Pp +The ZFS GUIDs of the first successfully probed device and the first +detected pool are made available to +.Xr zfsloader 8 +in the +.Cm vfs.zfs.boot.primary_vdev +and +.Cm vfs.zfs.boot.primary_pool +variables. +.Sh USAGE +Normally +.Nm +will boot in fully automatic mode. +However, like +.Xr boot 8 , +it is possible to interrupt the automatic boot process and interact with +.Nm +through a prompt. +.Nm +accepts all the options that +.Xr boot 8 +supports. +.Pp +Filesystem specification and the path to +.Xr zfsloader 8 +is different from +.Xr boot 8 . +The format is +.Pp +.Sm off +.Oo zfs:pool/filesystem: Oc Oo /path/to/loader Oc +.Sm on +.Pp +Both the filesystem and the path can be specified. +If only a path is specified, then the default filesystem is used. +If only a pool and filesystem are specified, then +.Pa /boot/zfsloader +is used as a path. +.Pp +Additionally, the +.Ic status +command can be used to query information about discovered pools. +The output format is similar to that of +.Cm zpool status +.Pq see Xr zpool 8 . +.Pp +The configured or automatically determined ZFS boot filesystem is +stored in the +.Xr zfsloader 8 +.Cm loaddev +variable, and also set as the initial value of the +.Cm currdev +variable. +.Sh FILES +.Bl -tag -width /boot/gptzfsboot -compact +.It Pa /boot/gptzfsboot +boot code binary +.It Pa /boot.config +parameters for the boot block +.Pq optional +.It Pa /boot/config +alternative parameters for the boot block +.Pq optional +.El +.Sh EXAMPLES +.Nm +is typically installed in combination with a +.Dq protective MBR +.Po +see +.Xr gpart 8 +.Pc . +To install +.Nm +on the +.Pa ada0 +drive: +.Bd -literal -offset indent +gpart bootcode -b /boot/pmbr -p /boot/gptzfsboot -i 1 ada0 +.Ed +.Pp +.Nm +can also be installed without the PMBR: +.Bd -literal -offset indent +gpart bootcode -p /boot/gptzfsboot -i 1 ada0 +.Ed +.Sh SEE ALSO +.Xr boot.config 5 , +.Xr boot 8 , +.Xr gpart 8 , +.Xr loader 8 , +.Xr zfsloader 8 , +.Xr zpool 8 +.Sh HISTORY +.Nm +appeared in FreeBSD 7.3. +.Sh BUGS +.Nm +looks for ZFS meta-data only in MBR partitions +.Pq known on FreeBSD as slices . +It does not look into BSD +.Xr disklabel 8 +partitions that are traditionally called partitions. +If a disklabel partition happens to be placed so that ZFS meta-data can be +found at the fixed offsets relative to a slice, then +.Nm +will recognize the partition as a part of a ZFS pool, +but this is not guaranteed to happen. +.Sh AUTHORS +This manual page was written by +.An Andriy Gapon Aq avg@FreeBSD.org . diff --git a/sys/boot/i386/zfsboot/Makefile b/sys/boot/i386/zfsboot/Makefile index f4da642..0c24c40 100644 --- a/sys/boot/i386/zfsboot/Makefile +++ b/sys/boot/i386/zfsboot/Makefile @@ -3,6 +3,7 @@ .PATH: ${.CURDIR}/../boot2 ${.CURDIR}/../common ${.CURDIR}/../../common FILES= zfsboot +MAN= zfsboot.8 NM?= nm diff --git a/sys/boot/i386/zfsboot/zfsboot.8 b/sys/boot/i386/zfsboot/zfsboot.8 new file mode 100644 index 0000000..6450939 --- /dev/null +++ b/sys/boot/i386/zfsboot/zfsboot.8 @@ -0,0 +1,133 @@ +.\" Copyright (c) 2014 Andriy Gapon +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHORS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHORS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd September 15, 2014 +.Dt ZFSBOOT 8 +.Os +.Sh NAME +.Nm zfsboot +.Nd bootcode for ZFS on BIOS-based computers +.Sh DESCRIPTION +.Nm +is used on BIOS-based computers to boot from a filesystem in +a ZFS pool. +.Nm +is installed in two parts on a disk or a partition used by a ZFS pool. +The first part, a single-sector starter boot block, is installed +at the beginning of the disk or partition. +The second part, a main boot block, is installed at a special offset +within the disk or partition. +Both areas are reserved by the ZFS on-disk specification for boot use. +If +.Nm +is installed in a partition, then that partition should be made +bootable using appropriate configuration and boot blocks described in +.Xr boot 8 . +.Sh BOOTING +The +.Nm +boot process is very similar to that of +.Xr gptzfsboot 8 . +One significant difference is that +.Nm +does not currently support the GPT partitioning scheme. +Thus only whole disks and MBR partitions, traditionally referred to as +slices, are probed for ZFS disk labels. +See the BUGS section in +.Xr gptzfsboot 8 +for some limitations of the MBR scheme support. +.Sh USAGE +.Nm +supports all the same prompt and configuration file arguments as +.Xr gptzfsboot 8 . +.Sh FILES +.Bl -tag -width /boot/zfsboot -compact +.It Pa /boot/zfsboot +boot code binary +.It Pa /boot.config +parameters for the boot block +.Pq optional +.It Pa /boot/config +alternative parameters for the boot block +.Pq optional +.El +.Sh EXAMPLES +.Nm +is typically installed using +.Xr dd 1 . +To install +.Nm +on the +.Pa ada0 +drive: +.Bd -literal -offset indent +dd if=/boot/zfsboot of=/dev/ada0 count=1 +dd if=/boot/zfsboot of=/dev/ada0 iseek=1 oseek=1024 +.Ed +.Pp +If the drive is currently in use, the GEOM safety will prevent writes +and must be disabled before running the above commands: +.Bd -literal -offset indent +sysctl kern.geom.debugflags=0x10 +.Ed +.Pp +.Nm +can also be installed in an MBR slice: +.Bd -literal -offset indent +gpart create -s mbr ada0 +gpart add -t freebsd ada0 +gpart create -s BSD ada0s1 +gpart bootcode -b /boot/boot0 ada0 +gpart set -a active -i 1 ada0 +dd if=/boot/zfsboot of=/dev/ada0s1 count=1 +dd if=/boot/zfsboot of=/dev/ada0s1 iseek=1 oseek=1024 +.Ed +.Pp +Note that commands to create and populate a pool are not shown +in the example above. +.Sh SEE ALSO +.Xr dd 1 , +.Xr boot.config 5 , +.Xr boot 8 , +.Xr gptzfsboot 8 , +.Xr loader 8 , +.Xr zfsloader 8 , +.Xr zpool 8 +.Sh HISTORY +.Nm +appeared in FreeBSD 7.3. +.Sh AUTHORS +This manual page was written by +.An Andriy Gapon Aq avg@FreeBSD.org . +.Sh BUGS +Installing +.Nm +with +.Xr dd 1 +is a hack. +ZFS needs a command to properly install +.Nm +onto a ZFS-controlled disk or partition. -- cgit v1.1