man/portsreinstall-chroot.8

   1 .\" ==================================================================================
   2 .\" portsreinstall\-chroot(8) manual page
   3 .\" Copyright (C) 2018 Mamoru Sakaue, MwGhennndo, All Rights Reserved.
   4 .\" ==================================================================================
   5 .TH PORTSREINSTALL\-CHROOT 8 "29 June 2018" "FreeBSD" "FreeBSD System Manager's Manual"
   6 .SH NAME
   7 portsreinstall\-chroot \- Support utility for \fBportsreinstall\fR(8) to build packages in a virtual environment
   8 .SH SYNOPSIS
   9 .B portsreinstall\-chroot
  10 [
  11 .I
  12 OPTIONS
  13 ] [
  14 .B
  15 \-\-
  16 ] [
  17 .I
  18 command
  19 ]
  20 .SH DESCRIPTION
  21 This utility is updates packages based on \fBports\fR(7) by creating and using a \fBchroot\fR(8) environment and \fBportsreinstall\fR(8).
  22 .SH RESTRICTION
  23 When this utility is executed inside a \fBchroot\fR(8) or \fBjail\fR(8) virtual environment as the target, the execution MAY be terminated at the process of mounting and unmounting file systems.
  24 In this case, the user should follow a message which addresses to execute \fBportsreinstall\-chroot\-mount\fR(8) at the grand host environment.
  25 Note that this utility involves mounting and unmounting operations of unionfs whose implementation is still in a challenging level, and the user MAY find that the detection of the mounting/unmounting privilege is fluctuated, namely, sometimes available and sometimes not.
  26 If you want to forcibly invalidate the privilege of such operations inside \fBchroot\fR(8) or \fBjail\fR(8) environments, set \fB\-d\fR option.
  27 .PP
  28 \fI$basedir\fR/usr/local/share/portsreinstall/bin/portsreinstall\-chroot\-mount
  29 .PP
  30 for mounting, and
  31 .PP
  32 \fI$basedir\fR/usr/local/share/portsreinstall/bin/portsreinstall\-chroot\-mount unmount
  33 .PP
  34 for unmounting, where \fI$basedir\fR denotes the base directory of the target environment.
  35 Here, the exit code of the termination is 2  for mounting and 3 for unmounting.
  36 After the mounting or unmounting at the grand host environment, rerun this utility (\fBportsreinstall\-chroot\fR(8)) at the target environment.
  37 .PP
  38 If the installation path of \fBportsreinstall\fR(8) in the target environment is configured by non-default PREFIX, environment variable SYSTEMBASE must be defined for telling the base directory of the target environment as
  39 .PP
  40 .PD 0
  41 env SYSTEMBASE=\fI$basedir\fR \\
  42 .RS
  43 .PD 0
  44 \fI$basedir\fR\fI$PREFIX\fR/share/portsreinstall/bin/portsreinstall\-chroot\-mount
  45 .RE
  46 .PD 0
  47 for mounting, and
  48 .PP
  49 .PD 0
  50 env SYSTEMBASE=\fI$basedir\fR \\
  51 .RS
  52 .PD 0
  53 \fI$basedir\fR\fI$PREFIX\fR/share/portsreinstall/bin/portsreinstall\-chroot\-mount unmount
  54 .RE
  55 .PD 0
  56 for unmounting.
  57 .SH ROBUSTNESS AGAINST TERMINATION AND RESTART
  58 Execution of the commands except \fBclean\fR and \fBoptions\fR commands can be terminated at any points and restarted from there with the same options saved in the temporary database (independent among utilities). The saved options can be changed by the ways depending on the assigned groups of the options. The options and execution progress are reset to the default by \fBclean\fR command.
  59 .SH SHELL IN THE BUILDER CHROOT ENVIRONMENT
  60 The same login shell of the current user (which will be the superuser) is invoked as the login shell in the builder \fBchroot\fR(8) environment.
  61 For \fBsh\fR(1) and its families, environment variable \fIPS1\fR is modified for distinction from the host environment.
  62 For \fBtcsh\fR(1) and its families, the configuration file (\fB/root/.cshrc\fR) is modified to add a line for redefining \fBprompt\fR variable for the distinction.
  63 The original configuration file is backed up as \fB/root/.cshrc.bak\-portsreinstall\-chroot\fR.
  64 .SH ARGUMENTS
  65 One of the following \fIcommands\fR can be given for optional operations or confirmation.
  66 .TP
  67 \fBdo\fR
  68 (Default) Execute the whole process from creation of a \fBchroot\fR(8) environment to package update of the host system.
  69 .TP
  70 \fBenter\fR
  71 Just (create, if not yet, and) enter the builder \fBchroot\fR(8) environment.
  72 If once the upgrade of the host environment was completed, this command enables to reuse the same builder \fBchroot\fR(8) environment for the next upgrade with modified configuration or updated ports tree.
  73 .TP
  74 \fBmount\fR
  75 Just (create, if not yet, and) mount file systems for the builder \fBchroot\fR(8) environment.
  76 .TP
  77 \fBunmount\fR
  78 Just unmount file systems for the builder \fBchroot\fR(8) environment.
  79 .TP
  80 \fBsync\fR
  81 Synchronize the files affecting package installation (packages, distfiles, port options, ports/packages management tools configurations) of the host environment to the builder.
  82 .TP
  83 \fBclean\fR
  84 .PD 0
  85 .TP
  86 \fBclean [normal]\fR
  87 Destroy the builder \fBchroot\fR(8) environment and clean up the temporary database.
  88 .TP
  89 \fBclean force\fR
  90 Attempt to destroy the builder \fBchroot\fR(8) environment and clean up the temporary database without checking the lock and privilege.
  91 .TP
  92 \fBoptions\fR
  93 Show saved option settings and expected effects of option-resetting options \fB\-M\fR.
  94 With \fB\-a\fR option, the first, second and third columns denote the option-resetting options, reset options and remaining options, respectively.
  95 .TP
  96 .RE
  97 .SH OPTIONS
  98 If duplicated or conflicting ones are set, the last ones are effective.
  99 The end of options can be explicitly specified by \fB\-\-\fR.
 100 Short options can be given in compact forms, for example, \fB\-V \-a\fR to be \fB\-Va\fR.
 101 .PD
 102 .TP
 103 \fB*NOTE*\fR
 104 Option settings are loaded from the saved configuration (independent of \fBportsreinstall\fR(8)) unless explicitly reset by \fB\-M\fR option.
 105 The saved options can be checked by \fBportsreinstall-upgrade options\fR command.
 106 .PD
 107 .SS Group 1: Just show messages and exit without operation
 108 .IP \fB\-H\fR
 109 .PD 0
 110 .TP
 111 \fB\-\-long\-help\fR
 112 Show a long help whose content is the same as the manual page.
 113 .PD
 114 .IP \fB\-h\fR
 115 .PD 0
 116 .TP
 117 \fB\-\-help\fR
 118 .PD 0
 119 .TP
 120 \fB\-\-short\-help\fR
 121 Show a short help.
 122 .PD
 123 .IP \fB\-V\fR
 124 .PD 0
 125 .TP
 126 \fB\-\-show\-version\fR
 127 Show the current version.
 128 .PD
 129 .SS Group 2: Effective anytime
 130 .IP \fB\-a\fR
 131 .PD 0
 132 .TP
 133 \fB\-\-batch\-mode\fR
 134 Suppress messages so as to be friendly for batch operations.
 135 Comments are suppressed as much as possible.
 136 It is noted that log output in build/installation processes are not suppressed.
 137 .PD
 138 .IP \fB\-E\fR\ \fIdelimiter(s)\fR
 139 .PD 0
 140 .TP
 141 \fB\-\-extra\-dirs\-delim\fR=\fIdelimiter(s)\fR
 142 Sets a (set of) custom delimiter character(s) for \fB\-e\fR option.
 143 The default is comma (",").
 144 If a string longer than one-character length is set, the all characters are recognized as delimiters.
 145 .PD
 146 .IP \fB\-S\fR
 147 .PD 0
 148 .TP
 149 \fB\-\-no\-opening\-message\fR
 150 Suppress the credit and opening messages.
 151 Option \fB\-a\fR takes higher priority over this option.
 152 .PD
 153 .SS Group 3: Saved and not renewable until cleaning
 154 .IP \fB\-b\fR
 155 .PD 0
 156 .TP
 157 \fB\-\-basedir\fR
 158 Specifies the base directory of the \fBchroot\fR(8) environment.
 159 The default is "/home/.portsreinstall\-chroot".
 160 .PD
 161 .IP \fB\-c\fR
 162 .PD 0
 163 .TP
 164 \fB\-\-suppress\-cleaning\-obsolete\-database\fR
 165 Suppress cleaning the temporary database even if its obsolete.
 166 This option suppresses the default behavior that the temporary database is automatically cleaned up if it is older than the ports tree or portsreinstall itself is to be upgraded.
 167 Use of this option may cause unexpected results and basically unrecommended.
 168 .PD
 169 .IP \fB\-d\fR
 170 .PD 0
 171 .TP
 172 \fB\-\-invalidate\-mount\-privilege\fR
 173 Forcibly invalidate the privilege of the current environment for mounting/unmounting file systems.
 174 This option can be meaningful when this utility is executed inside a \fBchroot\fR(8) or \fBjail\fR(8) virtual environment.
 175 .PD
 176 .IP \fB\-e\fR\ \fIdir1\fR[\fB,\fIdir2\fR[\fB,\fR...]]
 177 .PD 0
 178 .TP
 179 \fB\-\-extra\-dirs\fR=\fIdir1\fR[\fB,\fIdir2\fR[\fB,\fR...]]
 180 Sets extra directories to mount for the chroot environment.
 181 By default (without this option), /bin, /compat, /etc, /lib, /libexec, /rootm /sbin, /sys, /usr and /var (or their entities if they themselves are symbolic links) as well as file systems overlaying their descendant directories are mounted by read-only nullfs from the host and overlaid by unionfs while /dev, /proc and /tmp are mounted with independent proper file systems.
 182 This option should be set if any of the above directories contain symbolic links referring to outside of the default directories, or if any package build/installation is customized to refer to outside of them.
 183 The delimiter is comma (",") by default and changeable by \fB\-E\fR option.
 184 .PD
 185 .IP \fB\-P\fR
 186 .PD 0
 187 .TP
 188 \fB\-\-load\-pkgtoolsconf\-as\-override\fR
 189 Import settings from \fBpkgtools.conf\fR(5) as the secondary.
 190 This option is effective only when \fBportupgrade\fR(1) is installed.
 191 For duplicated configurations, values in portsreinstall.conf are applied first and then those in \fBpkgtools.conf\fR(5) are.
 192 This option overrides preceding \fB\-p\fR option.
 193 .PD
 194 .IP \fB\-p\fR
 195 .PD 0
 196 .TP
 197 \fB\-\-load\-pkgtoolsconf\-as\-default\fR
 198 Import settings from \fBpkgtools.conf\fR(5) as the primary (default).
 199 This option is effective only when \fBportupgrade\fR(1) is installed.
 200 For duplicated configurations, values in \fBpkgtools.conf\fR(5) are applied first and then those in portsreinstall.conf are.
 201 This option overrides preceding \fB\-P\fR option.
 202 .PD
 203 .IP \fB\-Q\fR
 204 .PD 0
 205 .TP
 206 \fB\-\-ignore\-pkgtoolsconf\fR
 207 Ignore \fBpkgtools.conf\fR(5) even if it exists.
 208 .PD
 209 .SH DETAILS
 210 .SS Overview
 211 This utility is a supporting tool of \fBportsreinstall\fR(8) to build packages in a \fBchroot\fR(8) environment "forked" from the host environment which is the final target of upgrading.
 212 On-the-fly smart entire upgrade of all installed ports and robustness against termination/restart is pursued by this tool.
 213 .PP
 214 The forked environment is created by \fBnullfs\fR(5) and \fBmount_unionfs\fR(8) onto the host environment.
 215 Fetched/deleted distfiles and created/fetched/deleted packages are synchronized at the host to the forked environment.
 216 The ports options and other configurations of ports management (\fB/etc/make.conf\fR, \fB/usr/local/etc/portsreinstall.conf\fR, \fB/usr/local/etc/pkgtools.conf\fR, \fB/usr/local/etc/pkg.conf\fR and the temporary database of \fBportsreinstall\fR(8) in usual environments) are also synchronized as well.
 217 .PP
 218 The execution of \fBdo\fR command proceeds in the following step:
 219 .TP
 220 1.
 221 This utility will create and mount the \fBchroot\fR(8) builder environment.
 222 .PD
 223 .TP
 224 2.
 225 This utility will enter the builder environment, and the user will be prompted in a shell to complete the upgrade of pakages by \fBportsreinstall\fR(8).
 226 .PD
 227 .TP
 228 3.
 229 The user will exit from the builder environment when the upgrade is complete.
 230 .PD
 231 .TP
 232 4.
 233 This utility will create packages and an archive of dispatch script for upgrade.
 234 .PD
 235 .TP
 236 5.
 237 This utility will synchronize the host environment to the builder about distfiles, pakage files, ports options and other configurations of ports management.
 238 .PD
 239 .TP
 240 6.
 241 The utility will upgrade the ports in host environment using the created packages and dispatched script set.
 242 .PD
 243 .SS Example
 244 The conventional flow of using this utility will be as follows:
 245 .PP
 246 1. In the host (target) environment, update the ports tree and the package repository catalog.
 247 .RS
 248 root@[host]#
 249 .B portsnap fetch update
 250 .RE
 251 .RS
 252 root@[host]#
 253 .B pkg update
 254 .RE
 255 2. Launch a "forked" chroot environment by executing this utility.
 256 .RS
 257 root@[host]#
 258 .B portsreinstall\-chroot
 259 .RE
 260 3. Then the user will be prompted in the chroot (builder) environment.
 261 .RS
 262 root@[chroot]#
 263 .RE
 264 4. In the chroot (builder) environment, upgrade the all pakages completely by \fBportsreinstall\fR (the command line options are just an example; muitiple redoing and reconfiguration of port options and other configuration files of ports management may be required).
 265 .RS
 266 root@[chroot]#
 267 .B portsreinstall -qC
 268 .RE
 269 5. Exit from the chroot (builder) environment.
 270 .RS
 271 root@[chroot]#
 272 .B exit
 273 .RE
 274 6. When the exit code is zero and the upgrading of ports is complete, following processes will be carried out automatically. Otherwise, the process will be terminated here.
 275 .PP
 276 7. Updated packages and dispatch script set will be created by internally invoking \fBportsreinstall packupgrade create\fR and \fBportsreinstall packupgrade archive\fR commands.
 277 .PP
 278 8. Then distfiles, pakage files, ports options and other configurations of ports management will be synchronized from the chroot (builder) environment.
 279 .PP
 280 9. Then the ports in the host (target) environment will be updated by internally invoking the dispatched script set.
 281 .SH "ENVIRONMENT VARIABLES"
 282 .TP
 283 .B SYSTEMBASE
 284 (Used only when the target environment is a virtual environment implemented by \fBchroot\fR(8) or \fBjail\fR(8))
 285 The base directory of the target environment at its grand host environment.
 286 This variable is referred by portsreinstall\-chroot\-mount, which is to be executed in the grand host environment of the target environment.
 287 The default is the two-levels higher directory of PREFIX applied for installation of \fBportsreinstall\fR(8) in the target environment.
 288 .PP
 289 See also the corresponding section of \fBportsreinstall\fR(8).
 290 The variables are conveyed to the forked environment from the target host.
 291 .SH HISTORY
 292 See the corresponding section of \fBportsreinstall\fR(8).
 293 This utility first appeared in \fBportsreinstall\fR(8) version 4.0.0.
 294 .SH "SEE ALSO"
 295 \fBchroot\fR(8)
 296 \fBportsreinstall\fR(8),
 297 \fBportsreinstall\-chroot\-mount\fR(8),
 298 \fBportsreinstall\-upgrade\fR(8).
 299 .SH COPYRIGHT
 300 This software is distributed under the 2-Clause BSD License.
 301 .PP
 302 (C)\ 2018\ Mamoru\ Sakaue,\ MwGhennndo,\ All\ Rights\ Reserved.
 303 .PP
 304 Email:\ sakaue.mamoru@samurai.mwghennn.net
 305 .PP
 306 Homepage:\ http://www.mwghennndo.com/software/portsreinstall/