Skip to content

CheriBSD: offline package mirroring

Jump to bottom
Konrad Witaszczyk edited this page Apr 24, 2026 · 15 revisions

The CHERI project provides Morello packages built from the CheriBSD ports collection on pkg.CheriBSD.org. This works well enough of most cases, but sometimes a Morello box can't be connected to the Internet and needs packages. This page describes how to create and use offline mirrors of packages as well as describing how to install the packages the CheriBSD installer would provide if they were available. You can follow the steps to create the mirrors on FreeBSD, Linux or macOS.

The pkg tool

FreeBSD packages are managed by a tool called "pkg". You can use pkg on FreeBSD, Linux or macOS to manage offline packages or install them in a rootfs directory of cross-compiled CheriBSD. In addition to managing the installation of packages from a repository, it contains the tools to construct package repositories and to mirror sets of packages from another repository. If you are not downloading from a CheriBSD system, you must use pkg 2.7.4 or newer (latest releases). You can build the latest version it as follows:

$ git clone https://github.com/freebsd/pkg.git
$ cd pkg
$ git checkout 2.7.4
$ ./configure
Host System...x86_64-pc-linux-gnu
Build System...x86_64-pc-linux-gnu
C compiler...ccache cc  
C++ compiler...ccache c++  
Build C compiler...cc
Checking for stdlib.h...ok
<...>
$ make
<...>
make[1]: Leaving directory '/local/scratch/bed22/pkg/scripts'
$

You can install the package with make install or simply use the binary in place in src/pkg.

Available packages

You can find information about available packages in the Getting Started with CheriBSD guide.

The following packages may be of particular interest to offline users:

  • aarch64c (managed by pkg64c)
    • cheri-desktop - Meta package which installs the main desktop
    • cheri-vm-support - Supporting bits for the bhyve VM
  • aarch64 (managed by pkg64)
    • cheri-desktop-hybrid-extras - Meta package which installs desktop bits that aren't ported to CHERI yet

The desktop installation step in the installer installs both cheri-desktop and cheri-desktop-hybrid-extras. It also prompts to add users to the video group. You must do this or no one will be able to log in to the GUI.

The VM support installation step installs cheri-vm-support.

Note that in is essential that your package repository contain the pkg package as the base system contains only a small wrapper for the purpose of bootstrapping the pkg tool.

Fetching packages on an external host

First, create a working directory and change into it (you will be creating configuration, repository, and database directories here).

Create a repos directory and add a CheriBSD.conf with the following contents:

CheriBSD: {
  url: "http://pkg.CheriBSD.org/${ABI}",
  mirror_type: "none",
# If desired, you can grab the contents of /usr/share/keys/pkg on a Morello box
# and update the fingerprints: line and uncomment these if you want to verify
# signatures.
#  signature_type: "fingerprints",
#  fingerprints: "/usr/share/keys/pkg",
  enabled: yes,
  priority: 1
}

In the examples below the ABI string appears twice on the command line. Once to set the ABI variable (overriding the system ABI) and once for the repository directory. You can find the value of ABI corresponding to your CheriBSD version at pkg.CheriBSD.org (e.g., CheriBSD:20250301:aarch64c and CheriBSD:20250301:aarch64 for pkg64c and pkg64 package managers, respectively, on the 25.03 release). Alternatively, you can execute the following command on your CheriBSD host to read the date part of ABI and later use it in the ABI strings CheriBSD:<date>:aarch64c and CheriBSD:<date>:aarch64:

$ grep '^#define __CheriBSD_version' /usr/include/sys/param.h
#define __CheriBSD_version 20250301

A package repository must always include a package for the pkg package manager itself. To download pure-capability versions of pkg and sudo, run the following command on the external host connected to the Internet:

../pkg/src/pkg -R repos/ \
    -o ABI=CheriBSD:20250301:aarch64c \
    -o INSTALL_AS_USER=yes \
    -o PKG_DBDIR=`pwd`/db64c \
    fetch -y -o CheriBSD:20250301:aarch64c -d pkg sudo

Example output:

Updating CheriBSD repository catalogue...
CheriBSD repository is up to date.
All repositories are up to date.
The following packages will be fetched:

New packages to be FETCHED:
        pkg: 1.20.5_1 (9 MiB: 93.38% of the 9 MiB to download)
        sudo: 1.9.14p3 (622 KiB: 6.62% of the 9 MiB to download)

Number of packages to be fetched: 2

The process will require 9 MiB more space.
9 MiB to be downloaded.
Fetching pkg-1.20.5_1: 100%  8774 KiB   9.0 MB/s    00:01    
Fetching sudo-1.9.14p3: 100%   622 KiB 636.7 kB/s    00:01

Likewise, to download the pkg and toolchain packages run:

../pkg/src/pkg -R repos/ \
    -o ABI=CheriBSD:20250301:aarch64 \
    -o INSTALL_AS_USER=yes \
    -o PKG_DBDIR=`pwd`/db64 \
    fetch -y -o CheriBSD:20250301:aarch64 -d pkg llvm-base

Example output:

Updating CheriBSD repository catalogue...
CheriBSD repository is up to date.
All repositories are up to date.
The following packages will be fetched:

New packages to be FETCHED:
        llvm: 17,1 (11 KiB: 0.01% of the 125 MiB to download)
        llvm-base: 20240315 (1 KiB: 0.00% of the 125 MiB to download)
        llvm-morello: 17.0.d20260205_3 (116 MiB: 92.97% of the 125 MiB to download)
        pkg: 1.20.5_1 (9 MiB: 7.02% of the 125 MiB to download)

Number of packages to be fetched: 4

The process will require 125 MiB more space.
125 MiB to be downloaded.
Fetching pkg-1.20.5_1: 100%  8961 KiB   9.2 MB/s    00:01    
Fetching llvm-base-20240315: 100%    1056 B   1.1 kB/s    00:01    
Fetching llvm-morello-17.0.d20260205_3: 100%   116 MiB 121.5 MB/s    00:01    
Fetching llvm-17,1: 100%    11 KiB  11.7 kB/s    00:01

Note that it is possible to fetch all available packages by replacing the list of packages with -a, but this is 6GiB for pure-capability packages and 67GiB for hybrid packages.

Repo metadata and bootstrapping

Before you transfer your newly downloaded packages to your disconnected host, you will need to create or update package metadata and add a symlink to the pkg package so the bootstrapping process can find it. For the first part, run the pkg repo command on the repository directory:

$ ../pkg/src/pkg repo CheriBSD\:20250301\:aarch64

Which will produce output like:

Creating repository in CheriBSD:20250301:aarch64: 100%
Packing files for repository: 100%

For the second part, examine the All directory in the repository for the latest package, currently pkg-1.20.5_1.pkg then create a directory and symlink as follows:

mkdir -p CheriBSD\:20250301\:aarch64/Latest
ln -s ../All/pkg-1.20.5_1.pkg CheriBSD\:20250301\:aarch64/Latest/pkg.pkg

Do the above for both repositories.

Using the downloaded packages on CheriBSD/Morello

To use the packages, copy the two repo directories to the Morello system and put them somewhere. In the example below they are in /var/pkg.

Next create the directories /usr/local/etc/pkg/repos and /usr/local64/etc/pkg/repos and create files /usr/local/etc/pkg/repos/CheriBSD-local.conf, /usr/local64/etc/pkg/repos/CheriBSD-local.conf in them with the following contents:

CheriBSD-local: {
  url: "file:///var/pkg/${ABI}",
  mirror_type: "none",
  enabled: yes,
  priority: 1
}
CheriBSD: { enabled: no }

This enables the local repositories and disables the remote ones. If typing by hand, note that the syntax is quite fussy. For example yes must not be quoted and file:///... requires three / characters in a row after file: the package bootstrapping process will eat the first path component.

You can now use pkg64 and pkg64c as usual.

Clone this wiki locally