1.\"- 2.\" Copyright (c) 2011-2013 Nathan Whitehorn <nwhitehorn@FreeBSD.org> 3.\" All rights reserved. 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 October 31, 2014 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. If 48invoked with no arguments, it will invoke the 49.Cm auto 50target, which provides a standard interactive installation, invoking the 51others in sequence. To perform a scripted installation, these subtargets 52can be invoked separately by an installation script. 53.Sh OPTIONS 54.Nm 55supports the following options, global to all targets: 56.Bl -tag -width indent+ 57.It Fl D Ar file 58Provide a path for the installation log file 59.Pq overrides Ev BSDINSTALL_LOG . 60See 61.Sx ENVIRONMENT VARIABLES 62for more information on 63.Ev BSDINSTALL_LOG . 64.El 65.Sh TARGETS 66Most of the following targets are only useful for scripting the installer. 67For interactive use, most users will be interested only in the 68.Cm auto , 69.Cm jail , 70and 71.Cm script 72targets. 73.Bl -tag -width ".Cm jail Ar destination" 74.It Cm auto 75Run the standard interactive installation, including disk partitioning. 76.It Cm jail Ar destination 77Sets up a new chroot system at 78.Pa destination , 79suitable for use with 80.Xr jail 8 . 81Behavior is generally similar to 82.Cm auto , 83except that disk partitioning and network setup are skipped and a kernel is 84not installed into the new system. 85.It Cm script Ar script 86Runs the installation script at 87.Pa script . 88See 89.Sx SCRIPTING 90for more information on this target. 91.It Cm keymap 92If the current controlling TTY is a 93.Xr syscons 4 94or 95.Xr vt 4 96console, asks the user to set the current keymap, and saves the result to the 97new system's 98.Pa rc.conf . 99.It Cm hostname 100Prompts the user for a host name for the new system and saves the result to the 101new system's 102.Pa rc.conf . 103If 104.Ev BSDINSTALL_CONFIGCURRENT 105is set, also sets the host name of the current system. 106.It Cm netconfig 107Interactively configures network interfaces (first invoking 108.Cm wlanconfig 109on wireless interfaces), saving the result to the new system's 110.Pa rc.conf 111and 112.Pa resolv.conf . 113If 114.Ev BSDINSTALL_CONFIGCURRENT 115is set, also configures the network interfaces of the current system to match. 116.It Cm autopart 117Provides the installer's interactive guided disk partitioner for single-disk 118installations. Defaults to UFS. 119.It Cm zfsboot 120Provides an alternative ZFS-only automatic interactive disk partitioner. 121Creates a single 122.Ic zpool 123with separate datasets for 124.Pa /tmp , 125.Pa /usr , 126.Pa /usr/home , 127.Pa /usr/ports , 128.Pa /usr/src , 129and 130.Pa /var . 131Optionally can set up 132.Xr geli 8 133to encrypt the disk. 134.It Cm partedit 135Provides the installer's interactive manual disk partitioner with an interface 136identical to 137.Xr sade 8 . 138Supports multiple disks as well as UFS, ZFS, and FAT file systems. ZFS 139is set up with one pool and dataset per partition. 140.It Cm scriptedpart Ar parameters 141Sets up disks like 142.Cm autopart 143and 144.Cm partedit , 145but non-interactively according to the disk setup specified in 146.Ar parameters . 147Each disk setup is specified by a three-part argument: 148.Pp 149.Ar disk 150.Op Ar scheme 151.Op Ar {partitions} 152.Pp 153Multiple disk setups are separated by semicolons. The 154.Ar disk 155argument specifies the disk on which to operate (which will be erased), 156while the 157.Ar scheme 158argument specifies the 159.Xr gpart 8 160partition scheme to apply to the disk. If 161.Ar scheme 162is unspecified, 163.Cm scriptedpart 164will apply the default bootable scheme on your platform. 165The 166.Ar partitions 167argument is also optional and specifies how to partition 168.Ar disk . 169It consists of a comma-separated list of partitions to create enclosed in 170curly braces. Each partition declaration takes the form 171.Pp 172.Ar size 173.Ar type 174.Op Ar mount point 175.Pp 176.Ar size 177specifies the partition size to create in bytes (K, M, and G suffixes 178can be appended to specify kilobytes, megabytes, and gigabytes respectively), 179while the 180.Em auto 181keyword causes the partition to take all the remaining space on the disk. The 182.Ar type 183option chooses the 184.Xr gpart 8 185filesystem type (e.g. freebsd-ufs, freebsd-zfs, or freebsd-swap). 186The optional 187.Ar mount point 188argument sets where the created partition is to be mounted in the installed 189system. As an example, a typical invocation looks like: 190.Pp 191bsdinstall scriptedpart ada0 { 20G freebsd-ufs /, 4G freebsd-swap, 20G freebsd-ufs /var, auto freebsd-ufs /usr } 192.Pp 193A shorter invocation to use the default partitioning (as 194.Cm autopart 195would have used) on the same disk: 196.Pp 197bsdinstall scriptedpart ada0 198.It Cm mount 199Mounts the file systems previously configured by 200.Cm autopart , 201.Cm partedit , 202or 203.Cm scriptedpart 204under 205.Ev BSDINSTALL_CHROOT . 206.It Cm distfetch 207Fetches the distributions in 208.Ev DISTRIBUTIONS 209to 210.Ev BSDINSTALL_DISTDIR 211from 212.Ev BSDINSTALL_DISTSITE . 213.It Cm checksum 214Verifies the checksums of the distributions listed in 215.Ev DISTRIBUTIONS 216against the distribution manifest. 217.It Cm distextract 218Extracts the distributions listed in 219.Ev DISTRIBUTIONS 220into 221.Ev BSDINSTALL_CHROOT . 222.It Cm rootpass 223Interactively invokes 224.Xr passwd 1 225in the new system to set the root user's password. 226.It Cm adduser 227Interactively invokes 228.Xr adduser 8 229in the new system. 230.It Cm time 231Interactively sets the time, date, and time zone of the new system. 232.It Cm services 233Queries the user for the system daemons to begin at system startup, 234writing the result into the new system's 235.Pa rc.conf . 236.It Cm entropy 237Reads a small amount of data from 238.Pa /dev/random 239and stores it in a file in the new system's root directory. 240.It Cm config 241Installs the configuration files destined for the new system (e.g. rc.conf 242fragments generated by 243.Cm netconfig , 244etc.) onto the new system. 245.El 246.Sh ENVIRONMENT VARIABLES 247The following environment variables control various aspects of the installation 248process. Many are used internally during installation and have reasonable 249default values for most installation scenarios. Others are set by various 250interactive user prompts, and can be usefully overridden when making scripted 251or customized installers. 252.Bl -tag -width ".Ev BSDINSTALL_DISTSITE" 253.It Ev DISTRIBUTIONS 254The set of distributions to install (e.g. "base kernel ports"). Default: none 255.It Ev BSDINSTALL_DISTDIR 256The directory in which the distribution files can be found (or to which they 257should be downloaded). Default: 258.Pa /usr/freebsd-dist 259.It Ev BSDINSTALL_DISTSITE 260URL from which the distribution files should be downloaded if they are not 261already present in the directory defined by 262.Ev BSDINSTALL_DISTDIR . 263This should be a full path to the files, including architecture and release 264names. Most targets (e.g. 265.Cm auto 266and 267.Cm jail ) 268that prompt for a 269.Fx 270mirror will skip that step if this variable is already defined in the 271environment. Example: 272.Pa ftp://ftp.freebsd.org/pub/FreeBSD/releases/powerpc/powerpc64/9.1-RELEASE 273.It Ev BSDINSTALL_CHROOT 274The directory into which the distribution files should be unpacked and the 275directory at which the root file system of the new system should be mounted. 276Default: 277.Pa /mnt 278.It Ev BSDINSTALL_LOG 279Path to a log file for the installation. Default: 280.Pa /tmp/bsdinstall_log 281.It Ev BSDINSTALL_TMPETC 282Directory where files destined for the new system's 283.Pa /etc 284will be stored until the 285.Cm config 286target is executed. If this directory does not already exist, it will be 287created. Default: 288.Pa /tmp/bsdinstall_etc 289.It Ev BSDINSTALL_TMPBOOT 290Directory where files destined for the new system's 291.Pa /boot 292will be stored until the 293.Cm config 294target is executed. If this directory does not already exist, it will be 295created. Default: 296.Pa /tmp/bsdinstall_boot 297.El 298.Sh SCRIPTING 299.Nm 300scripts consist of two parts: a 301.Em preamble 302and a 303.Em setup script . 304The preamble sets up the options for the installation (how to partition the 305disk[s], which distributions to install, etc.) and the optional second part is 306a shell script run under 307.Xr chroot 8 308in the newly installed system before 309.Nm 310exits. The two parts are separated by the usual script header (#!), which 311also sets the interpreter for the setup script. 312.Pp 313A typical bsdinstall script looks like this: 314.Bd -literal -offset indent 315PARTITIONS=ada0 316DISTRIBUTIONS="kernel.txz base.txz" 317 318#!/bin/sh 319echo "ifconfig_em0=DHCP" >> /etc/rc.conf 320echo "sshd_enable=YES" >> /etc/rc.conf 321pkg install puppet 322.Ed 323.Pp 324On 325.Fx 326release media, such a script placed at 327.Pa /etc/installerconfig 328will be run at boot time and the system will be rebooted automatically after 329the installation has completed. This can be used for unattended network 330installation of new systems; see 331.Xr diskless 8 332for details. 333.Ss PREAMBLE 334The preamble consists of installer settings. These control global installation 335parameters (see 336.Sx ENVIRONMENT VARIABLES ) 337as well as disk partitioning. The preamble is interpreted as a 338.Xr sh 1 339script run at the very beginning of the install. If more complicated behavior 340than setting these variables is desired, arbitrary commands can be run here 341to extend the installer. In addition to the variables in 342.Sx ENVIRONMENT VARIABLES , 343in particular 344.Ev DISTRIBUTIONS , 345the preamble can contain a variable 346.Ev PARTITIONS 347which is passed to the 348.Cm scriptedpart 349target to control disk setup. 350Alternatively, 351to use 352.Cm zfsboot 353instead of 354.Cm partedit , 355the preamble can contain the variable 356.Ev ZFSBOOT_DATASETS 357instead of 358.Ev PARTITIONS . 359.Ss SETUP SCRIPT 360Following the preamble is an optional shell script, beginning with a #! 361declaration. This script will be run at the end of the installation process 362inside a 363.Xr chroot 8 364environment in the newly installed system and can be used to set up 365configuration files, install packages, etc. Note that newly configured 366system services (e.g. networking) have not been started in the installed 367system at this time and only installation host services are available. 368.Sh HISTORY 369This version of 370.Nm 371first appeared in 372.Fx 9.0 . 373.Sh AUTHORS 374.An Nathan Whitehorn Aq Mt nwhitehorn@FreeBSD.org 375