PROOT(1)

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. 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)
PORTSDIR
DISTDIR
PACKAGE_REPOSITORY
PLIST_REPOSITORY
LOGDIR
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.

    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), chroot(8)

AUTHORS
Marc Espie <espie@openbsd.org>