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 15, 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 or
  99 .Xr vt 4
 100 console, asks the user to set the current keymap, and saves the result to the
 101 new system's
 102 .Pa rc.conf .
 103 .It Cm hostname
 104 Prompts the user for a host name for the new system and saves the result to the
 105 new system's
 106 .Pa rc.conf .
 107 If
 108 .Ev BSDINSTALL_CONFIGCURRENT
 109 is set, also sets the host name of the current system.
 110 .It Cm netconfig
 111 Interactively configures network interfaces (first invoking
 112 .Cm wlanconfig
 113 on wireless interfaces), saving the result to the new system's
 114 .Pa rc.conf
 115 and
 116 .Pa resolv.conf .
 117 If
 118 .Ev BSDINSTALL_CONFIGCURRENT
 119 is set, also configures the network interfaces of the current system to match.
 120 .It Cm autopart
 121 Provides the installer's interactive guided disk partitioner for single-disk
 122 installations. Partitions disks, runs
 123 .Xr newfs 8 ,
 124 and writes the new system's
 125 .Pa fstab .
 126 .It Cm zfsboot
 127 Provides the installer's
 128 .Pq experimental
 129 interactive/scriptable ZFS partitioner for multi-disk installations.
 130 Creates a single
 131 .Ic zpool
 132 with datasets and writes to the new system's
 133 .Pa rc.conf ,
 134 .Pa loader.conf ,
 135 and
 136 .Pa fstab .
 137 Supports
 138 .Xr geli 8 ,
 139 .Xr gnop 8 ,
 140 and many other features.
 141 .It Cm partedit
 142 Provides the installer's interactive manual disk partitioner, with support
 143 for multi disk setups, non-UFS file systems, and manual selection of
 144 partition schemes. Partitions disks, runs
 145 .Xr newfs 8 ,
 146 and writes the new system's
 147 .Pa fstab .
 148 .It Cm scriptedpart Ar parameters
 149 Sets up disks like
 150 .Cm autopart
 151 and
 152 .Cm partedit ,
 153 but non-interactively according to the disk setup specified in
 154 .Ar parameters .
 155 Each disk setup is specified by a three-part argument:
 156 .Pp
 157 .Ar disk
 158 .Op Ar scheme
 159 .Op Ar {partitions}
 160 .Pp
 161 Multiple disk setups are separated by semicolons. The
 162 .Ar disk
 163 argument specifies the disk on which to operate (which will be erased),
 164 while the
 165 .Ar scheme
 166 argument specifies the
 167 .Xr gpart 8
 168 partition scheme to apply to the disk. If
 169 .Ar scheme
 170 is unspecified,
 171 .Cm scriptedpart
 172 will apply the default bootable scheme on your platform.
 173 The
 174 .Ar partitions
 175 argument is also optional and specifies how to partition
 176 .Ar disk .
 177 It consists of a comma-separated list of partitions to create enclosed in
 178 curly braces. Each partition declaration takes the form
 179 .Pp
 180 .Ar size
 181 .Ar type
 182 .Op Ar mount point
 183 .Pp
 184 .Ar size
 185 specifies the partition size to create in bytes (K, M, and G suffixes
 186 can be appended to specify kilobytes, megabytes, and gigabytes respectively),
 187 while the
 188 .Em auto
 189 keyword causes the partition to take all the remaining space on the disk. The
 190 .Ar type
 191 option chooses the
 192 .Xr gpart 8
 193 filesystem type (e.g. freebsd-ufs or freebsd-swap).
 194 The optional
 195 .Ar mount point
 196 argument sets where the created partition is to be mounted in the installed
 197 system. As an example, a typical invocation looks like:
 198 .Pp
 199 bsdinstall scriptedpart ada0 { 20G freebsd-ufs /, 4G freebsd-swap, 20G freebsd-ufs /var, auto freebsd-ufs /usr }
 200 .It Cm mount
 201 Mounts the file systems previously configured by
 202 .Cm autopart ,
 203 .Cm partedit ,
 204 or
 205 .Cm scriptedpart
 206 under
 207 .Ev BSDINSTALL_CHROOT .
 208 .It Cm distfetch
 209 Fetches the distributions in
 210 .Ev DISTRIBUTIONS
 211 to
 212 .Ev BSDINSTALL_DISTDIR
 213 from
 214 .Ev BSDINSTALL_DISTSITE .
 215 .It Cm checksum
 216 Verifies the checksums of the distributions listed in
 217 .Ev DISTRIBUTIONS
 218 against the distribution manifest.
 219 .It Cm distextract
 220 Extracts the distributions listed in
 221 .Ev DISTRIBUTIONS
 222 into
 223 .Ev BSDINSTALL_CHROOT .
 224 .It Cm rootpass
 225 Interactively invokes
 226 .Xr passwd 1
 227 in the new system to set the root user's password.
 228 .It Cm adduser
 229 Interactively invokes
 230 .Xr adduser 8
 231 in the new system.
 232 .It Cm time
 233 Interactively sets the time, date, and time zone of the new system.
 234 .It Cm services
 235 Queries the user for the system daemons to begin at system startup,
 236 writing the result into the new system's
 237 .Pa rc.conf .
 238 .It Cm config
 239 Installs the configuration files destined for the new system (e.g. rc.conf
 240 fragments generated by
 241 .Cm netconfig ,
 242 etc.) onto the new system.
 243 .El
 244 .Sh ENVIRONMENT VARIABLES
 245 The following environment variables control various aspects of the installation
 246 process. Many are used internally during installation and have reasonable
 247 default values for most installation scenarios. Others are set by various
 248 interactive user prompts, and can be usefully overridden when making scripted
 249 or customized installers.
 250 .Bl -tag -width ".Ev BSDINSTALL_DISTSITE"
 251 .It Ev DISTRIBUTIONS
 252 The set of distributions to install (e.g. "base kernel ports"). Default: none
 253 .It Ev BSDINSTALL_DISTDIR
 254 The directory in which the distribution files can be found (or to which they
 255 should be downloaded). Default:
 256 .Pa /usr/freebsd-dist
 257 .It Ev BSDINSTALL_DISTSITE
 258 URL from which the distribution files should be downloaded if they are not
 259 already present in the directory defined by
 260 .Ev BSDINSTALL_DISTDIR .
 261 This should be a full path to the files, including architecture and release
 262 names. Most targets (e.g.
 263 .Cm auto
 264 and
 265 .Cm jail )
 266 that prompt for a
 267 .Fx
 268 mirror will skip that step if this variable is already defined in the
 269 environment. Example:
 270 .Pa ftp://ftp.freebsd.org/pub/FreeBSD/releases/powerpc/powerpc64/9.1-RELEASE
 271 .It Ev BSDINSTALL_CHROOT
 272 The directory into which the distribution files should be unpacked and the
 273 directory at which the root file system of the new system should be mounted.
 274 Default:
 275 .Pa /mnt
 276 .It Ev BSDINSTALL_LOG
 277 Path to a log file for the installation. Default:
 278 .Pa /tmp/bsdinstall_log
 279 .It Ev BSDINSTALL_TMPETC
 280 Directory where files destined for the new system's
 281 .Pa /etc
 282 will be stored until the
 283 .Cm config
 284 target is executed. If this directory does not already exist, it will be
 285 created. Default:
 286 .Pa /tmp/bsdinstall_etc
 287 .It Ev BSDINSTALL_TMPBOOT
 288 Directory where files destined for the new system's
 289 .Pa /boot
 290 will be stored until the
 291 .Cm config
 292 target is executed. If this directory does not already exist, it will be
 293 created. Default:
 294 .Pa /tmp/bsdinstall_boot
 295 .El
 296 .Sh SCRIPTING
 297 .Nm
 298 scripts consist of two parts: a
 299 .Em preamble
 300 and a
 301 .Em setup script .
 302 The preamble sets up the options for the installation (how to partition the
 303 disk[s], which distributions to install, etc.) and the optional second part is
 304 a shell script run under
 305 .Xr chroot 8
 306 in the newly installed system before
 307 .Nm
 308 exits. The two parts are separated by the usual script header (#!), which
 309 also sets the interpreter for the setup script.
 310 .Pp
 311 A typical bsdinstall script looks like this:
 312 .Bd -literal -offset indent
 313 PARTITIONS=ada0
 314 DISTRIBUTIONS="kernel.txz base.txz"
 315
 316 #!/bin/sh
 317 echo "ifconfig_em0=DHCP" >> /etc/rc.conf
 318 echo "sshd_enable=YES" >> /etc/rc.conf
 319 pkg install puppet
 320 .Ed
 321 .Pp
 322 On
 323 .Fx
 324 release media, such a script placed at
 325 .Pa /etc/installerconfig
 326 will be run at boot time and the system will be rebooted automatically after
 327 the installation has completed. This can be used for unattended network
 328 installation of new systems; see
 329 .Xr diskless 8
 330 for details.
 331 .Ss PREAMBLE
 332 The preamble consists of installer settings. These control global installation
 333 parameters (see
 334 .Sx ENVIRONMENT VARIABLES )
 335 as well as disk partitioning. The preamble is interpreted as a
 336 .Xr sh 1
 337 script run at the very beginning of the install. If more complicated behavior
 338 than setting these variables is desired, arbitrary commands can be run here
 339 to extend the installer. In addition to the variables in
 340 .Sx ENVIRONMENT VARIABLES ,
 341 in particular
 342 .Ev DISTRIBUTIONS ,
 343 the preamble can contain a variable
 344 .Ev PARTITIONS
 345 which is passed to the
 346 .Cm scriptedpart
 347 target to control disk setup.
 348 Alternatively,
 349 instead of
 350 .Ev PARTITIONS ,
 351 the preamble can contain the variable
 352 .Ev ZFSBOOT_DATASETS
 353 which is parsed by the
 354 .Pq experimental
 355 .Cm zfsboot
 356 target to control ZFS datasets/options of the boot pool setup.
 357 .Ss SETUP SCRIPT
 358 Following the preamble is an optional shell script, beginning with a #!
 359 declaration. This script will be run at the end of the installation process
 360 inside a
 361 .Xr chroot 8
 362 environment in the newly installed system and can be used to set up
 363 configuration files, install packages, etc. Note that newly configured
 364 system services (e.g. networking) have not been started in the installed
 365 system at this time and only installation host services are available.
 366 .Sh HISTORY
 367 This version of
 368 .Nm
 369 first appeared in
 370 .Fx 9.0 .
 371 .Sh AUTHORS
 372 .An -nosplit
 373 .An Nathan Whitehorn Aq nwhitehorn@FreeBSD.org