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.
40 is used for installation of new systems, both for system setup from
41 installation media (e.g. CD-ROMs) and for use on live systems to prepare
46 takes a target and possible parameters of the target as arguments. If
47 invoked with no arguments, it will invoke the
49 target, which provides a standard interactive installation, invoking the
50 others in sequence. To perform a scripted installation, these subtargets
51 can be invoked separately by an installation script.
53 Most of the following targets are only useful for scripting the installer.
54 For interactive use, most users will be interested only in the
60 .Bl -tag -width ".Cm jail Ar destination"
62 Run the standard interactive installation, including disk partitioning.
64 Reads a small amount of data from
66 and stores it in a file in the new system's root directory.
67 .It Cm jail Ar destination
68 Sets up a new chroot system at
72 Behavior is generally similar to
74 except that disk partitioning and network setup are skipped and a kernel is
75 not installed into the new system.
76 .It Cm script Ar script
77 Runs the installation script at
81 for more information on this target.
83 If the current controlling TTY is a
85 console, asks the user to set the current keymap, and saves the result to the
89 Prompts the user for a host name for the new system and saves the result to the
93 .Ev BSDINSTALL_CONFIGCURRENT
94 is set, also sets the host name of the current system.
96 Interactively configures network interfaces (first invoking
98 on wireless interfaces), saving the result to the new system's
103 .Ev BSDINSTALL_CONFIGCURRENT
104 is set, also configures the network interfaces of the current system to match.
106 Provides the installer's interactive guided disk partitioner for single-disk
107 installations. Partitions disks, runs
109 and writes the new system's
112 Provides the installer's
114 interactive/scriptable ZFS partitioner for multi-disk installations.
117 with datasets and writes to the new system's
125 and many other features.
127 Provides the installer's interactive manual disk partitioner, with support
128 for multi disk setups, non-UFS file systems, and manual selection of
129 partition schemes. Partitions disks, runs
131 and writes the new system's
133 .It Cm scriptedpart Ar parameters
138 but non-interactively according to the disk setup specified in
140 Each disk setup is specified by a three-part argument:
146 Multiple disk setups are separated by semicolons. The
148 argument specifies the disk on which to operate (which will be erased),
151 argument specifies the
153 partition scheme to apply to the disk. If
157 will apply the default bootable scheme on your platform.
160 argument is also optional and specifies how to partition
162 It consists of a comma-separated list of partitions to create enclosed in
163 curly braces. Each partition declaration takes the form
170 specifies the partition size to create in bytes (K, M, and G suffixes
171 can be appended to specify kilobytes, megabytes, and gigabytes respectively),
174 keyword causes the partition to take all the remaining space on the disk. The
178 filesystem type (e.g. freebsd-ufs or freebsd-swap).
181 argument sets where the created partition is to be mounted in the installed
182 system. As an example, a typical invocation looks like:
184 bsdinstall scriptedpart ada0 { 20G freebsd-ufs /, 4G freebsd-swap, 20G freebsd-ufs /var, auto freebsd-ufs /usr }
186 Mounts the file systems previously configured by
192 .Ev BSDINSTALL_CHROOT .
194 Fetches the distributions in
197 .Ev BSDINSTALL_DISTDIR
199 .Ev BSDINSTALL_DISTSITE .
201 Verifies the checksums of the distributions listed in
203 against the distribution manifest.
205 Extracts the distributions listed in
208 .Ev BSDINSTALL_CHROOT .
210 Interactively invokes
212 in the new system to set the root user's password.
214 Interactively invokes
218 Interactively sets the time, date, and time zone of the new system.
220 Queries the user for the system daemons to begin at system startup,
221 writing the result into the new system's
224 Installs the configuration files destined for the new system (e.g. rc.conf
225 fragments generated by
227 etc.) onto the new system.
229 .Sh ENVIRONMENT VARIABLES
230 The following environment variables control various aspects of the installation
231 process. Many are used internally during installation and have reasonable
232 default values for most installation scenarios. Others are set by various
233 interactive user prompts, and can be usefully overridden when making scripted
234 or customized installers.
235 .Bl -tag -width ".Ev BSDINSTALL_DISTSITE"
237 The set of distributions to install (e.g. "base kernel ports"). Default: none
238 .It Ev BSDINSTALL_DISTDIR
239 The directory in which the distribution files can be found (or to which they
240 should be downloaded). Default:
241 .Pa /usr/freebsd-dist
242 .It Ev BSDINSTALL_DISTSITE
243 URL from which the distribution files should be downloaded if they are not
244 already present in the directory defined by
245 .Ev BSDINSTALL_DISTDIR .
246 This should be a full path to the files, including architecture and release
247 names. Most targets (e.g.
253 mirror will skip that step if this variable is already defined in the
254 environment. Example:
255 .Pa ftp://ftp.freebsd.org/pub/FreeBSD/releases/powerpc/powerpc64/9.1-RELEASE
256 .It Ev BSDINSTALL_CHROOT
257 The directory into which the distribution files should be unpacked and the
258 directory at which the root file system of the new system should be mounted.
261 .It Ev BSDINSTALL_LOG
262 Path to a log file for the installation. Default:
263 .Pa /tmp/bsdinstall_log
264 .It Ev BSDINSTALL_TMPETC
265 Directory where files destined for the new system's
267 will be stored until the
269 target is executed. If this directory does not already exist, it will be
271 .Pa /tmp/bsdinstall_etc
272 .It Ev BSDINSTALL_TMPBOOT
273 Directory where files destined for the new system's
275 will be stored until the
277 target is executed. If this directory does not already exist, it will be
279 .Pa /tmp/bsdinstall_boot
283 scripts consist of two parts: a
287 The preamble sets up the options for the installation (how to partition the
288 disk[s], which distributions to install, etc.) and the optional second part is
289 a shell script run under
291 in the newly installed system before
293 exits. The two parts are separated by the usual script header (#!), which
294 also sets the interpreter for the setup script.
296 A typical bsdinstall script looks like this:
297 .Bd -literal -offset indent
299 DISTRIBUTIONS="kernel.txz base.txz"
302 echo "ifconfig_em0=DHCP" >> /etc/rc.conf
303 echo "sshd_enable=YES" >> /etc/rc.conf
309 release media, such a script placed at
310 .Pa /etc/installerconfig
311 will be run at boot time and the system will be rebooted automatically after
312 the installation has completed. This can be used for unattended network
313 installation of new systems; see
317 The preamble consists of installer settings. These control global installation
319 .Sx ENVIRONMENT VARIABLES )
320 as well as disk partitioning. The preamble is interpreted as a
322 script run at the very beginning of the install. If more complicated behavior
323 than setting these variables is desired, arbitrary commands can be run here
324 to extend the installer. In addition to the variables in
325 .Sx ENVIRONMENT VARIABLES ,
328 the preamble can contain a variable
330 which is passed to the
332 target to control disk setup.
336 the preamble can contain the variable
338 which is parsed by the
341 target to control ZFS datasets/options of the boot pool setup.
343 Following the preamble is an optional shell script, beginning with a #!
344 declaration. This script will be run at the end of the installation process
347 environment in the newly installed system and can be used to set up
348 configuration files, install packages, etc. Note that newly configured
349 system services (e.g. networking) have not been started in the installed
350 system at this time and only installation host services are available.
358 .An Nathan Whitehorn Aq nwhitehorn@FreeBSD.org