xref: /src/usr.sbin/bsdinstall/bsdinstall.8 (revision ed5023c96c6e0228d4c38d89b86809c713ed3d68)

.\"
.\" SPDX-License-Identifier: BSD-2-Clause
.\"
.\" Copyright (c) 2011-2013 Nathan Whitehorn <nwhitehorn@FreeBSD.org> All rights reserved.
.\" Copyright (c) 2018 Roberto Fernandez Cueto <roberfern@gmail.com>
.\" Copyright (c) 2024 The FreeBSD Foundation
.\"
.\" Portions of this documentation were written by Björn Zeeb
.\" under sponsorship from the FreeBSD Foundation.
.\"
.\" 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 ``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 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.
.\"
.Dd October 3, 2025
.Dt BSDINSTALL 8
.Os
.Sh NAME
.Nm bsdinstall
.Nd system installer
.Sh SYNOPSIS
.Nm
.Op Ar options
.Op Ar target
.Op Ar ...
.Sh DESCRIPTION
.Nm
is used for installation of new systems,
both for system setup from installation media,
such as discs, USBs, or network boot environments,
and for use on live systems to prepare jails and virtual machine images.
.Pp
Much like
.Xr make 1 , Nm
takes a target and possible parameters of the target as arguments.
If invoked with no arguments, it will invoke the
.Cm auto
target, which provides a standard interactive installation, invoking the
others in sequence.
To perform a scripted installation,
these subtargets can be invoked separately by an installation script.
.Sh OPTIONS
.Nm
supports the following options, global to all targets:
.Bl -tag -width "-D file"
.It Fl D Ar file
Provide a path for the installation log file
.Pq overrides Ev BSDINSTALL_LOG .
See
.Sx ENVIRONMENT VARIABLES
for more information on
.Ev BSDINSTALL_LOG .
.El
.Sh TARGETS
Most of the following targets are only useful for scripting the installer.
For interactive use, most users will be interested only in the
.Cm auto ,
.Cm jail ,
and
.Cm script
targets.
.Bl -tag -width "-D file"
.It Cm auto
Run the standard interactive installation, including disk partitioning.
.It Cm jail Ar destination
Sets up a new chroot system at
.Pa destination ,
suitable for use with
.Xr jail 8 .
Behavior is generally similar to
.Cm auto ,
except that disk partitioning and network setup are skipped and a kernel is
not installed into the new system.
.It Cm script Ar script
Runs the installation script at
.Pa script .
See
.Sx SCRIPTING
for more information on this target.
.It Cm keymap
If the current controlling TTY is a
.Xr syscons 4
or
.Xr vt 4
console, asks the user to set the current keymap, and saves the result to the
new system's
.Pa rc.conf .
.It Cm hostname
Prompts the user for a host name for the new system and saves the result to the
new system's
.Pa rc.conf .
If
.Ev BSDINSTALL_CONFIGCURRENT
is set, also sets the host name of the current system.
.It Cm netconfig
Interactively configures network interfaces (first invoking
.Cm wlanconfig
on wireless interfaces), saving the result to the new system's
.Pa rc.conf
and
.Pa resolv.conf .
If
.Ev BSDINSTALL_CONFIGCURRENT
is set, also configures the network interfaces of the current system to match.
.It Cm autopart
Provides the installer's interactive guided disk partitioner for single-disk
installations.
Defaults to UFS.
.It Cm bootconfig
Detects an appropriate partition and installs UEFI boot loader files.
.It Cm zfsboot
Provides a ZFS-only automatic interactive disk partitioner.
Creates a single
.Ic zpool
with separate datasets for
.Pa /home ,
.Pa /tmp ,
.Pa /usr ,
.Pa /usr/ports ,
.Pa /usr/src ,
and
.Pa /var .
Optionally can set up
.Xr geli 8
to encrypt the disk.
.It Cm partedit
Provides the installer's interactive manual disk partitioner with an interface
identical to
.Xr sade 8 .
Supports multiple disks as well as UFS, ZFS, and FAT file systems.
ZFS is set up with one pool and dataset per partition.
.It Cm scriptedpart Ar parameters
Sets up disks like
.Cm autopart
and
.Cm partedit ,
but non-interactively according to the disk setup specified in
.Ar parameters .
Each disk setup is specified by a three-part argument:
.Pp
.Ar disk
.Op Ar scheme
.Op Ar {partitions}
.Pp
Multiple disk setups are separated by semicolons.
The
.Ar disk
argument specifies the disk on which to operate (which will be erased),
or the special value
.Em DEFAULT ,
which will result in either a selection window (as in
.Cm autopart )
for the destination disk or, if there is only one possible disk, will
automatically select it.
The
.Ar scheme
argument specifies the
.Xr gpart 8
partition scheme to apply to the disk.
If
.Ar scheme
is unspecified,
.Cm scriptedpart
will apply the default bootable scheme on your platform.
The
.Ar partitions
argument is also optional and specifies how to partition
.Ar disk .
It consists of a comma-separated list of partitions to create enclosed in
curly braces.
Each partition declaration takes the form
.Pp
.Ar size
.Ar type
.Op Ar mount point
.Pp
.Ar size
specifies the partition size to create in bytes (K, M, and G suffixes
can be appended to specify kilobytes, megabytes, and gigabytes respectively),
while the
.Em auto
keyword causes the partition to take all the remaining space on the disk.
The
.Ar type
option chooses the
.Xr gpart 8
filesystem type, e.g., freebsd-ufs, freebsd-zfs, or freebsd-swap.
The optional
.Ar mount point
argument sets where the created partition is to be mounted in the installed
system.
As an example, a typical invocation looks like:
.Pp
bsdinstall scriptedpart ada0 { 20G freebsd-ufs /, 4G freebsd-swap, 20G freebsd-ufs /var, auto freebsd-ufs /usr }
.Pp
Note that the list of partitions should
.Em not
include boot partitions (e.g. EFI system partitions), which will be created automatically on whatever disk includes /.
.Pp
A shorter invocation to use the default partitioning (as
.Cm autopart
would have used) on the same disk:
.Pp
bsdinstall scriptedpart ada0
.Pp
or, even shorter:
.Pp
bsdinstall scriptedpart DEFAULT
.It Cm mount
Mounts the file systems previously configured by
.Cm autopart ,
.Cm partedit ,
or
.Cm scriptedpart
under
.Ev BSDINSTALL_CHROOT .
.It Cm distfetch
Fetches the distributions in
.Ev DISTRIBUTIONS
to
.Ev BSDINSTALL_DISTDIR
from
.Ev BSDINSTALL_DISTSITE .
.It Cm checksum
Verifies the checksums of the distributions listed in
.Ev DISTRIBUTIONS
against the distribution manifest.
.It Cm distextract
Extracts the distributions listed in
.Ev DISTRIBUTIONS
into
.Ev BSDINSTALL_CHROOT .
.It Cm pkgbase Op Fl -jail
Fetch and install base system packages to
.Ev BSDINSTALL_CHROOT .
Packages are fetched according to repository configuration in
.Ev BSDINSTALL_PKG_REPOS_DIR
if set, or
.Lk pkg.freebsd.org
otherwise.
If the
.Fl -jail
option is passed, no kernel is installed, and the
.Dq jail
variant of each package set will be selected where applicable.
.It Cm firmware
executes
.Xr fwget 8
inside the
.Ev BSDINSTALL_CHROOT
to install any needed and available firmware for the new system.
.It Cm rootpass
Interactively invokes
.Xr passwd 1
in the new system to set the root user's password.
.It Cm adduser
Interactively invokes
.Xr adduser 8
in the new system.
.It Cm time
Interactively sets the time, date, and time zone of the new system.
.It Cm services
Queries the user for the system daemons to begin at system startup,
writing the result into the new system's
.Pa rc.conf .
.It Cm entropy
Reads a small amount of data from
.Pa /dev/random
and stores it in a file in the new system's root directory.
.It Cm config
Installs the configuration files destined for the new system, e.g.,
.Xr rc.conf 5
fragments generated by
.Cm netconfig ,
etc.) onto the new system.
.El
.Sh ENVIRONMENT VARIABLES
The following environment variables control various aspects of the installation
process.
Many are used internally during installation and have reasonable default values
for most installation scenarios.
Others are set by various interactive user prompts, and can be usefully
overridden when making scripted or customized installers.
.Bl -tag -width "-D file"
.It Ev TMPDIR
The directory to use for temporary files.
Default:
.Dq Pa /tmp
.It Ev DISTRIBUTIONS
The set of distributions to install, e.g., "base.txz kernel.txz ports.txz".
Default: unset
.It Ev PARTITIONS
The partitioning of the disk onto which the system is being installed.
See
.Cm scriptedpart
of
the
.Sx TARGETS
section for format details. If this variable is unset, the installer will
use the default partitioning as in
.Cm autopart .
Default: unset
.It Ev BSDINSTALL_DISTDIR
The directory in which the distribution files can be found (or to which they
should be downloaded).
Default:
.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
.Ev BSDINSTALL_DISTDIR .
This should be a full path to the files, including architecture and release
names.
Most targets, e.g.,
.Cm auto
and
.Cm jail ,
that prompt for a
.Fx
mirror will skip that step if this variable is already defined in the
environment.
Example:
.Pa https://download.freebsd.org/ftp/releases/powerpc/powerpc64/13.1-RELEASE/
or
.Pa http://ftp-archive.freebsd.org/pub/FreeBSD-Archive/old-releases/amd64/12.2-RELEASE/ .
.It Ev BSDINSTALL_PKG_REPOS_DIR
Directory containing
.Xr pkg 8
repository configuration files used by the
.Cm pkgbase
target.
See
.Sx REPOSITORY CONFIGURATION
in
.Xr pkg.conf 5 .
Default: unset
.It Ev BSDINSTALL_CHROOT
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:
.Dq Pa /mnt
.It Ev BSDINSTALL_LOG
Path to a log file for the installation.
Default:
.Dq Pa $TMPDIR/bsdinstall_log
.It Ev BSDINSTALL_SKIP_FIRMWARE
If not empty, the
.Cm auto
target
will not invoke the
.Cm firmware
target.
.It Ev BSDINSTALL_SKIP_HARDENING
If not empty, the
.Cm auto
target
will not invoke the
.Cm hardening
target.
.It Ev BSDINSTALL_SKIP_HOSTNAME
If not empty, the
.Cm auto
target
will not invoke the
.Cm hostname
target.
.It Ev BSDINSTALL_SKIP_KEYMAP
If not empty, the
.Cm auto
target
will not invoke the
.Cm keymap
target.
.It Ev BSDINSTALL_SKIP_MANUAL
If not empty, the
.Cm auto
target will not offer to open a shell in the new system
for final manual modifications.
.It Ev BSDINSTALL_SKIP_SERVICES
If not empty, the
.Cm auto
target
will not invoke the
.Cm services
target.
.It Ev BSDINSTALL_SKIP_TIME
If not empty, the
.Cm auto
target
will not invoke the
.Cm time
target.
.It Ev BSDINSTALL_SKIP_USERS
If not empty, the
.Cm auto
target
will not invoke the
.Cm adduser
target.
.It Ev BSDINSTALL_SKIP_FINALCONFIG
If not empty, the
.Cm auto
target will not show the final configuration dialog,
where earlier configuration choices can be revisited.
.It Ev BSDINSTALL_TMPETC
Directory where files destined for the new system's
.Pa /etc
will be stored until the
.Cm config
target is executed.
If this directory does not already exist, it will be created.
Default:
.Dq Pa $TMPDIR/bsdinstall_etc
.It Ev BSDINSTALL_TMPBOOT
Directory where files destined for the new system's
.Pa /boot
will be stored until the
.Cm config
target is executed.
If this directory does not already exist, it will be created.
Default:
.Dq Pa $TMPDIR/bsdinstall_boot
.It Ev ROOTPASS_ENC
Encrypted string to set the root password to in the format expected by
.Xr pw 8
.Fl H Ar 0 .
This option is used if both it and
.Ev ROOTPASS_PLAIN
are set.
.It Ev ROOTPASS_PLAIN
Plain text string to set the root password to.
.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 preceded 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 compression=on -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 redundancy),
mirror (n-Way mirroring), raid10 (RAID 1+0 - n x 2-Way Mirrors),
raidz1 (RAID-Z1 - Single Redundancy RAID), raidz2 (RAID-Z2 - Double Redundancy RAID)
or raidz3 (RAID-Z3 Triple Redundancy RAID).
Default:
.Dq stripe
.It Ev ZFSBOOT_FORCE_4K_SECTORS
Controls the minimum sector size of the pool.
If this variable is not empty, the minimum sector size is 4K.
If this variable is empty, the minimum sector size is 512.
Note that the sector size of the pool will always be at least
the sector size of the backing disks.
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 .
Default: ""
.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 how to populate this variable and
its default value.
.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
supports unattended, or minimally-attended, installations using scripting.
This can be used with either modified physical installation media or with
.Xr diskless 8
installations over the network; information on preparing such media can be
found in
.Sx BUILDING AUTOMATIC INSTALL MEDIA
.Pp
Scripted installations follow an essentially identical path to interactive
installations, though with some minor feature differences (for example,
scripted installations do not support fetching of remote distribution files
since scripted installations normally install the same files and the distributions
can be added directly to the installation media).
.Nm
scripts consist of two parts: a
.Em preamble
and a
.Em setup script .
The preamble sets up the options for the installation (how to partition the
disk[s], which distributions to install, etc.) and the optional second part is
a shell script run under
.Xr chroot 8
in the newly installed system before
.Nm
exits.
The two parts are separated by the usual script header (#!), which also sets
the interpreter for the setup script.
.Pp
A typical bsdinstall script, using the default filesystem layout and the UFS
filesystem, looks like this:
.Bd -literal -offset indent
PARTITIONS=DEFAULT
DISTRIBUTIONS="kernel.txz base.txz"

#!/bin/sh
sysrc ifconfig_DEFAULT=DHCP
sysrc sshd_enable=YES
pkg install puppet
.Ed
.Pp
For a scripted installation involving a ZFS pool spanning multiple disks,
the script instead looks like this:
.Bd -literal -offset indent
DISTRIBUTIONS="kernel.txz base.txz"
export ZFSBOOT_VDEV_TYPE=stripe
export ZFSBOOT_DISKS="ada0 ada1"
export nonInteractive="YES"

#!/bin/sh
echo "ifconfig_DEFAULT=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
.Pa /etc/installerconfig
will be run at boot time and the system will be rebooted automatically after
the installation has completed.
This can be used for unattended network installation of new systems; see
.Xr diskless 8
for details.
.Ss PREAMBLE
The preamble consists of installer settings.
These control global installation parameters (see
.Sx ENVIRONMENT VARIABLES )
as well as disk partitioning.
The preamble is interpreted as a
.Xr sh 1
script run at the very beginning of the install.
If more complicated behavior than setting these variables is desired,
arbitrary commands can be run here to extend the installer.
In addition to the variables in
.Sx ENVIRONMENT VARIABLES ,
in particular
.Ev DISTRIBUTIONS ,
the preamble can contain a variable
.Ev PARTITIONS
which is passed to the
.Cm scriptedpart
target to control disk setup.
.Pp
Alternatively,
to use
.Cm zfsboot
instead of
.Cm partedit ,
the preamble can contain the variable
.Ev ZFSBOOT_DATASETS
instead of
.Ev PARTITIONS
(see below).
If using
.Cm zfsboot ,
the variables
.Ev ZFSBOOT_DISKS
and
.Ev ZFSBOOT_VDEV_TYPE
must be set to create the pool of disks for the base system.
Usually, for a mirrored booting disk, these two variables look like this:
.Bd -literal -offset indent
ZFSBOOT_DISKS="ada0 ada1"
ZFSBOOT_VDEV_TYPE=mirror
.Ed
.Pp
Remember to export all the variables for the
.Cm zfsboot
command, otherwise installation will fail.
.Ss SETUP SCRIPT
Following the preamble is an optional shell script, beginning with a #!
declaration.
This script will be run at the end of the installation process inside a
.Xr chroot 8
environment in the newly installed system and can be used to set up
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
If using
.Cm zfsboot
in an installation script, the
.Cm zfsboot
partitioning tool takes the
.Ev ZFSBOOT_DATASETS
variable to create the ZFS datasets on the base system.
This variable definition can become large if the pool contains many datasets.
The default value of
.Ev ZFSBOOT_DATASETS
is:
.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=/

# Home directories separated so they are common to all BEs
/home		mountpoint=/home

# Create /tmp and 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

# Ports tree
/usr/ports	setuid=off

# Source tree
/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 is the name of the dataset to be created as part of the
.Ev ZFSBOOT_POOL_NAME
pool and the remainder of each line contains the options to be set on each dataset.
If multiple options are given, they can be separated by either commas or whitespace;
everything following a pound/hash character is ignored as a comment.
.Ss BUILDING AUTOMATIC INSTALL MEDIA
If building automatic install media, use tar to extract a release ISO:
.Dl mkdir release-media
.Dl tar -C release-media -xvf FreeBSD-13.0-RELEASE-amd64-disc1.iso
.Pp
Then place a script as above in
.Pa etc/installerconfig
.Pp
This directory can then be used directly as an NFS root for
.Xr diskless 8
installations or it can be rebuilt into an ISO image using the release scripts in
.Pa /usr/src/release .
For example, on amd64:
.Dl sh /usr/src/release/amd64/mkisoimages.sh -b '13_0_RELEASE_AMD64_CD' output.iso release-media
.Sh HISTORY
This version of
.Nm
first appeared in
.Fx 9.0 .
.Sh AUTHORS
.An Nathan Whitehorn Aq Mt nwhitehorn@FreeBSD.org
.An Devin Teske Aq Mt dteske@FreeBSD.org
.An Allan Jude Aq Mt allanjude@FreeBSD.org