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