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