Copyright (c) 2011-2013 Nathan Whitehorn <nwhitehorn@FreeBSD.org>
All rights reserved.
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions
are met:
1. Redistributions of source code must retain the above copyright
notice, this list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright
notice, this list of conditions and the following disclaimer in the
documentation and/or other materials provided with the distribution.
THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT,
INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
POSSIBILITY OF SUCH DAMAGE.
$FreeBSD: stable/10/usr.sbin/bsdinstall/bsdinstall.8 245792 2013-01-22 15:26:19Z nwhitehorn $
.Dd January 21, 2013 .Dt BSDINSTALL 8 .Os .Sh NAME .Nm bsdinstall .Nd system installer .Sh SYNOPSIS .Nm .Op Ar target .Op Ar ... .Sh DESCRIPTION .Nm is used for installation of new systems, both for system setup from installation media (e.g. CD-ROMs) and for use on live systems to prepare VM images and jails.
p Much like .Xr make 1 , Nm takes a target and possible parameters of the target as arguments. If invoked with no arguments, it will invoke the .Cm auto target, which provides a standard interactive installation, invoking the others in sequence. To perform a scripted installation, these subtargets can be invoked separately by an installation script. .Sh TARGETS Most of the following targets are only useful for scripting the installer. For interactive use, most users will be interested only in the .Cm auto , .Cm jail , and .Cm script targets. l -tag -width ".Cm jail Ar destination" t Cm auto Run the standard interactive installation, including disk partitioning. t Cm jail Ar destination Sets up a new chroot system at
a destination , suitable for use with .Xr jail 8 . Behavior is generally similar to .Cm auto , except that disk partitioning and network setup are skipped and a kernel is not installed into the new system. t Cm script Ar script Runs the installation script at
a script . See .Sx SCRIPTING for more information on this target. t Cm keymap If the current controlling TTY is a .Xr syscons 4 console, asks the user to set the current keymap, and saves the result to the new system's
a rc.conf . t Cm hostname Prompts the user for a host name for the new system and saves the result to the new system's
a rc.conf . If .Ev BSDINSTALL_CONFIGCURRENT is set, also sets the host name of the current system. t Cm netconfig Interactively configures network interfaces (first invoking .Cm wlanconfig on wireless interfaces), saving the result to the new system's
a rc.conf and
a resolv.conf . If .Ev BSDINSTALL_CONFIGCURRENT is set, also configures the network interfaces of the current system to match. t Cm autopart Provides the installer's interactive guided disk partitioner for single-disk installations. Partitions disks, runs .Xr newfs 8 , and writes the new system's
a fstab . t Cm partedit Provides the installer's interactive manual disk partitioner, with support for multi disk setups, non-UFS file systems, and manual selection of partition schemes. Partitions disks, runs .Xr newfs 8 , and writes the new system's
a fstab . t Cm scriptedpart Ar parameters Sets up disks like .Cm autopart and .Cm partedit , but non-interactively according to the disk setup specified in .Ar parameters . Each disk setup is specified by a three-part argument:
p .Ar disk .Op Ar scheme .Op Ar {partitions}
p Multiple disk setups are separated by semicolons. The .Ar disk argument specifies the disk on which to operate (which will be erased), while the .Ar scheme argument specifies the .Xr gpart 8 partition scheme to apply to the disk. If .Ar scheme is unspecified, .Cm scriptedpart will apply the default bootable scheme on your platform. The .Ar partitions argument is also optional and specifies how to partition .Ar disk . It consists of a comma-separated list of partitions to create enclosed in curly braces. Each partition declaration takes the form
p .Ar size .Ar type .Op Ar mount point
p .Ar size specifies the partition size to create in bytes (K, M, and G suffixes can be appended to specify kilobytes, megabytes, and gigabytes respectively), while the .Em auto keyword causes the partition to take all the remaining space on the disk. The .Ar type option chooses the .Xr gpart 8 filesystem type (e.g. freebsd-ufs or freebsd-swap). The optional .Ar mount point argument sets where the created partition is to be mounted in the installed system. As an example, a typical invocation looks like:
p bsdinstall scriptedpart ada0 { 20G freebsd-ufs /, 4G freebsd-swap, 20G freebsd-ufs /var, auto freebsd-ufs /usr } t Cm mount Mounts the file systems previously configured by .Cm autopart , .Cm partedit , or .Cm scriptedpart under .Ev BSDINSTALL_CHROOT . t Cm distfetch Fetches the distributions in .Ev DISTRIBUTIONS to .Ev BSDINSTALL_DISTDIR from .Ev BSDINSTALL_DISTSITE . t Cm checksum Verifies the checksums of the distributions listed in .Ev DISTRIBUTIONS against the distribution manifest. t Cm distextract Extracts the distributions listed in .Ev DISTRIBUTIONS into .Ev BSDINSTALL_CHROOT . t Cm rootpass Interactively invokes .Xr passwd 1 in the new system to set the root user's password. t Cm adduser Interactively invokes .Xr adduser 8 in the new system. t Cm time Interactively sets the time, date, and time zone of the new system. t Cm services Queries the user for the system daemons to begin at system startup, writing the result into the new system's
a rc.conf . t Cm config Installs the configuration files destined for the new system (e.g. rc.conf fragments generated by .Cm netconfig , etc.) onto the new system. .El .Sh ENVIRONMENT VARIABLES The following environment variables control various aspects of the installation process. Many are used internally during installation and have reasonable default values for most installation scenarios. Others are set by various interactive user prompts, and can be usefully overridden when making scripted or customized installers. l -tag -width ".Ev BSDINSTALL_DISTSITE" t Ev DISTRIBUTIONS The set of distributions to install (e.g. "base kernel ports"). Default: none t Ev BSDINSTALL_DISTDIR The directory in which the distribution files can be found (or to which they should be downloaded). Default:
a /usr/freebsd-dist t Ev BSDINSTALL_DISTSITE URL from which the distribution files should be downloaded if they are not already present in the directory defined by .Ev BSDINSTALL_DISTDIR . This should be a full path to the files, including architecture and release names. Most targets (e.g. .Cm auto and .Cm jail ) that prompt for a .Fx mirror will skip that step if this variable is already defined in the environment. Example:
a ftp://ftp.freebsd.org/pub/FreeBSD/releases/powerpc/powerpc64/9.1-RELEASE t Ev BSDINSTALL_CHROOT The directory into which the distribution files should be unpacked and the directory at which the root file system of the new system should be mounted. Default:
a /mnt t Ev BSDINSTALL_LOG Path to a log file for the installation. Default:
a /tmp/bsdinstall_log t Ev BSDINSTALL_TMPETC Directory where files destined for the new system's
a /etc will be stored until the .Cm config target is executed. If this directory does not already exist, it will be created. Default:
a /tmp/bsdinstall_etc .El .Sh SCRIPTING .Nm scripts consist of two parts: a .Em preamble and a .Em setup script . The preamble sets up the options for the installation (how to partition the disk[s], which distributions to install, etc.) and the optional second part is a shell script run under .Xr chroot 8 in the newly installed system before .Nm exits. The two parts are separated by the usual script header (#!), which also sets the interpreter for the setup script.
p A typical bsdinstall script looks like this: d -literal -offset indent PARTITIONS=ada0 DISTRIBUTIONS="kernel.txz base.txz" #!/bin/sh echo "ifconfig_em0=DHCP" >> /etc/rc.conf echo "sshd_enable=YES" >> /etc/rc.conf pkg install puppet .Ed
p On .Fx release media, such a script placed at
a /etc/installerconfig will be run at boot time and the system will be rebooted automatically after the installation has completed. This can be used for unattended network installation of new systems; see .Xr diskless 8 for details. .Ss PREAMBLE The preamble consists of installer settings. These control global installation parameters (see .Sx ENVIRONMENT VARIABLES ) as well as disk partitioning. The preamble is interpreted as a .Xr sh 1 script run at the very beginning of the install. If more complicated behavior than setting these variables is desired, arbitrary commands can be run here to extend the installer. In addition to the variables in .Sx ENVIRONMENT VARIABLES , in particular .Ev DISTRIBUTIONS , the preamble can contain a variable .Ev PARTITIONS which is passed to the .Cm scriptedpart target to control disk setup. .Ss SETUP SCRIPT Following the preamble is an optional shell script, beginning with a #! declaration. This script will be run at the end of the installation process inside a .Xr chroot 8 environment in the newly installed system and can be used to set up configuration files, install packages, etc. Note that newly configured system services (e.g. networking) have not been started in the installed system at this time and only installation host services are available. .Sh HISTORY This version of .Nm first appeared in .Fx 9.0 . .Sh AUTHORS .An -nosplit .An Nathan Whitehorn Aq nwhitehorn@FreeBSD.org