View source for 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 {{u|Dereckson}} for any question about FreeBSD.

== Ports ==
Some packages need to be built through ports.

On some roles, this process is automated by Salt:
* {{Ops file|roles/dbserver-pgsql/server/build.sls}} for PostgreSQL with XML support (required by Orbeon)
* {{Ops file|roles/devserver/userland-software/ports.sls}} for the list defined in {{Ops file|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 ==
{{Ops file|utils/bootstrap/hello-FreeBSD.sh}} can be used to install Salt and connect to Complector.

== Upgrade OS ==
You can use the <code>freebsd-update</code> 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 [https://docs.freebsd.org/en/books/handbook/cutting-edge/ Updating and Upgrading FreeBSD] in FreeBSD handbook.

At the end:

* Regenerate /etc/os-release content with <code>service os-release restart</code>
* 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 {{T|1888}}, 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 {{Ops file|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 <code>arcology</code> 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