- Things to know ......................................................... [000]
- Creating a disk ........................................................ [001]
- Extracting necessary files ............................................. [010]
- Creating device files .................................................. [011]
- Setting DNS ............................................................ [012]
- Dynamic linker hints file creation ..................................... [013]
- Password database and group file creation .............................. [014]
- Entering the chroot .................................................... [020]

[000] Things to know -----------------------------------------------------------
To start off with, I'd like to thank Karsten Pedersen for posting "Creating a
Chroot In OpenBSD" on IBM's DeveloperWorks platform, as this post is based on
it.

Since I usually use the entire disk when installing OpenBSD, I'll be using a
disk image to put the chroot on. If you want to resize your partitions, have a
spare disk, or are installing a new system, then you can create a partition just
for your chroots. If you do this, mount it and skip to -[010].

This guide was originally made for OpenBSD 7.8, but I will try to update it as
necessary.

[001] Creating a disk ----------------------------------------------------------
Determine what mounts are free enough for your disk drive with df -h. My
/home mount was the most free place that I felt would be appropriate to
place the disk image. Change directory to that place, and create the raw disk
dd if=/dev/zero of=disk.img bs=1M count=<N>. Then configure it as a device
file vnconfig disk.img. Since I won't be using this disk for anything else,
I'm just going to create the filesystem without creating an MBR/GPT or disklabel
newfs vnd0c. Now mount it where your chroots will be stored, /jails is
what I chose mount /dev/vnd0c /jails.

If necessary, now is a good time to automatically mount the image. Add the
following to your /etc/fstab
/home/disk.img /dev/vnd0c vnd rw 0 0
/dev/vnd0c /jails ffs rw 0 0

If the wxallowed option is necessary for a certain program, it should tell
you to remount the necessary filesystems with that, in which case you can simply
change that last line to rw,wxallowed instead of rw.

[010] Extracting necessary files -----------------------------------------------
If you still have the installer around, and you used an installXX.* image, then
you should vnconfig it, mount the appropriate partition from it, and use
that install set. If not, download (https://ftp.openbsd.org/pub/OpenBSD/)
the file sets.

Create your new chroot jail mkdir /jails/a && cd $_.

Extract all of them, or select the ones you want.
for i in /path/to/sets/*.tgz; do
  tar xzf $i
done

[011] Creating device files ----------------------------------------------------
This is fairly simple. Programs need /dev/stdin and such, so create them
cd dev
./MAKEDEV all
cd ..


[012] Setting DNS --------------------------------------------------------------
Again, simple cp /etc/resolv.conf etc. You can configure this manually if
desired.

[013] Dynamic linker hints file creation ---------------------------------------
The dynamic linker will only load shared libraries that are listed in
/var/run/ld.so.hints for SUID/SGID programs, so create it with
chroot /jails/a ldconfig /usr/lib /usr/X11R6/lib.

[014] Password database and group file creation --------------------------------
Modern OpenBSD uses a Berkeley Database for the passwd entries, and so the
database needs to be generated. But we have no passwd file! That's fine, create
one manually or copy it from the source tree, or your host system. In the source
tree it is called master.passwd. Then make the database
chroot /jails/a pwd_mkdb /etc/passwd.

[020] Entering the chroot ------------------------------------------------------
As normal, just chroot /jails/a. If you want a "real" shell environment, use
chroot /jails/a su -l, or env to control environment variables.

Written on 14/01/2026 17:02 UTC-6