bsdinstall(8): Document ZFS installation scripting.
- Extend the bsdinstall(8) man page with ZFS installation scripting details. [1] - Extend the bsdinstall(8) man page with the description of all the ZFS variables involved in a scripted installation of ZFS-based systems. [1] - Extend the SCRIPTING section with an example for a ZFS-based scripted installation. [1] - Create a new section explaining how ZFS datasets must be written into a variable to get them set on the final system. [1] While here: - Add Roberto to the copyrights for recognition as changes to the manual page are huge. - Use "Dq" for default values. - Use sysrc(8) instead of echo in examples. Submitted by: Roberto Fernandez Cueto <roberfern@gmail.com> [1] Reviewed by: dteske Approved by: re (gjb), krion (mentor, implicit), mat (mentor, implicit) Differential Revision: https://reviews.freebsd.org/D14169
This commit is contained in:
0mp
parent
da8348df52
commit
911e0929e5
@ -1,6 +1,6 @@
|
||||
.\"-
|
||||
.\" Copyright (c) 2011-2013 Nathan Whitehorn <nwhitehorn@FreeBSD.org>
|
||||
.\" All rights reserved.
|
||||
.\" Copyright (c) 2011-2013 Nathan Whitehorn <nwhitehorn@FreeBSD.org> All rights reserved.
|
||||
.\" Copyright (c) 2018 Roberto Fernandez Cueto <roberfern@gmail.com>
|
||||
.\"
|
||||
.\" Redistribution and use in source and binary forms, with or without
|
||||
.\" modification, are permitted provided that the following conditions
|
||||
@ -25,7 +25,7 @@
|
||||
.\"
|
||||
.\" $FreeBSD$
|
||||
.\"
|
||||
.Dd May 23, 2017
|
||||
.Dd October 4, 2018
|
||||
.Dt BSDINSTALL 8
|
||||
.Os
|
||||
.Sh NAME
|
||||
@ -261,12 +261,12 @@ overridden when making scripted or customized installers.
|
||||
.Bl -tag -width ".Ev BSDINSTALL_DISTSITE"
|
||||
.It Ev DISTRIBUTIONS
|
||||
The set of distributions to install, e.g., "base kernel ports".
|
||||
Default: none
|
||||
Default: unset
|
||||
.It Ev BSDINSTALL_DISTDIR
|
||||
The directory in which the distribution files can be found (or to which they
|
||||
should be downloaded).
|
||||
Default:
|
||||
.Pa /usr/freebsd-dist
|
||||
.Dq Pa /usr/freebsd-dist
|
||||
.It Ev BSDINSTALL_DISTSITE
|
||||
URL from which the distribution files should be downloaded if they are not
|
||||
already present in the directory defined by
|
||||
@ -287,11 +287,11 @@ Example:
|
||||
The directory into which the distribution files should be unpacked and the
|
||||
directory at which the root file system of the new system should be mounted.
|
||||
Default:
|
||||
.Pa /mnt
|
||||
.Dq Pa /mnt
|
||||
.It Ev BSDINSTALL_LOG
|
||||
Path to a log file for the installation.
|
||||
Default:
|
||||
.Pa /tmp/bsdinstall_log
|
||||
.Dq Pa /tmp/bsdinstall_log
|
||||
.It Ev BSDINSTALL_TMPETC
|
||||
Directory where files destined for the new system's
|
||||
.Pa /etc
|
||||
@ -300,7 +300,7 @@ will be stored until the
|
||||
target is executed.
|
||||
If this directory does not already exist, it will be created.
|
||||
Default:
|
||||
.Pa /tmp/bsdinstall_etc
|
||||
.Dq Pa /tmp/bsdinstall_etc
|
||||
.It Ev BSDINSTALL_TMPBOOT
|
||||
Directory where files destined for the new system's
|
||||
.Pa /boot
|
||||
@ -309,7 +309,113 @@ will be stored until the
|
||||
target is executed.
|
||||
If this directory does not already exist, it will be created.
|
||||
Default:
|
||||
.Pa /tmp/bsdinstall_boot
|
||||
.Dq Pa /tmp/bsdinstall_boot
|
||||
.It Ev ZFSBOOT_POOL_NAME
|
||||
Name for the pool containing the base system.
|
||||
Default:
|
||||
.Dq zroot
|
||||
.It Ev ZFSBOOT_POOL_CREATE_OPTIONS
|
||||
Options to be used when creating the base system's pool.
|
||||
Each option must be followed by the -O flag to be taken into consideration
|
||||
or the pool will not be created due to errors using the command
|
||||
.Cm zpool .
|
||||
Default:
|
||||
.Dq Li "-O compress=lz4 -O atime=off"
|
||||
.It Ev ZFSBOOT_BEROOT_NAME
|
||||
Name for the boot environment parent dataset.
|
||||
This is a non-mountable dataset meant to be a parent dataset where different
|
||||
boot environment are going to be created.
|
||||
Default:
|
||||
.Dq ROOT
|
||||
.It Ev ZFSBOOT_BOOTFS_NAME
|
||||
Name for the primary boot environment, which will be the default boot
|
||||
environment for the system.
|
||||
Default:
|
||||
.Dq default
|
||||
.It Ev ZFSBOOT_VDEV_TYPE
|
||||
The type of pool to be created for the base system.
|
||||
This variable can take one of this values: stripe (No redundacy),
|
||||
mirror (n-Way mirroring), raid10 (RAID 1+0 - n x 2-Way Mirrors),
|
||||
raidz1 (RAID-Z1 - Single Redundacy RAID), raidz2 (RAID-Z2 - Double Redundacy RAID)
|
||||
or raidz3 (RAID-Z3 Triple Redundacy RAID).
|
||||
Default:
|
||||
.Dq stripe
|
||||
.It Ev ZFSBOOT_FORCE_4K_SECTORS
|
||||
Indicates either the pool will use 4K or 512 sectors.
|
||||
If this variable is not empty, 4K sectors will be used.
|
||||
Default:
|
||||
.Dq 1
|
||||
.It Ev ZFSBOOT_GELI_ENCRYPTION
|
||||
If this variable is not empty, it will use
|
||||
.Xr geli 8
|
||||
to encrypt the root pool, enabling automatically the
|
||||
.Ev ZFSBOOT_BOOT_POOL
|
||||
variable.
|
||||
Default:
|
||||
.Dq ""
|
||||
.It Ev ZFSBOOT_GELI_KEY_FILE
|
||||
Path to the
|
||||
.Xr geli 8
|
||||
keyfile used to encrypt the pool where the base system is stored.
|
||||
Default:
|
||||
.Dq Pa /boot/encryption.key
|
||||
.It Ev ZFSBOOT_BOOT_POOL
|
||||
If set a separated boot pool will be created for the kernel of the
|
||||
system and
|
||||
.Xr loader 8 .
|
||||
Default: unset
|
||||
.It Ev ZFSBOOT_BOOT_POOL_CREATE_OPTIONS
|
||||
Options to use when creating the boot pool, when enabled (See
|
||||
.Ev ZFSBOOT_BOOT_POOL ).
|
||||
Default: unset
|
||||
.It Ev ZFSBOOT_BOOT_POOL_NAME
|
||||
Name for the optional boot pool when it is enabled, (See
|
||||
.Ev ZFSBOOT_BOOT_POOL ).
|
||||
Default:
|
||||
.Dq bootpool
|
||||
.It Ev ZFSBOOT_BOOT_POOL_SIZE
|
||||
Size of the boot pool when it is enabled (See
|
||||
.Ev ZFSBOOT_BOOT_POOL ).
|
||||
Default:
|
||||
.Dq 2g
|
||||
.It Ev ZFSBOOT_DISKS
|
||||
Disks to be used for the base system, including the boot pool.
|
||||
This variable must only be used on a scripted installation.
|
||||
See
|
||||
.Sx SCRIPTING
|
||||
for more information.
|
||||
Default: unset
|
||||
.It Ev ZFSBOOT_SWAP_SIZE
|
||||
Size of the swap partition on each block device.
|
||||
This variable will be passed to
|
||||
.Xr gpart 8 ;
|
||||
which supports SI unit suffixes.
|
||||
Default:
|
||||
.Dq 2g
|
||||
.It Ev ZFSBOOT_SWAP_ENCRYPTION
|
||||
If set, enables the encryption of the swap partition using
|
||||
.Xr geli 8 .
|
||||
Defaulf: ""
|
||||
.It Ev ZFSBOOT_SWAP_MIRROR
|
||||
If set, enables a swap mirroring using
|
||||
.Xr gmirror 8 .
|
||||
Default:
|
||||
unset
|
||||
.It Ev ZFSBOOT_DATASETS
|
||||
ZFS datasets to be created on the root zpool, it requires the
|
||||
following datasets:
|
||||
.Pa /tmp ,
|
||||
.Pa /var/tmp ,
|
||||
.Pa /$ZFSBOOT_BEROOT_NAME/$ZFSBOOT_BOOTFS_NAME .
|
||||
See
|
||||
.Sx ZFS DATASETS
|
||||
for more information about who to write this variable and to
|
||||
take a look into the default value of it.
|
||||
.It Ev ZFSBOOT_CONFIRM_LAYOUT
|
||||
If set and the installation is interactive, allow the user to confirm
|
||||
the layout before continuing with the installation.
|
||||
Default:
|
||||
.Dq 1
|
||||
.El
|
||||
.Sh SCRIPTING
|
||||
.Nm
|
||||
@ -338,6 +444,19 @@ sysrc sshd_enable=YES
|
||||
pkg install puppet
|
||||
.Ed
|
||||
.Pp
|
||||
For a ZFS scripted installation, the script looks like this:
|
||||
.Bd -literal -offset indent
|
||||
DISTRIBUTIONS="kernel.txz base.txz"
|
||||
export ZFSBOOT_VDEV_TYPE=stripe
|
||||
export ZFSBOOT_DISKS=ada0
|
||||
export nonInteractive="YES"
|
||||
|
||||
#!/bin/sh
|
||||
echo "ifconfig_em0=DHCP" >> /etc/rc.conf
|
||||
echo "sshd_enable=YES" >> /etc/rc.conf
|
||||
pkg install puppet
|
||||
.Ed
|
||||
.Pp
|
||||
On
|
||||
.Fx
|
||||
release media, such a script placed at
|
||||
@ -374,7 +493,21 @@ instead of
|
||||
the preamble can contain the variable
|
||||
.Ev ZFSBOOT_DATASETS
|
||||
instead of
|
||||
.Ev PARTITIONS .
|
||||
.Ev PARTITIONS ,
|
||||
and setting the variables
|
||||
.Ev ZFSBOOT_DISKS
|
||||
and
|
||||
.Ev ZFSBOOT_VDEV_TYPE
|
||||
to create the pool of disks for the base system.
|
||||
Usually, for a mirrored booting disk, this two variables looks like this:
|
||||
.Bd -literal -offset indent
|
||||
ZFSBOOT_DISKS="ada0 ada1"
|
||||
ZFSBOOT_VDEV_TYPE=mirror
|
||||
.Ed
|
||||
.Pp
|
||||
Remenber to export all the variables for the
|
||||
.Cm zfsboot
|
||||
command, otherwise it will not get set.
|
||||
.Ss SETUP SCRIPT
|
||||
Following the preamble is an optional shell script, beginning with a #!
|
||||
declaration.
|
||||
@ -385,6 +518,52 @@ configuration files, install packages, etc.
|
||||
Note that newly configured system services, e.g., networking have not
|
||||
been started in the installed system at this time and only installation
|
||||
host services are available.
|
||||
.Ss ZFS DATASETS
|
||||
The
|
||||
.Cm zfsboot
|
||||
partitioning takes the
|
||||
.Ev ZFSBOOT_DATASETS
|
||||
variable to create the datasets on the base system.
|
||||
This variable can get pretty huge if the pool contains a lot of datasets.
|
||||
The default value of the
|
||||
.Ev ZFSBOOT_DATASETS
|
||||
looks like this:
|
||||
.Bd -literal -offset indent
|
||||
# DATASET OPTIONS (comma or space separated; or both)
|
||||
|
||||
# Boot Environment [BE] root and default boot dataset
|
||||
/$ZFSBOOT_BEROOT_NAME mountpoint=none
|
||||
/$ZFSBOOT_BEROOT_NAME/$ZFSBOOT_BOOTFS_NAME mountpoint=/
|
||||
|
||||
# Compress /tmp, allow exec but not setuid
|
||||
/tmp mountpoint=/tmp,exec=on,setuid=off
|
||||
|
||||
# Do not mount /usr so that 'base' files go to the BEROOT
|
||||
/usr mountpoint=/usr,canmount=off
|
||||
|
||||
# Home directories separated so they are common to all BEs
|
||||
/usr/home # NB: /home is a symlink to /usr/home
|
||||
|
||||
# Ports tree
|
||||
/usr/ports setuid=off
|
||||
|
||||
# Source tree (compressed)
|
||||
/usr/src
|
||||
|
||||
# Create /var and friends
|
||||
/var mountpoint=/var,canmount=off
|
||||
/var/audit exec=off,setuid=off
|
||||
/var/crash exec=off,setuid=off
|
||||
/var/log exec=off,setuid=off
|
||||
/var/mail atime=on
|
||||
/var/tmp setuid=off
|
||||
.Ed
|
||||
.Pp
|
||||
The first column if the dataset to be created on the top of the
|
||||
.Ev ZFSBOOT_POOL_NAME
|
||||
and the rest of the columns are the options to be set on each dataset.
|
||||
The options must be written on a coma or space separated list, or both.
|
||||
And everything behind a pound/hash character is ignored as a comment.
|
||||
.Sh HISTORY
|
||||
This version of
|
||||
.Nm
|
||||
|
||||
Loading…
Reference in New Issue
Block a user