share/man/man8/beinstall.8

   1 .\"
   2 .\" SPDX-License-Identifier: BSD-2-Clause-FreeBSD
   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 .\"
  27 .\" $FreeBSD$
  28 .Dd October 30, 2020
  29 .Dt BEINSTALL.SH 8
  30 .Os
  31 .Sh NAME
  32 .Nm beinstall.sh
  33 .Nd "install a boot environment using the current FreeBSD source tree"
  34 .Sh SYNOPSIS
  35 .Nm
  36 .Op Ar options Ar ...
  37 .Sh DESCRIPTION
  38 .Nm
  39 installs a boot environment using the current
  40 .Fx
  41 source tree.
  42 .Nm
  43 also automatically performs
  44 .Pa /etc
  45 updates
  46 (using either
  47 .Xr etcupdate 8
  48 or
  49 .Xr mergemaster 8 )
  50 and
  51 package updates using
  52 .Xr pkg-upgrade 8
  53 automatically in the new boot environment sandbox.
  54 .Pp
  55 Upon successful completion, the system will be ready to boot into the new boot
  56 environment.
  57 Upon failure, the target boot environment will be destroyed.
  58 In all cases, the running system is left untouched
  59 and a reboot into a partially updated system
  60 (due to install or hardware failure) cannot happen.
  61 Additionally, the full installation process requires
  62 only one reboot as it is performed
  63 in a new boot environment.
  64 .Pp
  65 .Nm
  66 requires a fully built world and kernel.
  67 It also requires
  68 .Xr pkg 8 ,
  69 which is not present in the base system and has to be installed manually.
  70 .Pp
  71 The
  72 .Ar options
  73 provided to
  74 .Nm
  75 are world and kernel flags like
  76 .Ev KERNCONF
  77 as described in
  78 .Xr build 7 .
  79 .Sh ENVIRONMENT
  80 User modifiable variables.
  81 Set these in the environment if desired:
  82 .Bl -tag -width indent
  83 .It Ev BE_UTILITY Pq default: Dq Li "bectl"
  84 Utility to manage ZFS boot environments.
  85 This can be either
  86 .Xr bectl 8
  87 from the base system or
  88 .Xr beadm 1
  89 from ports (sysutils/beadm).
  90 .It Ev CONFIG_UPDATER Pq default: Dq Li "etcupdate"
  91 Config updater:
  92 .Xr etcupdate 8
  93 and
  94 .Xr mergemaster 8
  95 are supported.
  96 Set to an empty string to skip.
  97 .It Ev ETCUPDATE_FLAGS Pq default: Dq Li "-F"
  98 Flags for
  99 .Xr etcupdate 8
 100 if used.
 101 .It Ev MERGEMASTER_FLAGS Pq default: Dq Li "-iFU"
 102 Flags for
 103 .Xr mergemaster 8
 104 if used.
 105 .It Ev NO_PKG_UPGRADE Pq default: Dq Li ""
 106 If not empty,
 107 .Dq Li pkg upgrade
 108 will be skipped.
 109 .El
 110 .Sh FILES
 111 .Bl -tag -width indent
 112 .It Sy src/ Ns Pa tools/build/beinstall.sh
 113 Place where
 114 .Nm
 115 lives in the src tree.
 116 .El
 117 .Sh SEE ALSO
 118 .Xr build 7 ,
 119 .Xr development 7 ,
 120 .Xr bectl 8 ,
 121 .Xr etcupdate 8 ,
 122 .Xr mergemaster 8 ,
 123 .Xr pkg 8
 124 .Sh HISTORY
 125 .Nm
 126 is inspired by and similar in function to
 127 Solaris/illumos-style upgrades.
 128 .Pp
 129 The
 130 .Nm
 131 manual page first appeared in
 132 .Fx 12.0 .
 133 .Sh AUTHORS
 134 The
 135 .Nm
 136 script was implemented by
 137 .An Will Andrews Aq Mt will@FreeBSD.org .
 138 This manual page was written by
 139 .An Mateusz Piotrowski Aq Mt 0mp@FreeBSD.org .