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