diff options
Diffstat (limited to 'usr.sbin/bsdinstall/bsdinstall.8')
| -rw-r--r-- | usr.sbin/bsdinstall/bsdinstall.8 | 374 |
1 files changed, 374 insertions, 0 deletions
diff --git a/usr.sbin/bsdinstall/bsdinstall.8 b/usr.sbin/bsdinstall/bsdinstall.8 new file mode 100644 index 0000000..a08eff9 --- /dev/null +++ b/usr.sbin/bsdinstall/bsdinstall.8 @@ -0,0 +1,374 @@ +.\"- +.\" 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$ +.\" +.Dd October 31, 2014 +.Dt BSDINSTALL 8 +.Os +.Sh NAME +.Nm bsdinstall +.Nd system installer +.Sh SYNOPSIS +.Nm +.Op Ar options +.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. +.Pp +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 OPTIONS +.Nm +supports the following options, global to all targets: +.Bl -tag -width indent+ +.It Fl D Ar file +Provide a path for the installation log file +.Pq overrides Ev BSDINSTALL_LOG . +See +.Sx ENVIRONMENT VARIABLES +for more information on +.Ev BSDINSTALL_LOG . +.El +.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. +.Bl -tag -width ".Cm jail Ar destination" +.It Cm auto +Run the standard interactive installation, including disk partitioning. +.It Cm jail Ar destination +Sets up a new chroot system at +.Pa 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. +.It Cm script Ar script +Runs the installation script at +.Pa script . +See +.Sx SCRIPTING +for more information on this target. +.It Cm keymap +If the current controlling TTY is a +.Xr syscons 4 +or +.Xr vt 4 +console, asks the user to set the current keymap, and saves the result to the +new system's +.Pa rc.conf . +.It Cm hostname +Prompts the user for a host name for the new system and saves the result to the +new system's +.Pa rc.conf . +If +.Ev BSDINSTALL_CONFIGCURRENT +is set, also sets the host name of the current system. +.It Cm netconfig +Interactively configures network interfaces (first invoking +.Cm wlanconfig +on wireless interfaces), saving the result to the new system's +.Pa rc.conf +and +.Pa resolv.conf . +If +.Ev BSDINSTALL_CONFIGCURRENT +is set, also configures the network interfaces of the current system to match. +.It Cm autopart +Provides the installer's interactive guided disk partitioner for single-disk +installations. Defaults to UFS. +.It Cm zfsboot +Provides an alternative ZFS-only automatic interactive disk partitioner. +Creates a single +.Ic zpool +with separate datasets for +.Pa /tmp , +.Pa /usr , +.Pa /usr/home , +.Pa /usr/ports , +.Pa /usr/src , +and +.Pa /var . +Optionally can set up +.Xr geli 8 +to encrypt the disk. +.It Cm partedit +Provides the installer's interactive manual disk partitioner with an interface +identical to +.Xr sade 8 . +Supports multiple disks as well as UFS, ZFS, and FAT file systems. ZFS +is set up with one pool and dataset per partition. +.It 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: +.Pp +.Ar disk +.Op Ar scheme +.Op Ar {partitions} +.Pp +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 +.Pp +.Ar size +.Ar type +.Op Ar mount point +.Pp +.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, freebsd-zfs, 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: +.Pp +bsdinstall scriptedpart ada0 { 20G freebsd-ufs /, 4G freebsd-swap, 20G freebsd-ufs /var, auto freebsd-ufs /usr } +.Pp +A shorter invocation to use the default partitioning (as +.Cm autopart +would have used) on the same disk: +.Pp +bsdinstall scriptedpart ada0 +.It Cm mount +Mounts the file systems previously configured by +.Cm autopart , +.Cm partedit , +or +.Cm scriptedpart +under +.Ev BSDINSTALL_CHROOT . +.It Cm distfetch +Fetches the distributions in +.Ev DISTRIBUTIONS +to +.Ev BSDINSTALL_DISTDIR +from +.Ev BSDINSTALL_DISTSITE . +.It Cm checksum +Verifies the checksums of the distributions listed in +.Ev DISTRIBUTIONS +against the distribution manifest. +.It Cm distextract +Extracts the distributions listed in +.Ev DISTRIBUTIONS +into +.Ev BSDINSTALL_CHROOT . +.It Cm rootpass +Interactively invokes +.Xr passwd 1 +in the new system to set the root user's password. +.It Cm adduser +Interactively invokes +.Xr adduser 8 +in the new system. +.It Cm time +Interactively sets the time, date, and time zone of the new system. +.It Cm services +Queries the user for the system daemons to begin at system startup, +writing the result into the new system's +.Pa rc.conf . +.It Cm entropy +Reads a small amount of data from +.Pa /dev/random +and stores it in a file in the new system's root directory. +.It 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. +.Bl -tag -width ".Ev BSDINSTALL_DISTSITE" +.It Ev DISTRIBUTIONS +The set of distributions to install (e.g. "base kernel ports"). Default: none +.It Ev BSDINSTALL_DISTDIR +The directory in which the distribution files can be found (or to which they +should be downloaded). Default: +.Pa /usr/freebsd-dist +.It 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: +.Pa ftp://ftp.freebsd.org/pub/FreeBSD/releases/powerpc/powerpc64/9.1-RELEASE +.It 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: +.Pa /mnt +.It Ev BSDINSTALL_LOG +Path to a log file for the installation. Default: +.Pa /tmp/bsdinstall_log +.It Ev BSDINSTALL_TMPETC +Directory where files destined for the new system's +.Pa /etc +will be stored until the +.Cm config +target is executed. If this directory does not already exist, it will be +created. Default: +.Pa /tmp/bsdinstall_etc +.It Ev BSDINSTALL_TMPBOOT +Directory where files destined for the new system's +.Pa /boot +will be stored until the +.Cm config +target is executed. If this directory does not already exist, it will be +created. Default: +.Pa /tmp/bsdinstall_boot +.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. +.Pp +A typical bsdinstall script looks like this: +.Bd -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 +.Pp +On +.Fx +release media, such a script placed at +.Pa /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. +Alternatively, +to use +.Cm zfsboot +instead of +.Cm partedit , +the preamble can contain the variable +.Ev ZFSBOOT_DATASETS +instead of +.Ev PARTITIONS . +.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 Nathan Whitehorn Aq Mt nwhitehorn@FreeBSD.org |
