2 .\" Copyright (c) 2011-2013 Nathan Whitehorn <nwhitehorn@FreeBSD.org> All rights reserved.
3 .\" Copyright (c) 2018 Roberto Fernandez Cueto <roberfern@gmail.com>
5 .\" Redistribution and use in source and binary forms, with or without
6 .\" modification, are permitted provided that the following conditions
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.
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.
39 is used for installation of new systems, both for system setup from
40 installation media, e.g., CD-ROMs, and for use on live systems to prepare
45 takes a target and possible parameters of the target as arguments.
46 If invoked with no arguments, it will invoke the
48 target, which provides a standard interactive installation, invoking the
50 To perform a scripted installation,
51 these subtargets can be invoked separately by an installation script.
54 supports the following options, global to all targets:
55 .Bl -tag -width indent+
57 Provide a path for the installation log file
58 .Pq overrides Ev BSDINSTALL_LOG .
60 .Sx ENVIRONMENT VARIABLES
61 for more information on
65 Most of the following targets are only useful for scripting the installer.
66 For interactive use, most users will be interested only in the
72 .Bl -tag -width "jail destination"
74 Run the standard interactive installation, including disk partitioning.
75 .It Cm jail Ar destination
76 Sets up a new chroot system at
80 Behavior is generally similar to
82 except that disk partitioning and network setup are skipped and a kernel is
83 not installed into the new system.
84 .It Cm script Ar script
85 Runs the installation script at
89 for more information on this target.
91 If the current controlling TTY is a
95 console, asks the user to set the current keymap, and saves the result to the
99 Prompts the user for a host name for the new system and saves the result to the
103 .Ev BSDINSTALL_CONFIGCURRENT
104 is set, also sets the host name of the current system.
106 Interactively configures network interfaces (first invoking
108 on wireless interfaces), saving the result to the new system's
113 .Ev BSDINSTALL_CONFIGCURRENT
114 is set, also configures the network interfaces of the current system to match.
116 Provides the installer's interactive guided disk partitioner for single-disk
120 Detects an appropriate partition and installs UEFI boot loader files.
122 Provides a ZFS-only automatic interactive disk partitioner.
125 with separate datasets for
133 Optionally can set up
137 Provides the installer's interactive manual disk partitioner with an interface
140 Supports multiple disks as well as UFS, ZFS, and FAT file systems.
141 ZFS is set up with one pool and dataset per partition.
142 .It Cm scriptedpart Ar parameters
147 but non-interactively according to the disk setup specified in
149 Each disk setup is specified by a three-part argument:
155 Multiple disk setups are separated by semicolons.
158 argument specifies the disk on which to operate (which will be erased),
161 which will result in either a selection window (as in
163 for the destination disk or, if there is only one possible disk, will
164 automatically select it.
167 argument specifies the
169 partition scheme to apply to the disk.
174 will apply the default bootable scheme on your platform.
177 argument is also optional and specifies how to partition
179 It consists of a comma-separated list of partitions to create enclosed in
181 Each partition declaration takes the form
188 specifies the partition size to create in bytes (K, M, and G suffixes
189 can be appended to specify kilobytes, megabytes, and gigabytes respectively),
192 keyword causes the partition to take all the remaining space on the disk.
197 filesystem type, e.g., freebsd-ufs, freebsd-zfs, or freebsd-swap.
200 argument sets where the created partition is to be mounted in the installed
202 As an example, a typical invocation looks like:
204 bsdinstall scriptedpart ada0 { 20G freebsd-ufs /, 4G freebsd-swap, 20G freebsd-ufs /var, auto freebsd-ufs /usr }
206 Note that the list of partitions should
208 include boot partitions (e.g. EFI system partitions), which will be created automatically on whatever disk includes /.
210 A shorter invocation to use the default partitioning (as
212 would have used) on the same disk:
214 bsdinstall scriptedpart ada0
218 bsdinstall scriptedpart DEFAULT
220 Mounts the file systems previously configured by
226 .Ev BSDINSTALL_CHROOT .
228 Fetches the distributions in
231 .Ev BSDINSTALL_DISTDIR
233 .Ev BSDINSTALL_DISTSITE .
235 Verifies the checksums of the distributions listed in
237 against the distribution manifest.
239 Extracts the distributions listed in
242 .Ev BSDINSTALL_CHROOT .
244 Interactively invokes
246 in the new system to set the root user's password.
248 Interactively invokes
252 Interactively sets the time, date, and time zone of the new system.
254 Queries the user for the system daemons to begin at system startup,
255 writing the result into the new system's
258 Reads a small amount of data from
260 and stores it in a file in the new system's root directory.
262 Installs the configuration files destined for the new system, e.g.,
264 fragments generated by
266 etc.) onto the new system.
268 .Sh ENVIRONMENT VARIABLES
269 The following environment variables control various aspects of the installation
271 Many are used internally during installation and have reasonable default values
272 for most installation scenarios.
273 Others are set by various interactive user prompts, and can be usefully
274 overridden when making scripted or customized installers.
275 .Bl -tag -width "BSDINSTALL_DISTSITE"
277 The directory to use for temporary files.
281 The set of distributions to install, e.g., "base.txz kernel.txz ports.txz".
284 The partitioning of the disk onto which the system is being installed.
290 section for format details. If this variable is unset, the installer will
291 use the default partitioning as in
294 .It Ev BSDINSTALL_DISTDIR
295 The directory in which the distribution files can be found (or to which they
296 should be downloaded).
298 .Dq Pa /usr/freebsd-dist
299 .It Ev BSDINSTALL_DISTSITE
300 URL from which the distribution files should be downloaded if they are not
301 already present in the directory defined by
302 .Ev BSDINSTALL_DISTDIR .
303 This should be a full path to the files, including architecture and release
311 mirror will skip that step if this variable is already defined in the
314 .Pa https://download.freebsd.org/ftp/releases/powerpc/powerpc64/13.1-RELEASE/
316 .Pa http://ftp-archive.freebsd.org/pub/FreeBSD-Archive/old-releases/amd64/12.2-RELEASE/ .
317 .It Ev BSDINSTALL_CHROOT
318 The directory into which the distribution files should be unpacked and the
319 directory at which the root file system of the new system should be mounted.
322 .It Ev BSDINSTALL_LOG
323 Path to a log file for the installation.
325 .Dq Pa $TMPDIR/bsdinstall_log
326 .It Ev BSDINSTALL_SKIP_HARDENING
333 .It Ev BSDINSTALL_SKIP_HOSTNAME
340 .It Ev BSDINSTALL_SKIP_KEYMAP
347 .It Ev BSDINSTALL_SKIP_MANUAL
350 target will not offer to open a shell in the new system
351 for final manual modifications.
352 .It Ev BSDINSTALL_SKIP_SERVICES
359 .It Ev BSDINSTALL_SKIP_TIME
366 .It Ev BSDINSTALL_SKIP_USERS
373 .It Ev BSDINSTALL_SKIP_FINALCONFIG
376 target will not show the final configuration dialog,
377 where earlier configuration choices can be revisited.
378 .It Ev BSDINSTALL_TMPETC
379 Directory where files destined for the new system's
381 will be stored until the
384 If this directory does not already exist, it will be created.
386 .Dq Pa $TMPDIR/bsdinstall_etc
387 .It Ev BSDINSTALL_TMPBOOT
388 Directory where files destined for the new system's
390 will be stored until the
393 If this directory does not already exist, it will be created.
395 .Dq Pa $TMPDIR/bsdinstall_boot
397 Encrypted string to set the root password to in the format expected by
400 This option is used if both it and
403 .It Ev ROOTPASS_PLAIN
404 Plain text string to set the root password to.
405 .It Ev ZFSBOOT_POOL_NAME
406 Name for the pool containing the base system.
409 .It Ev ZFSBOOT_POOL_CREATE_OPTIONS
410 Options to be used when creating the base system's pool.
411 Each option must be preceded by the -O flag to be taken into consideration
412 or the pool will not be created due to errors using the command
415 .Dq Li "-O compress=lz4 -O atime=off"
416 .It Ev ZFSBOOT_BEROOT_NAME
417 Name for the boot environment parent dataset.
418 This is a non-mountable dataset meant to be a parent dataset where different
419 boot environment are going to be created.
422 .It Ev ZFSBOOT_BOOTFS_NAME
423 Name for the primary boot environment, which will be the default boot
424 environment for the system.
427 .It Ev ZFSBOOT_VDEV_TYPE
428 The type of pool to be created for the base system.
429 This variable can take one of this values: stripe (No redundancy),
430 mirror (n-Way mirroring), raid10 (RAID 1+0 - n x 2-Way Mirrors),
431 raidz1 (RAID-Z1 - Single Redundancy RAID), raidz2 (RAID-Z2 - Double Redundancy RAID)
432 or raidz3 (RAID-Z3 Triple Redundancy RAID).
435 .It Ev ZFSBOOT_FORCE_4K_SECTORS
436 Controls the minimum sector size of the pool.
437 If this variable is not empty, the minimum sector size is 4K.
438 If this variable is empty, the minimum sector size is 512.
439 Note that the sector size of the pool will always be at least
440 the sector size of the backing disks.
443 .It Ev ZFSBOOT_GELI_ENCRYPTION
444 If this variable is not empty, it will use
446 to encrypt the root pool, enabling automatically the
447 .Ev ZFSBOOT_BOOT_POOL
451 .It Ev ZFSBOOT_GELI_KEY_FILE
454 keyfile used to encrypt the pool where the base system is stored.
456 .Dq Pa /boot/encryption.key
457 .It Ev ZFSBOOT_BOOT_POOL
458 If set, a separated boot pool will be created for the kernel of the
462 .It Ev ZFSBOOT_BOOT_POOL_CREATE_OPTIONS
463 Options to use when creating the boot pool, when enabled (See
464 .Ev ZFSBOOT_BOOT_POOL ).
466 .It Ev ZFSBOOT_BOOT_POOL_NAME
467 Name for the optional boot pool when it is enabled, (See
468 .Ev ZFSBOOT_BOOT_POOL ).
471 .It Ev ZFSBOOT_BOOT_POOL_SIZE
472 Size of the boot pool when it is enabled (See
473 .Ev ZFSBOOT_BOOT_POOL ).
477 Disks to be used for the base system, including the boot pool.
478 This variable must only be used on a scripted installation.
481 for more information.
483 .It Ev ZFSBOOT_SWAP_SIZE
484 Size of the swap partition on each block device.
485 This variable will be passed to
487 which supports SI unit suffixes.
490 .It Ev ZFSBOOT_SWAP_ENCRYPTION
491 If set, enables the encryption of the swap partition using
494 .It Ev ZFSBOOT_SWAP_MIRROR
495 If set, enables a swap mirroring using
499 .It Ev ZFSBOOT_DATASETS
500 ZFS datasets to be created on the root zpool, it requires the
504 .Pa /$ZFSBOOT_BEROOT_NAME/$ZFSBOOT_BOOTFS_NAME .
507 for more information about how to populate this variable and
509 .It Ev ZFSBOOT_CONFIRM_LAYOUT
510 If set and the installation is interactive, allow the user to confirm
511 the layout before continuing with the installation.
517 supports unattended, or minimally-attended, installations using scripting.
518 This can be used with either modified physical installation media or with
520 installations over the network; information on preparing such media can be
522 .Sx BUILDING AUTOMATIC INSTALL MEDIA
524 Scripted installations follow an essentially identical path to interactive
525 installations, though with some minor feature differences (for example,
526 scripted installations do not support fetching of remote distribution files
527 since scripted installations normally install the same files and the distributions
528 can be added directly to the installation media).
530 scripts consist of two parts: a
534 The preamble sets up the options for the installation (how to partition the
535 disk[s], which distributions to install, etc.) and the optional second part is
536 a shell script run under
538 in the newly installed system before
541 The two parts are separated by the usual script header (#!), which also sets
542 the interpreter for the setup script.
544 A typical bsdinstall script, using the default filesystem layout and the UFS
545 filesystem, looks like this:
546 .Bd -literal -offset indent
548 DISTRIBUTIONS="kernel.txz base.txz"
551 sysrc ifconfig_DEFAULT=DHCP
552 sysrc sshd_enable=YES
556 For a scripted installation involving a ZFS pool spanning multiple disks,
557 the script instead looks like this:
558 .Bd -literal -offset indent
559 DISTRIBUTIONS="kernel.txz base.txz"
560 export ZFSBOOT_VDEV_TYPE=stripe
561 export ZFSBOOT_DISKS="ada0 ada1"
562 export nonInteractive="YES"
565 echo "ifconfig_DEFAULT=DHCP" >> /etc/rc.conf
566 echo "sshd_enable=YES" >> /etc/rc.conf
572 release media, such a script placed at
573 .Pa /etc/installerconfig
574 will be run at boot time and the system will be rebooted automatically after
575 the installation has completed.
576 This can be used for unattended network installation of new systems; see
580 The preamble consists of installer settings.
581 These control global installation parameters (see
582 .Sx ENVIRONMENT VARIABLES )
583 as well as disk partitioning.
584 The preamble is interpreted as a
586 script run at the very beginning of the install.
587 If more complicated behavior than setting these variables is desired,
588 arbitrary commands can be run here to extend the installer.
589 In addition to the variables in
590 .Sx ENVIRONMENT VARIABLES ,
593 the preamble can contain a variable
595 which is passed to the
597 target to control disk setup.
604 the preamble can contain the variable
614 .Ev ZFSBOOT_VDEV_TYPE
615 must be set to create the pool of disks for the base system.
616 Usually, for a mirrored booting disk, these two variables look like this:
617 .Bd -literal -offset indent
618 ZFSBOOT_DISKS="ada0 ada1"
619 ZFSBOOT_VDEV_TYPE=mirror
622 Remember to export all the variables for the
624 command, otherwise installation will fail.
626 Following the preamble is an optional shell script, beginning with a #!
628 This script will be run at the end of the installation process inside a
630 environment in the newly installed system and can be used to set up
631 configuration files, install packages, etc.
632 Note that newly configured system services, e.g., networking have not
633 been started in the installed system at this time and only installation
634 host services are available.
638 in an installation script, the
640 partitioning tool takes the
642 variable to create the ZFS datasets on the base system.
643 This variable definition can become large if the pool contains many datasets.
647 .Bd -literal -offset indent
648 # DATASET OPTIONS (comma or space separated; or both)
650 # Boot Environment [BE] root and default boot dataset
651 /$ZFSBOOT_BEROOT_NAME mountpoint=none
652 /$ZFSBOOT_BEROOT_NAME/$ZFSBOOT_BOOTFS_NAME mountpoint=/
654 # Home directories separated so they are common to all BEs
655 /home mountpoint=/home
657 # Compress /tmp, allow exec but not setuid
658 /tmp mountpoint=/tmp,exec=on,setuid=off
660 # Do not mount /usr so that 'base' files go to the BEROOT
661 /usr mountpoint=/usr,canmount=off
664 /usr/ports setuid=off
666 # Source tree (compressed)
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
678 The first column is the name of the dataset to be created as part of the
679 .Ev ZFSBOOT_POOL_NAME
680 pool and the remainder of each line contains the options to be set on each dataset.
681 If multiple options are given, they can be separated by either commas or whitespace;
682 everything following a pound/hash character is ignored as a comment.
683 .Ss BUILDING AUTOMATIC INSTALL MEDIA
684 If 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
688 Then place a script as above in
689 .Pa etc/installerconfig
691 This directory can then be used directly as an NFS root for
693 installations or it can be rebuilt into an ISO image using the release scripts in
694 .Pa /usr/src/release .
695 For example, on amd64:
696 .Dl sh /usr/src/release/amd64/mkisoimages.sh -b '13_0_RELEASE_AMD64_CD' output.iso release-media
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