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 September 18, 2023 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 "jail 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 "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_SKIP_HARDENING 327If not empty, the 328.Cm auto 329target 330will not invoke the 331.Cm hardening 332target. 333.It Ev BSDINSTALL_SKIP_HOSTNAME 334If not empty, the 335.Cm auto 336target 337will not invoke the 338.Cm hostname 339target. 340.It Ev BSDINSTALL_SKIP_KEYMAP 341If not empty, the 342.Cm auto 343target 344will not invoke the 345.Cm keymap 346target. 347.It Ev BSDINSTALL_SKIP_MANUAL 348If not empty, the 349.Cm auto 350target will not offer to open a shell in the new system 351for final manual modifications. 352.It Ev BSDINSTALL_SKIP_SERVICES 353If not empty, the 354.Cm auto 355target 356will not invoke the 357.Cm services 358target. 359.It Ev BSDINSTALL_SKIP_TIME 360If not empty, the 361.Cm auto 362target 363will not invoke the 364.Cm time 365target. 366.It Ev BSDINSTALL_SKIP_USERS 367If not empty, the 368.Cm auto 369target 370will not invoke the 371.Cm adduser 372target. 373.It Ev BSDINSTALL_SKIP_FINALCONFIG 374If not empty, the 375.Cm auto 376target will not show the final configuration dialog, 377where earlier configuration choices can be revisited. 378.It Ev BSDINSTALL_TMPETC 379Directory where files destined for the new system's 380.Pa /etc 381will be stored until the 382.Cm config 383target is executed. 384If this directory does not already exist, it will be created. 385Default: 386.Dq Pa $TMPDIR/bsdinstall_etc 387.It Ev BSDINSTALL_TMPBOOT 388Directory where files destined for the new system's 389.Pa /boot 390will be stored until the 391.Cm config 392target is executed. 393If this directory does not already exist, it will be created. 394Default: 395.Dq Pa $TMPDIR/bsdinstall_boot 396.It Ev ROOTPASS_ENC 397Encrypted string to set the root password to in the format expected by 398.Xr pw 8 399.Fl H Ar 0 . 400This option is used if both it and 401.Ev ROOTPASS_PLAIN 402are set. 403.It Ev ROOTPASS_PLAIN 404Plain text string to set the root password to. 405.It Ev ZFSBOOT_POOL_NAME 406Name for the pool containing the base system. 407Default: 408.Dq zroot 409.It Ev ZFSBOOT_POOL_CREATE_OPTIONS 410Options to be used when creating the base system's pool. 411Each option must be preceded by the -O flag to be taken into consideration 412or the pool will not be created due to errors using the command 413.Cm zpool . 414Default: 415.Dq Li "-O compress=lz4 -O atime=off" 416.It Ev ZFSBOOT_BEROOT_NAME 417Name for the boot environment parent dataset. 418This is a non-mountable dataset meant to be a parent dataset where different 419boot environment are going to be created. 420Default: 421.Dq ROOT 422.It Ev ZFSBOOT_BOOTFS_NAME 423Name for the primary boot environment, which will be the default boot 424environment for the system. 425Default: 426.Dq default 427.It Ev ZFSBOOT_VDEV_TYPE 428The type of pool to be created for the base system. 429This variable can take one of this values: stripe (No redundancy), 430mirror (n-Way mirroring), raid10 (RAID 1+0 - n x 2-Way Mirrors), 431raidz1 (RAID-Z1 - Single Redundancy RAID), raidz2 (RAID-Z2 - Double Redundancy RAID) 432or raidz3 (RAID-Z3 Triple Redundancy RAID). 433Default: 434.Dq stripe 435.It Ev ZFSBOOT_FORCE_4K_SECTORS 436Indicates either the pool will use 4K or 512 sectors. 437If this variable is not empty, 4K sectors will be used. 438Default: 439.Dq 1 440.It Ev ZFSBOOT_GELI_ENCRYPTION 441If this variable is not empty, it will use 442.Xr geli 8 443to encrypt the root pool, enabling automatically the 444.Ev ZFSBOOT_BOOT_POOL 445variable. 446Default: 447.Dq "" 448.It Ev ZFSBOOT_GELI_KEY_FILE 449Path to the 450.Xr geli 8 451keyfile used to encrypt the pool where the base system is stored. 452Default: 453.Dq Pa /boot/encryption.key 454.It Ev ZFSBOOT_BOOT_POOL 455If set, a separated boot pool will be created for the kernel of the 456system and 457.Xr loader 8 . 458Default: unset 459.It Ev ZFSBOOT_BOOT_POOL_CREATE_OPTIONS 460Options to use when creating the boot pool, when enabled (See 461.Ev ZFSBOOT_BOOT_POOL ). 462Default: unset 463.It Ev ZFSBOOT_BOOT_POOL_NAME 464Name for the optional boot pool when it is enabled, (See 465.Ev ZFSBOOT_BOOT_POOL ). 466Default: 467.Dq bootpool 468.It Ev ZFSBOOT_BOOT_POOL_SIZE 469Size of the boot pool when it is enabled (See 470.Ev ZFSBOOT_BOOT_POOL ). 471Default: 472.Dq 2g 473.It Ev ZFSBOOT_DISKS 474Disks to be used for the base system, including the boot pool. 475This variable must only be used on a scripted installation. 476See 477.Sx SCRIPTING 478for more information. 479Default: unset 480.It Ev ZFSBOOT_SWAP_SIZE 481Size of the swap partition on each block device. 482This variable will be passed to 483.Xr gpart 8 ; 484which supports SI unit suffixes. 485Default: 486.Dq 2g 487.It Ev ZFSBOOT_SWAP_ENCRYPTION 488If set, enables the encryption of the swap partition using 489.Xr geli 8 . 490Default: "" 491.It Ev ZFSBOOT_SWAP_MIRROR 492If set, enables a swap mirroring using 493.Xr gmirror 8 . 494Default: 495unset 496.It Ev ZFSBOOT_DATASETS 497ZFS datasets to be created on the root zpool, it requires the 498following datasets: 499.Pa /tmp , 500.Pa /var/tmp , 501.Pa /$ZFSBOOT_BEROOT_NAME/$ZFSBOOT_BOOTFS_NAME . 502See 503.Sx ZFS DATASETS 504for more information about how to populate this variable and 505its default value. 506.It Ev ZFSBOOT_CONFIRM_LAYOUT 507If set and the installation is interactive, allow the user to confirm 508the layout before continuing with the installation. 509Default: 510.Dq 1 511.El 512.Sh SCRIPTING 513.Nm 514supports unattended, or minimally-attended, installations using scripting. 515This can be used with either modified physical installation media or with 516.Xr diskless 8 517installations over the network; information on preparing such media can be 518found in 519.Sx BUILDING AUTOMATIC INSTALL MEDIA 520.Pp 521Scripted installations follow an essentially identical path to interactive 522installations, though with some minor feature differences (for example, 523scripted installations do not support fetching of remote distribution files 524since scripted installations normally install the same files and the distributions 525can be added directly to the installation media). 526.Nm 527scripts consist of two parts: a 528.Em preamble 529and a 530.Em setup script . 531The preamble sets up the options for the installation (how to partition the 532disk[s], which distributions to install, etc.) and the optional second part is 533a shell script run under 534.Xr chroot 8 535in the newly installed system before 536.Nm 537exits. 538The two parts are separated by the usual script header (#!), which also sets 539the interpreter for the setup script. 540.Pp 541A typical bsdinstall script, using the default filesystem layout and the UFS 542filesystem, looks like this: 543.Bd -literal -offset indent 544PARTITIONS=DEFAULT 545DISTRIBUTIONS="kernel.txz base.txz" 546 547#!/bin/sh 548sysrc ifconfig_DEFAULT=DHCP 549sysrc sshd_enable=YES 550pkg install puppet 551.Ed 552.Pp 553For a scripted installation involving a ZFS pool spanning multiple disks, 554the script instead looks like this: 555.Bd -literal -offset indent 556DISTRIBUTIONS="kernel.txz base.txz" 557export ZFSBOOT_VDEV_TYPE=stripe 558export ZFSBOOT_DISKS="ada0 ada1" 559export nonInteractive="YES" 560 561#!/bin/sh 562echo "ifconfig_DEFAULT=DHCP" >> /etc/rc.conf 563echo "sshd_enable=YES" >> /etc/rc.conf 564pkg install puppet 565.Ed 566.Pp 567On 568.Fx 569release media, such a script placed at 570.Pa /etc/installerconfig 571will be run at boot time and the system will be rebooted automatically after 572the installation has completed. 573This can be used for unattended network installation of new systems; see 574.Xr diskless 8 575for details. 576.Ss PREAMBLE 577The preamble consists of installer settings. 578These control global installation parameters (see 579.Sx ENVIRONMENT VARIABLES ) 580as well as disk partitioning. 581The preamble is interpreted as a 582.Xr sh 1 583script run at the very beginning of the install. 584If more complicated behavior than setting these variables is desired, 585arbitrary commands can be run here to extend the installer. 586In addition to the variables in 587.Sx ENVIRONMENT VARIABLES , 588in particular 589.Ev DISTRIBUTIONS , 590the preamble can contain a variable 591.Ev PARTITIONS 592which is passed to the 593.Cm scriptedpart 594target to control disk setup. 595.Pp 596Alternatively, 597to use 598.Cm zfsboot 599instead of 600.Cm partedit , 601the preamble can contain the variable 602.Ev ZFSBOOT_DATASETS 603instead of 604.Ev PARTITIONS 605(see below). 606If using 607.Cm zfsboot , 608the variables 609.Ev ZFSBOOT_DISKS 610and 611.Ev ZFSBOOT_VDEV_TYPE 612must be set to create the pool of disks for the base system. 613Usually, for a mirrored booting disk, these two variables look like this: 614.Bd -literal -offset indent 615ZFSBOOT_DISKS="ada0 ada1" 616ZFSBOOT_VDEV_TYPE=mirror 617.Ed 618.Pp 619Remember to export all the variables for the 620.Cm zfsboot 621command, otherwise installation will fail. 622.Ss SETUP SCRIPT 623Following the preamble is an optional shell script, beginning with a #! 624declaration. 625This script will be run at the end of the installation process inside a 626.Xr chroot 8 627environment in the newly installed system and can be used to set up 628configuration files, install packages, etc. 629Note that newly configured system services, e.g., networking have not 630been started in the installed system at this time and only installation 631host services are available. 632.Ss ZFS DATASETS 633If using 634.Cm zfsboot 635in an installation script, the 636.Cm zfsboot 637partitioning tool takes the 638.Ev ZFSBOOT_DATASETS 639variable to create the ZFS datasets on the base system. 640This variable definition can become large if the pool contains many datasets. 641The default value of 642.Ev ZFSBOOT_DATASETS 643is: 644.Bd -literal -offset indent 645# DATASET OPTIONS (comma or space separated; or both) 646 647# Boot Environment [BE] root and default boot dataset 648/$ZFSBOOT_BEROOT_NAME mountpoint=none 649/$ZFSBOOT_BEROOT_NAME/$ZFSBOOT_BOOTFS_NAME mountpoint=/ 650 651# Home directories separated so they are common to all BEs 652/home mountpoint=/home 653 654# Compress /tmp, allow exec but not setuid 655/tmp mountpoint=/tmp,exec=on,setuid=off 656 657# Do not mount /usr so that 'base' files go to the BEROOT 658/usr mountpoint=/usr,canmount=off 659 660# Ports tree 661/usr/ports setuid=off 662 663# Source tree (compressed) 664/usr/src 665 666# Create /var and friends 667/var mountpoint=/var,canmount=off 668/var/audit exec=off,setuid=off 669/var/crash exec=off,setuid=off 670/var/log exec=off,setuid=off 671/var/mail atime=on 672/var/tmp setuid=off 673.Ed 674.Pp 675The first column is the name of the dataset to be created as part of the 676.Ev ZFSBOOT_POOL_NAME 677pool and the remainder of each line contains the options to be set on each dataset. 678If multiple options are given, they can be separated by either commas or whitespace; 679everything following a pound/hash character is ignored as a comment. 680.Ss BUILDING AUTOMATIC INSTALL MEDIA 681If building automatic install media, use tar to extract a release ISO: 682.Dl mkdir release-media 683.Dl tar -C release-media -xvf FreeBSD-13.0-RELEASE-amd64-disc1.iso 684.Pp 685Then place a script as above in 686.Pa etc/installerconfig 687.Pp 688This directory can then be used directly as an NFS root for 689.Xr diskless 8 690installations or it can be rebuilt into an ISO image using the release scripts in 691.Pa /usr/src/release . 692For example, on amd64: 693.Dl sh /usr/src/release/amd64/mkisoimages.sh -b '13_0_RELEASE_AMD64_CD' output.iso release-media 694.Sh HISTORY 695This version of 696.Nm 697first appeared in 698.Fx 9.0 . 699.Sh AUTHORS 700.An Nathan Whitehorn Aq Mt nwhitehorn@FreeBSD.org 701.An Devin Teske Aq Mt dteske@FreeBSD.org 702.An Allan Jude Aq Mt allanjude@FreeBSD.org 703