usr.sbin/bsdinstall/bsdinstall.8

   1 .\"-
   2 .\" Copyright (c) 2011-2013 Nathan Whitehorn <nwhitehorn@FreeBSD.org>
   3 .\" All rights reserved.
   4 .\"
   5 .\" Redistribution and use in source and binary forms, with or without
   6 .\" modification, are permitted provided that the following conditions
   7 .\" are met:
   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.
  13 .\"
  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.
  25 .\"
  26 .\" $FreeBSD$
  27 .\"
  28 .Dd October 6, 2013
  29 .Dt BSDINSTALL 8
  30 .Os
  31 .Sh NAME
  32 .Nm bsdinstall
  33 .Nd system installer
  34 .Sh SYNOPSIS
  35 .Nm
  36 .Op Ar options
  37 .Op Ar target
  38 .Op Ar ...
  39 .Sh DESCRIPTION
  40 .Nm
  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
  43 VM images and jails.
  44 .Pp
  45 Much like
  46 .Xr make 1 , Nm
  47 takes a target and possible parameters of the target as arguments. If
  48 invoked with no arguments, it will invoke the
  49 .Cm auto
  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.
  53 .Sh OPTIONS
  54 .Nm
  55 supports the following options, global to all targets:
  56 .Bl -tag -width indent+
  57 .It Fl D Ar file
  58 Provide a path for the installation log file
  59 .Pq overrides Ev BSDINSTALL_LOG .
  60 See
  61 .Sx ENVIRONMENT VARIABLES
  62 for more information on
  63 .Ev BSDINSTALL_LOG .
  64 .El
  65 .Sh TARGETS
  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
  68 .Cm auto ,
  69 .Cm jail ,
  70 and
  71 .Cm script
  72 targets.
  73 .Bl -tag -width ".Cm jail Ar destination"
  74 .It Cm auto
  75 Run the standard interactive installation, including disk partitioning.
  76 .It Cm entropy
  77 Reads a small amount of data from
  78 .Pa /dev/random
  79 and stores it in a file in the new system's root directory.
  80 .It Cm jail Ar destination
  81 Sets up a new chroot system at
  82 .Pa destination ,
  83 suitable for use with
  84 .Xr jail 8 .
  85 Behavior is generally similar to
  86 .Cm auto ,
  87 except that disk partitioning and network setup are skipped and a kernel is
  88 not installed into the new system.
  89 .It Cm script Ar script
  90 Runs the installation script at
  91 .Pa script .
  92 See
  93 .Sx SCRIPTING
  94 for more information on this target.
  95 .It Cm keymap
  96 If the current controlling TTY is a
  97 .Xr syscons 4
  98 console, asks the user to set the current keymap, and saves the result to the
  99 new system's
 100 .Pa rc.conf .
 101 .It Cm hostname
 102 Prompts the user for a host name for the new system and saves the result to the
 103 new system's
 104 .Pa rc.conf .
 105 If
 106 .Ev BSDINSTALL_CONFIGCURRENT
 107 is set, also sets the host name of the current system.
 108 .It Cm netconfig
 109 Interactively configures network interfaces (first invoking
 110 .Cm wlanconfig
 111 on wireless interfaces), saving the result to the new system's
 112 .Pa rc.conf
 113 and
 114 .Pa resolv.conf .
 115 If
 116 .Ev BSDINSTALL_CONFIGCURRENT
 117 is set, also configures the network interfaces of the current system to match.
 118 .It Cm autopart
 119 Provides the installer's interactive guided disk partitioner for single-disk
 120 installations. Partitions disks, runs
 121 .Xr newfs 8 ,
 122 and writes the new system's
 123 .Pa fstab .
 124 .It Cm partedit
 125 Provides the installer's interactive manual disk partitioner, with support
 126 for multi disk setups, non-UFS file systems, and manual selection of
 127 partition schemes. Partitions disks, runs
 128 .Xr newfs 8 ,
 129 and writes the new system's
 130 .Pa fstab .
 131 .It Cm scriptedpart Ar parameters
 132 Sets up disks like
 133 .Cm autopart
 134 and
 135 .Cm partedit ,
 136 but non-interactively according to the disk setup specified in
 137 .Ar parameters .
 138 Each disk setup is specified by a three-part argument:
 139 .Pp
 140 .Ar disk
 141 .Op Ar scheme
 142 .Op Ar {partitions}
 143 .Pp
 144 Multiple disk setups are separated by semicolons. The
 145 .Ar disk
 146 argument specifies the disk on which to operate (which will be erased),
 147 while the
 148 .Ar scheme
 149 argument specifies the
 150 .Xr gpart 8
 151 partition scheme to apply to the disk. If
 152 .Ar scheme
 153 is unspecified,
 154 .Cm scriptedpart
 155 will apply the default bootable scheme on your platform.
 156 The
 157 .Ar partitions
 158 argument is also optional and specifies how to partition
 159 .Ar disk .
 160 It consists of a comma-separated list of partitions to create enclosed in
 161 curly braces. Each partition declaration takes the form
 162 .Pp
 163 .Ar size
 164 .Ar type
 165 .Op Ar mount point
 166 .Pp
 167 .Ar size
 168 specifies the partition size to create in bytes (K, M, and G suffixes
 169 can be appended to specify kilobytes, megabytes, and gigabytes respectively),
 170 while the
 171 .Em auto
 172 keyword causes the partition to take all the remaining space on the disk. The
 173 .Ar type
 174 option chooses the
 175 .Xr gpart 8
 176 filesystem type (e.g. freebsd-ufs or freebsd-swap).
 177 The optional
 178 .Ar mount point
 179 argument sets where the created partition is to be mounted in the installed
 180 system. As an example, a typical invocation looks like:
 181 .Pp
 182 bsdinstall scriptedpart ada0 { 20G freebsd-ufs /, 4G freebsd-swap, 20G freebsd-ufs /var, auto freebsd-ufs /usr }
 183 .It Cm mount
 184 Mounts the file systems previously configured by
 185 .Cm autopart ,
 186 .Cm partedit ,
 187 or
 188 .Cm scriptedpart
 189 under
 190 .Ev BSDINSTALL_CHROOT .
 191 .It Cm distfetch
 192 Fetches the distributions in
 193 .Ev DISTRIBUTIONS
 194 to
 195 .Ev BSDINSTALL_DISTDIR
 196 from
 197 .Ev BSDINSTALL_DISTSITE .
 198 .It Cm checksum
 199 Verifies the checksums of the distributions listed in
 200 .Ev DISTRIBUTIONS
 201 against the distribution manifest.
 202 .It Cm distextract
 203 Extracts the distributions listed in
 204 .Ev DISTRIBUTIONS
 205 into
 206 .Ev BSDINSTALL_CHROOT .
 207 .It Cm rootpass
 208 Interactively invokes
 209 .Xr passwd 1
 210 in the new system to set the root user's password.
 211 .It Cm adduser
 212 Interactively invokes
 213 .Xr adduser 8
 214 in the new system.
 215 .It Cm time
 216 Interactively sets the time, date, and time zone of the new system.
 217 .It Cm services
 218 Queries the user for the system daemons to begin at system startup,
 219 writing the result into the new system's
 220 .Pa rc.conf .
 221 .It Cm config
 222 Installs the configuration files destined for the new system (e.g. rc.conf
 223 fragments generated by
 224 .Cm netconfig ,
 225 etc.) onto the new system.
 226 .El
 227 .Sh ENVIRONMENT VARIABLES
 228 The following environment variables control various aspects of the installation
 229 process. Many are used internally during installation and have reasonable
 230 default values for most installation scenarios. Others are set by various
 231 interactive user prompts, and can be usefully overridden when making scripted
 232 or customized installers.
 233 .Bl -tag -width ".Ev BSDINSTALL_DISTSITE"
 234 .It Ev DISTRIBUTIONS
 235 The set of distributions to install (e.g. "base kernel ports"). Default: none
 236 .It Ev BSDINSTALL_DISTDIR
 237 The directory in which the distribution files can be found (or to which they
 238 should be downloaded). Default:
 239 .Pa /usr/freebsd-dist
 240 .It Ev BSDINSTALL_DISTSITE
 241 URL from which the distribution files should be downloaded if they are not
 242 already present in the directory defined by
 243 .Ev BSDINSTALL_DISTDIR .
 244 This should be a full path to the files, including architecture and release
 245 names. Most targets (e.g.
 246 .Cm auto
 247 and
 248 .Cm jail )
 249 that prompt for a
 250 .Fx
 251 mirror will skip that step if this variable is already defined in the
 252 environment. Example:
 253 .Pa ftp://ftp.freebsd.org/pub/FreeBSD/releases/powerpc/powerpc64/9.1-RELEASE
 254 .It Ev BSDINSTALL_CHROOT
 255 The directory into which the distribution files should be unpacked and the
 256 directory at which the root file system of the new system should be mounted.
 257 Default:
 258 .Pa /mnt
 259 .It Ev BSDINSTALL_LOG
 260 Path to a log file for the installation. Default:
 261 .Pa /tmp/bsdinstall_log
 262 .It Ev BSDINSTALL_TMPETC
 263 Directory where files destined for the new system's
 264 .Pa /etc
 265 will be stored until the
 266 .Cm config
 267 target is executed. If this directory does not already exist, it will be
 268 created. Default:
 269 .Pa /tmp/bsdinstall_etc
 270 .El
 271 .Sh SCRIPTING
 272 .Nm
 273 scripts consist of two parts: a
 274 .Em preamble
 275 and a
 276 .Em setup script .
 277 The preamble sets up the options for the installation (how to partition the
 278 disk[s], which distributions to install, etc.) and the optional second part is
 279 a shell script run under
 280 .Xr chroot 8
 281 in the newly installed system before
 282 .Nm
 283 exits. The two parts are separated by the usual script header (#!), which
 284 also sets the interpreter for the setup script.
 285 .Pp
 286 A typical bsdinstall script looks like this:
 287 .Bd -literal -offset indent
 288 PARTITIONS=ada0
 289 DISTRIBUTIONS="kernel.txz base.txz"
 290
 291 #!/bin/sh
 292 echo "ifconfig_em0=DHCP" >> /etc/rc.conf
 293 echo "sshd_enable=YES" >> /etc/rc.conf
 294 pkg install puppet
 295 .Ed
 296 .Pp
 297 On
 298 .Fx
 299 release media, such a script placed at
 300 .Pa /etc/installerconfig
 301 will be run at boot time and the system will be rebooted automatically after
 302 the installation has completed. This can be used for unattended network
 303 installation of new systems; see
 304 .Xr diskless 8
 305 for details.
 306 .Ss PREAMBLE
 307 The preamble consists of installer settings. These control global installation
 308 parameters (see
 309 .Sx ENVIRONMENT VARIABLES )
 310 as well as disk partitioning. The preamble is interpreted as a
 311 .Xr sh 1
 312 script run at the very beginning of the install. If more complicated behavior
 313 than setting these variables is desired, arbitrary commands can be run here
 314 to extend the installer. In addition to the variables in
 315 .Sx ENVIRONMENT VARIABLES ,
 316 in particular
 317 .Ev DISTRIBUTIONS ,
 318 the preamble can contain a variable
 319 .Ev PARTITIONS
 320 which is passed to the
 321 .Cm scriptedpart
 322 target to control disk setup.
 323 .Ss SETUP SCRIPT
 324 Following the preamble is an optional shell script, beginning with a #!
 325 declaration. This script will be run at the end of the installation process
 326 inside a
 327 .Xr chroot 8
 328 environment in the newly installed system and can be used to set up
 329 configuration files, install packages, etc. Note that newly configured
 330 system services (e.g. networking) have not been started in the installed
 331 system at this time and only installation host services are available.
 332 .Sh HISTORY
 333 This version of
 334 .Nm
 335 first appeared in
 336 .Fx 9.0 .
 337 .Sh AUTHORS
 338 .An -nosplit
 339 .An Nathan Whitehorn Aq nwhitehorn@FreeBSD.org