share/man/man8/beinstall.8

   1 .\"
   2 .\" SPDX-License-Identifier: BSD-2-Clause
   3 .\"
   4 .\" Copyright (c) 2018 Mateusz Piotrowski <0mp@FreeBSD.org>
   5 .\"
   6 .\" Redistribution and use in source and binary forms, with or without
   7 .\" modification, are permitted provided that the following conditions
   8 .\" are met:
   9 .\" 1. Redistributions of source code must retain the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer.
  11 .\" 2. Redistributions in binary form must reproduce the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer in the
  13 .\"    documentation and/or other materials provided with the distribution.
  14 .\"
  15 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  16 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  17 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  18 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  19 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  20 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  21 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  22 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  23 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  24 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  25 .\" SUCH DAMAGE.
  26 .Dd October 30, 2020
  27 .Dt BEINSTALL.SH 8
  28 .Os
  29 .Sh NAME
  30 .Nm beinstall.sh
  31 .Nd "install a boot environment using the current FreeBSD source tree"
  32 .Sh SYNOPSIS
  33 .Nm
  34 .Op Ar options Ar ...
  35 .Sh DESCRIPTION
  36 .Nm
  37 installs a boot environment using the current
  38 .Fx
  39 source tree.
  40 .Nm
  41 also automatically performs
  42 .Pa /etc
  43 updates
  44 (using
  45 .Xr etcupdate 8 )
  46 and
  47 package updates using
  48 .Xr pkg-upgrade 8
  49 automatically in the new boot environment sandbox.
  50 .Pp
  51 Upon successful completion, the system will be ready to boot into the new boot
  52 environment.
  53 Upon failure, the target boot environment will be destroyed.
  54 In all cases, the running system is left untouched
  55 and a reboot into a partially updated system
  56 (due to install or hardware failure) cannot happen.
  57 Additionally, the full installation process requires
  58 only one reboot as it is performed
  59 in a new boot environment.
  60 .Pp
  61 .Nm
  62 requires a fully built world and kernel.
  63 It also requires
  64 .Xr pkg 8 ,
  65 which is not present in the base system and has to be installed manually.
  66 .Pp
  67 The
  68 .Ar options
  69 provided to
  70 .Nm
  71 are world and kernel flags like
  72 .Ev KERNCONF
  73 as described in
  74 .Xr build 7 .
  75 .Sh ENVIRONMENT
  76 User modifiable variables.
  77 Set these in the environment if desired:
  78 .Bl -tag -width indent
  79 .It Ev BE_UTILITY Pq default: Dq Li "bectl"
  80 Utility to manage ZFS boot environments.
  81 This can be either
  82 .Xr bectl 8
  83 from the base system or
  84 .Xr beadm 1
  85 from ports (sysutils/beadm).
  86 .It Ev CONFIG_UPDATER Pq default: Dq Li "etcupdate"
  87 Config updater:
  88 .Xr etcupdate 8
  89 is supported.
  90 Set to an empty string to skip.
  91 .It Ev ETCUPDATE_FLAGS Pq default: Dq Li "-F"
  92 Flags for
  93 .Xr etcupdate 8
  94 if used.
  95 .It Ev NO_PKG_UPGRADE Pq default: Dq Li ""
  96 If not empty,
  97 .Dq Li pkg upgrade
  98 will be skipped.
  99 .El
 100 .Sh FILES
 101 .Bl -tag -width indent
 102 .It Sy src/ Ns Pa tools/build/beinstall.sh
 103 Place where
 104 .Nm
 105 lives in the src tree.
 106 .El
 107 .Sh SEE ALSO
 108 .Xr build 7 ,
 109 .Xr development 7 ,
 110 .Xr bectl 8 ,
 111 .Xr etcupdate 8 ,
 112 .Xr pkg 8
 113 .Sh HISTORY
 114 .Nm
 115 is inspired by and similar in function to
 116 Solaris/illumos-style upgrades.
 117 .Pp
 118 The
 119 .Nm
 120 manual page first appeared in
 121 .Fx 12.0 .
 122 .Sh AUTHORS
 123 The
 124 .Nm
 125 script was implemented by
 126 .An Will Andrews Aq Mt will@FreeBSD.org .
 127 This manual page was written by
 128 .An Mateusz Piotrowski Aq Mt 0mp@FreeBSD.org .