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

NAME
     bsdinstall -- system installer

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

DESCRIPTION
     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 pre-
     pare 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,  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.

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

     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 invok-
		       ing 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 net-
		       work 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 disk.

     partedit	       Provides the installer's interactive manual  disk  parti-
		       tioner  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-inter-
		       actively   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  speci-
		       fies  the gpart(8) partition scheme to apply to the disk.
		       If scheme is unspecified, scriptedpart will apply the de-
		       fault 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  parti-
		       tions 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  in-
		       stalled	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
		       }

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

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

ENVIRONMENT VARIABLES
     The following environment variables control various aspects of the  instal-
     lation process.  Many are used internally during installation and have rea-
     sonable  default values for most installation scenarios.  Others are set by
     various interactive user prompts, and can be usefully overridden when  mak-
     ing scripted or customized installers.

     TMPDIR		  The  directory  to  use for temporary files.	Default:
			  "/tmp"

     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.  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 down-
			  loaded if they are not already present in  the  direc-
			  tory	defined by BSDINSTALL_DISTDIR.	This should be a
			  full path to the files, including architecture and re-
			  lease 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:
			  ftp://ftp.freebsd.org/pub/FreeBSD/releases/powerpc/powerpc64/9.1-RELEASE

     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_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"

     ZFSBOOT_POOL_CREATE_OPTIONS
			  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.   De-
			  fault: "-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  cre-
			  ated.  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 Re-
			  dundancy  RAID),  raidz2  (RAID-Z2 - Double Redundancy
			  RAID) or raidz3 (RAID-Z3 Triple Redundancy RAID).  De-
			  fault: "stripe"

     ZFSBOOT_FORCE_4K_SECTORS
			  Indicates either the pool will use 4K or 512	sectors.
			  If  this  variable  is  not  empty, 4K sectors will be
			  used.  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 en-
			  abled (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  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 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 re-
			  quires  the  following   datasets:   /tmp,   /var/tmp,
			  /$ZFSBOOT_BEROOT_NAME/$ZFSBOOT_BOOTFS_NAME.	See "ZFS
			  DATASETS" for more information about who to write this
			  variable and to take a look into the default value  of
			  it.

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

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

	   #!/bin/sh
	   gpart bootcode -b /boot/pmbr -p /boot/gptboot -i 1 ada0
	   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"

	   #!/bin/sh
	   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  in-
     stallation of new systems; see diskless(8) for details.

   PREAMBLE
     The  preamble consists of installer settings.  These control global instal-
     lation parameters (see "ENVIRONMENT VARIABLES") as well as disk  partition-
     ing.   The preamble is interpreted as a sh(1) script run at the very begin-
     ning of the install.  If more complicated behavior than setting these vari-
     ables is desired, arbitrary commands can be run  here  to	extend	the  in-
     staller.	In addition to the variables in "ENVIRONMENT VARIABLES", in par-
     ticular 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 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"
	   ZFSBOOT_VDEV_TYPE=mirror

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

   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
     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
     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
	   /$ZFSBOOT_BEROOT_NAME/$ZFSBOOT_BOOTFS_NAME	   mountpoint=/

	   # 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)
	   /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  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 separated
     list, or both.  And everything behind a pound/hash character is ignored  as
     a comment.

HISTORY
     This version of bsdinstall first appeared in FreeBSD 9.0.

AUTHORS
     Nathan Whitehorn <nwhitehorn@FreeBSD.org>

FreeBSD 13.0			February 6, 2020		   BSDINSTALL(8)

home | help