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.

     zfsboot	       Provides	an alternative ZFS-only	automatic interactive
		       disk partitioner.  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 disk.

     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), while the scheme	argument spec-
		       ifies the gpart(8) partition scheme to apply to the
		       disk.  If scheme	is unspecified,	scriptedpart will ap-
		       ply 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	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 }

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

		       bsdinstall scriptedpart ada0

     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.

     DISTRIBUTIONS	  The set of distributions to install, e.g., "base
			  kernel ports".  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: "/tmp/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: "/tmp/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 redundacy), mirror (n-Way	mirroring), raid10
			  (RAID	1+0 - n	x 2-Way	Mirrors), raidz1 (RAID-Z1 -
			  Single Redundacy RAID), raidz2 (RAID-Z2 - Double Re-
			  dundacy RAID)	or raidz3 (RAID-Z3 Triple Redundacy
			  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	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 looks like this:

	   DISTRIBUTIONS="kernel.txz base.txz"

	   sysrc ifconfig_em0=DHCP
	   sysrc sshd_enable=YES
	   pkg install puppet

     For a ZFS scripted	installation, the script looks like this:

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

	   echo	"ifconfig_em0=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.	Alter-
     natively, to use zfsboot instead of partedit, the preamble	can contain
     the variable ZFSBOOT_DATASETS instead of PARTITIONS, and setting the
     variables ZFSBOOT_DISKS and 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:

	   ZFSBOOT_DISKS="ada0 ada1"

     Remenber to export	all the	variables for the zfsboot command, otherwise
     it	will not get set.

     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.

     The zfsboot partitioning takes the	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
     ZFSBOOT_DATASETS looks like this:

	   # 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 if the dataset to	be created on the top of the
     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 sepa-
     rated list, or both.  And everything behind a pound/hash character	is ig-
     nored as a	comment.

     This version of bsdinstall	first appeared in FreeBSD 9.0.

     Nathan Whitehorn <>

FreeBSD	13.0			October	4, 2018			  FreeBSD 13.0


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

home | help