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