BSDINSTALL(8)

🦋 NAME 🦋

bsdinstall — system installer. Yes bestie, this is the bsdinstall(8) page, and it's literally the main character of installing a new system. 💅

---

✨ SYNOPSIS ✨

bsdinstall [options] [target] [...]

---

💖 DESCRIPTION 💖

bsdinstall is used for installation of new systems — both for system setup from installation media (think discs, USBs, or network boot environments) and for use on live systems to prepare jails and virtual machine images. It's giving "one tool, many moods." 🎀

Much like make(1), bsdinstall takes a target and possible parameters of the target as arguments. If you invoke it with no arguments, it will invoke the auto target, which provides a standard interactive installation, invoking the others in sequence. So no args = the whole guided vibe. 🫶

To perform a scripted installation, these subtargets can be invoked separately by an installation script. Script girlies, this one's for you. 💻✨

---

🌸 OPTIONS 🌸

bsdinstall supports the following options, global to all targets:

• -D file — Provide a path for the installation log file (overrides BSDINSTALL_LOG). See “ENVIRONMENT VARIABLES” for more information on BSDINSTALL_LOG. Log it, don't lose it. 📝

---

🔥 TARGETS 🔥

Most of the following targets are only useful for scripting the installer. For interactive use, most users will be interested only in the auto, jail, and script targets. The rest are lowkey for the automation girlies. 🤖

• auto — Run the standard interactive installation, including disk partitioning.

The DISTRIBUTIONS environment variable is set to “base.txz kernel.txz” by default for this target.

• jail destination — Sets up a new chroot system at destination, suitable for use with jail(8). Behavior is generally similar to auto, except that disk partitioning and network setup are skipped and a kernel is not installed into the new system.

The DISTRIBUTIONS environment variable is set to “base.txz” by default for this target.

• script script — Runs the installation script at script. See “SCRIPTING” for more information on this target.

The DISTRIBUTIONS environment variable is unset by default for this target. Instead, the COMPONENTS environment variable is effectively set to “base kernel kernel-dbg” for this target.

• keymap — If the current controlling TTY is a syscons(4) or vt(4) console, asks the user to set the current keymap, and saves the result to the new system's rc.conf. Keyboard glow-up, secured. ⌨️✨
• hostname — Prompts the user for a host name for the new system and saves the result to the new system's rc.conf. If BSDINSTALL_CONFIGCURRENT is set, also sets the host name of the current system. Name reveal moment. 🏷️
• netconfig — Interactively configures network interfaces (first invoking wlanconfig on wireless interfaces), saving the result to the new system's rc.conf and resolv.conf. If BSDINSTALL_CONFIGCURRENT is set, also configures the network interfaces of the current system to match. Wi-Fi bestie behavior. 📶
• autopart — Provides the installer's interactive guided disk partitioner for single-disk installations. Defaults to UFS. Slice it, dice it, UFS it. 💽
• bootconfig — Detects an appropriate partition and installs UEFI boot loader files.
• zfsboot — Provides a ZFS-only automatic interactive disk partitioner. Creates a single zpool with separate datasets for /home, /tmp, /usr, /usr/ports, /usr/src, and /var. Optionally can set up geli(8) to encrypt the disk. ZFS girlies rise. 🌊🔐
• partedit — Provides the installer's interactive manual disk partitioner with an interface identical to 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.
• scriptedpart parameters — Sets up disks like autopart and partedit, but non-interactively according to the disk setup specified in parameters. Each disk setup is specified by a three-part argument:

disk [scheme] [{partitions}]

Multiple disk setups are separated by semicolons. The disk argument specifies the disk on which to operate (which will be erased), or the special value DEFAULT, which will result in either a selection window (as in autopart) for the destination disk or, if there is only one possible disk, will automatically select it. The scheme argument specifies the gpart(8) partition scheme to apply to the disk. If scheme is unspecified, scriptedpart will apply the default bootable scheme on your platform. The partitions argument is also optional and specifies how to partition disk. It consists of a comma-separated list of partitions to create enclosed in curly braces. Each partition declaration takes the form:

size type [mount point]

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 auto keyword causes the partition to take all the remaining space on the disk. The type option chooses the gpart(8) filesystem type, e.g., freebsd-ufs, freebsd-zfs, or freebsd-swap. The optional mount point argument sets where the created partition is to be mounted in the installed system. As an example, a typical invocation looks like:

bsdinstall scriptedpart ada0 { 20G freebsd-ufs /, 4G freebsd-swap, 20G freebsd-ufs /var, auto freebsd-ufs /usr }

Note that the list of partitions should not include boot partitions (e.g. EFI system partitions), which will be created automatically on whatever disk includes /.

A shorter invocation to use the default partitioning (as autopart would have used) on the same disk:

bsdinstall scriptedpart ada0

or, even shorter:

bsdinstall scriptedpart DEFAULT

• mount — Mounts the file systems previously configured by autopart, partedit, or scriptedpart under BSDINSTALL_CHROOT. Mount up, bestie. 🗂️
• distfetch — Fetches the distributions in DISTRIBUTIONS to BSDINSTALL_DISTDIR from BSDINSTALL_DISTSITE.
• checksum — Verifies the checksums of the distributions listed in DISTRIBUTIONS against the distribution manifest. Trust but verify, no cap. ✅
• distextract — Extracts the distributions listed in DISTRIBUTIONS into BSDINSTALL_CHROOT.
• pkgbase [--jail] — Fetch and install base system packages to BSDINSTALL_CHROOT. Packages are fetched according to repository configuration in BSDINSTALL_PKG_REPOS_DIR if set, or pkg.freebsd.org otherwise. If the --jail option is passed, no kernel is installed, and the “jail” variant of each package set will be selected where applicable.
• firmware — Executes fwget(8) inside the BSDINSTALL_CHROOT to install any needed and available firmware for the new system. Firmware update era. 🔌
• rootpass — Interactively invokes passwd(1) in the new system to set the root user's password. Keep it secret, keep it safe. 🔐
• adduser — Interactively invokes adduser(8) in the new system.
• time — Interactively sets the time, date, and time zone of the new system. ⏰
• services — Queries the user for the system daemons to begin at system startup, writing the result into the new system's rc.conf. Daemon selection ceremony. 🧚
• entropy — Reads a small amount of data from /dev/random and stores it in a file in the new system's root directory. Entropy is literally the vibe. 🌀
• config — Installs the configuration files destined for the new system, e.g., rc.conf(5) fragments generated by netconfig, etc.) onto the new system.

✨ ENVIRONMENT VARIABLES ✨

okay bestie, these are the environment variables that control the installation process. 💖 A bunch of them are used internally during installation and come with reasonable default values for most installation scenarios. Others get set by various interactive user prompts, and you can usefully override them when you're making scripted or customized installers. slay. 🎀

---

• TMPDIR — the directory to use for temporary files. Default: /tmp. 🦋
• COMPONENTS — the set of components to install for scripted installations using base system packages, e.g., base lib32 kernel-dbg tests. Default: "base kernel-dbg". ✨
• DISTRIBUTIONS — the set of distributions to install for traditional installations, e.g., base.txz kernel.txz ports.txz. If unset, then bsdinstall will install using base system packages. Default: unset unless noted otherwise in the TARGETS section. 💅
• PARTITIONS — the partitioning of the disk onto which the system is being installed. See scriptedpart of the TARGETS section for format details. If this variable is unset, the installer will use the default partitioning as in autopart. Default: unset. 🌸
• BSDINSTALL_DISTDIR — the directory in which the distribution files can be found (or to which they should be downloaded). Default: /usr/freebsd-dist. 🫶
• BSDINSTALL_DISTSITE — URL from which the distribution files should be downloaded if they are not already present in the directory defined by BSDINSTALL_DISTDIR. This should be a full path to the files, including architecture and release names. Most targets, e.g., auto and jail, that prompt for a FreeBSD mirror will skip that step if this variable is already defined in the environment. Example: https://download.freebsd.org/ftp/releases/powerpc/powerpc64/13.1-RELEASE/ or http://ftp-archive.freebsd.org/pub/FreeBSD-Archive/old-releases/amd64/12.2-RELEASE/. 🔥
• BSDINSTALL_PKG_REPOS_DIR — directory containing pkg(8) repository configuration files used by the pkgbase target. See “REPOSITORY CONFIGURATION” in pkg.conf(5). Default: unset. 🧚
• 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: /mnt. 🌈
• BSDINSTALL_LOG — path to a log file for the installation. Default: $TMPDIR/bsdinstall_log. ⭐
• BSDINSTALL_SKIP_FIRMWARE — if not empty, the auto target will not invoke the firmware target. 💜
• BSDINSTALL_SKIP_HARDENING — if not empty, the auto target will not invoke the hardening target. 🎀
• BSDINSTALL_SKIP_HOSTNAME — if not empty, the auto target will not invoke the hostname target. 🦋
• BSDINSTALL_SKIP_KEYMAP — if not empty, the auto target will not invoke the keymap target. ✨
• BSDINSTALL_SKIP_MANUAL — if not empty, the auto target will not offer to open a shell in the new system for final manual modifications. 💅
• BSDINSTALL_SKIP_SERVICES — if not empty, the auto target will not invoke the services target. 🌸
• BSDINSTALL_SKIP_TIME — if not empty, the auto target will not invoke the time target. 🫶
• BSDINSTALL_SKIP_USERS — if not empty, the auto target will not invoke the adduser target. 🔥
• BSDINSTALL_SKIP_FINALCONFIG — if not empty, the auto target will not show the final configuration dialog, where earlier configuration choices can be revisited. 🧚
• BSDINSTALL_TMPETC — directory where files destined for the new system's /etc will be stored until the config target is executed. If this directory does not already exist, it will be created. Default: $TMPDIR/bsdinstall_etc. 🌈
• BSDINSTALL_TMPBOOT — directory where files destined for the new system's /boot will be stored until the config target is executed. If this directory does not already exist, it will be created. Default: $TMPDIR/bsdinstall_boot. ⭐
• ROOTPASS_ENC — encrypted string to set the root password to in the format expected by pw(8) -H 0. This option is used if both it and ROOTPASS_PLAIN are set. 💜
• ROOTPASS_PLAIN — plain text string to set the root password to. 🎀
• ZFSBOOT_POOL_NAME — name for the pool containing the base system. Default: zroot. 🦋
• 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 zpool. Default: -O compression=on -O atime=off. ✨
• 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 environments are going to be created. Default: ROOT. 💅
• ZFSBOOT_BOOTFS_NAME — name for the primary boot environment, which will be the default boot environment for the system. Default: default. 🌸
• ZFSBOOT_VDEV_TYPE — the type of pool to be created for the base system. This variable can take one of these 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: stripe. 🫶
• 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: 1. 🔥
• ZFSBOOT_GELI_ENCRYPTION — if this variable is not empty, it will use geli(8) to encrypt the root pool, enabling automatically the ZFSBOOT_BOOT_POOL variable. Default: "". 🧚
• ZFSBOOT_GELI_KEY_FILE — path to the geli(8) keyfile used to encrypt the pool where the base system is stored. Default: /boot/encryption.key. 🌈
• ZFSBOOT_BOOT_POOL — if set, a separated boot pool will be created for the kernel of the system and loader(8). Default: unset. ⭐
• ZFSBOOT_BOOT_POOL_CREATE_OPTIONS — options to use when creating the boot pool, when enabled (see ZFSBOOT_BOOT_POOL). Default: unset. 💜
• ZFSBOOT_BOOT_POOL_NAME — name for the optional boot pool when it is enabled (see ZFSBOOT_BOOT_POOL). Default: bootpool. 🎀
• ZFSBOOT_BOOT_POOL_SIZE — size of the boot pool when it is enabled (see ZFSBOOT_BOOT_POOL). Default: 2g. 🦋
• 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 SCRIPTING for more information. Default: unset. ✨
• ZFSBOOT_SWAP_SIZE — size of the swap partition on each block device. This variable will be passed to gpart(8), which supports SI unit suffixes. Default: 2g. 💅
• ZFSBOOT_SWAP_ENCRYPTION — if set, enables the encryption of the swap partition using geli(8). Default: "". 🌸
• ZFSBOOT_SWAP_MIRROR — if set, enables a swap mirroring using gmirror(8). Default: unset. 🫶
• ZFSBOOT_DATASETS — ZFS datasets to be created on the root zpool, it requires the following datasets: /tmp, /var/tmp, /$ZFSBOOT_BEROOT_NAME/$ZFSBOOT_BOOTFS_NAME. See “ZFS DATASETS” for more information about how to populate this variable and its default value. 🔥
• ZFSBOOT_CONFIRM_LAYOUT — if set and the installation is interactive, allow the user to confirm the layout before continuing with the installation. Default: 1. 🧚

💾 SCRIPTING 💾

okay so this is the part where bsdinstall gets ✨hands-free✨ — it supports unattended (or barely-attended) installations using scripting, and honestly it's giving main character energy. You can use this with either modified physical installation media or with diskless(8) installations over the network — and if you need to know how to prep that media, go read “BUILDING AUTOMATIC INSTALL MEDIA” (it's literally further down this page, bestie, keep scrolling).

Scripted installs follow an essentially identical path to interactive installs, though there are some minor feature differences — for example, scripted installations do not support fetching of remote distribution files, because scripted installations normally install the same files and the distributions can be added directly to the installation media. No cap.

A bsdinstall script is made of two parts:

1. a preamble — this sets up the options for the installation (how to partition the disk[s], which distributions to install, etc.)
2. an optional setup script — a shell script run under chroot(8) in the newly installed system before bsdinstall exits

The two parts are separated by the usual script header (#!), which also sets the interpreter for the setup script. 🎀

---

A typical bsdinstall script, using the default filesystem layout and the UFS filesystem, looks like this:

PARTITIONS=DEFAULT
COMPONENTS="base debug"

#!/bin/sh
sysrc ifconfig_DEFAULT=DHCP
sysrc sshd_enable=YES
pkg install -y puppet

For a scripted installation involving a ZFS pool spanning multiple disks, the script instead looks like this:

COMPONENTS="base debug"
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 -y puppet

To install using traditional distributions sets instead of packages, set DISTRIBUTIONS to the list of distribution sets to install, like this:

PARTITIONS=DEFAULT
DISTRIBUTIONS="kernel.txz base.txz"

#!/bin/sh
sysrc ifconfig_DEFAULT=DHCP
sysrc sshd_enable=YES
pkg install -y puppet

On FreeBSD release media, such a script placed at /etc/installerconfig will be run at boot time and the system will be rebooted automatically after the installation has completed 🔥 — perfect for unattended network installation of new systems; see diskless(8) for details.

🧚 PREAMBLE 🧚

The preamble is literally just installer settings. They control global installation parameters (peep “ENVIRONMENT VARIABLES”) as well as disk partitioning. The preamble is interpreted as a sh(1) script run at the very beginning of the install — so if you want more complicated behavior than setting these variables, you can run arbitrary commands right here to extend the installer. Obsessed.

In addition to the variables in “ENVIRONMENT VARIABLES”, in particular COMPONENTS, the preamble can contain a variable PARTITIONS which is passed to the scriptedpart target to control disk setup.

Alternatively, to use zfsboot instead of partedit, the preamble can contain the variable ZFSBOOT_DATASETS instead of PARTITIONS (see below, bestie 👀). If you're using zfsboot, the variables ZFSBOOT_DISKS and 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:

ZFSBOOT_DISKS="ada0 ada1"
ZFSBOOT_VDEV_TYPE=mirror

⚠️ Remember to export all the variables for the zfsboot command — otherwise installation will fail. fr fr, don't skip this one 😭

🌸 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 chroot(8) environment in the newly installed system, and it can be used to set up configuration files, install packages, etc.

Heads up: 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. So don't be surprised when your freshly-written rc.conf isn't doing anything yet 🙈

🦋 ZFS DATASETS 🦋

If you're using zfsboot in an installation script, the zfsboot partitioning tool takes the ZFSBOOT_DATASETS variable to create the ZFS datasets on the base system. This variable definition can become large if the pool contains many datasets (it's giving "I have a lot of folders and I'm not sorry"). The default value of ZFSBOOT_DATASETS is:

# 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

The first column is the name of the dataset to be created as part of the 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. 💅

⭐ BUILDING AUTOMATIC INSTALL MEDIA ⭐

If you're building automatic install media, use tar to extract a release ISO:

mkdir release-media
tar -C release-media -xvf FreeBSD-13.0-RELEASE-amd64-disc1.iso

Then place a script as above in etc/installerconfig

This directory can then be used directly as an NFS root for diskless(8) installations, or it can be rebuilt into an ISO image using the release scripts in /usr/src/release. For example, on amd64:

sh /usr/src/release/amd64/mkisoimages.sh -b
'13_0_RELEASE_AMD64_CD' output.iso release-media

---

📜 HISTORY 📜

This version of bsdinstall first appeared in FreeBSD 9.0. vintage 👑

🫶 AUTHORS 🫶

• Nathan Whitehorn <nwhitehorn@FreeBSD.org>
• Devin Teske <dteske@FreeBSD.org>
• Allan Jude <allanjude@FreeBSD.org>

---

and that's the whole page, bestie 🎀✨ This one shipped out from Debian on May 12, 2026 — go forth and install things unattended, you absolute icon 💖