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