PROOT(1) | General Commands Manual | 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`)
`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>

April 11, 2023 | Debian