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