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 March 22, 2021 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), 161while the 162.Ar scheme 163argument specifies the 164.Xr gpart 8 165partition scheme to apply to the disk. 166If 167.Ar scheme 168is unspecified, 169.Cm scriptedpart 170will apply the default bootable scheme on your platform. 171The 172.Ar partitions 173argument is also optional and specifies how to partition 174.Ar disk . 175It consists of a comma-separated list of partitions to create enclosed in 176curly braces. 177Each partition declaration takes the form 178.Pp 179.Ar size 180.Ar type 181.Op Ar mount point 182.Pp 183.Ar size 184specifies the partition size to create in bytes (K, M, and G suffixes 185can be appended to specify kilobytes, megabytes, and gigabytes respectively), 186while the 187.Em auto 188keyword causes the partition to take all the remaining space on the disk. 189The 190.Ar type 191option chooses the 192.Xr gpart 8 193filesystem type, e.g., freebsd-ufs, freebsd-zfs, or freebsd-swap. 194The optional 195.Ar mount point 196argument sets where the created partition is to be mounted in the installed 197system. 198As an example, a typical invocation looks like: 199.Pp 200bsdinstall scriptedpart ada0 { 20G freebsd-ufs /, 4G freebsd-swap, 20G freebsd-ufs /var, auto freebsd-ufs /usr } 201.Pp 202Note that the list of partitions should 203.Em not 204include boot partitions (e.g. EFI system partitions), which will be created automatically on whatever disk includes /. 205.Pp 206A shorter invocation to use the default partitioning (as 207.Cm autopart 208would have used) on the same disk: 209.Pp 210bsdinstall scriptedpart ada0 211.It Cm mount 212Mounts the file systems previously configured by 213.Cm autopart , 214.Cm partedit , 215or 216.Cm scriptedpart 217under 218.Ev BSDINSTALL_CHROOT . 219.It Cm distfetch 220Fetches the distributions in 221.Ev DISTRIBUTIONS 222to 223.Ev BSDINSTALL_DISTDIR 224from 225.Ev BSDINSTALL_DISTSITE . 226.It Cm checksum 227Verifies the checksums of the distributions listed in 228.Ev DISTRIBUTIONS 229against the distribution manifest. 230.It Cm distextract 231Extracts the distributions listed in 232.Ev DISTRIBUTIONS 233into 234.Ev BSDINSTALL_CHROOT . 235.It Cm rootpass 236Interactively invokes 237.Xr passwd 1 238in the new system to set the root user's password. 239.It Cm adduser 240Interactively invokes 241.Xr adduser 8 242in the new system. 243.It Cm time 244Interactively sets the time, date, and time zone of the new system. 245.It Cm services 246Queries the user for the system daemons to begin at system startup, 247writing the result into the new system's 248.Pa rc.conf . 249.It Cm entropy 250Reads a small amount of data from 251.Pa /dev/random 252and stores it in a file in the new system's root directory. 253.It Cm config 254Installs the configuration files destined for the new system, e.g., 255.Xr rc.conf 5 256fragments generated by 257.Cm netconfig , 258etc.) onto the new system. 259.El 260.Sh ENVIRONMENT VARIABLES 261The following environment variables control various aspects of the installation 262process. 263Many are used internally during installation and have reasonable default values 264for most installation scenarios. 265Others are set by various interactive user prompts, and can be usefully 266overridden when making scripted or customized installers. 267.Bl -tag -width ".Ev BSDINSTALL_DISTSITE" 268.It Ev TMPDIR 269The directory to use for temporary files. 270Default: 271.Dq Pa /tmp 272.It Ev DISTRIBUTIONS 273The set of distributions to install, e.g., "base.txz kernel.txz ports.txz". 274Default: unset 275.It Ev PARTITIONS 276The partitioning of the disk onto which the system is being installed. 277See 278.Cm scriptedpart 279of 280the 281.Sx TARGETS 282section for format details. 283Default: unset 284.It Ev BSDINSTALL_DISTDIR 285The directory in which the distribution files can be found (or to which they 286should be downloaded). 287Default: 288.Dq Pa /usr/freebsd-dist 289.It Ev BSDINSTALL_DISTSITE 290URL from which the distribution files should be downloaded if they are not 291already present in the directory defined by 292.Ev BSDINSTALL_DISTDIR . 293This should be a full path to the files, including architecture and release 294names. 295Most targets, e.g., 296.Cm auto 297and 298.Cm jail , 299that prompt for a 300.Fx 301mirror will skip that step if this variable is already defined in the 302environment. 303Example: 304.Pa ftp://ftp.freebsd.org/pub/FreeBSD/releases/powerpc/powerpc64/9.1-RELEASE 305.It Ev BSDINSTALL_CHROOT 306The directory into which the distribution files should be unpacked and the 307directory at which the root file system of the new system should be mounted. 308Default: 309.Dq Pa /mnt 310.It Ev BSDINSTALL_LOG 311Path to a log file for the installation. 312Default: 313.Dq Pa $TMPDIR/bsdinstall_log 314.It Ev BSDINSTALL_TMPETC 315Directory where files destined for the new system's 316.Pa /etc 317will be stored until the 318.Cm config 319target is executed. 320If this directory does not already exist, it will be created. 321Default: 322.Dq Pa $TMPDIR/bsdinstall_etc 323.It Ev BSDINSTALL_TMPBOOT 324Directory where files destined for the new system's 325.Pa /boot 326will be stored until the 327.Cm config 328target is executed. 329If this directory does not already exist, it will be created. 330Default: 331.Dq Pa $TMPDIR/bsdinstall_boot 332.It Ev ZFSBOOT_POOL_NAME 333Name for the pool containing the base system. 334Default: 335.Dq zroot 336.It Ev ZFSBOOT_POOL_CREATE_OPTIONS 337Options to be used when creating the base system's pool. 338Each option must be followed by the -O flag to be taken into consideration 339or the pool will not be created due to errors using the command 340.Cm zpool . 341Default: 342.Dq Li "-O compress=lz4 -O atime=off" 343.It Ev ZFSBOOT_BEROOT_NAME 344Name for the boot environment parent dataset. 345This is a non-mountable dataset meant to be a parent dataset where different 346boot environment are going to be created. 347Default: 348.Dq ROOT 349.It Ev ZFSBOOT_BOOTFS_NAME 350Name for the primary boot environment, which will be the default boot 351environment for the system. 352Default: 353.Dq default 354.It Ev ZFSBOOT_VDEV_TYPE 355The type of pool to be created for the base system. 356This variable can take one of this values: stripe (No redundancy), 357mirror (n-Way mirroring), raid10 (RAID 1+0 - n x 2-Way Mirrors), 358raidz1 (RAID-Z1 - Single Redundancy RAID), raidz2 (RAID-Z2 - Double Redundancy RAID) 359or raidz3 (RAID-Z3 Triple Redundancy RAID). 360Default: 361.Dq stripe 362.It Ev ZFSBOOT_FORCE_4K_SECTORS 363Indicates either the pool will use 4K or 512 sectors. 364If this variable is not empty, 4K sectors will be used. 365Default: 366.Dq 1 367.It Ev ZFSBOOT_GELI_ENCRYPTION 368If this variable is not empty, it will use 369.Xr geli 8 370to encrypt the root pool, enabling automatically the 371.Ev ZFSBOOT_BOOT_POOL 372variable. 373Default: 374.Dq "" 375.It Ev ZFSBOOT_GELI_KEY_FILE 376Path to the 377.Xr geli 8 378keyfile used to encrypt the pool where the base system is stored. 379Default: 380.Dq Pa /boot/encryption.key 381.It Ev ZFSBOOT_BOOT_POOL 382If set a separated boot pool will be created for the kernel of the 383system and 384.Xr loader 8 . 385Default: unset 386.It Ev ZFSBOOT_BOOT_POOL_CREATE_OPTIONS 387Options to use when creating the boot pool, when enabled (See 388.Ev ZFSBOOT_BOOT_POOL ). 389Default: unset 390.It Ev ZFSBOOT_BOOT_POOL_NAME 391Name for the optional boot pool when it is enabled, (See 392.Ev ZFSBOOT_BOOT_POOL ). 393Default: 394.Dq bootpool 395.It Ev ZFSBOOT_BOOT_POOL_SIZE 396Size of the boot pool when it is enabled (See 397.Ev ZFSBOOT_BOOT_POOL ). 398Default: 399.Dq 2g 400.It Ev ZFSBOOT_DISKS 401Disks to be used for the base system, including the boot pool. 402This variable must only be used on a scripted installation. 403See 404.Sx SCRIPTING 405for more information. 406Default: unset 407.It Ev ZFSBOOT_SWAP_SIZE 408Size of the swap partition on each block device. 409This variable will be passed to 410.Xr gpart 8 ; 411which supports SI unit suffixes. 412Default: 413.Dq 2g 414.It Ev ZFSBOOT_SWAP_ENCRYPTION 415If set, enables the encryption of the swap partition using 416.Xr geli 8 . 417Default: "" 418.It Ev ZFSBOOT_SWAP_MIRROR 419If set, enables a swap mirroring using 420.Xr gmirror 8 . 421Default: 422unset 423.It Ev ZFSBOOT_DATASETS 424ZFS datasets to be created on the root zpool, it requires the 425following datasets: 426.Pa /tmp , 427.Pa /var/tmp , 428.Pa /$ZFSBOOT_BEROOT_NAME/$ZFSBOOT_BOOTFS_NAME . 429See 430.Sx ZFS DATASETS 431for more information about who to write this variable and to 432take a look into the default value of it. 433.It Ev ZFSBOOT_CONFIRM_LAYOUT 434If set and the installation is interactive, allow the user to confirm 435the layout before continuing with the installation. 436Default: 437.Dq 1 438.El 439.Sh SCRIPTING 440.Nm 441scripts consist of two parts: a 442.Em preamble 443and a 444.Em setup script . 445The preamble sets up the options for the installation (how to partition the 446disk[s], which distributions to install, etc.) and the optional second part is 447a shell script run under 448.Xr chroot 8 449in the newly installed system before 450.Nm 451exits. 452The two parts are separated by the usual script header (#!), which also sets 453the interpreter for the setup script. 454.Pp 455A typical bsdinstall script looks like this: 456.Bd -literal -offset indent 457PARTITIONS=ada0 458DISTRIBUTIONS="kernel.txz base.txz" 459 460#!/bin/sh 461sysrc ifconfig_DEFAULT=DHCP 462sysrc sshd_enable=YES 463pkg install puppet 464.Ed 465.Pp 466For a ZFS scripted installation, the script looks like this: 467.Bd -literal -offset indent 468DISTRIBUTIONS="kernel.txz base.txz" 469export ZFSBOOT_VDEV_TYPE=stripe 470export ZFSBOOT_DISKS=ada0 471export nonInteractive="YES" 472 473#!/bin/sh 474echo "ifconfig_DEFAULT=DHCP" >> /etc/rc.conf 475echo "sshd_enable=YES" >> /etc/rc.conf 476pkg install puppet 477.Ed 478.Pp 479On 480.Fx 481release media, such a script placed at 482.Pa /etc/installerconfig 483will be run at boot time and the system will be rebooted automatically after 484the installation has completed. 485This can be used for unattended network installation of new systems; see 486.Xr diskless 8 487for details. 488.Ss PREAMBLE 489The preamble consists of installer settings. 490These control global installation parameters (see 491.Sx ENVIRONMENT VARIABLES ) 492as well as disk partitioning. 493The preamble is interpreted as a 494.Xr sh 1 495script run at the very beginning of the install. 496If more complicated behavior than setting these variables is desired, 497arbitrary commands can be run here to extend the installer. 498In addition to the variables in 499.Sx ENVIRONMENT VARIABLES , 500in particular 501.Ev DISTRIBUTIONS , 502the preamble can contain a variable 503.Ev PARTITIONS 504which is passed to the 505.Cm scriptedpart 506target to control disk setup. 507Alternatively, 508to use 509.Cm zfsboot 510instead of 511.Cm partedit , 512the preamble can contain the variable 513.Ev ZFSBOOT_DATASETS 514instead of 515.Ev PARTITIONS , 516and setting the variables 517.Ev ZFSBOOT_DISKS 518and 519.Ev ZFSBOOT_VDEV_TYPE 520to create the pool of disks for the base system. 521Usually, for a mirrored booting disk, this two variables looks like this: 522.Bd -literal -offset indent 523ZFSBOOT_DISKS="ada0 ada1" 524ZFSBOOT_VDEV_TYPE=mirror 525.Ed 526.Pp 527Remember to export all the variables for the 528.Cm zfsboot 529command, otherwise it will not get set. 530.Ss SETUP SCRIPT 531Following the preamble is an optional shell script, beginning with a #! 532declaration. 533This script will be run at the end of the installation process inside a 534.Xr chroot 8 535environment in the newly installed system and can be used to set up 536configuration files, install packages, etc. 537Note that newly configured system services, e.g., networking have not 538been started in the installed system at this time and only installation 539host services are available. 540.Ss ZFS DATASETS 541The 542.Cm zfsboot 543partitioning takes the 544.Ev ZFSBOOT_DATASETS 545variable to create the datasets on the base system. 546This variable can get pretty huge if the pool contains a lot of datasets. 547The default value of the 548.Ev ZFSBOOT_DATASETS 549looks like this: 550.Bd -literal -offset indent 551# DATASET OPTIONS (comma or space separated; or both) 552 553# Boot Environment [BE] root and default boot dataset 554/$ZFSBOOT_BEROOT_NAME mountpoint=none 555/$ZFSBOOT_BEROOT_NAME/$ZFSBOOT_BOOTFS_NAME mountpoint=/ 556 557# Compress /tmp, allow exec but not setuid 558/tmp mountpoint=/tmp,exec=on,setuid=off 559 560# Do not mount /usr so that 'base' files go to the BEROOT 561/usr mountpoint=/usr,canmount=off 562 563# Home directories separated so they are common to all BEs 564/usr/home # NB: /home is a symlink to /usr/home 565 566# Ports tree 567/usr/ports setuid=off 568 569# Source tree (compressed) 570/usr/src 571 572# Create /var and friends 573/var mountpoint=/var,canmount=off 574/var/audit exec=off,setuid=off 575/var/crash exec=off,setuid=off 576/var/log exec=off,setuid=off 577/var/mail atime=on 578/var/tmp setuid=off 579.Ed 580.Pp 581The first column if the dataset to be created on the top of the 582.Ev ZFSBOOT_POOL_NAME 583and the rest of the columns are the options to be set on each dataset. 584The options must be written on a coma or space separated list, or both. 585And everything behind a pound/hash character is ignored as a comment. 586.Ss BUILDING AUTOMATIC INSTALL MEDIA 587If building automatic install media, use tar to extract a release ISO: 588.Dl mkdir release-media 589.Dl tar xvf -C release-media FreeBSD-13.0-RELEASE-amd64-disc1.iso 590.Pp 591Then place a script as above in 592.Pa etc/installerconfig 593.Pp 594This directory can then be used directly as an NFS root for 595.Xr diskless 8 596installations or it can be rebuilt into an ISO image using the release scripts in 597.Pa /usr/src/release . 598For example, on amd64: 599.Dl sh /usr/src/release/amd64/mkisoimages.sh -b '13_0_RELEASE_AMD64_CD' output.iso release-media 600.Sh HISTORY 601This version of 602.Nm 603first appeared in 604.Fx 9.0 . 605.Sh AUTHORS 606.An Nathan Whitehorn Aq Mt nwhitehorn@FreeBSD.org 607