---
name: "proot"
section: "1"
platform: "openbsd"
package: "man"
version: "8.0-current-20261101"
release: "OpenBSD 8.0-current (2026-11-01)"
platforms: ["linux", "openbsd"]
url: "https://new.carta.tech/proot"
---

# proot(1)

ports chroot builder

## 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)](/locate/1.md) 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)](/resolv.conf/5.md) and [hosts(5)](/hosts/5.md) 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)](/ldconfig/8.md).

- **devs**

  Regenerate devices using [MAKEDEV(8)](/MAKEDEV/8.md) and [dev\_mkdb(8)](/dev_mkdb/8.md).

- **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)](/dpb/1.md). If **chown\_all** is set to 1, [chown(2)](/chown/2.md) 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)](/mk.conf/5.md) 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)](/bsd.port.mk/5.md)

- **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)](/dpb/1.md) cluster( refer to [bulk(8)](/bulk/8.md) 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)](/dpb/1.md).

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)](/dpb/1.md), [bulk(8)](/bulk/8.md), [chroot(8)](/chroot/8.md)

## AUTHORS

Marc Espie ⟨*espie@openbsd.org*⟩