[howtos] Add some instructions regarding ABI changes #5

Merged
meena merged 2 commits from evilham/pkgbase-website:main into main 5 months ago
  1. 2
      Makefile
  2. 68
      howto/abi-changes.html
  3. 12
      howto/bootstrap.md
  4. 1
      howto/index.md

2
Makefile

@ -4,7 +4,7 @@ website: howtos pkg-sets
tidy -quiet -mi --indent-spaces 4 --wrap 111 index.html
howtos:
.for f in index bootstrap jails fresh howdo
.for f in index bootstrap jails fresh howdo abi-changes
pandoc --template template.html --css /style.css \
-f markdown -t html < howto/${f}.md > howto/${f}.html
tidy -quiet -mi --indent-spaces 4 --wrap 111 howto/${f}.html

68
howto/abi-changes.html

@ -0,0 +1,68 @@
---
title: "Howto: Performing release upgrades"
author: Evilham
lang: en
---
After we [bootstrap `pkgbase`](/howto/bootstrap.html), we may want to change the FreeBSD version we are running.
As before any major change to the system, we'll use [`bectl(8)`](https://man.freebsd.org/bectl(8)) first, check the [how to bootstrap `pkgbase`](/howto/bootstrap.html) page for an in-depth explanation.
If instead of using `"https://alpha.pkgbase.live/release/${ABI}/latest"` as the [`pkg(8)`](https://man.freebsd.org/pkg(8)) repository we hardcode the `ABI` (for example by using `FreeBSD:13:amd64` instead of `${ABI}`), we may get an error like:
```
# pkg update -r FreeBSD-base
Updating FreeBSD-base repository catalogue...
evilham marked this conversation as resolved
Review

please stick to the existing link style of using inline links

this breaks the reading flow of the markdown document

so if you want to introduce them, they need to all go at the end of a section or the end of the document

please stick to the existing link style of using inline links this breaks the reading flow of the markdown document so if you want to introduce them, they need to all go at the end of a section or the end of the document
Fetching meta.conf: 100% 163 B 0.2kB/s 00:01
Fetching packagesite.txz: 100% 66 KiB 67.1kB/s 00:01
Processing entries: 0%
pkg: wrong architecture: FreeBSD:13:* instead of FreeBSD:12:amd64
pkg: repository FreeBSD-base contains packages with wrong ABI: FreeBSD:13:*
Processing entries: 100%
Unable to update repository FreeBSD-base
Error updating repositories!
```
## Forcing the `ABI` value
Instead of hardcoding the value for `ABI`, we are better off instructing `pkg(8)` to use a different `ABI` by defining its `ABI` environment variable as follows (this is documented in [`pkg.conf(5)`](https://man.freebsd.org/pkg.conf(5)) under `VARIABLES`):
```
# env ABI=FreeBSD:13:amd64 pkg update -r FreeBSD-base
```
This will enable us to upgrade to a different FreeBSD version.
For example, to upgrade from 12.1-RELEASE to 13.0-RELEASE, we can run:
```
# env ABI=FreeBSD:13:amd64 pkg upgrade -r FreeBSD-base
```
## Switching from RELEASE to CURRENT
Note that if we are switching from a RELEASE version to a CURRENT version, we also have to change the repository's URL to reflect that, that is:
```
# FreeBSD pkgbase repo
FreeBSD-base: {
url: "https://alpha.pkgbase.live/current/${ABI}/latest",
signature_type: "pubkey",
pubkey: "/usr/share/keys/pkg/trusted/alpha.pkgbase.live.pub",
enabled: yes
}
```
Notice the `current` instead of `release` in the URL field.
## Safety net
Remember that with Boot Environments you can safely go back to a RELEASE version of the OS and that Boot Environments are now even selectable from the bootloader.
## Other considerations
This method might support system downgrades, though that's not officially supported!
It would be an interesting thing to test, of course always in a testing machine.
Once `pkgbase` is better tested and supported, it might be worth it to consider what some kind of compatibility with the [`freebsd-update(8)`](https://man.freebsd.org/freebsd-update(8)) command would look like.

12
howto/bootstrap.md

@ -13,7 +13,7 @@ To make our lives easier, we can set up the repository as described on the [fron
Another way to make our lives easier is to create a `-r`ecursive boot environment:
```
~ $ sudo bectl create -r PkgBase
~ $ sudo bectl create -r PkgBase
```
## Setup
@ -36,7 +36,7 @@ We are now ready to bootstrap:
# pkg install -r FreeBSD-base -g 'FreeBSD-*'
```
– this `-g`lob-matches and installs all packages in the `FreeBSD-base` repo with names that begin with `FreeBSD-`.
– this `-g`lob-matches and installs all packages in the `FreeBSD-base` repo with names that begin with `FreeBSD-`.
Then we need to:
@ -52,7 +52,7 @@ FreeBSD-kernel-minimal-13.0.a2.20210123174755 FreeBSD MINIMAL kernel
FreeBSD-kernel-minimal-dbg-13.0.a2.20210123174755 FreeBSD MINIMAL kernel -dbg
```
The `generic` kernel is the default kernel. We can either:
The `generic` kernel is the default kernel. We can either:
* decide which kernel to keep, and `pkg-remove(8)` all others; or
* leave them all installed and choose with the bootloader.
@ -113,7 +113,7 @@ You can now `exit` the jail.
## UEFI
If your computer has UEFI, there is one more step before you reboot to fully experience all the new goodies. You must copy the new `loader.efi` to the EFI partition.
If your computer has UEFI, there is one more step before you reboot to fully experience all the new goodies. You must copy the new `loader.efi` to the EFI partition.
First, find it:
@ -142,3 +142,7 @@ Now we can:
```
– and reboot.
## See also
- [Performing release upgrades](/howto/abi-changes.html)

1
howto/index.md

@ -9,6 +9,7 @@ This howto is a focused extract from the [FreeBSD wiki on PkgBase](https://wiki.
Due to its size, we'll split this howto into three parts:
- [Bootstrapping an Existing Installation](/howto/bootstrap.html)
- [Performing release upgrades](/howto/abi-changes.html)
- [Setting up Jails](/howto/jails.html)
- [Setting up a Fresh Install](/howto/fresh.html)

Loading…
Cancel
Save