Operations grimoire/FreeBSD

FreeBSD is the most deployed OS on Nasqueron servers.

General tips

• Directories adheres to UNIX hierarchy:
  • Applications use /usr/local/etc for configuration
  • More generally, if an application on Linux uses /usr/..., on FreeBSD it will generally be /usr/local/...
• BSD userland is different than Linux userland, but GNU coreutils is available, with g as prefix. For example, you can use gsed -i for inline sed replacement
• Use GNU Makefile (gmake) if something is wrong with make

You can ask Dereckson for any question about FreeBSD.

Ports

Some packages need to be built through ports.

On some roles, this process is automated by Salt:

• rOPS: roles/dbserver-pgsql/server/build.sls for PostgreSQL with XML support (required by Orbeon)
• rOPS: roles/devserver/userland-software/ports.sls for the list defined in rOPS: pillar/devserver/ports.sls

In other cases, for example when there is a conflict of versions, it's handled manually.

For example, as of 2023-05-30, the PDO extension in packages is built against PostgreSQL 13 while we use PostgreSQL 15.

Good to know. We maintain a package repository to put our own packages.

Example of upgrade

The general process is to go to the port directory, build it and install it. To avoid any reinstallation with wrong parameters, you can lock it.

To use the previous example:

   $ portsnap fetch update
   $ cd /usr/ports/databases/php82-pdo_pgsql
   $ pkg unlock php82-pdo_pgsql
   $ make clean build package deinstall reinstall
   $ pkg lock php82-pdo_pgsql

List locked packges

   $ pkg lock -l

Salt bootstrap

rOPS: utils/bootstrap/hello-FreeBSD.sh can be used to install Salt and connect to Complector.

Upgrade OS

You can use the freebsd-update utility:

   $ freebsd-update fetch
   […]
   No updates needed to update system to 13.2-RELEASE-p0.

For upgrade to a new version:

   $ freebsd-update upgrade -r 14.0-RELEASE

See also Updating and Upgrading FreeBSD in FreeBSD handbook.

At the end:

• Regenerate /etc/os-release content with service os-release restart
• Run needed Salt units (see below)

Salt units to run

php-fpm

When you upgrade packages, if php-fpm (php package) is touched, run:

   $ salt-call --local state.apply roles/webserver-alkane/php/service

If you are invited to upgrade the ZFS pool, please follow instructions form Operations_grimoire/ZFS.

PostgreSQL

PostgreSQL requires XML support for Orbeon, see T1888, so the package should be run again.

We need a lot of things to rebuild the package:

• An up-to-date ports tree
• To unlock the previous package
• To clean the build to avoid artefacts from previous version
• Rebuild the package
• Check no library is missing (see "an up-to-date ports tree")
• Install it
• Restart the service

If the ports tree would have been up-to-date, that could work:

  $ salt -G "roles:dbserver-pgsql" cmd.run "pkg unlock --yes postgresql15-server"
  $ salt -G "roles:dbserver-pgsql" cmd.run "sh -c 'cd /usr/ports/databases/postgresql15-server && make clean'"
  $ salt -G "roles:dbserver-pgsql" cmd.run "rm /usr/local/bin/postgres"
  $ salt -G "roles:dbserver-pgsql" state.apply roles/dbserver-pgsql/server/build
  $ salt -G "roles:dbserver-pgsql" service.restart postgresql

This assumes rOPS: roles/dbserver-pgsql/server/build.sls still uses postgresql15 as version, check that first.

It's safe to remove the old postgres process, as it's currently loaded in RAM. Also, if the file exists, postgresql_build_port will.

When the procedure was tested, we had a PostgreSQL against old library:

   ld-elf.so.1: Shared object "libicui18n.so.72" not found, required by "postgres"

Here the manual procedure to follow if portsnap is missing:

   $ pkg install portsnap
   $ portsnap fetch
   $ mv /usr/ports /usr/ports.delme # too much files to delete it right now
   $ portsnap extract

If /usr/ports is a ZFS volume in the arcology pool:

  $ mv /usr/ports /usr/ports.delme
  mv: rename ports to ports.delme: Operation not supported
  $ umount -f /usr/ports
  $ zfs destroy arcology/usr/ports
  $ zfs create arcology/usr/ports
  $ zfs set mountpoint=/usr/ports arcology/usr/ports
  $ zfs mount arcology/usr/ports
  cannot mount 'arcology/usr/ports': filesystem already mounted
  $ portsnap extract

If portsnap is present:

   $ portsnap fetch update

Then you can rebuild:

   $ cd /usr/ports/databases/postgresql15-server
   $ make depends
   ===>   postgresql15-server-15.5_4 depends on file: /usr/local/sbin/pkg - found
   ===>   postgresql15-server-15.5_4 depends on shared library: libicudata.so - found (/usr/local/lib/libicudata.so)
   ===>   postgresql15-server-15.5_4 depends on shared library: liblz4.so - found (/usr/local/lib/liblz4.so)
   ===>   postgresql15-server-15.5_4 depends on shared library: libxml2.so - found (/usr/local/lib/libxml2.so)
   ===>   postgresql15-server-15.5_4 depends on shared library: libzstd.so - found (/usr/local/lib/libzstd.so)
   ===>   postgresql15-server-15.5_4 depends on shared library: libpq.so.5 - found (/usr/local/lib/libpq.so.5)
   ===>   postgresql15-server-15.5_4 depends on shared library: libLLVM-15.so - found (/usr/local/llvm15/lib/libLLVM-15.so)
   ===>   postgresql15-server-15.5_4 depends on shared library: libintl.so - found (/usr/local/lib/libintl.so)
   ===>   postgresql15-server-15.5_4 depends on package: gmake>=4.3 - found
   ===>   postgresql15-server-15.5_4 depends on package: pkgconf>=1.3.0_1 - found
   ===>   postgresql15-server-15.5_4 depends on package: gettext-runtime>=0.22_1 - found
   ===>   postgresql15-server-15.5_4 depends on executable: msgfmt - found
   $ pkg unlock --yes postgresql15-server
   $ make build package deinstall reinstall
   $ pkg lock --yes postgresql15-server