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.
76 .It Cm jail Ar destination
77 Sets up a new chroot system at
81 Behavior is generally similar to
83 except that disk partitioning and network setup are skipped and a kernel is
84 not installed into the new system.
85 .It Cm script Ar script
86 Runs the installation script at
90 for more information on this target.
92 If the current controlling TTY is a
96 console, asks the user to set the current keymap, and saves the result to the
100 Prompts the user for a host name for the new system and saves the result to the
104 .Ev BSDINSTALL_CONFIGCURRENT
105 is set, also sets the host name of the current system.
107 Interactively configures network interfaces (first invoking
109 on wireless interfaces), saving the result to the new system's
114 .Ev BSDINSTALL_CONFIGCURRENT
115 is set, also configures the network interfaces of the current system to match.
117 Provides the installer's interactive guided disk partitioner for single-disk
118 installations. Defaults to UFS.
120 Provides an alternative ZFS-only automatic interactive disk partitioner.
123 with separate datasets for
131 Optionally can set up
135 Provides the installer's interactive manual disk partitioner with an interface
138 Supports multiple disks as well as UFS, ZFS, and FAT file systems. ZFS
139 is set up with one pool and dataset per partition.
140 .It Cm scriptedpart Ar parameters
145 but non-interactively according to the disk setup specified in
147 Each disk setup is specified by a three-part argument:
153 Multiple disk setups are separated by semicolons. The
155 argument specifies the disk on which to operate (which will be erased),
158 argument specifies the
160 partition scheme to apply to the disk. If
164 will apply the default bootable scheme on your platform.
167 argument is also optional and specifies how to partition
169 It consists of a comma-separated list of partitions to create enclosed in
170 curly braces. Each partition declaration takes the form
177 specifies the partition size to create in bytes (K, M, and G suffixes
178 can be appended to specify kilobytes, megabytes, and gigabytes respectively),
181 keyword causes the partition to take all the remaining space on the disk. The
185 filesystem type (e.g. freebsd-ufs, freebsd-zfs, or freebsd-swap).
188 argument sets where the created partition is to be mounted in the installed
189 system. As an example, a typical invocation looks like:
191 bsdinstall scriptedpart ada0 { 20G freebsd-ufs /, 4G freebsd-swap, 20G freebsd-ufs /var, auto freebsd-ufs /usr }
193 A shorter invocation to use the default partitioning (as
195 would have used) on the same disk:
197 bsdinstall scriptedpart ada0
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 Reads a small amount of data from
239 and stores it in a file in the new system's root directory.
241 Installs the configuration files destined for the new system (e.g. rc.conf
242 fragments generated by
244 etc.) onto the new system.
246 .Sh ENVIRONMENT VARIABLES
247 The following environment variables control various aspects of the installation
248 process. Many are used internally during installation and have reasonable
249 default values for most installation scenarios. Others are set by various
250 interactive user prompts, and can be usefully overridden when making scripted
251 or customized installers.
252 .Bl -tag -width ".Ev BSDINSTALL_DISTSITE"
254 The set of distributions to install (e.g. "base kernel ports"). Default: none
255 .It Ev BSDINSTALL_DISTDIR
256 The directory in which the distribution files can be found (or to which they
257 should be downloaded). Default:
258 .Pa /usr/freebsd-dist
259 .It Ev BSDINSTALL_DISTSITE
260 URL from which the distribution files should be downloaded if they are not
261 already present in the directory defined by
262 .Ev BSDINSTALL_DISTDIR .
263 This should be a full path to the files, including architecture and release
264 names. Most targets (e.g.
270 mirror will skip that step if this variable is already defined in the
271 environment. Example:
272 .Pa ftp://ftp.freebsd.org/pub/FreeBSD/releases/powerpc/powerpc64/9.1-RELEASE
273 .It Ev BSDINSTALL_CHROOT
274 The directory into which the distribution files should be unpacked and the
275 directory at which the root file system of the new system should be mounted.
278 .It Ev BSDINSTALL_LOG
279 Path to a log file for the installation. Default:
280 .Pa /tmp/bsdinstall_log
281 .It Ev BSDINSTALL_TMPETC
282 Directory where files destined for the new system's
284 will be stored until the
286 target is executed. If this directory does not already exist, it will be
288 .Pa /tmp/bsdinstall_etc
289 .It Ev BSDINSTALL_TMPBOOT
290 Directory where files destined for the new system's
292 will be stored until the
294 target is executed. If this directory does not already exist, it will be
296 .Pa /tmp/bsdinstall_boot
300 scripts consist of two parts: a
304 The preamble sets up the options for the installation (how to partition the
305 disk[s], which distributions to install, etc.) and the optional second part is
306 a shell script run under
308 in the newly installed system before
310 exits. The two parts are separated by the usual script header (#!), which
311 also sets the interpreter for the setup script.
313 A typical bsdinstall script looks like this:
314 .Bd -literal -offset indent
316 DISTRIBUTIONS="kernel.txz base.txz"
319 echo "ifconfig_em0=DHCP" >> /etc/rc.conf
320 echo "sshd_enable=YES" >> /etc/rc.conf
326 release media, such a script placed at
327 .Pa /etc/installerconfig
328 will be run at boot time and the system will be rebooted automatically after
329 the installation has completed. This can be used for unattended network
330 installation of new systems; see
334 The preamble consists of installer settings. These control global installation
336 .Sx ENVIRONMENT VARIABLES )
337 as well as disk partitioning. The preamble is interpreted as a
339 script run at the very beginning of the install. If more complicated behavior
340 than setting these variables is desired, arbitrary commands can be run here
341 to extend the installer. In addition to the variables in
342 .Sx ENVIRONMENT VARIABLES ,
345 the preamble can contain a variable
347 which is passed to the
349 target to control disk setup.
355 the preamble can contain the variable
360 Following the preamble is an optional shell script, beginning with a #!
361 declaration. This script will be run at the end of the installation process
364 environment in the newly installed system and can be used to set up
365 configuration files, install packages, etc. Note that newly configured
366 system services (e.g. networking) have not been started in the installed
367 system at this time and only installation host services are available.
375 .An Nathan Whitehorn Aq nwhitehorn@FreeBSD.org