PROOT(1) - General Commands Manual

PROOT(1) - General Commands Manual #

PROOT(1) - General Commands Manual

NAME #

proot - ports chroot builder

SYNOPSIS #

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

DESCRIPTION #

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:

check_mount

Verify the state of mount points in the system, specifically whether the chroot area is not nodev.

unpopulate

Remove everything from the chroot apart from selected data. See Preserved areas and unpopulate for details.

snapshot

Copy things from a snapshot, to be retrieved from a URL or from the local filesystem.

trusted_snapshot

Like snapshot, but without signature checking. Use with caution, usually with snapshots you’ve built yourself.

locate

Copy things from the base system, perusing the system locate(1) databases. Sy Note that this might erase data, in case it doesn’t match the base system and is in the way.

resolv

Copy the system resolv.conf(5) and hosts(5) files.

copy_ports

Copy the ports tree.

copy_sys

Copy system include files (deprecated).

unpopulate_light

Remove everything from the chroot apart from selected data. See Preserved areas and unpopulate for details.

ldconfig

Rerun ldconfig(8).

devs

Regenerate devices using MAKEDEV(8) and dev_mkdb(8).

checkout_ports

Check out a ports tree from cvs using a provided portscvs location.

ports_subdirs

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.

stragglers

Double-check filled up chroot for files we don’t know about.

write_mk

If some values are different from the default, write a skeleton mk.conf(5) file.

check_symlinks

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:

chroot

same as -B chroot

srcroot

same as -S srcroot

PORT_USER

Who the ports tree should belong to

BUILD_USER

Who to build as (defaults to _pbuild)

FETCH_USER

Who to fetch as (defaults to _pfetch)

LOG_USER

Who to write log as (defaults to BUILD_USER)

LOGDIR

Where to write logs (defaults to ${PORTSDIR}/logs)

PORTSDIR

DISTDIR

PACKAGE_REPOSITORY

PLIST_REPOSITORY

LOCKDIR

WRKOBJDIR

same as in bsd.port.mk(5)

chown_all

set to 1 to have the action ports_subdirs change owners of every content.

extra

extra file to copy into the chroot.

mkconf_lines

Add lines to the generated /etc/mk.conf.

mkconf_tail

Add file to the generated /etc/mk.conf.

preserve

Supplemental directory to preserve during unpopulate.

sets

Add or remove sets compared to the default list required to build ports (defaults to all sets).

snapshot

Location of snapshot for the snapshot action.

portscvs

Where to get a ports snapshot for the checkout_ports action.

Preserved areas and unpopulate #

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…

EXAMPLES #

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.

SEE ALSO #

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

AUTHORS #

Marc Espie <espie@openbsd.org>

OpenBSD 7.5 - April 11, 2023