usr.sbin/bsdinstall/bsdinstall.8

   1 .\"-
   2 .\" Copyright (c) 2011-2013 Nathan Whitehorn <nwhitehorn@FreeBSD.org> All rights reserved.
   3 .\" Copyright (c) 2018 Roberto Fernandez Cueto <roberfern@gmail.com>
   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 November 21, 2019
  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 a 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 TMPDIR
 263 The directory to use for temporary files.
 264 Default:
 265 .Dq Pa /tmp
 266 .It Ev DISTRIBUTIONS
 267 The set of distributions to install, e.g., "base.txz kernel.txz ports.txz".
 268 Default: unset
 269 .It Ev BSDINSTALL_DISTDIR
 270 The directory in which the distribution files can be found (or to which they
 271 should be downloaded).
 272 Default:
 273 .Dq Pa /usr/freebsd-dist
 274 .It Ev BSDINSTALL_DISTSITE
 275 URL from which the distribution files should be downloaded if they are not
 276 already present in the directory defined by
 277 .Ev BSDINSTALL_DISTDIR .
 278 This should be a full path to the files, including architecture and release
 279 names.
 280 Most targets, e.g.,
 281 .Cm auto
 282 and
 283 .Cm jail ,
 284 that prompt for a
 285 .Fx
 286 mirror will skip that step if this variable is already defined in the
 287 environment.
 288 Example:
 289 .Pa ftp://ftp.freebsd.org/pub/FreeBSD/releases/powerpc/powerpc64/9.1-RELEASE
 290 .It Ev BSDINSTALL_CHROOT
 291 The directory into which the distribution files should be unpacked and the
 292 directory at which the root file system of the new system should be mounted.
 293 Default:
 294 .Dq Pa /mnt
 295 .It Ev BSDINSTALL_LOG
 296 Path to a log file for the installation.
 297 Default:
 298 .Dq Pa $TMPDIR/bsdinstall_log
 299 .It Ev BSDINSTALL_TMPETC
 300 Directory where files destined for the new system's
 301 .Pa /etc
 302 will be stored until the
 303 .Cm config
 304 target is executed.
 305 If this directory does not already exist, it will be created.
 306 Default:
 307 .Dq Pa $TMPDIR/bsdinstall_etc
 308 .It Ev BSDINSTALL_TMPBOOT
 309 Directory where files destined for the new system's
 310 .Pa /boot
 311 will be stored until the
 312 .Cm config
 313 target is executed.
 314 If this directory does not already exist, it will be created.
 315 Default:
 316 .Dq Pa $TMPDIR/bsdinstall_boot
 317 .It Ev ZFSBOOT_POOL_NAME
 318 Name for the pool containing the base system.
 319 Default:
 320 .Dq zroot
 321 .It Ev ZFSBOOT_POOL_CREATE_OPTIONS
 322 Options to be used when creating the base system's pool.
 323 Each option must be followed by the -O flag to be taken into consideration
 324 or the pool will not be created due to errors using the command
 325 .Cm zpool .
 326 Default:
 327 .Dq Li "-O compress=lz4 -O atime=off"
 328 .It Ev ZFSBOOT_BEROOT_NAME
 329 Name for the boot environment parent dataset.
 330 This is a non-mountable dataset meant to be a parent dataset where different
 331 boot environment are going to be created.
 332 Default:
 333 .Dq ROOT
 334 .It Ev ZFSBOOT_BOOTFS_NAME
 335 Name for the primary boot environment, which will be the default boot
 336 environment for the system.
 337 Default:
 338 .Dq default
 339 .It Ev ZFSBOOT_VDEV_TYPE
 340 The type of pool to be created for the base system.
 341 This variable can take one of this values: stripe (No redundacy),
 342 mirror (n-Way mirroring), raid10 (RAID 1+0 - n x 2-Way Mirrors),
 343 raidz1 (RAID-Z1 - Single Redundancy RAID), raidz2 (RAID-Z2 - Double Redundancy RAID)
 344 or raidz3 (RAID-Z3 Triple Redundancy RAID).
 345 Default:
 346 .Dq stripe
 347 .It Ev ZFSBOOT_FORCE_4K_SECTORS
 348 Indicates either the pool will use 4K or 512 sectors.
 349 If this variable is not empty, 4K sectors will be used.
 350 Default:
 351 .Dq 1
 352 .It Ev ZFSBOOT_GELI_ENCRYPTION
 353 If this variable is not empty, it will use
 354 .Xr geli 8
 355 to encrypt the root pool, enabling automatically the
 356 .Ev ZFSBOOT_BOOT_POOL
 357 variable.
 358 Default:
 359 .Dq ""
 360 .It Ev ZFSBOOT_GELI_KEY_FILE
 361 Path to the
 362 .Xr geli 8
 363 keyfile used to encrypt the pool where the base system is stored.
 364 Default:
 365 .Dq Pa /boot/encryption.key
 366 .It Ev ZFSBOOT_BOOT_POOL
 367 If set a separated boot pool will be created for the kernel of the
 368 system and
 369 .Xr loader 8 .
 370 Default: unset
 371 .It Ev ZFSBOOT_BOOT_POOL_CREATE_OPTIONS
 372 Options to use when creating the boot pool, when enabled (See
 373 .Ev ZFSBOOT_BOOT_POOL ).
 374 Default: unset
 375 .It Ev ZFSBOOT_BOOT_POOL_NAME
 376 Name for the optional boot pool when it is enabled, (See
 377 .Ev ZFSBOOT_BOOT_POOL ).
 378 Default:
 379 .Dq bootpool
 380 .It Ev ZFSBOOT_BOOT_POOL_SIZE
 381 Size of the boot pool when it is enabled (See
 382 .Ev ZFSBOOT_BOOT_POOL ).
 383 Default:
 384 .Dq 2g
 385 .It Ev ZFSBOOT_DISKS
 386 Disks to be used for the base system, including the boot pool.
 387 This variable must only be used on a scripted installation.
 388 See
 389 .Sx SCRIPTING
 390 for more information.
 391 Default: unset
 392 .It Ev ZFSBOOT_SWAP_SIZE
 393 Size of the swap partition on each block device.
 394 This variable will be passed to
 395 .Xr gpart 8 ;
 396 which supports SI unit suffixes.
 397 Default:
 398 .Dq 2g
 399 .It Ev ZFSBOOT_SWAP_ENCRYPTION
 400 If set, enables the encryption of the swap partition using
 401 .Xr geli 8 .
 402 Default: ""
 403 .It Ev ZFSBOOT_SWAP_MIRROR
 404 If set, enables a swap mirroring using
 405 .Xr gmirror 8 .
 406 Default:
 407 unset
 408 .It Ev ZFSBOOT_DATASETS
 409 ZFS datasets to be created on the root zpool, it requires the
 410 following datasets:
 411 .Pa /tmp ,
 412 .Pa /var/tmp ,
 413 .Pa /$ZFSBOOT_BEROOT_NAME/$ZFSBOOT_BOOTFS_NAME .
 414 See
 415 .Sx ZFS DATASETS
 416 for more information about who to write this variable and to
 417 take a look into the default value of it.
 418 .It Ev ZFSBOOT_CONFIRM_LAYOUT
 419 If set and the installation is interactive, allow the user to confirm
 420 the layout before continuing with the installation.
 421 Default:
 422 .Dq 1
 423 .El
 424 .Sh SCRIPTING
 425 .Nm
 426 scripts consist of two parts: a
 427 .Em preamble
 428 and a
 429 .Em setup script .
 430 The preamble sets up the options for the installation (how to partition the
 431 disk[s], which distributions to install, etc.) and the optional second part is
 432 a shell script run under
 433 .Xr chroot 8
 434 in the newly installed system before
 435 .Nm
 436 exits.
 437 The two parts are separated by the usual script header (#!), which also sets
 438 the interpreter for the setup script.
 439 .Pp
 440 A typical bsdinstall script looks like this:
 441 .Bd -literal -offset indent
 442 PARTITIONS=ada0
 443 DISTRIBUTIONS="kernel.txz base.txz"
 444
 445 #!/bin/sh
 446 sysrc ifconfig_em0=DHCP
 447 sysrc sshd_enable=YES
 448 pkg install puppet
 449 .Ed
 450 .Pp
 451 For a ZFS scripted installation, the script looks like this:
 452 .Bd -literal -offset indent
 453 DISTRIBUTIONS="kernel.txz base.txz"
 454 export ZFSBOOT_VDEV_TYPE=stripe
 455 export ZFSBOOT_DISKS=ada0
 456 export nonInteractive="YES"
 457
 458 #!/bin/sh
 459 echo "ifconfig_em0=DHCP" >> /etc/rc.conf
 460 echo "sshd_enable=YES" >> /etc/rc.conf
 461 pkg install puppet
 462 .Ed
 463 .Pp
 464 On
 465 .Fx
 466 release media, such a script placed at
 467 .Pa /etc/installerconfig
 468 will be run at boot time and the system will be rebooted automatically after
 469 the installation has completed.
 470 This can be used for unattended network installation of new systems; see
 471 .Xr diskless 8
 472 for details.
 473 .Ss PREAMBLE
 474 The preamble consists of installer settings.
 475 These control global installation parameters (see
 476 .Sx ENVIRONMENT VARIABLES )
 477 as well as disk partitioning.
 478 The preamble is interpreted as a
 479 .Xr sh 1
 480 script run at the very beginning of the install.
 481 If more complicated behavior than setting these variables is desired,
 482 arbitrary commands can be run here to extend the installer.
 483 In addition to the variables in
 484 .Sx ENVIRONMENT VARIABLES ,
 485 in particular
 486 .Ev DISTRIBUTIONS ,
 487 the preamble can contain a variable
 488 .Ev PARTITIONS
 489 which is passed to the
 490 .Cm scriptedpart
 491 target to control disk setup.
 492 Alternatively,
 493 to use
 494 .Cm zfsboot
 495 instead of
 496 .Cm partedit ,
 497 the preamble can contain the variable
 498 .Ev ZFSBOOT_DATASETS
 499 instead of
 500 .Ev PARTITIONS ,
 501 and setting the variables
 502 .Ev ZFSBOOT_DISKS
 503 and
 504 .Ev ZFSBOOT_VDEV_TYPE
 505 to create the pool of disks for the base system.
 506 Usually, for a mirrored booting disk, this two variables looks like this:
 507 .Bd -literal -offset indent
 508 ZFSBOOT_DISKS="ada0 ada1"
 509 ZFSBOOT_VDEV_TYPE=mirror
 510 .Ed
 511 .Pp
 512 Remember to export all the variables for the
 513 .Cm zfsboot
 514 command, otherwise it will not get set.
 515 .Ss SETUP SCRIPT
 516 Following the preamble is an optional shell script, beginning with a #!
 517 declaration.
 518 This script will be run at the end of the installation process inside a
 519 .Xr chroot 8
 520 environment in the newly installed system and can be used to set up
 521 configuration files, install packages, etc.
 522 Note that newly configured system services, e.g., networking have not
 523 been started in the installed system at this time and only installation
 524 host services are available.
 525 .Ss ZFS DATASETS
 526 The
 527 .Cm zfsboot
 528 partitioning takes the
 529 .Ev ZFSBOOT_DATASETS
 530 variable to create the datasets on the base system.
 531 This variable can get pretty huge if the pool contains a lot of datasets.
 532 The default value of the
 533 .Ev ZFSBOOT_DATASETS
 534 looks like this:
 535 .Bd -literal -offset indent
 536 # DATASET       OPTIONS (comma or space separated; or both)
 537
 538 # Boot Environment [BE] root and default boot dataset
 539 /$ZFSBOOT_BEROOT_NAME                           mountpoint=none
 540 /$ZFSBOOT_BEROOT_NAME/$ZFSBOOT_BOOTFS_NAME      mountpoint=/
 541
 542 # Compress /tmp, allow exec but not setuid
 543 /tmp            mountpoint=/tmp,exec=on,setuid=off
 544
 545 # Do not mount /usr so that 'base' files go to the BEROOT
 546 /usr            mountpoint=/usr,canmount=off
 547
 548 # Home directories separated so they are common to all BEs
 549 /usr/home       # NB: /home is a symlink to /usr/home
 550
 551 # Ports tree
 552 /usr/ports      setuid=off
 553
 554 # Source tree (compressed)
 555 /usr/src
 556
 557 # Create /var and friends
 558 /var            mountpoint=/var,canmount=off
 559 /var/audit      exec=off,setuid=off
 560 /var/crash      exec=off,setuid=off
 561 /var/log        exec=off,setuid=off
 562 /var/mail       atime=on
 563 /var/tmp        setuid=off
 564 .Ed
 565 .Pp
 566 The first column if the dataset to be created on the top of the
 567 .Ev ZFSBOOT_POOL_NAME
 568 and the rest of the columns are the options to be set on each dataset.
 569 The options must be written on a coma or space separated list, or both.
 570 And everything behind a pound/hash character is ignored as a comment.
 571 .Sh HISTORY
 572 This version of
 573 .Nm
 574 first appeared in
 575 .Fx 9.0 .
 576 .Sh AUTHORS
 577 .An Nathan Whitehorn Aq Mt nwhitehorn@FreeBSD.org