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