d/freebsd-nq
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
freebsd-nq/usr.sbin/bsdinstall/bsdinstall.8
Devin Teske bc4a673f89 A series of changes tested together as a whole: 
+ Add a `-D FILE" command-line option for overriding the path to the
  bsdinstall log file (BSDINSTALL_LOG env var).
+ Document new `-D FILE' in the man page for bsdinstall.
+ If FILE in `-D FILE' begins with a +, debug output goes to stdout
  (interleaved between dialog(1) invocations/output) as well as to FILE
  (minus the leading + of course).
+ If BSDINSTALL_LOG cannot be written, then debugging is disabled (except in
  the case of a leading + in the pathname, wherein debug will still be
  printed to stdout).
+ Update source code formatting style.
+ Fix a dangling participle ("Begun ..." -> "Began ...")
+ Rewrite the docsinstall script (was necessary to abate direct dependency
  on BSDINSTALL_LOG (instead, use fault-tolerant bsdconfig framework which
  displays appropriate errors for package management).
NB: docsinstall is still using pkg(8) after this change.
+ Add additional debug output for dhclient/rtsol/wpa_cliscan
+ Display script errors in a textbox rather than just on stdout
+ Update many coments.
+ Add new f_show_err() API call (like f_show_msg but changes the dialog
  title to "Error")(see bsdconfig's `common.subr').
+ Add new f_eval_catch() API call for executing a command via eval but not
  before logging the command to debug. Several example cases documented in
  API header for function in bsdconfig's `common.subr'.
+ Fix dialog auto-sizing when launched as an rvalue to a pipe for indirected
  scripts (previously would default to 24x80 sizing in this case, now it can
  autosize to full size even when in a pipe chain).
+ Fix bug in f_snprintf if $format argument began with "-"; printf would
  misinterpret as a flag. (this is in bsdcofig's `strings.subr').
+ Add accompanying f_sprintf() and f_vsprintf() to go along with already
  existing f_snprintf() and f_vsnprintf() (see bsdconfig's `strings.subr').
+ Remove some unnecessary default ZFS datasets from the automatic "zfsboot"
  script. Such as: /usr/ports/distfiles /usr/ports/packages /usr/obj /var/db
  /var/empty /var/mail and /var/run (these can all be created as-needed once
  the system is installed).
+ Remove setuid=off for /usr/home (as discussed from last round of CFT).
+ Fix some i18n string violations in "zfsboot".
+ Bolster debugging output in "zfsboot".
+ Fix some string quoting issues in "zfsboot".
+ Fix some variable scope issues in "zfsboot".
+ Change "Create" to "Install" in "zfsboot" main menu.
+ Increase error checking in "zfsboot" (type-check arguments and such).
+ Add call to "graid destroy" killing automatic metadata (part of the series
  of pedantic destructions we do when bootstrapping a new/naked disk).
+ Make judicious use of new f_eval_catch() in "zfsboot".
+ Fixup some variable names for consistency (zfsboot).
+ Fix an underride syntax parameter expansion folly (zfsboot).
+ Confirm layout if not explicitly chosen when blindly proceeding (no
  longer have to touch anything on the ZFS menu if it scares you, just
  choose the omnibus "Install" option at the top and you'll be prompted to
  select vdev type and disks in the layout confirmation dialog).
+ Change numbered menu items to alphabetic for more efficient navigation.
+ Consolidate vdev selection and disk selection into a single stateful
  menu which performs validation and allows backing out to each previous
  menu as you go deeper.
+ Redesign the ``Last Chance'' dialog (still using the same colors, but
  make it conform to a tolerable width and make disks appear in a block-
  quote style indented region).
+ Fix a bug wherein we used the a lowercase variable name by accident
  (actual variable name declared as all-uppercase) at the time of
  initializing fstab(5) (not believed to cause any issues though).
+ Update the geli setup infobox for each provider being initialized
  (not just at the onset -- since each ``geli init'' causes kernel messages
  to push our infobox off-screen).

Reviewed by:	Allan Jude <freebsd@allanjude.com>
Discussed on:	-current
MFC after:	3 days
2013-11-08 09:57:03 +00:00

371 lines
11 KiB
Groff
Raw Blame History

.\"-
.\" 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 15, 2013
.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 .
.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 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 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
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. Partitions disks, runs
.Xr newfs 8 ,
and writes the new system's
.Pa fstab .
.It Cm zfsboot
Provides the installer's
.Pq experimental
interactive/scriptable ZFS partitioner for multi-disk installations.
Creates a single
.Ic zpool
with datasets and writes to the new system's
.Pa rc.conf ,
.Pa loader.conf ,
and
.Pa fstab .
Supports
.Xr geli 8 ,
.Xr gnop 8 ,
and many other features.
.It 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
.Pa fstab .
.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 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 }
.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 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,
instead of
.Ev PARTITIONS ,
the preamble can contain the variable
.Ev ZFSBOOT_DATASETS
which is parsed by the
.Pq experimental
.Cm zfsboot
target to control ZFS datasets/options of the boot pool 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
Reference in New Issue View Git Blame Copy Permalink