FreeBSD Manual Pages
PORTSREI...LL-CHROOT(8) FreeBSD System Manager's ManualPORTSREI...LL-CHROOT(8) NAME portsreinstall-chroot - Support utility for portsreinstall(8) to build packages in a virtual environment SYNOPSIS portsreinstall-chroot [ OPTIONS ] [ -- ] [ command ] DESCRIPTION This utility assists to update packages by creating and using ch- root(8) environment for building. The chchroot(8)root environment is first created by forking the host environment, and the user is asked to complete update of packages at the chroot(8) environment. RESTRICTION When this utility is executed inside a chroot(8) or jail(8) virtual en- vironment as the target, the execution MAY be terminated at the process of mounting and unmounting file systems. In this case, the user should follow a message which addresses to execute portsreinstall-ch- root-mount(8) at the grand host environment. Note that this utility involves mounting and unmounting operations of unionfs whose implemen- tation 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. If you want to forcibly invali- date the privilege of such operations inside chroot(8) or jail(8) envi- ronments, set -d option. $basedir/usr/local/share/portsreinstall/bin/portsreinstall-chroot-mount for mounting, and $basedir/usr/local/share/portsreinstall/bin/portsreinstall-chroot-mount unmount for unmounting, where $basedir denotes the base directory of the target environment. Here, the exit code of the termination is 2 for mounting and 3 for unmounting. After the mounting or unmounting at the grand host environment, rerun this utility (portsreinstall-chroot(8)) at the target environment. If the installation path of portsreinstall(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 environ- ment as env SYSTEMBASE=$basedir \ $basedir$PREFIX/share/portsreinstall/bin/portsreinstall-ch- root-mount for mounting, and env SYSTEMBASE=$basedir \ $basedir$PREFIX/share/portsreinstall/bin/portsreinstall-ch- root-mount unmount for unmounting. ROBUSTNESS AGAINST TERMINATION AND RESTART Execution of the commands except clean and options commands can be ter- minated 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 clean command. SHELL IN THE BUILDER CHROOT ENVIRONMENT The same login shell of the current user (which will be the superuser) is invoked as the login shell in the builder chroot(8) environment. For sh(1) and its families, environment variable PS1 is modified for distinction from the host environment. For tcsh(1) and its families, the configuration file (/root/.cshrc) is modified to add a line for re- defining prompt variable for the distinction. The original configura- tion file is backed up as /root/.cshrc.bak-portsreinstall-chroot. ARGUMENTS One of the following commands can be given for optional operations or confirmation. do (Default) Execute the whole process from creation of a builder chroot(8) environment to package update of the host system, where the flow corresponds to mount, enter, portsreinstall pack- upgrade create at the builder chroot, portsreinstall packupgrade crop at the builder chroot, sync, then portsreinstall-upgrade at the host, in order. auto [options] [arguments] Automatically execute portsreinstall(8) in the builder chroot(8) environment instead of the enter stage in the conventional do process. If given, options and arguments are passed to portsre- install(8). In case of the lost of the lower layer image of unionfs by its bug, the file system will be automatically recov- ered by re-mounting. enter Just (create, if not yet, and) enter the builder chroot(8) envi- ronment. If once the upgrade of the host environment was com- pleted, this command enables to reuse the same builder chroot(8) environment for the next upgrade with modified configuration or updated ports tree. mount Just (create, if not yet, and) mount file systems for the builder chroot(8) environment. unmount Just unmount file systems for the builder chroot(8) environment. sync Synchronize the files affecting package installation (packages, distfiles, port options, ports/packages management tools config- urations) of the host environment to the builder. destroy Destroy the builder chroot(8) environment. The difference from clean command is that the saved options are preserved. clean clean [normal] Destroy the builder chroot(8) environment and clean up the tem- porary database. clean force Attempt to destroy the builder chroot(8) environment and clean up the temporary database without checking the lock and privi- lege. options Show saved option settings and expected effects of option-reset- ting options -M. With -a option, the first, second and third columns denote the option-resetting options, reset options and remaining options, respectively. OPTIONS If duplicated or conflicting ones are set, the last ones are ef- fective. The end of options can be explicitly specified by --. Short options can be given in compact forms, for example, -V -a to be -Va. *NOTE* Option settings are loaded from the saved configuration (inde- pendent of portsreinstall(8)) unless explicitly reset by -M op- tion. The saved options can be checked by portsreinstall-up- grade options command. Group 1: Just show messages and exit without operation -H --long-help Show a long help whose content is the same as the manual page. -h --help --short-help Show a short help. -V --show-version Show the current version. Group 2: Effective anytime -a --batch-mode Suppress messages so as to be friendly for batch operations. Comments are suppressed as much as possible. It is noted that log output in build/installation processes are not suppressed. -E delimiter(s) --extra-dirs-delim=delimiter(s) Sets a (set of) custom delimiter character(s) for -e option. The default is comma (","). If a string longer than one-charac- ter length is set, the all characters are recognized as delim- iters. -S --no-opening-message Suppress the credit, opening and terminating messages. Option -a takes higher priority over this option. Group 3: Saved and not renewable until cleaning -b --basedir=basedir Specifies the base directory of the chroot(8) environment. The default is "/home/.portsreinstall-chroot". -c --suppress-cleaning-obsolete-database Suppress cleaning the temporary database even if its obsolete. 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. Use of this option may cause unexpected results and basically unrecom- mended. -d --invalidate-mount-privilege Forcibly invalidate the privilege of the current environment for mounting/unmounting file systems. This option can be meaningful when this utility is executed inside a chroot(8) or jail(8) vir- tual environment. -e --extra-dirs=dir1[,dir2[,...]] Sets extra directories to mount for the chroot environment. 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. 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. The delimiter is comma (",") by default and changeable by -E option. -f --fullcourse Carry out the do 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 then operation in the builder chroot(8) environment is started by cleaning of the tem- porary database and execution of portsreinstall(8) initiated with option -CGSjqx (-CGSYajqx if -a option is set). Resuming do command automatically executes portsreinstall(8) in the builder chroot(8) environment. With -a option, the all detected leaf and obsolete packages will be deleted. -g --upgraded-system Adjust the all operations to be suitable as post-processes after system upgrade. Concretely, the full course mode is adjusted to reinstall the all ports by removing -q option of portsrein- stall(8). -P --load-pkgtoolsconf-as-override Import settings from pkgtools.conf(5) as the secondary. This option is effective only when portupgrade(1) is installed. For duplicated configurations, values in portsreinstall.conf are ap- plied first and then those in pkgtools.conf(5) are. This option overrides preceding -p option. -p --load-pkgtoolsconf-as-default Import settings from pkgtools.conf(5) as the primary (default). This option is effective only when portupgrade(1) is installed. For duplicated configurations, values in pkgtools.conf(5) are applied first and then those in portsreinstall.conf are. This option overrides preceding -P option. -Q --ignore-pkgtoolsconf Ignore pkgtools.conf(5) even if it exists. -s --share-port-pkgs-dirs Share the ports tree (PORTSDIR=/usr/ports by default), portsnap work directory (WORKDIR=/var/db/portsnap in portsnap.conf(5) by default) and package cache (PKG_CACHEDIR=/var/cache/pkg in pkg.conf(5) by default) with the host by nullfs. DETAILS Overview This utility is a supporting tool of portsreinstall(8) to build pack- ages in a chroot(8) environment "forked" from the host environment which is the final target of upgrading. On-the-fly smart entire up- grade of all installed ports and robustness against termination/restart is pursued by this utility. The forked environment is created by nullfs(5) and mount_unionfs(8) onto the host environment. Fetched/deleted distfiles and cre- ated/fetched/deleted packages are synchronized at the host to the forked environment. The ports options and other configurations of ports management (/etc/make.conf, /usr/local/etc/portsreinstall.conf, /usr/local/etc/pkgtools.conf, /usr/local/etc/pkg.conf and the temporary database of portsreinstall(8) in usual environments) are also synchro- nized as well. The execution of do command proceeds in the following step (while use of auto command can be more practical): 1. This utility will create and mount the chroot(8) builder envi- ronment. 2. This utility will enter the builder environment, and the user will be prompted in a shell to complete the upgrade of packages by portsreinstall(8). 3. The user will exit from the builder environment when the upgrade is complete. 4. This utility will create packages and an archive of dispatch script for upgrade. 5. This utility will synchronize the host environment to the builder about distfiles, package files, ports options and other configurations of ports management. 6. The utility will upgrade the ports in host environment using the created packages and dispatched script set. Example The conventional flow of using this utility will be as follows: 1. In the host (target) environment, execute this utility by the full course mode. root@[host]# portsreinstall-chroot -f 2. After successful build of the temporary database, portsreinstall(8) may show select dialogues for leaf and obsolete ports/packages. Note that the choice made here can be changed afterward without any fatal risk as long as the current builder chroot(8) environment is preserved even after the upgrade of the host environment. 3. portsreinstall(8) will continue to build, (re)install and deinstall processes, which take very long and impose a high load. You may want to interrupt the execution to cool down or shutdown your machine for your work or travel. In this case, press Ctrl+C at any point so that portsreinstall(8) will stop by preserving its progress marker informa- tion in the temporary database and this utility will unmount the builder chroot(8) environment. Some network troubles in fetching dist- files or packages may be resolved by terminating the process once. (Even damages due to critical accidents of kernel panics, overheating and sudden shutdown may be recovered without problem just like this in- tentional termination.) Ctrl+C 4. At any convenient time, restart the processes. Note that no option should be speified here. root@[host]# portsreinstall-chroot auto 5. The process may stop with some failures which cannot be resolved au- tomatically. It may be mismatches of port option configurations of de- pendencies, unrecognized conflict or essential conflict between needed packages. In this case, you will need to enter the builder chroot(8) environment for the manual troubleshooting. root@[host]# portsreinstall-chroot enter 6. Then the you will be prompted in the builder chroot(8) environment. root@[chroot]# 7. Troubleshooting may be done by modifying the configuration files or struggling with freeze/taboo/escape/ok/need/noneed/reselect/reconf com- mands of portsreinstall(8) referring to information obtained by show command of portsreinstall(8). After such possible patchwork, exit from the builder chroot(8) environment. root@[chroot]# exit 8. Retry to continue the processes by executing root@[host]# portsreinstall-chroot auto or, when the configuration files were modified, root@[host]# portsreinstall-chroot auto -L redo 9. When the all necessary upgrade is completed inside the builder ch- root(8) environment, you will be asked whether to reflect the upgrade to the host environment. If you select Yes here, package archiving in the builder chroot(8) environment, synchronization of package files, distfiles, port option database and configuration files for portsrein- stall(8), and the update of the packages at the host environment will be automatically carried out. Here, again, Ctrl+C interruption and un- intentional termination will be recovered by simple re-exeution of this utility. ENVIRONMENT VARIABLES SYSTEMBASE (Used only when the target environment is a virtual environment implemented by chroot(8) or jail(8)) The base directory of the target environment at its grand host environment. This variable is referred by portsreinstall-chroot-mount(8), which is to be executed in the grand host environment of the target environ- ment. The default is the two-levels higher directory of PREFIX applied for installation of portsreinstall(8) in the target en- vironment. See also the corresponding section of portsreinstall(8). The variables are conveyed to the forked environment from the target host. HISTORY This utility first appeared as a part of portsreinstall(8) version 4.0.0 released on June 29, 2018. BUGS This tool is still experimental and may not work in typical environ- ments. It has been observed that pkg-add(8) command froze at the preparation stage in a ZFS-mounted environment with 12.2-RELEASE. SEE ALSO chroot(8) portsreinstall(8), portsreinstall-chroot-mount(8), portsrein- stall-upgrade(8). COPYRIGHT This software is distributed under the 2-Clause BSD License. (C) 2018 Mamoru Sakaue, MwGhennndo, All Rights Reserved. Email: sakaue.mamoru@samurai.mwghennn.net Homepage: http://www.mwghennndo.com/software/portsreinstall/ FreeBSD 20 April 2022 PORTSREI...LL-CHROOT(8)
NAME | SYNOPSIS | DESCRIPTION | RESTRICTION | ROBUSTNESS AGAINST TERMINATION AND RESTART | SHELL IN THE BUILDER CHROOT ENVIRONMENT | ARGUMENTS | DETAILS | ENVIRONMENT VARIABLES | HISTORY | BUGS | SEE ALSO | COPYRIGHT
Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=portsreinstall-chroot&sektion=8&manpath=FreeBSD+Ports+15.0>