Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
PORTSREINSTALL-CHROOT(8)FreeBSD	System Manager's ManuaPORTSREINSTALL-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	thhen 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.

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			       22 September 2018      PORTSREINSTALL-CHROOT(8)

NAME | SYNOPSIS | DESCRIPTION | RESTRICTION | ROBUSTNESS AGAINST TERMINATION AND RESTART | SHELL IN THE BUILDER CHROOT ENVIRONMENT | ARGUMENTS | DETAILS | ENVIRONMENT VARIABLES | HISTORY | SEE ALSO | COPYRIGHT

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=portsreinstall-chroot&sektion=8&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help