Tuesday, 15. April 2021
[This article has been bi-posted to Gemini and the Web]
In the previous posts of this series, there was an introduction to package building on FreeBSD and we discussed basic Synth usage. The program's configuration, working with compiler cache and using the tool to update the installed applications was covered as well. We also discussed Synth web reports, serving repositories over HTTP and building package sets. We also took a brief look at the logs to find out why some ports failed.
FreeBSD package building pt. 1: Introduction and test system
FreeBSD package building pt. 2: Basic Synth
FreeBSD package building pt. 3: Intermediate Synth
FreeBSD package building pt. 4: (Slightly) Advanced Synth
In this article we are going to sign our package repository, make use of HTTPS and explore make.conf options. We will also add an additional profile to build packages for an obsolete FreeBSD release that is 32-bit and automate package building with cron.
So far we've only considered building basically one local package set (even though we've shared it). If we want to have a single build server manage multiple package sets, we will need a somewhat more complex directory structure to allow for separate repositories and such. Should you be building on a UFS system, it's easy: Just create the additional directories. I'm using ZFS here, though, and need to think if I want to create the whole structure as several datasets or just two single datasets with custom mount? As usually there's pros and cons for both. I'm going with the former here:
# rm -r /var/synth
# zfs create zroot/var/synth
# zfs create zroot/var/synth/www
# zfs create zroot/var/synth/www/log
# zfs create zroot/var/synth/www/log/13.0_amd64
# zfs create zroot/var/synth/www/packages
# zfs create zroot/var/synth/www/packages/13.0_amd64
# synth configure
Now we need to adapt the Synth configuration for the new paths:
_B_ needs to be set to _/var/synth/www/packages/13.0_amd64_ and _E_ to _/var/synth/www/log/13.0_amd64_. Normally I'd create a custom profile for that, but as I'm covering that a little later in this article, we're going to abuse the LiveSystem default profile for now.
Next is re-configuring the webserver:
# vi /usr/local/etc/obhttpd.conf
Remove the _block return_ directive in the _location "/"_ block on the synth.local vhost and replace it with:
directory auto index
Then change the location to "/*". I'm also removing the second location block. Create a new .htpasswd and bring over authentication to the main block if you want to.
# service obhttpd restart
To be able to use signing, we need a key pair available to Synth. Use the _openssl_ command to create a private key, change permissions and then create a public key, too:
# openssl genrsa -out /usr/local/etc/synth/LiveSystem-private.key 2048
# chmod 0400 /usr/local/etc/synth/LiveSystem-private.key
# openssl rsa -pubout -in /usr/local/etc/synth/LiveSystem-private.key -out /usr/local/etc/synth/LiveSystem-public.key
Mind the filenames here! The _LiveSystem_ part refers to the name of the profile we're using. If you want to sign different repositories resulting from various profiles, make sure that you place the two key files for each of the profiles in /usr/local/etc/synth.
While you're at it, consider either generating a self-signed TLS certificate or using Let's Encrypt (if you have own a proper domain). If you opted to use TLS, change the webserver configuration once more to have it serve both the log and the package vhosts via HTTPS. There's an example configuration (_obhttpd.conf.sample_) that comes with obhttpd in case you want to take a look. It covers HTTPS vhosts.
Alright! Since we changed the paths, we don't currently have any repository to sign. Let's build a popular browser now:
# synth build www/firefox
Firefox failed in the configure phase! (PNG)
Firefox failed to build. This is what the log says:
DEBUG: Executing: `/usr/local/bin/cbindgen --version`
DEBUG: /usr/local/bin/cbindgen has version 0.18.0
ERROR: cbindgen version 0.18.0 is too old. At least version 0.19.0 is required.
Please update using 'cargo install cbindgen --force' or running
'./mach bootstrap', after removing the existing executable located at
/usr/local/bin/cbindgen.
===> Script "configure" failed unexpectedly.
Please report the problem to gecko@FreeBSD.org [maintainer] and attach the
"/construction/xports/www/firefox/work/.build/config.log" including the output
of the failure of your make command. Also, it might be a good idea to provide
an overview of all packages installed on your system (e.g. a
/usr/local/sbin/pkg-static info -g -Ea).
*** Error code 1
Stop.
make: stopped in /xports/www/firefox
--------------------------------------------------
-- Termination
--------------------------------------------------
Finished: Friday, 11 JUN 2021 at 03:03:06 UTC
Duration: 00:03:06
Oh well! We've hit a problem in the ports tree. Somebody updated the Firefox port in our branch to a version that requires a newer cbindgen port than is available in the same branch! Breakage like this does happen sometimes (we're all human after all). What to do about it? In our case: Ignore it as it's only an example. Otherwise I'd advise you to update to a newer ports tree as these problems are usually quickly redeemed.
Synth is asking whether it should rebuild the repository. Yes, we want to do that. Then it asks if it should update the system with the newly built packages. And no, not now. Also note: The _synth build_ command that we used here, is _interactive_ and thus not well fit if you want to automate things:
Would you like to rebuild the local repository (Y/N)? y
Stand by, recursively scanning 1 port serially.
Scanning existing packages.
Packages validated, rebuilding local repository.
Local repository successfully rebuilt
Would you like to upgrade your system with the new packages now (Y/N)? n
What else do we have to do to sign the repository? Nothing. Synth has already done that and even changed the local repository configuration to make the package manager verify the signature:
# tail -n 3 /usr/local/etc/pkg/00_synth.conf
signature_type: PUBKEY,
pubkey : /usr/local/etc/synth/LiveSystem-public.key
}
That wasn't so hard now, was it? You might want to know that Synth also supports using a signing server instead of signing locally. If this is something you're interested in, do a _man 1 synth_ and read the appropriate section.
FreeBSD has two main configuration files that affect the compilation process when using the system compiler. The more general one, _/etc/make.conf_ and another one that is only used when building FreeBSD from source: _/etc/src.conf_. Since we're talking about building ports, we can ignore the latter.
There's a manual page, make.conf(5), which describes some of the options that can be put into there. Most of the ones covered there are only relevant for building the system. Do by all means leave things like CFLAGS alone if you don't know what you're doing! Regarding the ports tree, it's most useful to set or unset common options globally. It's very tedious to set all the options for your ports manually like this:
# make -C /usr/ports/sysutils/tmux config-recursive
You need to do this for specific ports that you want to change the options for. But if there's some that you have a global policy for, it's better to use make.conf. Let's say we want to _never_ include documentation and examples in our ports. This would be done by adding the following line to _/etc/make.conf_:
OPTIONS_UNSET+=DOCS EXAMPLES
This affects all ports whether built by Synth or not as well as each and every Synth profile. Let's say we also want no foreign language support in our packages for the default Synth profile (but in all others), we'd create the file _/usr/local/etc/synth/LiveSystem-make.conf_ and put the following in there:
OPTIONS_UNSET+=NLS
That setting will build packages without NLS in addition to building without DOCS and EXAMPLES - if "LiveSystem" is the active profile.
If you want to build all ports that support it with e.g. the DEBUG option, add another line:
OPTION_SET+=DEBUG
Some common options that you might want to use include:
After unsetting DOCS and EXAMPLES globally as well as NLS for the default profile, we're going to rebuild the installed packages next:
# synth prepare-system
Note that Synth only rebuilt the packages that were affected by the changed options either directly or via their dependencies. For that reason only 219 of the 344 packages actually installed were rebuilt. If we now use _pkg upgrade_, this is what happens (see screenshot):
pkg upgrade will free space due to removing docs, examples and nls files (PNG)
Ignore the 3 packages getting updated; this is due to packages that were skipped due to the Rust failure originally. That port has successfully built when we were trying to build Firefox, so our latest package runs built three more packages that have not been updated to, yet.
More interestingly: There's 31 reinstalls. Most of them due to the package manager detecting changed options and one due to a change to a required shared library. It's not hard to do the math and figure out that 31 is quite a bit less than 219. It's a little less obvious that build-time dependencies count towards that greater number while they don't appear in the count of packages that are eventually reinstalled. Still it's true that Synth takes a "better safe than sorry" approach and tends to rebuild some packages that pkg(8) will end up not reinstalling. But this is not much of a problem, especially if you're using ccache.
If you want to use Synth to build more than one specific set of packages for exactly one platform, you can. One way to achive this would be to always change Synth's configuration. But that's tedious and error prone. For that reason _profiles_ exist. They allow you to have multiple different configurations available at the same time. If you're simply running Synth from the command line like we've always done so far, it will use the configuration of the _active profile_.
To show off how powerful this is, we're going to do something a little special: Building 32-bit packages for the no longer supported version of FreeBSD 12.1. Since amd64 CPUs are capable of running i386 programs, this does not even involve emulation. We need to create a couple of new directories first:
# mkdir /var/synth/www/packages/12.1_i386
# mkdir /var/synth/www/log/12.1_i386
# mkdir -p /var/synth/sysroot/12.1_i386
The last one is something that you might or might not be familiar with. A _sysroot_ is a somewhat common term for - well, the root of a system. The sysroot of our running system is /. But we can put the data for other systems somewhere in our filesystem. If we put the base system of 32-bit 12.1-RELEASE into the directory created last, that'll be a sysroot for 12.1 i386. Technically we don't need all of the base system and could cherry-pick. It's easier to simply use the whole thing, though:
# fetch -o /tmp/12.1-i386-base.txz http://ftp-archive.freebsd.org/pub/FreeBSD-Archive/old-releases/i386/12.1-RELEASE/base.txz
# tar -C /var/synth/sysroot/12.1_i386 -xf /tmp/12.1-i386-base.txz
# rm /tmp/12.1-i386-base.txz
# synth configure
Alright. Now we're going to create an additional profile. To do so, press _>_ (greater than key), then chose _2_ (i.e. _Create new profile_) and give it a name like e.g. 12.1-i386. Then change the following three settings:
_B_: /var/synth/www/packages/12.1_i386
_E_: /var/synth/www/log/12.1_i386
_G_: /var/synth/sysroot/12.1_i386
That's all, after you save the configuration you're ready to go. Create a list of packages you want to build and let Synth do it's thing:
# synth just-build /var/synth/pkglist.12.1_i386
The build will fail almost immediately. Why? Let's take a look. Building pkg(8) failed and here's why:
--------------------------------------------------------------------------------
-- Phase: check-sanity
--------------------------------------------------------------------------------
/!\ ERROR: /!\
Ports Collection support for your FreeBSD version has ended, and no ports are
guaranteed to build on this system. Please upgrade to a supported release.
No support will be provided if you silence this message by defining
ALLOW_UNSUPPORTED_SYSTEM.
*** Error code 1
Stop.
make: stopped in /xports/ports-mgmt/pkg
Ok, since we're trying to build for a system that's not supported anymore, the ports infrastructure warns us about that. We have to tell it to ignore that. How do we do that? You might have guessed: By using a make.conf for the profile we're using for this set of packages:
# echo ALLOW_UNSUPPORTED_SYSTEM=1 > /usr/local/etc/synth/12.1-i386-make.conf
Then try again to build the set - and it will just work.
Successfully built all the packages using the i386 profile (PNG)
Last but not least let's put everything we've done so far together to automate building two package sets. We can make use of cron(8) to schedule the tasks. Let's add the first one to _/etc/crontab_ like this:
0 23 * * 7 root env TERM=dumb /usr/local/bin/synth just-build /var/synth/pkglist-12.1-i386
What does it do? It will run synth at 11pm every sunday to build all of the packages defined in the package list referenced there. There's two things to note here:
1) You need to disable curses mode in all the profiles you're going to use. Synth still expects to find the TERM environment variable to figure out the terminal's capabilities. You can set it to _dumb_ as done here or to _xterm_ or other valid values. If you don't set it at all, Synth will not run.
2) The cron entry as we're using it here will use the _active profile_ for Synth. It's better to explicitly state which profile should be used. Let's add another line to crontab for building the amd64 packages for 13.0 on Friday night:
0 23 * * 5 root env TERM=dumb SYNTHPROFILE=LiveSystem /usr/local/bin/synth just-build /var/synth/pkglist-13.0-amd64
In general I'd recommend to consider not calling synth directly from cron but to write small scripts instead. You could for example backup the current package set before actually starting the new build or you could snapshot the dataset after the successful build and zfs-send it off to another system.
One thing that you should be aware of is that Synth provides hooks like _hook_run_start_, _hook_run_end_, _hook_pkg_failure_ and so on. If you're considering using hooks, have a look at the Synth manpage, they are covered well there.
Next topic would be covering Poudriere. However I'm considering taking a little break from package building and writing about something else instead before returning to this topic.
