--- name: "bsdinstall" section: "8" platform: "freebsd" package: "base" version: "16.0-CURRENT-20261027-61c70dc16a79" release: "FreeBSD 16.0-CURRENT (2026-10-27)" platforms: ["freebsd"] url: "https://new.carta.tech/bsdinstall" --- # bsdinstall(8) system installer ## NAME **bsdinstall** – system installer ## SYNOPSIS **bsdinstall** \[*options*\] \[*target*\] \[*...*\] ## DESCRIPTION **bsdinstall** 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. Much like [make(1)](/make/1.md), **bsdinstall** takes a target and possible parameters of the target as arguments. If invoked with no arguments, it will invoke the **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. ## 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. ## 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. - **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)](/jail/8.md). 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)](/syscons/4.md) or [vt(4)](/vt/4.md) console, asks the user to set the current keymap, and saves the result to the new system's *rc.conf*. - **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. - **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. - **autopart** Provides the installer's interactive guided disk partitioner for single-disk installations. Defaults to UFS. - **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)](/geli/8.md) to encrypt the disk. - **partedit** Provides the installer's interactive manual disk partitioner with an interface identical to [sade(8)](/sade/8.md). 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)](/gpart/8.md) 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)](/gpart/8.md) 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. - **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. - **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)](/fwget/8.md) inside the BSDINSTALL\_CHROOT to install any needed and available firmware for the new system. - **rootpass** Interactively invokes [passwd(1)](/passwd/1.md) in the new system to set the root user's password. - **adduser** Interactively invokes [adduser(8)](/adduser/8.md) 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*. - **entropy** Reads a small amount of data from */dev/random* and stores it in a file in the new system's root directory. - **config** Installs the configuration files destined for the new system, e.g., [rc.conf(5)](/rc.conf/5.md) fragments generated by **netconfig**, etc.) onto the new system. ## 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. - 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)](/pw/8.md) **-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 environment 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 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: “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)](/geli/8.md) to encrypt the root pool, enabling automatically the ZFSBOOT\_BOOT\_POOL variable. Default: “” - ZFSBOOT\_GELI\_KEY\_FILE Path to the [geli(8)](/geli/8.md) 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)](/loader/8.md). 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)](/gpart/8.md); which supports SI unit suffixes. Default: “2g” - ZFSBOOT\_SWAP\_ENCRYPTION If set, enables the encryption of the swap partition using [geli(8)](/geli/8.md). Default: "" - ZFSBOOT\_SWAP\_MIRROR If set, enables a swap mirroring using [gmirror(8)](/gmirror/8.md). 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 **bsdinstall** supports unattended, or minimally-attended, installations using scripting. This can be used with either modified physical installation media or with [diskless(8)](/diskless/8.md) installations over the network; information on preparing such media can be found in BUILDING AUTOMATIC INSTALL MEDIA 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). **bsdinstall** scripts consist of two parts: a *preamble* and a *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 [chroot(8)](/chroot/8.md) 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. This can be used for unattended network installation of new systems; see [diskless(8)](/diskless/8.md) for details. ### PREAMBLE The preamble consists of installer settings. These control global installation parameters (see ENVIRONMENT VARIABLES) as well as disk partitioning. The preamble is interpreted as a [sh(1)](/sh/1.md) 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 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). If 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. ### 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)](/chroot/8.md) 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. ### ZFS DATASETS If 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. 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 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)](/diskless/8.md) 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. ## AUTHORS Nathan Whitehorn ⟨*nwhitehorn@FreeBSD.org*⟩ Devin Teske ⟨*dteske@FreeBSD.org*⟩ Allan Jude ⟨*allanjude@FreeBSD.org*⟩