1.\"- 2.\" Copyright (c) 2011-2013 Nathan Whitehorn <nwhitehorn@FreeBSD.org> All rights reserved. 3.\" Copyright (c) 2018 Roberto Fernandez Cueto <roberfern@gmail.com> 4.\" 5.\" Redistribution and use in source and binary forms, with or without 6.\" modification, are permitted provided that the following conditions 7.\" are met: 8.\" 1. Redistributions of source code must retain the above copyright 9.\" notice, this list of conditions and the following disclaimer. 10.\" 2. Redistributions in binary form must reproduce the above copyright 11.\" notice, this list of conditions and the following disclaimer in the 12.\" documentation and/or other materials provided with the distribution. 13.\" 14.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR 15.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED 16.\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 17.\" DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, 18.\" INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES 19.\" (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR 20.\" SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 21.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, 22.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN 23.\" ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 24.\" POSSIBILITY OF SUCH DAMAGE. 25.\" 26.\" $FreeBSD$ 27.\" 28.Dd July 18, 2022 29.Dt BSDINSTALL 8 30.Os 31.Sh NAME 32.Nm bsdinstall 33.Nd system installer 34.Sh SYNOPSIS 35.Nm 36.Op Ar options 37.Op Ar target 38.Op Ar ... 39.Sh DESCRIPTION 40.Nm 41is used for installation of new systems, both for system setup from 42installation media, e.g., CD-ROMs, and for use on live systems to prepare 43VM images and jails. 44.Pp 45Much like 46.Xr make 1 , Nm 47takes a target and possible parameters of the target as arguments. 48If invoked with no arguments, it will invoke the 49.Cm auto 50target, which provides a standard interactive installation, invoking the 51others in sequence. 52To perform a scripted installation, 53these subtargets can be invoked separately by an installation script. 54.Sh OPTIONS 55.Nm 56supports the following options, global to all targets: 57.Bl -tag -width indent+ 58.It Fl D Ar file 59Provide a path for the installation log file 60.Pq overrides Ev BSDINSTALL_LOG . 61See 62.Sx ENVIRONMENT VARIABLES 63for more information on 64.Ev BSDINSTALL_LOG . 65.El 66.Sh TARGETS 67Most of the following targets are only useful for scripting the installer. 68For interactive use, most users will be interested only in the 69.Cm auto , 70.Cm jail , 71and 72.Cm script 73targets. 74.Bl -tag -width ".Cm jail Ar destination" 75.It Cm auto 76Run the standard interactive installation, including disk partitioning. 77.It Cm jail Ar destination 78Sets up a new chroot system at 79.Pa destination , 80suitable for use with 81.Xr jail 8 . 82Behavior is generally similar to 83.Cm auto , 84except that disk partitioning and network setup are skipped and a kernel is 85not installed into the new system. 86.It Cm script Ar script 87Runs the installation script at 88.Pa script . 89See 90.Sx SCRIPTING 91for more information on this target. 92.It Cm keymap 93If the current controlling TTY is a 94.Xr syscons 4 95or 96.Xr vt 4 97console, asks the user to set the current keymap, and saves the result to the 98new system's 99.Pa rc.conf . 100.It Cm hostname 101Prompts the user for a host name for the new system and saves the result to the 102new system's 103.Pa rc.conf . 104If 105.Ev BSDINSTALL_CONFIGCURRENT 106is set, also sets the host name of the current system. 107.It Cm netconfig 108Interactively configures network interfaces (first invoking 109.Cm wlanconfig 110on wireless interfaces), saving the result to the new system's 111.Pa rc.conf 112and 113.Pa resolv.conf . 114If 115.Ev BSDINSTALL_CONFIGCURRENT 116is set, also configures the network interfaces of the current system to match. 117.It Cm autopart 118Provides the installer's interactive guided disk partitioner for single-disk 119installations. 120Defaults to UFS. 121.It Cm bootconfig 122Detects an appropriate partition and installs UEFI boot loader files. 123.It Cm zfsboot 124Provides a ZFS-only automatic interactive disk partitioner. 125Creates a single 126.Ic zpool 127with separate datasets for 128.Pa /tmp , 129.Pa /usr , 130.Pa /usr/home , 131.Pa /usr/ports , 132.Pa /usr/src , 133and 134.Pa /var . 135Optionally can set up 136.Xr geli 8 137to encrypt the disk. 138.It Cm partedit 139Provides the installer's interactive manual disk partitioner with an interface 140identical to 141.Xr sade 8 . 142Supports multiple disks as well as UFS, ZFS, and FAT file systems. 143ZFS is set up with one pool and dataset per partition. 144.It Cm scriptedpart Ar parameters 145Sets up disks like 146.Cm autopart 147and 148.Cm partedit , 149but non-interactively according to the disk setup specified in 150.Ar parameters . 151Each disk setup is specified by a three-part argument: 152.Pp 153.Ar disk 154.Op Ar scheme 155.Op Ar {partitions} 156.Pp 157Multiple disk setups are separated by semicolons. 158The 159.Ar disk 160argument specifies the disk on which to operate (which will be erased), 161or the special value 162.Em DEFAULT , 163which will result in either a selection window (as in 164.Cm autopart ) 165for the destination disk or, if there is only one possible disk, will 166automatically select it. 167The 168.Ar scheme 169argument specifies the 170.Xr gpart 8 171partition scheme to apply to the disk. 172If 173.Ar scheme 174is unspecified, 175.Cm scriptedpart 176will apply the default bootable scheme on your platform. 177The 178.Ar partitions 179argument is also optional and specifies how to partition 180.Ar disk . 181It consists of a comma-separated list of partitions to create enclosed in 182curly braces. 183Each partition declaration takes the form 184.Pp 185.Ar size 186.Ar type 187.Op Ar mount point 188.Pp 189.Ar size 190specifies the partition size to create in bytes (K, M, and G suffixes 191can be appended to specify kilobytes, megabytes, and gigabytes respectively), 192while the 193.Em auto 194keyword causes the partition to take all the remaining space on the disk. 195The 196.Ar type 197option chooses the 198.Xr gpart 8 199filesystem type, e.g., freebsd-ufs, freebsd-zfs, or freebsd-swap. 200The optional 201.Ar mount point 202argument sets where the created partition is to be mounted in the installed 203system. 204As an example, a typical invocation looks like: 205.Pp 206bsdinstall scriptedpart ada0 { 20G freebsd-ufs /, 4G freebsd-swap, 20G freebsd-ufs /var, auto freebsd-ufs /usr } 207.Pp 208Note that the list of partitions should 209.Em not 210include boot partitions (e.g. EFI system partitions), which will be created automatically on whatever disk includes /. 211.Pp 212A shorter invocation to use the default partitioning (as 213.Cm autopart 214would have used) on the same disk: 215.Pp 216bsdinstall scriptedpart ada0 217.Pp 218or, even shorter: 219.Pp 220bsdinstall scriptedpart DEFAULT 221.It Cm mount 222Mounts the file systems previously configured by 223.Cm autopart , 224.Cm partedit , 225or 226.Cm scriptedpart 227under 228.Ev BSDINSTALL_CHROOT . 229.It Cm distfetch 230Fetches the distributions in 231.Ev DISTRIBUTIONS 232to 233.Ev BSDINSTALL_DISTDIR 234from 235.Ev BSDINSTALL_DISTSITE . 236.It Cm checksum 237Verifies the checksums of the distributions listed in 238.Ev DISTRIBUTIONS 239against the distribution manifest. 240.It Cm distextract 241Extracts the distributions listed in 242.Ev DISTRIBUTIONS 243into 244.Ev BSDINSTALL_CHROOT . 245.It Cm rootpass 246Interactively invokes 247.Xr passwd 1 248in the new system to set the root user's password. 249.It Cm adduser 250Interactively invokes 251.Xr adduser 8 252in the new system. 253.It Cm time 254Interactively sets the time, date, and time zone of the new system. 255.It Cm services 256Queries the user for the system daemons to begin at system startup, 257writing the result into the new system's 258.Pa rc.conf . 259.It Cm entropy 260Reads a small amount of data from 261.Pa /dev/random 262and stores it in a file in the new system's root directory. 263.It Cm config 264Installs the configuration files destined for the new system, e.g., 265.Xr rc.conf 5 266fragments generated by 267.Cm netconfig , 268etc.) onto the new system. 269.El 270.Sh ENVIRONMENT VARIABLES 271The following environment variables control various aspects of the installation 272process. 273Many are used internally during installation and have reasonable default values 274for most installation scenarios. 275Others are set by various interactive user prompts, and can be usefully 276overridden when making scripted or customized installers. 277.Bl -tag -width ".Ev BSDINSTALL_DISTSITE" 278.It Ev TMPDIR 279The directory to use for temporary files. 280Default: 281.Dq Pa /tmp 282.It Ev DISTRIBUTIONS 283The set of distributions to install, e.g., "base.txz kernel.txz ports.txz". 284Default: unset 285.It Ev PARTITIONS 286The partitioning of the disk onto which the system is being installed. 287See 288.Cm scriptedpart 289of 290the 291.Sx TARGETS 292section for format details. If this variable is unset, the installer will 293use the default partitioning as in 294.Cm autopart . 295Default: unset 296.It Ev BSDINSTALL_DISTDIR 297The directory in which the distribution files can be found (or to which they 298should be downloaded). 299Default: 300.Dq Pa /usr/freebsd-dist 301.It Ev BSDINSTALL_DISTSITE 302URL from which the distribution files should be downloaded if they are not 303already present in the directory defined by 304.Ev BSDINSTALL_DISTDIR . 305This should be a full path to the files, including architecture and release 306names. 307Most targets, e.g., 308.Cm auto 309and 310.Cm jail , 311that prompt for a 312.Fx 313mirror will skip that step if this variable is already defined in the 314environment. 315Example: 316.Pa https://download.freebsd.org/ftp/releases/powerpc/powerpc64/13.1-RELEASE/ 317or 318.Pa http://ftp-archive.freebsd.org/pub/FreeBSD-Archive/old-releases/amd64/12.2-RELEASE/ . 319.It Ev BSDINSTALL_CHROOT 320The directory into which the distribution files should be unpacked and the 321directory at which the root file system of the new system should be mounted. 322Default: 323.Dq Pa /mnt 324.It Ev BSDINSTALL_LOG 325Path to a log file for the installation. 326Default: 327.Dq Pa $TMPDIR/bsdinstall_log 328.It Ev BSDINSTALL_TMPETC 329Directory where files destined for the new system's 330.Pa /etc 331will be stored until the 332.Cm config 333target is executed. 334If this directory does not already exist, it will be created. 335Default: 336.Dq Pa $TMPDIR/bsdinstall_etc 337.It Ev BSDINSTALL_TMPBOOT 338Directory where files destined for the new system's 339.Pa /boot 340will be stored until the 341.Cm config 342target is executed. 343If this directory does not already exist, it will be created. 344Default: 345.Dq Pa $TMPDIR/bsdinstall_boot 346.It Ev ROOTPASS_ENC 347Encrypted string to set the root password to in the format expected by 348.Xr pw 8 349.Fl H Ar 0 . 350This option is used if both it and 351.Ev ROOTPASS_PLAIN 352are set. 353.It Ev ROOTPASS_PLAIN 354Plain text string to set the root password to. 355.It Ev ZFSBOOT_POOL_NAME 356Name for the pool containing the base system. 357Default: 358.Dq zroot 359.It Ev ZFSBOOT_POOL_CREATE_OPTIONS 360Options to be used when creating the base system's pool. 361Each option must be preceded by the -O flag to be taken into consideration 362or the pool will not be created due to errors using the command 363.Cm zpool . 364Default: 365.Dq Li "-O compress=lz4 -O atime=off" 366.It Ev ZFSBOOT_BEROOT_NAME 367Name for the boot environment parent dataset. 368This is a non-mountable dataset meant to be a parent dataset where different 369boot environment are going to be created. 370Default: 371.Dq ROOT 372.It Ev ZFSBOOT_BOOTFS_NAME 373Name for the primary boot environment, which will be the default boot 374environment for the system. 375Default: 376.Dq default 377.It Ev ZFSBOOT_VDEV_TYPE 378The type of pool to be created for the base system. 379This variable can take one of this values: stripe (No redundancy), 380mirror (n-Way mirroring), raid10 (RAID 1+0 - n x 2-Way Mirrors), 381raidz1 (RAID-Z1 - Single Redundancy RAID), raidz2 (RAID-Z2 - Double Redundancy RAID) 382or raidz3 (RAID-Z3 Triple Redundancy RAID). 383Default: 384.Dq stripe 385.It Ev ZFSBOOT_FORCE_4K_SECTORS 386Indicates either the pool will use 4K or 512 sectors. 387If this variable is not empty, 4K sectors will be used. 388Default: 389.Dq 1 390.It Ev ZFSBOOT_GELI_ENCRYPTION 391If this variable is not empty, it will use 392.Xr geli 8 393to encrypt the root pool, enabling automatically the 394.Ev ZFSBOOT_BOOT_POOL 395variable. 396Default: 397.Dq "" 398.It Ev ZFSBOOT_GELI_KEY_FILE 399Path to the 400.Xr geli 8 401keyfile used to encrypt the pool where the base system is stored. 402Default: 403.Dq Pa /boot/encryption.key 404.It Ev ZFSBOOT_BOOT_POOL 405If set, a separated boot pool will be created for the kernel of the 406system and 407.Xr loader 8 . 408Default: unset 409.It Ev ZFSBOOT_BOOT_POOL_CREATE_OPTIONS 410Options to use when creating the boot pool, when enabled (See 411.Ev ZFSBOOT_BOOT_POOL ). 412Default: unset 413.It Ev ZFSBOOT_BOOT_POOL_NAME 414Name for the optional boot pool when it is enabled, (See 415.Ev ZFSBOOT_BOOT_POOL ). 416Default: 417.Dq bootpool 418.It Ev ZFSBOOT_BOOT_POOL_SIZE 419Size of the boot pool when it is enabled (See 420.Ev ZFSBOOT_BOOT_POOL ). 421Default: 422.Dq 2g 423.It Ev ZFSBOOT_DISKS 424Disks to be used for the base system, including the boot pool. 425This variable must only be used on a scripted installation. 426See 427.Sx SCRIPTING 428for more information. 429Default: unset 430.It Ev ZFSBOOT_SWAP_SIZE 431Size of the swap partition on each block device. 432This variable will be passed to 433.Xr gpart 8 ; 434which supports SI unit suffixes. 435Default: 436.Dq 2g 437.It Ev ZFSBOOT_SWAP_ENCRYPTION 438If set, enables the encryption of the swap partition using 439.Xr geli 8 . 440Default: "" 441.It Ev ZFSBOOT_SWAP_MIRROR 442If set, enables a swap mirroring using 443.Xr gmirror 8 . 444Default: 445unset 446.It Ev ZFSBOOT_DATASETS 447ZFS datasets to be created on the root zpool, it requires the 448following datasets: 449.Pa /tmp , 450.Pa /var/tmp , 451.Pa /$ZFSBOOT_BEROOT_NAME/$ZFSBOOT_BOOTFS_NAME . 452See 453.Sx ZFS DATASETS 454for more information about how to populate this variable and 455its default value. 456.It Ev ZFSBOOT_CONFIRM_LAYOUT 457If set and the installation is interactive, allow the user to confirm 458the layout before continuing with the installation. 459Default: 460.Dq 1 461.El 462.Sh SCRIPTING 463.Nm 464supports unattended, or minimally-attended, installations using scripting. 465This can be used with either modified physical installation media or with 466.Xr diskless 8 467installations over the network; information on preparing such media can be 468found in 469.Sx BUILDING AUTOMATIC INSTALL MEDIA 470.Pp 471Scripted installations follow an essentially identical path to interactive 472installations, though with some minor feature differences (for example, 473scripted installations do not support fetching of remote distribution files 474since scripted installations normally install the same files and the distributions 475can be added directly to the installation media). 476.Nm 477scripts consist of two parts: a 478.Em preamble 479and a 480.Em setup script . 481The preamble sets up the options for the installation (how to partition the 482disk[s], which distributions to install, etc.) and the optional second part is 483a shell script run under 484.Xr chroot 8 485in the newly installed system before 486.Nm 487exits. 488The two parts are separated by the usual script header (#!), which also sets 489the interpreter for the setup script. 490.Pp 491A typical bsdinstall script, using the default filesystem layout and the UFS 492filesystem, looks like this: 493.Bd -literal -offset indent 494PARTITIONS=DEFAULT 495DISTRIBUTIONS="kernel.txz base.txz" 496 497#!/bin/sh 498sysrc ifconfig_DEFAULT=DHCP 499sysrc sshd_enable=YES 500pkg install puppet 501.Ed 502.Pp 503For a scripted installation involving a ZFS pool spanning multiple disks, 504the script instead looks like this: 505.Bd -literal -offset indent 506DISTRIBUTIONS="kernel.txz base.txz" 507export ZFSBOOT_VDEV_TYPE=stripe 508export ZFSBOOT_DISKS="ada0 ada1" 509export nonInteractive="YES" 510 511#!/bin/sh 512echo "ifconfig_DEFAULT=DHCP" >> /etc/rc.conf 513echo "sshd_enable=YES" >> /etc/rc.conf 514pkg install puppet 515.Ed 516.Pp 517On 518.Fx 519release media, such a script placed at 520.Pa /etc/installerconfig 521will be run at boot time and the system will be rebooted automatically after 522the installation has completed. 523This can be used for unattended network installation of new systems; see 524.Xr diskless 8 525for details. 526.Ss PREAMBLE 527The preamble consists of installer settings. 528These control global installation parameters (see 529.Sx ENVIRONMENT VARIABLES ) 530as well as disk partitioning. 531The preamble is interpreted as a 532.Xr sh 1 533script run at the very beginning of the install. 534If more complicated behavior than setting these variables is desired, 535arbitrary commands can be run here to extend the installer. 536In addition to the variables in 537.Sx ENVIRONMENT VARIABLES , 538in particular 539.Ev DISTRIBUTIONS , 540the preamble can contain a variable 541.Ev PARTITIONS 542which is passed to the 543.Cm scriptedpart 544target to control disk setup. 545.Pp 546Alternatively, 547to use 548.Cm zfsboot 549instead of 550.Cm partedit , 551the preamble can contain the variable 552.Ev ZFSBOOT_DATASETS 553instead of 554.Ev PARTITIONS 555(see below). 556If using 557.Cm zfsboot , 558the variables 559.Ev ZFSBOOT_DISKS 560and 561.Ev ZFSBOOT_VDEV_TYPE 562must be set to create the pool of disks for the base system. 563Usually, for a mirrored booting disk, these two variables look like this: 564.Bd -literal -offset indent 565ZFSBOOT_DISKS="ada0 ada1" 566ZFSBOOT_VDEV_TYPE=mirror 567.Ed 568.Pp 569Remember to export all the variables for the 570.Cm zfsboot 571command, otherwise installation will fail. 572.Ss SETUP SCRIPT 573Following the preamble is an optional shell script, beginning with a #! 574declaration. 575This script will be run at the end of the installation process inside a 576.Xr chroot 8 577environment in the newly installed system and can be used to set up 578configuration files, install packages, etc. 579Note that newly configured system services, e.g., networking have not 580been started in the installed system at this time and only installation 581host services are available. 582.Ss ZFS DATASETS 583If using 584.Cm zfsboot 585in an installation script, the 586.Cm zfsboot 587partitioning tool takes the 588.Ev ZFSBOOT_DATASETS 589variable to create the ZFS datasets on the base system. 590This variable definition can become large if the pool contains many datasets. 591The default value of 592.Ev ZFSBOOT_DATASETS 593is: 594.Bd -literal -offset indent 595# DATASET OPTIONS (comma or space separated; or both) 596 597# Boot Environment [BE] root and default boot dataset 598/$ZFSBOOT_BEROOT_NAME mountpoint=none 599/$ZFSBOOT_BEROOT_NAME/$ZFSBOOT_BOOTFS_NAME mountpoint=/ 600 601# Compress /tmp, allow exec but not setuid 602/tmp mountpoint=/tmp,exec=on,setuid=off 603 604# Do not mount /usr so that 'base' files go to the BEROOT 605/usr mountpoint=/usr,canmount=off 606 607# Home directories separated so they are common to all BEs 608/usr/home # NB: /home is a symlink to /usr/home 609 610# Ports tree 611/usr/ports setuid=off 612 613# Source tree (compressed) 614/usr/src 615 616# Create /var and friends 617/var mountpoint=/var,canmount=off 618/var/audit exec=off,setuid=off 619/var/crash exec=off,setuid=off 620/var/log exec=off,setuid=off 621/var/mail atime=on 622/var/tmp setuid=off 623.Ed 624.Pp 625The first column is the name of the dataset to be created as part of the 626.Ev ZFSBOOT_POOL_NAME 627pool and the remainder of each line contains the options to be set on each dataset. 628If multiple options are given, they can be separated by either commas or whitespace; 629everything following a pound/hash character is ignored as a comment. 630.Ss BUILDING AUTOMATIC INSTALL MEDIA 631If building automatic install media, use tar to extract a release ISO: 632.Dl mkdir release-media 633.Dl tar -C release-media -xvf FreeBSD-13.0-RELEASE-amd64-disc1.iso 634.Pp 635Then place a script as above in 636.Pa etc/installerconfig 637.Pp 638This directory can then be used directly as an NFS root for 639.Xr diskless 8 640installations or it can be rebuilt into an ISO image using the release scripts in 641.Pa /usr/src/release . 642For example, on amd64: 643.Dl sh /usr/src/release/amd64/mkisoimages.sh -b '13_0_RELEASE_AMD64_CD' output.iso release-media 644.Sh HISTORY 645This version of 646.Nm 647first appeared in 648.Fx 9.0 . 649.Sh AUTHORS 650.An Nathan Whitehorn Aq Mt nwhitehorn@FreeBSD.org 651.An Devin Teske Aq Mt dteske@FreeBSD.org 652.An Allan Jude Aq Mt allanjude@FreeBSD.org 653