1 .\" ==================================================================================
2 .\" portsreinstall\-chroot(8) manual page
3 .\" Copyright (C) 2018 Mamoru Sakaue, MwGhennndo, All Rights Reserved.
4 .\" ==================================================================================
5 .TH PORTSREINSTALL\-CHROOT 8 "13 September 2018" "FreeBSD" "FreeBSD System Manager's Manual"
7 portsreinstall\-chroot \- Support utility for \fBportsreinstall\fR(8) to build packages in a virtual environment
9 .B portsreinstall\-chroot
21 This utility assists to update packages by creating and using \fBchroot\fR(8) environment for building. The ch\fBchroot\fR(8)root environment is first created by forking the host environment, and the user is asked to complete update of packages at the \fBchroot\fR(8) environment.
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.
28 \fI$basedir\fR/usr/local/share/portsreinstall/bin/portsreinstall\-chroot\-mount
32 \fI$basedir\fR/usr/local/share/portsreinstall/bin/portsreinstall\-chroot\-mount unmount
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.
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
41 env SYSTEMBASE=\fI$basedir\fR \\
44 \fI$basedir\fR\fI$PREFIX\fR/share/portsreinstall/bin/portsreinstall\-chroot\-mount
50 env SYSTEMBASE=\fI$basedir\fR \\
53 \fI$basedir\fR\fI$PREFIX\fR/share/portsreinstall/bin/portsreinstall\-chroot\-mount unmount
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.
65 One of the following \fIcommands\fR can be given for optional operations or confirmation.
68 (Default) Execute the whole process from creation of a builder \fBchroot\fR(8) environment to package update of the host system, where the flow corresponds to \fBmount\fR, \fBenter\fR, \fBportsreinstall packupgrade create\fR at the builder chroot, \fBportsreinstall packupgrade crop\fR at the builder chroot, \fBsync\fR, then \fBportsreinstall\-upgrade\fR at the host, in order.
70 \fBauto\fR [\fIoptions\fR] [\fIarguments\fR]
71 Automatically execute \fBportsreinstall\fR(8) in the builder \fBchroot\fR(8) environment instead of the \fBenter\fR stage in the conventional \fBdo\fR process.
72 If given, \fIoptions\fR and \fIarguments\fR are passed to \fBportsreinstall\fR(8).
73 In case of the lost of the lower layer image of unionfs by its bug, the file system will be automatically recovered by re-mounting.
76 Just (create, if not yet, and) enter the builder \fBchroot\fR(8) environment.
77 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.
80 Just (create, if not yet, and) mount file systems for the builder \fBchroot\fR(8) environment.
83 Just unmount file systems for the builder \fBchroot\fR(8) environment.
86 Synchronize the files affecting package installation (packages, distfiles, port options, ports/packages management tools configurations) of the host environment to the builder.
89 Destroy the builder \fBchroot\fR(8) environment.
90 The difference from \fBclean\fR command is that the saved options are preserved.
96 Destroy the builder \fBchroot\fR(8) environment and clean up the temporary database.
99 Attempt to destroy the builder \fBchroot\fR(8) environment and clean up the temporary database without checking the lock and privilege.
102 Show saved option settings and expected effects of option-resetting options \fB\-M\fR.
103 With \fB\-a\fR option, the first, second and third columns denote the option-resetting options, reset options and remaining options, respectively.
107 If duplicated or conflicting ones are set, the last ones are effective.
108 The end of options can be explicitly specified by \fB\-\-\fR.
109 Short options can be given in compact forms, for example, \fB\-V \-a\fR to be \fB\-Va\fR.
113 Option settings are loaded from the saved configuration (independent of \fBportsreinstall\fR(8)) unless explicitly reset by \fB\-M\fR option.
114 The saved options can be checked by \fBportsreinstall-upgrade options\fR command.
116 .SS Group 1: Just show messages and exit without operation
121 Show a long help whose content is the same as the manual page.
129 \fB\-\-short\-help\fR
135 \fB\-\-show\-version\fR
136 Show the current version.
138 .SS Group 2: Effective anytime
142 \fB\-\-batch\-mode\fR
143 Suppress messages so as to be friendly for batch operations.
144 Comments are suppressed as much as possible.
145 It is noted that log output in build/installation processes are not suppressed.
147 .IP \fB\-E\fR\ \fIdelimiter(s)\fR
150 \fB\-\-extra\-dirs\-delim\fR=\fIdelimiter(s)\fR
151 Sets a (set of) custom delimiter character(s) for \fB\-e\fR option.
152 The default is comma (",").
153 If a string longer than one-character length is set, the all characters are recognized as delimiters.
158 \fB\-\-no\-opening\-message\fR
159 Suppress the credit, opening and terminating messages.
160 Option \fB\-a\fR takes higher priority over this option.
162 .SS Group 3: Saved and not renewable until cleaning
163 .IP \fB\-b\fR \fIbasedir\fR
166 \fB\-\-basedir\fR=\fIbasedir\fR
167 Specifies the base directory of the \fBchroot\fR(8) environment.
168 The default is "/home/.portsreinstall\-chroot".
173 \fB\-\-suppress\-cleaning\-obsolete\-database\fR
174 Suppress cleaning the temporary database even if its obsolete.
175 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.
176 Use of this option may cause unexpected results and basically unrecommended.
181 \fB\-\-invalidate\-mount\-privilege\fR
182 Forcibly invalidate the privilege of the current environment for mounting/unmounting file systems.
183 This option can be meaningful when this utility is executed inside a \fBchroot\fR(8) or \fBjail\fR(8) virtual environment.
185 .IP \fB\-e\fR \fIdir1\fR[\fB,\fIdir2\fR[\fB,\fR...]]
188 \fB\-\-extra\-dirs\fR=\fIdir1\fR[\fB,\fIdir2\fR[\fB,\fR...]]
189 Sets extra directories to mount for the chroot environment.
190 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.
191 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.
192 The delimiter is comma (",") by default and changeable by \fB\-E\fR option.
198 Carry out the \fBdo\fR process as the "full course" automatic mode where update of the ports tree and package repository are done first at the target host environment and thhen operation in the builder \fBchroot\fR(8) environment is started by cleaning of the temporary database and execution of \fBportsreinstall\fR(8) initiated with option \fB\-CGSjqx\fR (\fB\-CGSYajqx\fR if \fB\-a\fR option is set).
199 Resuming \fBdo\fR command automatically executes \fBportsreinstall\fR(8) in the builder \fBchroot\fR(8) environment.
200 With \fB\-a\fR option, the all detected leaf and obsolete packages will be deleted.
205 \fB\-\-upgraded\-system\fR
206 Adjust the all operations to be suitable as post-processes after system upgrade.
207 Concretely, the full course mode is adjusted to reinstall the all ports by removing \fB\-q\fR option of \fBportsreinstall\fR(8).
212 \fB\-\-load\-pkgtoolsconf\-as\-override\fR
213 Import settings from \fBpkgtools.conf\fR(5) as the secondary.
214 This option is effective only when \fBportupgrade\fR(1) is installed.
215 For duplicated configurations, values in portsreinstall.conf are applied first and then those in \fBpkgtools.conf\fR(5) are.
216 This option overrides preceding \fB\-p\fR option.
221 \fB\-\-load\-pkgtoolsconf\-as\-default\fR
222 Import settings from \fBpkgtools.conf\fR(5) as the primary (default).
223 This option is effective only when \fBportupgrade\fR(1) is installed.
224 For duplicated configurations, values in \fBpkgtools.conf\fR(5) are applied first and then those in portsreinstall.conf are.
225 This option overrides preceding \fB\-P\fR option.
230 \fB\-\-ignore\-pkgtoolsconf\fR
231 Ignore \fBpkgtools.conf\fR(5) even if it exists.
236 \fB\-\-share\-port\-pkgs\-dirs\fR
237 Share the ports tree (PORTSDIR=/usr/ports by default), portsnap work directory (WORKDIR=/var/db/portsnap in \fBportsnap.conf\fR(5) by default) and package cache (PKG_CACHEDIR=/var/cache/pkg in \fBpkg.conf\fR(5) by default) with the host by nullfs.
241 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.
242 On-the-fly smart entire upgrade of all installed ports and robustness against termination/restart is pursued by this utility.
244 The forked environment is created by \fBnullfs\fR(5) and \fBmount_unionfs\fR(8) onto the host environment.
245 Fetched/deleted distfiles and created/fetched/deleted packages are synchronized at the host to the forked environment.
246 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.
248 The execution of \fBdo\fR command proceeds in the following step (while use of \fBauto\fR command can be more practical):
251 This utility will create and mount the \fBchroot\fR(8) builder environment.
255 This utility will enter the builder environment, and the user will be prompted in a shell to complete the upgrade of packages by \fBportsreinstall\fR(8).
259 The user will exit from the builder environment when the upgrade is complete.
263 This utility will create packages and an archive of dispatch script for upgrade.
267 This utility will synchronize the host environment to the builder about distfiles, package files, ports options and other configurations of ports management.
271 The utility will upgrade the ports in host environment using the created packages and dispatched script set.
274 The conventional flow of using this utility will be as follows:
276 1. In the host (target) environment, execute this utility by the full course mode.
279 .B portsreinstall\-chroot -f
281 2. After successful build of the temporary database, \fBportsreinstall\fR(8) may show select dialogues for leaf and obsolete ports/packages.
282 Note that the choice made here can be changed afterward without any fatal risk as long as the current builder \fBchroot\fR(8) environment is preserved even after the upgrade of the host environment.
284 3. \fBportsreinstall\fR(8) will continue to build, (re)install and deinstall processes, which take very long and impose a high load.
285 You may want to interrupt the execution to cool down or shutdown your machine for your work or travel.
286 In this case, press Ctrl+C at any point so that \fBportsreinstall\fR(8) will stop by preserving its progress marker information in the temporary database and this utility will unmount the builder \fBchroot\fR(8) environment.
287 Some network troubles in fetching distfiles or packages may be resolved by terminating the process once.
288 (Even damages due to critical accidents of kernel panics, overheating and sudden shutdown may be recovered without problem just like this intentional termination.)
292 4. At any convenient time, restart the processes.
293 Note that no option should be speified here.
296 .B portsreinstall\-chroot auto
298 5. The process may stop with some failures which cannot be resolved automatically.
299 It may be mismatches of port option configurations of dependencies, unrecognized conflict or essential conflict between needed packages.
300 In this case, you will need to enter the builder \fBchroot\fR(8) environment for the manual troubleshooting.
303 .B portsreinstall\-chroot enter
305 6. Then the you will be prompted in the builder \fBchroot\fR(8) environment.
309 7. Troubleshooting may be done by modifying the configuration files or struggling with \fBfreeze\fR/\fBtaboo\fR/\fBescape\fR/\fBok\fR/\fBneed\fR/\fBnoneed\fR/\fBreselect\fR/\fBreconf\fR commands of \fBportsreinstall\fR(8) referring to information obtained by \fBshow\fR command of \fBportsreinstall\fR(8).
310 After such possible patchwork, exit from the builder \fBchroot\fR(8) environment.
315 8. Retry to continue the processes by executing
318 .B portsreinstall\-chroot auto
320 or, when the configuration files were modified,
323 .B portsreinstall\-chroot auto -L redo
325 9. When the all necessary upgrade is completed inside the builder \fBchroot\fR(8) environment, you will be asked whether to reflect the upgrade to the host environment.
326 If you select Yes here, package archiving in the builder \fBchroot\fR(8) environment, synchronization of package files, distfiles, port option database and configuration files for \fBportsreinstall\fR(8), and the update of the packages at the host environment will be automatically carried out.
327 Here, again, Ctrl+C interruption and unintentional termination will be recovered by simple re-exeution of this utility.
328 .SH "ENVIRONMENT VARIABLES"
331 (Used only when the target environment is a virtual environment implemented by \fBchroot\fR(8) or \fBjail\fR(8))
332 The base directory of the target environment at its grand host environment.
333 This variable is referred by \fBportsreinstall\-chroot\-mount\fR(8), which is to be executed in the grand host environment of the target environment.
334 The default is the two-levels higher directory of PREFIX applied for installation of \fBportsreinstall\fR(8) in the target environment.
336 See also the corresponding section of \fBportsreinstall\fR(8).
337 The variables are conveyed to the forked environment from the target host.
339 This utility first appeared as a part of \fBportsreinstall\fR(8) version 4.0.0 released on June 29, 2018.
342 \fBportsreinstall\fR(8),
343 \fBportsreinstall\-chroot\-mount\fR(8),
344 \fBportsreinstall\-upgrade\fR(8).
346 This software is distributed under the 2-Clause BSD License.
348 (C)\ 2018\ Mamoru\ Sakaue,\ MwGhennndo,\ All\ Rights\ Reserved.
350 Email:\ sakaue.mamoru@samurai.mwghennn.net
352 Homepage:\ http://www.mwghennndo.com/software/portsreinstall/
OSDN Git Service
