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