1.\" $OpenBSD: proot.1,v 1.11 2023/04/11 11:23:09 espie Exp $ 2.\" 3.\" Copyright (c) 2016 Marc Espie <espie@openbsd.org> 4.\" 5.\" Permission to use, copy, modify, and distribute this software for any 6.\" purpose with or without fee is hereby granted, provided that the above 7.\" copyright notice and this permission notice appear in all copies. 8.\" 9.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 10.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 11.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 12.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 13.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 14.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 15.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 16.\" 17.Dd $Mdocdate: April 11 2023 $ 18.Dt PROOT 1 19.Os 20.Sh NAME 21.Nm proot 22.Nd ports chroot builder 23.Sh SYNOPSIS 24.Nm proot 25.Op Fl B Ar chroot 26.Op Fl c Ar configfile 27.Op Fl S Ar srcroot 28.Op Ar attribute Ns = Ns Ar value ... 29.Sh DESCRIPTION 30.Nm 31can fill up a chroot directory for ports building usage. 32It will perform a set of 33.Cm actions 34that should fill up a destination 35.Ar chroot 36directory from the base system (or an optional 37.Ar srcroot ) . 38.Pp 39As far as possible, 40.Nm 41will create hardlinks instead of copying files, so that cloning an existing 42chroot will often only consume i-nodes. 43.Pp 44Some attributes can take multiple values. 45As a shorthand, several values can be specified in a row without having 46to repeat the 47.Ar attribute 48name, for instance: 49.Pp 50.Dl proot -B /build actions=unpopulate_light check_symlinks 51.Pp 52A 53.Ar configfile 54mostly contains one 55.Ar attribute Ns = Ns Ar value 56assignment per line, with comments starting with a 57.Sq # 58character. 59.Pp 60Possible 61.Cm actions 62(in the order of execution) are as follows: 63.Pp 64.Bl -tag -width unpopulate_light -compact -offset indent 65.It Cm check_mount 66Verify the state of mount points in the system, specifically whether 67the chroot area is not nodev. 68.It Cm unpopulate 69Remove everything from the chroot apart from selected data. 70See 71.Sx Preserved areas and unpopulate 72for details. 73.It Cm snapshot 74Copy things from a snapshot, 75to be retrieved from a URL or from the local filesystem. 76.It Cm trusted_snapshot 77Like 78.Cm snapshot , 79but without signature checking. 80Use with caution, usually with snapshots you've built yourself. 81.It Cm locate 82Copy things from the base system, perusing the system 83.Xr locate 1 84databases. 85.Bf Sy 86Note that this might erase data, in case it doesn't match the base system 87and is in the way. 88.Ef 89.It Cm resolv 90Copy the system 91.Xr resolv.conf 5 92and 93.Xr hosts 5 94files. 95.It Cm copy_ports 96Copy the ports tree. 97.It Cm copy_sys 98Copy system include files (deprecated). 99.It Cm unpopulate_light 100Remove everything from the chroot apart from selected data. 101See 102.Sx Preserved areas and unpopulate 103for details. 104.It Cm ldconfig 105Rerun 106.Xr ldconfig 8 . 107.It Cm devs 108Regenerate devices using 109.Xr MAKEDEV 8 110and 111.Xr dev_mkdb 8 . 112.It Cm checkout_ports 113Check out a ports tree from cvs using a provided 114.Cm portscvs 115location. 116.It Cm ports_subdirs 117Create ports infrastructure subdirs, according to users required for 118.Xr dpb 1 . 119If 120.Cm chown_all 121is set to 1, 122.Xr chown 2 123any content within to the appropriate users. 124.It Cm stragglers 125Double-check filled up chroot for files we don't know about. 126.It Cm write_mk 127If some values are different from the default, 128write a skeleton 129.Xr mk.conf 5 130file. 131.It Cm check_symlinks 132Report absolute symlinks that exist under the 133.Ar chroot , 134white-listing known base system links. 135.El 136.Pp 137By default, 138.Nm 139will run 140.Cm check_mount , unpopulate_light , devs , ldconfig , ports_subdirs , 141.Cm resolv , write_mk . 142If 143.Cm unpopulate 144is used, 145.Cm unpopulate_light 146won't be run. 147It will also run 148.Cm snapshot 149if a snapshot location is provided, 150or 151.Cm locate 152otherwise. 153.Pp 154Add actions with 155.Cm actions Ns = Ns Ar value , 156remove them with 157.Cm actions Ns =- Ns Ar value . 158.Pp 159Other attributes are: 160.Pp 161.Bl -tag -width mkconf_lines -offset indent -compact 162.It Cm chroot 163same as 164.Fl B Ar chroot 165.It Cm srcroot 166same as 167.Fl S Ar srcroot 168.It Cm PORT_USER 169Who the ports tree should belong to 170.It Cm BUILD_USER 171Who to build as (defaults to _pbuild) 172.It Cm FETCH_USER 173Who to fetch as (defaults to _pfetch) 174.It Cm LOG_USER 175Who to write log as (defaults to 176.Cm BUILD_USER ) 177.It Cm LOGDIR 178Where to write logs (defaults to 179.Pa ${PORTSDIR}/logs ) 180.It Cm PORTSDIR 181.It Cm DISTDIR 182.It Cm PACKAGE_REPOSITORY 183.It Cm PLIST_REPOSITORY 184.It Cm LOCKDIR 185.It Cm WRKOBJDIR 186same as in 187.Xr bsd.port.mk 5 188.Pp 189.It Cm chown_all 190set to 1 to have the action 191.Cm ports_subdirs 192change owners of every content. 193.It Cm extra 194extra file to copy into the 195.Ar chroot . 196.It Cm mkconf_lines 197Add lines to the generated 198.Pa /etc/mk.conf . 199.It Cm mkconf_tail 200Add file to the generated 201.Pa /etc/mk.conf . 202.It Cm preserve 203Supplemental directory to preserve during 204.Cm unpopulate . 205.It Cm sets 206Add or remove sets compared to the default list required to build ports 207(defaults to all sets). 208.It Cm snapshot 209Location of snapshot for the 210.Cm snapshot 211action. 212.It Cm portscvs 213Where to get a ports snapshot for the 214.Cm checkout_ports 215action. 216.El 217.Ss Preserved areas and unpopulate 218The following entries won't be erased during a 219.Cm locate 220or 221.Cm unpopulate* 222action: 223.Pp 224.Bl -dash -compact -offset indent 225.It 226Items explicitly marked with the 227.Cm preserve 228attribute. 229.It 230A 231.Cm snapshot 232directory containing the base sets. 233.It 234All the ports specific sub directories if they are defined, 235namely 236.Cm DISTDIR , WRKOBJDIR , LOGDIR , PACKAGE_REPOSITORY , PLIST_REPOSITORY , 237.Cm LOCKDIR . 238.It 239The 240.Cm PORTSDIR 241itself, unless 242.Cm copy_ports 243is used. 244.It 245Any mount point. 246.It 247Data explicitly copied through other actions, e.g., 248.Cm extra 249files, key files... 250.El 251.Sh EXAMPLES 252The following 253.Ar configfile 254sets things up for an initial build on a 255.Xr dpb 1 256cluster 257.Po 258refer to 259.Xr bulk 8 260for typical setups of such build clusters 261.Pc . 262.Bd -literal -offset index 263chroot=/build 264PORT_USER=espie 265extra=/home/espie/startup 266WRKOBJDIR=/tmp/pobj 267LOCKDIR=/tmp/locks 268PLIST_REPOSITORY=/data/plist 269DISTDIR=/data/distfiles 270PACKAGE_REPOSITORY=/data/packages 271actions=unpopulate_light 272 copy_ports 273.Ed 274.Pp 275It assumes 276.Pa /build/data 277is a separate partition that won't be cleaned up by 278.Cm unpopulate_light , 279and that can be mounted on slaves. 280Note also that 281.Pa /tmp 282should be a fast local directory on every machine of the cluster. 283.Pp 284.Pa /home/espie/startup 285is a startup script for 286.Xr dpb 1 . 287.Pp 288Initial invocation on the master could be 289.Pp 290.D1 Nm Fl c Ar configfile Cm chown_all Ns =1 291.Pp 292to ensure correct permissions for existing data under various 293ports directories. 294.Pp 295Slaves should not need the extra arguments, as the directories will 296already have correct owners. 297.Sh SEE ALSO 298.Xr dpb 1 , 299.Xr bulk 8 , 300.Xr chroot 8 301.Sh AUTHORS 302.An Marc Espie Aq Mt espie@openbsd.org 303