OpenBSD manual page server

Manual Page Search Parameters
PROOT(1) General Commands Manual PROOT(1)

proot — ports chroot builder

proot [-B chroot] [-c configfile] [-S srcroot] [attribute=value ...]

proot can fill up a chroot directory for ports building usage. It will perform a set of actions that should fill up a destination chroot directory from the base system (or an optional srcroot).

As far as possible, proot will create hardlinks instead of copying files, so that cloning an existing chroot will often only consume i-nodes.

Some attributes can take multiple values. As a shorthand, several values can be specified in a row without having to repeat the attribute name, for instance:

proot -B /build actions=unpopulate_light check_symlinks

A configfile mostly contains one attribute=value assignment per line, with comments starting with a ‘#’ character.

Possible actions (in the order of execution) are as follows:

Verify the state of mount points in the system, specifically whether the chroot area is not nodev.
Remove everything from the chroot apart from selected data. See Preserved areas and unpopulate for details.
Copy things from a snapshot, to be retrieved from a URL or from the local filesystem.
Like snapshot, but without signature checking. Use with caution, usually with snapshots you've built yourself.
Copy things from the base system, perusing the system locate(1) databases.
Note that this might erase data, in case it doesn't match the base system and is in the way.
Copy the system resolv.conf(5) and hosts(5) files.
Copy the ports tree.
Copy system include files (deprecated).
Remove everything from the chroot apart from selected data. See Preserved areas and unpopulate for details.
Rerun ldconfig(8).
Regenerate devices using MAKEDEV(8) and dev_mkdb(8).
Check out a ports tree from cvs using a provided portscvs location.
Create ports infrastructure subdirs, according to users required for dpb(1). If chown_all is set to 1, chown(2) any content within to the appropriate users.
Double-check filled up chroot for files we don't know about.
If some values are different from the default, write a skeleton mk.conf(5) file.
Report absolute symlinks that exist under the chroot, white-listing known base system links.

By default, proot will run check_mount, unpopulate_light, devs, ldconfig, ports_subdirs, resolv, write_mk. If unpopulate is used, unpopulate_light won't be run. It will also run snapshot if a snapshot location is provided, or locate otherwise.

Add actions with actions=value, remove them with actions=-value.

Other attributes are:

same as -B chroot
same as -S srcroot
Who the ports tree should belong to
Who to build as (defaults to _pbuild)
Who to fetch as (defaults to _pfetch)
Who to write log as (defaults to BUILD_USER)
Where to write logs (defaults to ${PORTSDIR}/logs)
 
 
 
 
 
same as in bsd.port.mk(5)

set to 1 to have the action ports_subdirs change owners of every content.
extra file to copy into the chroot.
Add lines to the generated /etc/mk.conf.
Add file to the generated /etc/mk.conf.
Supplemental directory to preserve during unpopulate.
Add or remove sets compared to the default list required to build ports (defaults to all sets).
Location of snapshot for the snapshot action.
Where to get a ports snapshot for the checkout_ports action.

The following entries won't be erased during a locate or unpopulate* action:

  • Items explicitly marked with the preserve attribute.
  • A snapshot directory containing the base sets.
  • All the ports specific sub directories if they are defined, namely DISTDIR, WRKOBJDIR, LOGDIR, PACKAGE_REPOSITORY, PLIST_REPOSITORY, LOCKDIR.
  • The PORTSDIR itself, unless copy_ports is used.
  • Any mount point.
  • Data explicitly copied through other actions, e.g., extra files, key files...

The following configfile sets things up for an initial build on a dpb(1) cluster (refer to bulk(8) for typical setups of such build clusters).

chroot=/build
PORT_USER=espie
extra=/home/espie/startup
WRKOBJDIR=/tmp/pobj
LOCKDIR=/tmp/locks
PLIST_REPOSITORY=/data/plist
DISTDIR=/data/distfiles
PACKAGE_REPOSITORY=/data/packages
actions=unpopulate_light
	copy_ports

It assumes /build/data is a separate partition that won't be cleaned up by unpopulate_light, and that can be mounted on slaves. Note also that /tmp should be a fast local directory on every machine of the cluster.

/home/espie/startup is a startup script for dpb(1).

Initial invocation on the master could be

proot -c configfile chown_all=1

to ensure correct permissions for existing data under various ports directories.

Slaves should not need the extra arguments, as the directories will already have correct owners.

dpb(1), bulk(8), chroot(8)

Marc Espie <espie@openbsd.org>

April 11, 2023 OpenBSD-current