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 November 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 436Controls the minimum sector size of the pool. 437If this variable is not empty, the minimum sector size is 4K. 438If this variable is empty, the minimum sector size is 512. 439Note that the sector size of the pool will always be at least 440the sector size of the backing disks. 441Default: 442.Dq 1 443.It Ev ZFSBOOT_GELI_ENCRYPTION 444If this variable is not empty, it will use 445.Xr geli 8 446to encrypt the root pool, enabling automatically the 447.Ev ZFSBOOT_BOOT_POOL 448variable. 449Default: 450.Dq "" 451.It Ev ZFSBOOT_GELI_KEY_FILE 452Path to the 453.Xr geli 8 454keyfile used to encrypt the pool where the base system is stored. 455Default: 456.Dq Pa /boot/encryption.key 457.It Ev ZFSBOOT_BOOT_POOL 458If set, a separated boot pool will be created for the kernel of the 459system and 460.Xr loader 8 . 461Default: unset 462.It Ev ZFSBOOT_BOOT_POOL_CREATE_OPTIONS 463Options to use when creating the boot pool, when enabled (See 464.Ev ZFSBOOT_BOOT_POOL ). 465Default: unset 466.It Ev ZFSBOOT_BOOT_POOL_NAME 467Name for the optional boot pool when it is enabled, (See 468.Ev ZFSBOOT_BOOT_POOL ). 469Default: 470.Dq bootpool 471.It Ev ZFSBOOT_BOOT_POOL_SIZE 472Size of the boot pool when it is enabled (See 473.Ev ZFSBOOT_BOOT_POOL ). 474Default: 475.Dq 2g 476.It Ev ZFSBOOT_DISKS 477Disks to be used for the base system, including the boot pool. 478This variable must only be used on a scripted installation. 479See 480.Sx SCRIPTING 481for more information. 482Default: unset 483.It Ev ZFSBOOT_SWAP_SIZE 484Size of the swap partition on each block device. 485This variable will be passed to 486.Xr gpart 8 ; 487which supports SI unit suffixes. 488Default: 489.Dq 2g 490.It Ev ZFSBOOT_SWAP_ENCRYPTION 491If set, enables the encryption of the swap partition using 492.Xr geli 8 . 493Default: "" 494.It Ev ZFSBOOT_SWAP_MIRROR 495If set, enables a swap mirroring using 496.Xr gmirror 8 . 497Default: 498unset 499.It Ev ZFSBOOT_DATASETS 500ZFS datasets to be created on the root zpool, it requires the 501following datasets: 502.Pa /tmp , 503.Pa /var/tmp , 504.Pa /$ZFSBOOT_BEROOT_NAME/$ZFSBOOT_BOOTFS_NAME . 505See 506.Sx ZFS DATASETS 507for more information about how to populate this variable and 508its default value. 509.It Ev ZFSBOOT_CONFIRM_LAYOUT 510If set and the installation is interactive, allow the user to confirm 511the layout before continuing with the installation. 512Default: 513.Dq 1 514.El 515.Sh SCRIPTING 516.Nm 517supports unattended, or minimally-attended, installations using scripting. 518This can be used with either modified physical installation media or with 519.Xr diskless 8 520installations over the network; information on preparing such media can be 521found in 522.Sx BUILDING AUTOMATIC INSTALL MEDIA 523.Pp 524Scripted installations follow an essentially identical path to interactive 525installations, though with some minor feature differences (for example, 526scripted installations do not support fetching of remote distribution files 527since scripted installations normally install the same files and the distributions 528can be added directly to the installation media). 529.Nm 530scripts consist of two parts: a 531.Em preamble 532and a 533.Em setup script . 534The preamble sets up the options for the installation (how to partition the 535disk[s], which distributions to install, etc.) and the optional second part is 536a shell script run under 537.Xr chroot 8 538in the newly installed system before 539.Nm 540exits. 541The two parts are separated by the usual script header (#!), which also sets 542the interpreter for the setup script. 543.Pp 544A typical bsdinstall script, using the default filesystem layout and the UFS 545filesystem, looks like this: 546.Bd -literal -offset indent 547PARTITIONS=DEFAULT 548DISTRIBUTIONS="kernel.txz base.txz" 549 550#!/bin/sh 551sysrc ifconfig_DEFAULT=DHCP 552sysrc sshd_enable=YES 553pkg install puppet 554.Ed 555.Pp 556For a scripted installation involving a ZFS pool spanning multiple disks, 557the script instead looks like this: 558.Bd -literal -offset indent 559DISTRIBUTIONS="kernel.txz base.txz" 560export ZFSBOOT_VDEV_TYPE=stripe 561export ZFSBOOT_DISKS="ada0 ada1" 562export nonInteractive="YES" 563 564#!/bin/sh 565echo "ifconfig_DEFAULT=DHCP" >> /etc/rc.conf 566echo "sshd_enable=YES" >> /etc/rc.conf 567pkg install puppet 568.Ed 569.Pp 570On 571.Fx 572release media, such a script placed at 573.Pa /etc/installerconfig 574will be run at boot time and the system will be rebooted automatically after 575the installation has completed. 576This can be used for unattended network installation of new systems; see 577.Xr diskless 8 578for details. 579.Ss PREAMBLE 580The preamble consists of installer settings. 581These control global installation parameters (see 582.Sx ENVIRONMENT VARIABLES ) 583as well as disk partitioning. 584The preamble is interpreted as a 585.Xr sh 1 586script run at the very beginning of the install. 587If more complicated behavior than setting these variables is desired, 588arbitrary commands can be run here to extend the installer. 589In addition to the variables in 590.Sx ENVIRONMENT VARIABLES , 591in particular 592.Ev DISTRIBUTIONS , 593the preamble can contain a variable 594.Ev PARTITIONS 595which is passed to the 596.Cm scriptedpart 597target to control disk setup. 598.Pp 599Alternatively, 600to use 601.Cm zfsboot 602instead of 603.Cm partedit , 604the preamble can contain the variable 605.Ev ZFSBOOT_DATASETS 606instead of 607.Ev PARTITIONS 608(see below). 609If using 610.Cm zfsboot , 611the variables 612.Ev ZFSBOOT_DISKS 613and 614.Ev ZFSBOOT_VDEV_TYPE 615must be set to create the pool of disks for the base system. 616Usually, for a mirrored booting disk, these two variables look like this: 617.Bd -literal -offset indent 618ZFSBOOT_DISKS="ada0 ada1" 619ZFSBOOT_VDEV_TYPE=mirror 620.Ed 621.Pp 622Remember to export all the variables for the 623.Cm zfsboot 624command, otherwise installation will fail. 625.Ss SETUP SCRIPT 626Following the preamble is an optional shell script, beginning with a #! 627declaration. 628This script will be run at the end of the installation process inside a 629.Xr chroot 8 630environment in the newly installed system and can be used to set up 631configuration files, install packages, etc. 632Note that newly configured system services, e.g., networking have not 633been started in the installed system at this time and only installation 634host services are available. 635.Ss ZFS DATASETS 636If using 637.Cm zfsboot 638in an installation script, the 639.Cm zfsboot 640partitioning tool takes the 641.Ev ZFSBOOT_DATASETS 642variable to create the ZFS datasets on the base system. 643This variable definition can become large if the pool contains many datasets. 644The default value of 645.Ev ZFSBOOT_DATASETS 646is: 647.Bd -literal -offset indent 648# DATASET OPTIONS (comma or space separated; or both) 649 650# Boot Environment [BE] root and default boot dataset 651/$ZFSBOOT_BEROOT_NAME mountpoint=none 652/$ZFSBOOT_BEROOT_NAME/$ZFSBOOT_BOOTFS_NAME mountpoint=/ 653 654# Home directories separated so they are common to all BEs 655/home mountpoint=/home 656 657# Compress /tmp, allow exec but not setuid 658/tmp mountpoint=/tmp,exec=on,setuid=off 659 660# Do not mount /usr so that 'base' files go to the BEROOT 661/usr mountpoint=/usr,canmount=off 662 663# Ports tree 664/usr/ports setuid=off 665 666# Source tree (compressed) 667/usr/src 668 669# Create /var and friends 670/var mountpoint=/var,canmount=off 671/var/audit exec=off,setuid=off 672/var/crash exec=off,setuid=off 673/var/log exec=off,setuid=off 674/var/mail atime=on 675/var/tmp setuid=off 676.Ed 677.Pp 678The first column is the name of the dataset to be created as part of the 679.Ev ZFSBOOT_POOL_NAME 680pool and the remainder of each line contains the options to be set on each dataset. 681If multiple options are given, they can be separated by either commas or whitespace; 682everything following a pound/hash character is ignored as a comment. 683.Ss BUILDING AUTOMATIC INSTALL MEDIA 684If building automatic install media, use tar to extract a release ISO: 685.Dl mkdir release-media 686.Dl tar -C release-media -xvf FreeBSD-13.0-RELEASE-amd64-disc1.iso 687.Pp 688Then place a script as above in 689.Pa etc/installerconfig 690.Pp 691This directory can then be used directly as an NFS root for 692.Xr diskless 8 693installations or it can be rebuilt into an ISO image using the release scripts in 694.Pa /usr/src/release . 695For example, on amd64: 696.Dl sh /usr/src/release/amd64/mkisoimages.sh -b '13_0_RELEASE_AMD64_CD' output.iso release-media 697.Sh HISTORY 698This version of 699.Nm 700first appeared in 701.Fx 9.0 . 702.Sh AUTHORS 703.An Nathan Whitehorn Aq Mt nwhitehorn@FreeBSD.org 704.An Devin Teske Aq Mt dteske@FreeBSD.org 705.An Allan Jude Aq Mt allanjude@FreeBSD.org 706