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