Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
BSDINSTALL(8)		FreeBSD	System Manager's Manual		 BSDINSTALL(8)

     bsdinstall	-- system installer

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

     bsdinstall	is used	for installation of new	systems, both for system setup
     from installation media, e.g., CD-ROMs, and for use on live systems to
     prepare VM	images and jails.

     Much like make(1),	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, in-
     voking the	others in sequence.  To	perform	a scripted installation, these
     subtargets	can be invoked separately by an	installation script.

     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

     Most of the following targets are only useful for scripting the in-
     staller.  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.

     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

     script script     Runs the	installation script at script.	See SCRIPTING
		       for more	information on 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.

     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 in-
		       voking 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	parti-
		       tioner 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 parti-
		       tioner.	Creates	a single zpool with separate datasets
		       for /tmp, /usr, /usr/home, /usr/ports, /usr/src,	and
		       /var.  Optionally can set up geli(8) to encrypt the

     partedit	       Provides	the installer's	interactive manual disk	parti-
		       tioner with an interface	identical to sade(8).  Sup-
		       ports multiple disks as well as UFS, ZFS, and FAT file
		       systems.	 ZFS is	set up with one	pool and dataset per

     scriptedpart parameters
		       Sets up disks like autopart and partedit, but non-in-
		       teractively 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 op-
		       tional and specifies how	to partition disk.  It con-
		       sists 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	kilo-
		       bytes, 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,	free-
		       bsd-zfs,	or freebsd-swap.  The optional mount point ar-
		       gument sets where the created partition is to be
		       mounted in the installed	system.	 As an example,	a typ-
		       ical 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

     distfetch	       Fetches the distributions in DISTRIBUTIONS to

     checksum	       Verifies	the checksums of the distributions listed in
		       DISTRIBUTIONS against the distribution manifest.

     distextract       Extracts	the distributions listed in DISTRIBUTIONS into

     rootpass	       Interactively invokes passwd(1) in the new system to
		       set the root user's password.

     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 sys-
		       tem'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)	fragments generated by
		       netconfig, etc.)	onto the new system.

     The following environment variables control various aspects of the	in-
     stallation	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 overrid-
     den when making scripted or customized installers.

     TMPDIR		  The directory	to use for temporary files.  Default:

     DISTRIBUTIONS	  The set of distributions to install, e.g., "base.txz
			  kernel.txz ports.txz".  Default: unset

     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 un-
			  set, 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).  De-
			  fault: "/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	archi-
			  tecture 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:

     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:

     BSDINSTALL_TMPETC	  Directory where files	destined for the new system's
			  /etc will be stored until the	config target is exe-
			  cuted.  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 exe-
			  cuted.  If this directory does not already exist, it
			  will be created.  Default: "$TMPDIR/bsdinstall_boot"

     ZFSBOOT_POOL_NAME	  Name for the pool containing the base	system.	 De-
			  fault: "zroot"

			  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 zpool.
			  Default: "-O compress=lz4 -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.	De-
			  fault: "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 Redun-
			  dancy	RAID).	Default: "stripe"

			  Indicates either the pool will use 4K	or 512 sec-
			  tors.	 If this variable is not empty,	4K sectors
			  will be used.	 Default: "1"

			  If this variable is not empty, it will use geli(8)
			  to encrypt the root pool, enabling automatically the
			  ZFSBOOT_BOOT_POOL variable.  Default:	""

			  Path to the geli(8) keyfile used to encrypt the pool
			  where	the base system	is stored.  Default:

     ZFSBOOT_BOOT_POOL	  If set a separated boot pool will be created for the
			  kernel of the	system and loader(8).  Default:	unset

			  Options to use when creating the boot	pool, when en-
			  abled	(See ZFSBOOT_BOOT_POOL ). Default: unset

			  Name for the optional	boot pool when it is enabled,
			  (See ZFSBOOT_BOOT_POOL ). Default: "bootpool"

			  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 in-
			  formation.  Default: unset

     ZFSBOOT_SWAP_SIZE	  Size of the swap partition on	each block device.
			  This variable	will be	passed to gpart(8); which sup-
			  ports	SI unit	suffixes.  Default: "2g"

			  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 re-
			  quires the following datasets: /tmp, /var/tmp,
			  DATASETS for more information	about who to write
			  this variable	and to take a look into	the default
			  value	of it.

			  If set and the installation is interactive, allow
			  the user to confirm the layout before	continuing
			  with the installation.  Default: "1"

     bsdinstall	supports unattended, or	minimally-attended, installations us-
     ing scripting.  This can be used with either modified physical installa-
     tion media	or with	diskless(8) installations over the network; informa-
     tion on preparing such media can be found in BUILDING AUTOMATIC INSTALL

     Scripted installations follow an essentially identical path to interac-
     tive installations, though	with some minor	feature	differences (for exam-
     ple, scripted installations do not	support	fetching of remote distribu-
     tion 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 sec-
     ond part is 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:

	   DISTRIBUTIONS="kernel.txz base.txz"

	   sysrc ifconfig_DEFAULT=DHCP
	   sysrc sshd_enable=YES
	   pkg install puppet

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

	   DISTRIBUTIONS="kernel.txz base.txz"
	   export ZFSBOOT_VDEV_TYPE=stripe
	   export ZFSBOOT_DISKS="ada0 ada1"
	   export nonInteractive="YES"

	   echo	"ifconfig_DEFAULT=DHCP"	>> /etc/rc.conf
	   echo	"sshd_enable=YES" >> /etc/rc.conf
	   pkg install 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) for details.

     The preamble consists of installer	settings.  These control global	in-
     stallation	parameters (see	ENVIRONMENT VARIABLES) as well as disk parti-
     tioning.  The preamble is interpreted as a	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 ENVIRONMENT VARIABLES, in
     particular	DISTRIBUTIONS, 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 con-
     tain the variable ZFSBOOT_DATASETS	instead	of PARTITIONS (see below).  If
     using .Cm 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, this two variables looks like this:

	   ZFSBOOT_DISKS="ada0 ada1"

     Remember to export	all the	variables for the zfsboot command, otherwise
     installation will fail.

     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
     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.

     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 con-
     tains many	datasets.  The default value of	the ZFSBOOT_DATASETS is:

	   # DATASET	   OPTIONS (comma or space separated; or both)

	   # Boot Environment [BE] root	and default boot dataset
	   /$ZFSBOOT_BEROOT_NAME			   mountpoint=none

	   # 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)

	   # 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	op-
     tions 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.

     If	building automatic install media, use tar to extract a release ISO:
	   mkdir release-media
	   tar xvf -C release-media 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/ -b '13_0_RELEASE_AMD64_CD'
	   output.iso release-media

     This version of bsdinstall	first appeared in FreeBSD 9.0.

     Nathan Whitehorn <>
     Devin Teske <>
     Allan Jude	<>

FreeBSD	13.0			 July 18, 2022			  FreeBSD 13.0


Want to link to this manual page? Use this URL:

home | help