From owner-svn-src-stable-10@FreeBSD.ORG Tue Oct 7 13:35:36 2014 Return-Path: Delivered-To: svn-src-stable-10@freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:1900:2254:206a::19:1]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by hub.freebsd.org (Postfix) with ESMTPS id E004EEB9; Tue, 7 Oct 2014 13:35:36 +0000 (UTC) Received: from svn.freebsd.org (svn.freebsd.org [IPv6:2001:1900:2254:2068::e6a:0]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (Client did not present a certificate) by mx1.freebsd.org (Postfix) with ESMTPS id C992FFBF; Tue, 7 Oct 2014 13:35:36 +0000 (UTC) Received: from svn.freebsd.org ([127.0.1.70]) by svn.freebsd.org (8.14.9/8.14.9) with ESMTP id s97DZajb092133; Tue, 7 Oct 2014 13:35:36 GMT (envelope-from avg@FreeBSD.org) Received: (from avg@localhost) by svn.freebsd.org (8.14.9/8.14.9/Submit) id s97DZZIs092121; Tue, 7 Oct 2014 13:35:35 GMT (envelope-from avg@FreeBSD.org) Message-Id: <201410071335.s97DZZIs092121@svn.freebsd.org> X-Authentication-Warning: svn.freebsd.org: avg set sender to avg@FreeBSD.org using -f From: Andriy Gapon Date: Tue, 7 Oct 2014 13:35:35 +0000 (UTC) To: src-committers@freebsd.org, svn-src-all@freebsd.org, svn-src-stable@freebsd.org, svn-src-stable-10@freebsd.org Subject: svn commit: r272696 - in stable/10/sys/boot: common i386/gptzfsboot i386/zfsboot X-SVN-Group: stable-10 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit X-BeenThere: svn-src-stable-10@freebsd.org X-Mailman-Version: 2.1.18-1 Precedence: list List-Id: SVN commit messages for only the 10-stable src tree List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Tue, 07 Oct 2014 13:35:37 -0000 Author: avg Date: Tue Oct 7 13:35:34 2014 New Revision: 272696 URL: https://svnweb.freebsd.org/changeset/base/272696 Log: MFC r271609: add gptzfsboot.8, zfsboot.8 and zfsloader.8 manual pages Added: stable/10/sys/boot/common/zfsloader.8 - copied unchanged from r271609, head/sys/boot/common/zfsloader.8 stable/10/sys/boot/i386/gptzfsboot/gptzfsboot.8 - copied unchanged from r271609, head/sys/boot/i386/gptzfsboot/gptzfsboot.8 stable/10/sys/boot/i386/zfsboot/zfsboot.8 - copied unchanged from r271609, head/sys/boot/i386/zfsboot/zfsboot.8 Modified: stable/10/sys/boot/common/Makefile.inc stable/10/sys/boot/i386/gptzfsboot/Makefile stable/10/sys/boot/i386/zfsboot/Makefile Directory Properties: stable/10/ (props changed) Modified: stable/10/sys/boot/common/Makefile.inc ============================================================================== --- stable/10/sys/boot/common/Makefile.inc Tue Oct 7 13:31:04 2014 (r272695) +++ stable/10/sys/boot/common/Makefile.inc Tue Oct 7 13:35:34 2014 (r272696) @@ -73,3 +73,6 @@ CFLAGS+= -DBOOT_PROMPT_123 .endif MAN+= loader.8 +.if ${MK_ZFS} != "no" +MAN+= zfsloader.8 +.endif Copied: stable/10/sys/boot/common/zfsloader.8 (from r271609, head/sys/boot/common/zfsloader.8) ============================================================================== --- /dev/null 00:00:00 1970 (empty, because file is newly added) +++ stable/10/sys/boot/common/zfsloader.8 Tue Oct 7 13:35:34 2014 (r272696, copy of r271609, head/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 . Modified: stable/10/sys/boot/i386/gptzfsboot/Makefile ============================================================================== --- stable/10/sys/boot/i386/gptzfsboot/Makefile Tue Oct 7 13:31:04 2014 (r272695) +++ stable/10/sys/boot/i386/gptzfsboot/Makefile Tue Oct 7 13:35:34 2014 (r272696) @@ -5,6 +5,7 @@ ${.CURDIR}/../../common FILES= gptzfsboot +MAN= gptzfsboot.8 NM?= nm Copied: stable/10/sys/boot/i386/gptzfsboot/gptzfsboot.8 (from r271609, head/sys/boot/i386/gptzfsboot/gptzfsboot.8) ============================================================================== --- /dev/null 00:00:00 1970 (empty, because file is newly added) +++ stable/10/sys/boot/i386/gptzfsboot/gptzfsboot.8 Tue Oct 7 13:35:34 2014 (r272696, copy of r271609, head/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 . Modified: stable/10/sys/boot/i386/zfsboot/Makefile ============================================================================== --- stable/10/sys/boot/i386/zfsboot/Makefile Tue Oct 7 13:31:04 2014 (r272695) +++ stable/10/sys/boot/i386/zfsboot/Makefile Tue Oct 7 13:35:34 2014 (r272696) @@ -3,6 +3,7 @@ .PATH: ${.CURDIR}/../boot2 ${.CURDIR}/../common ${.CURDIR}/../../common FILES= zfsboot +MAN= zfsboot.8 NM?= nm Copied: stable/10/sys/boot/i386/zfsboot/zfsboot.8 (from r271609, head/sys/boot/i386/zfsboot/zfsboot.8) ============================================================================== --- /dev/null 00:00:00 1970 (empty, because file is newly added) +++ stable/10/sys/boot/i386/zfsboot/zfsboot.8 Tue Oct 7 13:35:34 2014 (r272696, copy of r271609, head/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.