MFC r271609: add gptzfsboot.8, zfsboot.8 and zfsloader.8 manual pages
This commit is contained in:
avg
parent
b65dd64687
commit
56f2d33977
@ -73,3 +73,6 @@ CFLAGS+= -DBOOT_PROMPT_123
|
||||
.endif
|
||||
|
||||
MAN+= loader.8
|
||||
.if ${MK_ZFS} != "no"
|
||||
MAN+= zfsloader.8
|
||||
.endif
|
||||
|
||||
109
sys/boot/common/zfsloader.8
Normal file
109
sys/boot/common/zfsloader.8
Normal file
@ -0,0 +1,109 @@
|
||||
.\" Copyright (c) 2014 Andriy Gapon <avg@FreeBSD.org>
|
||||
.\" 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 .
|
||||
@ -5,6 +5,7 @@
|
||||
${.CURDIR}/../../common
|
||||
|
||||
FILES= gptzfsboot
|
||||
MAN= gptzfsboot.8
|
||||
|
||||
NM?= nm
|
||||
|
||||
|
||||
193
sys/boot/i386/gptzfsboot/gptzfsboot.8
Normal file
193
sys/boot/i386/gptzfsboot/gptzfsboot.8
Normal file
@ -0,0 +1,193 @@
|
||||
.\" Copyright (c) 2014 Andriy Gapon <avg@FreeBSD.org>
|
||||
.\" 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 .
|
||||
@ -3,6 +3,7 @@
|
||||
.PATH: ${.CURDIR}/../boot2 ${.CURDIR}/../common ${.CURDIR}/../../common
|
||||
|
||||
FILES= zfsboot
|
||||
MAN= zfsboot.8
|
||||
|
||||
NM?= nm
|
||||
|
||||
|
||||
133
sys/boot/i386/zfsboot/zfsboot.8
Normal file
133
sys/boot/i386/zfsboot/zfsboot.8
Normal file
@ -0,0 +1,133 @@
|
||||
.\" Copyright (c) 2014 Andriy Gapon <avg@FreeBSD.org>
|
||||
.\" 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.
|
||||
Loading…
x
Reference in New Issue
Block a user