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