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.
41 is used for installation of new systems, both for system setup from
42 installation media, e.g., CD-ROMs, and for use on live systems to prepare
47 takes a target and possible parameters of the target as arguments.
48 If invoked with no arguments, it will invoke the
50 target, which provides a standard interactive installation, invoking the
52 To perform a scripted installation,
53 these subtargets can be invoked separately by an installation script.
56 supports the following options, global to all targets:
57 .Bl -tag -width indent+
59 Provide a path for the installation log file
60 .Pq overrides Ev BSDINSTALL_LOG .
62 .Sx ENVIRONMENT VARIABLES
63 for more information on
67 Most of the following targets are only useful for scripting the installer.
68 For interactive use, most users will be interested only in the
74 .Bl -tag -width ".Cm jail Ar destination"
76 Run the standard interactive installation, including disk partitioning.
77 .It Cm jail Ar destination
78 Sets up a new chroot system at
82 Behavior is generally similar to
84 except that disk partitioning and network setup are skipped and a kernel is
85 not installed into the new system.
86 .It Cm script Ar script
87 Runs the installation script at
91 for more information on this target.
93 If the current controlling TTY is a
97 console, asks the user to set the current keymap, and saves the result to the
101 Prompts the user for a host name for the new system and saves the result to the
105 .Ev BSDINSTALL_CONFIGCURRENT
106 is set, also sets the host name of the current system.
108 Interactively configures network interfaces (first invoking
110 on wireless interfaces), saving the result to the new system's
115 .Ev BSDINSTALL_CONFIGCURRENT
116 is set, also configures the network interfaces of the current system to match.
118 Provides the installer's interactive guided disk partitioner for single-disk
122 Detects an appropriate partition and installs UEFI boot loader files.
124 Provides a ZFS-only automatic interactive disk partitioner.
127 with separate datasets for
135 Optionally can set up
139 Provides the installer's interactive manual disk partitioner with an interface
142 Supports multiple disks as well as UFS, ZFS, and FAT file systems.
143 ZFS is set up with one pool and dataset per partition.
144 .It Cm scriptedpart Ar parameters
149 but non-interactively according to the disk setup specified in
151 Each disk setup is specified by a three-part argument:
157 Multiple disk setups are separated by semicolons.
160 argument specifies the disk on which to operate (which will be erased),
163 which will result in either a selection window (as in
165 for the destination disk or, if there is only one possible disk, will
166 automatically select it.
169 argument specifies the
171 partition scheme to apply to the disk.
176 will apply the default bootable scheme on your platform.
179 argument is also optional and specifies how to partition
181 It consists of a comma-separated list of partitions to create enclosed in
183 Each partition declaration takes the form
190 specifies the partition size to create in bytes (K, M, and G suffixes
191 can be appended to specify kilobytes, megabytes, and gigabytes respectively),
194 keyword causes the partition to take all the remaining space on the disk.
199 filesystem type, e.g., freebsd-ufs, freebsd-zfs, or freebsd-swap.
202 argument sets where the created partition is to be mounted in the installed
204 As an example, a typical invocation looks like:
206 bsdinstall scriptedpart ada0 { 20G freebsd-ufs /, 4G freebsd-swap, 20G freebsd-ufs /var, auto freebsd-ufs /usr }
208 Note that the list of partitions should
210 include boot partitions (e.g. EFI system partitions), which will be created automatically on whatever disk includes /.
212 A shorter invocation to use the default partitioning (as
214 would have used) on the same disk:
216 bsdinstall scriptedpart ada0
220 bsdinstall scriptedpart DEFAULT
222 Mounts the file systems previously configured by
228 .Ev BSDINSTALL_CHROOT .
230 Fetches the distributions in
233 .Ev BSDINSTALL_DISTDIR
235 .Ev BSDINSTALL_DISTSITE .
237 Verifies the checksums of the distributions listed in
239 against the distribution manifest.
241 Extracts the distributions listed in
244 .Ev BSDINSTALL_CHROOT .
246 Interactively invokes
248 in the new system to set the root user's password.
250 Interactively invokes
254 Interactively sets the time, date, and time zone of the new system.
256 Queries the user for the system daemons to begin at system startup,
257 writing the result into the new system's
260 Reads a small amount of data from
262 and stores it in a file in the new system's root directory.
264 Installs the configuration files destined for the new system, e.g.,
266 fragments generated by
268 etc.) onto the new system.
270 .Sh ENVIRONMENT VARIABLES
271 The following environment variables control various aspects of the installation
273 Many are used internally during installation and have reasonable default values
274 for most installation scenarios.
275 Others are set by various interactive user prompts, and can be usefully
276 overridden when making scripted or customized installers.
277 .Bl -tag -width ".Ev BSDINSTALL_DISTSITE"
279 The directory to use for temporary files.
283 The set of distributions to install, e.g., "base.txz kernel.txz ports.txz".
286 The partitioning of the disk onto which the system is being installed.
292 section for format details. If this variable is unset, the installer will
293 use the default partitioning as in
296 .It Ev BSDINSTALL_DISTDIR
297 The directory in which the distribution files can be found (or to which they
298 should be downloaded).
300 .Dq Pa /usr/freebsd-dist
301 .It Ev BSDINSTALL_DISTSITE
302 URL from which the distribution files should be downloaded if they are not
303 already present in the directory defined by
304 .Ev BSDINSTALL_DISTDIR .
305 This should be a full path to the files, including architecture and release
313 mirror will skip that step if this variable is already defined in the
316 .Pa https://download.freebsd.org/ftp/releases/powerpc/powerpc64/13.1-RELEASE/
318 .Pa http://ftp-archive.freebsd.org/pub/FreeBSD-Archive/old-releases/amd64/12.2-RELEASE/ .
319 .It Ev BSDINSTALL_CHROOT
320 The directory into which the distribution files should be unpacked and the
321 directory at which the root file system of the new system should be mounted.
324 .It Ev BSDINSTALL_LOG
325 Path to a log file for the installation.
327 .Dq Pa $TMPDIR/bsdinstall_log
328 .It Ev BSDINSTALL_TMPETC
329 Directory where files destined for the new system's
331 will be stored until the
334 If this directory does not already exist, it will be created.
336 .Dq Pa $TMPDIR/bsdinstall_etc
337 .It Ev BSDINSTALL_TMPBOOT
338 Directory where files destined for the new system's
340 will be stored until the
343 If this directory does not already exist, it will be created.
345 .Dq Pa $TMPDIR/bsdinstall_boot
347 Encrypted string to set the root password to in the format expected by
350 This option is used if both it and
353 .It Ev ROOTPASS_PLAIN
354 Plain text string to set the root password to.
355 .It Ev ZFSBOOT_POOL_NAME
356 Name for the pool containing the base system.
359 .It Ev ZFSBOOT_POOL_CREATE_OPTIONS
360 Options to be used when creating the base system's pool.
361 Each option must be preceded by the -O flag to be taken into consideration
362 or the pool will not be created due to errors using the command
365 .Dq Li "-O compress=lz4 -O atime=off"
366 .It Ev ZFSBOOT_BEROOT_NAME
367 Name for the boot environment parent dataset.
368 This is a non-mountable dataset meant to be a parent dataset where different
369 boot environment are going to be created.
372 .It Ev ZFSBOOT_BOOTFS_NAME
373 Name for the primary boot environment, which will be the default boot
374 environment for the system.
377 .It Ev ZFSBOOT_VDEV_TYPE
378 The type of pool to be created for the base system.
379 This variable can take one of this values: stripe (No redundancy),
380 mirror (n-Way mirroring), raid10 (RAID 1+0 - n x 2-Way Mirrors),
381 raidz1 (RAID-Z1 - Single Redundancy RAID), raidz2 (RAID-Z2 - Double Redundancy RAID)
382 or raidz3 (RAID-Z3 Triple Redundancy RAID).
385 .It Ev ZFSBOOT_FORCE_4K_SECTORS
386 Indicates either the pool will use 4K or 512 sectors.
387 If this variable is not empty, 4K sectors will be used.
390 .It Ev ZFSBOOT_GELI_ENCRYPTION
391 If this variable is not empty, it will use
393 to encrypt the root pool, enabling automatically the
394 .Ev ZFSBOOT_BOOT_POOL
398 .It Ev ZFSBOOT_GELI_KEY_FILE
401 keyfile used to encrypt the pool where the base system is stored.
403 .Dq Pa /boot/encryption.key
404 .It Ev ZFSBOOT_BOOT_POOL
405 If set, a separated boot pool will be created for the kernel of the
409 .It Ev ZFSBOOT_BOOT_POOL_CREATE_OPTIONS
410 Options to use when creating the boot pool, when enabled (See
411 .Ev ZFSBOOT_BOOT_POOL ).
413 .It Ev ZFSBOOT_BOOT_POOL_NAME
414 Name for the optional boot pool when it is enabled, (See
415 .Ev ZFSBOOT_BOOT_POOL ).
418 .It Ev ZFSBOOT_BOOT_POOL_SIZE
419 Size of the boot pool when it is enabled (See
420 .Ev ZFSBOOT_BOOT_POOL ).
424 Disks to be used for the base system, including the boot pool.
425 This variable must only be used on a scripted installation.
428 for more information.
430 .It Ev ZFSBOOT_SWAP_SIZE
431 Size of the swap partition on each block device.
432 This variable will be passed to
434 which supports SI unit suffixes.
437 .It Ev ZFSBOOT_SWAP_ENCRYPTION
438 If set, enables the encryption of the swap partition using
441 .It Ev ZFSBOOT_SWAP_MIRROR
442 If set, enables a swap mirroring using
446 .It Ev ZFSBOOT_DATASETS
447 ZFS datasets to be created on the root zpool, it requires the
451 .Pa /$ZFSBOOT_BEROOT_NAME/$ZFSBOOT_BOOTFS_NAME .
454 for more information about how to populate this variable and
456 .It Ev ZFSBOOT_CONFIRM_LAYOUT
457 If set and the installation is interactive, allow the user to confirm
458 the layout before continuing with the installation.
464 supports unattended, or minimally-attended, installations using scripting.
465 This can be used with either modified physical installation media or with
467 installations over the network; information on preparing such media can be
469 .Sx BUILDING AUTOMATIC INSTALL MEDIA
471 Scripted installations follow an essentially identical path to interactive
472 installations, though with some minor feature differences (for example,
473 scripted installations do not support fetching of remote distribution files
474 since scripted installations normally install the same files and the distributions
475 can be added directly to the installation media).
477 scripts consist of two parts: a
481 The preamble sets up the options for the installation (how to partition the
482 disk[s], which distributions to install, etc.) and the optional second part is
483 a shell script run under
485 in the newly installed system before
488 The two parts are separated by the usual script header (#!), which also sets
489 the interpreter for the setup script.
491 A typical bsdinstall script, using the default filesystem layout and the UFS
492 filesystem, looks like this:
493 .Bd -literal -offset indent
495 DISTRIBUTIONS="kernel.txz base.txz"
498 sysrc ifconfig_DEFAULT=DHCP
499 sysrc sshd_enable=YES
503 For a scripted installation involving a ZFS pool spanning multiple disks,
504 the script instead looks like this:
505 .Bd -literal -offset indent
506 DISTRIBUTIONS="kernel.txz base.txz"
507 export ZFSBOOT_VDEV_TYPE=stripe
508 export ZFSBOOT_DISKS="ada0 ada1"
509 export nonInteractive="YES"
512 echo "ifconfig_DEFAULT=DHCP" >> /etc/rc.conf
513 echo "sshd_enable=YES" >> /etc/rc.conf
519 release media, such a script placed at
520 .Pa /etc/installerconfig
521 will be run at boot time and the system will be rebooted automatically after
522 the installation has completed.
523 This can be used for unattended network installation of new systems; see
527 The preamble consists of installer settings.
528 These control global installation parameters (see
529 .Sx ENVIRONMENT VARIABLES )
530 as well as disk partitioning.
531 The preamble is interpreted as a
533 script run at the very beginning of the install.
534 If more complicated behavior than setting these variables is desired,
535 arbitrary commands can be run here to extend the installer.
536 In addition to the variables in
537 .Sx ENVIRONMENT VARIABLES ,
540 the preamble can contain a variable
542 which is passed to the
544 target to control disk setup.
551 the preamble can contain the variable
561 .Ev ZFSBOOT_VDEV_TYPE
562 must be set to create the pool of disks for the base system.
563 Usually, for a mirrored booting disk, these two variables look like this:
564 .Bd -literal -offset indent
565 ZFSBOOT_DISKS="ada0 ada1"
566 ZFSBOOT_VDEV_TYPE=mirror
569 Remember to export all the variables for the
571 command, otherwise installation will fail.
573 Following the preamble is an optional shell script, beginning with a #!
575 This script will be run at the end of the installation process inside a
577 environment in the newly installed system and can be used to set up
578 configuration files, install packages, etc.
579 Note that newly configured system services, e.g., networking have not
580 been started in the installed system at this time and only installation
581 host services are available.
585 in an installation script, the
587 partitioning tool takes the
589 variable to create the ZFS datasets on the base system.
590 This variable definition can become large if the pool contains many datasets.
594 .Bd -literal -offset indent
595 # DATASET OPTIONS (comma or space separated; or both)
597 # Boot Environment [BE] root and default boot dataset
598 /$ZFSBOOT_BEROOT_NAME mountpoint=none
599 /$ZFSBOOT_BEROOT_NAME/$ZFSBOOT_BOOTFS_NAME mountpoint=/
601 # Home directories separated so they are common to all BEs
602 /home mountpoint=/home
604 # Compress /tmp, allow exec but not setuid
605 /tmp mountpoint=/tmp,exec=on,setuid=off
607 # Do not mount /usr so that 'base' files go to the BEROOT
608 /usr mountpoint=/usr,canmount=off
611 /usr/ports setuid=off
613 # Source tree (compressed)
616 # Create /var and friends
617 /var mountpoint=/var,canmount=off
618 /var/audit exec=off,setuid=off
619 /var/crash exec=off,setuid=off
620 /var/log exec=off,setuid=off
625 The first column is the name of the dataset to be created as part of the
626 .Ev ZFSBOOT_POOL_NAME
627 pool and the remainder of each line contains the options to be set on each dataset.
628 If multiple options are given, they can be separated by either commas or whitespace;
629 everything following a pound/hash character is ignored as a comment.
630 .Ss BUILDING AUTOMATIC INSTALL MEDIA
631 If building automatic install media, use tar to extract a release ISO:
632 .Dl mkdir release-media
633 .Dl tar -C release-media -xvf FreeBSD-13.0-RELEASE-amd64-disc1.iso
635 Then place a script as above in
636 .Pa etc/installerconfig
638 This directory can then be used directly as an NFS root for
640 installations or it can be rebuilt into an ISO image using the release scripts in
641 .Pa /usr/src/release .
642 For example, on amd64:
643 .Dl sh /usr/src/release/amd64/mkisoimages.sh -b '13_0_RELEASE_AMD64_CD' output.iso release-media
650 .An Nathan Whitehorn Aq Mt nwhitehorn@FreeBSD.org
651 .An Devin Teske Aq Mt dteske@FreeBSD.org
652 .An Allan Jude Aq Mt allanjude@FreeBSD.org