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