2 .\" Copyright (c) 2011-2013 Nathan Whitehorn <nwhitehorn@FreeBSD.org>
3 .\" All rights reserved.
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. If
48 invoked with no arguments, it will invoke the
50 target, which provides a standard interactive installation, invoking the
51 others in sequence. To perform a scripted installation, these subtargets
52 can be invoked separately by an installation script.
55 supports the following options, global to all targets:
56 .Bl -tag -width indent+
58 Provide a path for the installation log file
59 .Pq overrides Ev BSDINSTALL_LOG .
61 .Sx ENVIRONMENT VARIABLES
62 for more information on
66 Most of the following targets are only useful for scripting the installer.
67 For interactive use, most users will be interested only in the
73 .Bl -tag -width ".Cm jail Ar destination"
75 Run the standard interactive installation, including disk partitioning.
77 Reads a small amount of data from
79 and stores it in a file in the new system's root directory.
80 .It Cm jail Ar destination
81 Sets up a new chroot system at
85 Behavior is generally similar to
87 except that disk partitioning and network setup are skipped and a kernel is
88 not installed into the new system.
89 .It Cm script Ar script
90 Runs the installation script at
94 for more information on this target.
96 If the current controlling TTY is a
98 console, asks the user to set the current keymap, and saves the result to the
102 Prompts the user for a host name for the new system and saves the result to the
106 .Ev BSDINSTALL_CONFIGCURRENT
107 is set, also sets the host name of the current system.
109 Interactively configures network interfaces (first invoking
111 on wireless interfaces), saving the result to the new system's
116 .Ev BSDINSTALL_CONFIGCURRENT
117 is set, also configures the network interfaces of the current system to match.
119 Provides the installer's interactive guided disk partitioner for single-disk
120 installations. Partitions disks, runs
122 and writes the new system's
125 Provides the installer's
127 interactive/scriptable ZFS partitioner for multi-disk installations.
130 with datasets and writes to the new system's
138 and many other features.
140 Provides the installer's interactive manual disk partitioner, with support
141 for multi disk setups, non-UFS file systems, and manual selection of
142 partition schemes. Partitions disks, runs
144 and writes the new system's
146 .It Cm scriptedpart Ar parameters
151 but non-interactively according to the disk setup specified in
153 Each disk setup is specified by a three-part argument:
159 Multiple disk setups are separated by semicolons. The
161 argument specifies the disk on which to operate (which will be erased),
164 argument specifies the
166 partition scheme to apply to the disk. If
170 will apply the default bootable scheme on your platform.
173 argument is also optional and specifies how to partition
175 It consists of a comma-separated list of partitions to create enclosed in
176 curly braces. Each partition declaration takes the form
183 specifies the partition size to create in bytes (K, M, and G suffixes
184 can be appended to specify kilobytes, megabytes, and gigabytes respectively),
187 keyword causes the partition to take all the remaining space on the disk. The
191 filesystem type (e.g. freebsd-ufs or freebsd-swap).
194 argument sets where the created partition is to be mounted in the installed
195 system. As an example, a typical invocation looks like:
197 bsdinstall scriptedpart ada0 { 20G freebsd-ufs /, 4G freebsd-swap, 20G freebsd-ufs /var, auto freebsd-ufs /usr }
199 Mounts the file systems previously configured by
205 .Ev BSDINSTALL_CHROOT .
207 Fetches the distributions in
210 .Ev BSDINSTALL_DISTDIR
212 .Ev BSDINSTALL_DISTSITE .
214 Verifies the checksums of the distributions listed in
216 against the distribution manifest.
218 Extracts the distributions listed in
221 .Ev BSDINSTALL_CHROOT .
223 Interactively invokes
225 in the new system to set the root user's password.
227 Interactively invokes
231 Interactively sets the time, date, and time zone of the new system.
233 Queries the user for the system daemons to begin at system startup,
234 writing the result into the new system's
237 Installs the configuration files destined for the new system (e.g. rc.conf
238 fragments generated by
240 etc.) onto the new system.
242 .Sh ENVIRONMENT VARIABLES
243 The following environment variables control various aspects of the installation
244 process. Many are used internally during installation and have reasonable
245 default values for most installation scenarios. Others are set by various
246 interactive user prompts, and can be usefully overridden when making scripted
247 or customized installers.
248 .Bl -tag -width ".Ev BSDINSTALL_DISTSITE"
250 The set of distributions to install (e.g. "base kernel ports"). Default: none
251 .It Ev BSDINSTALL_DISTDIR
252 The directory in which the distribution files can be found (or to which they
253 should be downloaded). Default:
254 .Pa /usr/freebsd-dist
255 .It Ev BSDINSTALL_DISTSITE
256 URL from which the distribution files should be downloaded if they are not
257 already present in the directory defined by
258 .Ev BSDINSTALL_DISTDIR .
259 This should be a full path to the files, including architecture and release
260 names. Most targets (e.g.
266 mirror will skip that step if this variable is already defined in the
267 environment. Example:
268 .Pa ftp://ftp.freebsd.org/pub/FreeBSD/releases/powerpc/powerpc64/9.1-RELEASE
269 .It Ev BSDINSTALL_CHROOT
270 The directory into which the distribution files should be unpacked and the
271 directory at which the root file system of the new system should be mounted.
274 .It Ev BSDINSTALL_LOG
275 Path to a log file for the installation. Default:
276 .Pa /tmp/bsdinstall_log
277 .It Ev BSDINSTALL_TMPETC
278 Directory where files destined for the new system's
280 will be stored until the
282 target is executed. If this directory does not already exist, it will be
284 .Pa /tmp/bsdinstall_etc
285 .It Ev BSDINSTALL_TMPBOOT
286 Directory where files destined for the new system's
288 will be stored until the
290 target is executed. If this directory does not already exist, it will be
292 .Pa /tmp/bsdinstall_boot
296 scripts consist of two parts: a
300 The preamble sets up the options for the installation (how to partition the
301 disk[s], which distributions to install, etc.) and the optional second part is
302 a shell script run under
304 in the newly installed system before
306 exits. The two parts are separated by the usual script header (#!), which
307 also sets the interpreter for the setup script.
309 A typical bsdinstall script looks like this:
310 .Bd -literal -offset indent
312 DISTRIBUTIONS="kernel.txz base.txz"
315 echo "ifconfig_em0=DHCP" >> /etc/rc.conf
316 echo "sshd_enable=YES" >> /etc/rc.conf
322 release media, such a script placed at
323 .Pa /etc/installerconfig
324 will be run at boot time and the system will be rebooted automatically after
325 the installation has completed. This can be used for unattended network
326 installation of new systems; see
330 The preamble consists of installer settings. These control global installation
332 .Sx ENVIRONMENT VARIABLES )
333 as well as disk partitioning. The preamble is interpreted as a
335 script run at the very beginning of the install. If more complicated behavior
336 than setting these variables is desired, arbitrary commands can be run here
337 to extend the installer. In addition to the variables in
338 .Sx ENVIRONMENT VARIABLES ,
341 the preamble can contain a variable
343 which is passed to the
345 target to control disk setup.
349 the preamble can contain the variable
351 which is parsed by the
354 target to control ZFS datasets/options of the boot pool setup.
356 Following the preamble is an optional shell script, beginning with a #!
357 declaration. This script will be run at the end of the installation process
360 environment in the newly installed system and can be used to set up
361 configuration files, install packages, etc. Note that newly configured
362 system services (e.g. networking) have not been started in the installed
363 system at this time and only installation host services are available.
371 .An Nathan Whitehorn Aq nwhitehorn@FreeBSD.org