Page MenuHomeFreeBSD
Differential D57517

15.1: Installation note -> Upgrading note
ClosedPublic
Actions

Authored by ziaee on Wed, Jun 10, 4:58 AM.
Tags
None
Referenced Files
F160347845: D57517.id179699.diff
Tue, Jun 23, 1:24 PM
F160347180: D57517.id179699.diff
Tue, Jun 23, 1:16 PM
F160346689: D57517.id179543.diff
Tue, Jun 23, 1:09 PM
F160346506: D57517.id179545.diff
Tue, Jun 23, 1:06 PM
F160346244: D57517.id179545.diff
Tue, Jun 23, 1:03 PM
F160344358: D57517.id179546.diff
Tue, Jun 23, 12:32 PM
F160343959: D57517.id179546.diff
Tue, Jun 23, 12:27 PM
F160339426: D57517.id179550.diff
Tue, Jun 23, 11:17 AM
View All Files
Subscribers
cperciva
dch
emaste
fuz
michaelo
vladlen

Details

Reviewers
carlavilla
michaelo
dch
Group Reviewers
releng
docs
Commits
R9:63927b02bb47: 15.1: Installation note -> Upgrading note
Summary

The installation note does not contain installation instructions, and
has not since FreeBSD 6.0. Rename it to the upgrading note to avoid
confusion with the installation guide. Consolidate all release upgrading
information here.

Rewrite the introduction to the release note to separate these out more.
Remove information that is not needed to introduce this release.
The release installation notes do not actually contain instructions on
installing FreeBSD, so rename it to the Upgrading Note.

I used Vladlen's previous diff where he invented the pkgbase info, boot
loader info, and the concept of numbering, which is the icing that ties
this together. His diff is located at https://reviews.freebsd.org/D57421

Co-authored-by: Vladlen Popolitov <vladlen@FreeBSD.org>

Test Plan

The proposed 15.1R/upgrading in this draft is rendered at:

https://people.freebsd.org/~ziaee/tmp/draft.html

Diff Detail

Repository
R9 FreeBSD doc repository
Lint
Lint Skipped
Unit
Tests Skipped
Build Status
Buildable 73899
Build 70782: arc lint + arc unit

Event Timeline

There are a very large number of changes, so older changes are hidden. Show Older Changes
ziaee added inline comments.Thu, Jun 11, 2:35 PM
website/content/en/releases/15.1R/upgrading.adoc
39

i took a crack at it, take a look

80

fixed thanks

92

i took a crack at it, take a look

142

+1

166

ok, i took a crack at it, let me know

224

i dont want to do that because that is a routine corner case. file system could always be too small for upgrade. if you try to copy the files but you dont have enough space, that's on you and you have to do take action depending on reasoning at that point.

what i do think we need to know and put in this document in the introduction is how much free space they need to have.

251

fixed thanks

258

fixed thanks

308

i dont want to do that because that equates to "if your system is different you need to act accordingly", which is, adding a lot of text that doesn't say anything. it's important to keep the text down. this is a massive document with conditional branching and it's really a bear.

a more common case is if youre using ipfw you need to disable it before reinstalling, but ipfw users are supposed to know that

like, we wouldn't say what they need to use if they're using 3rd party rc like ghostbsd. then their service units are different.

emaste added a comment.Thu, Jun 11, 3:09 PM

looks good

website/content/en/releases/15.1R/upgrading.adoc
39–40

I think src updates are a third case, so we ought to mention

  • src
  • dist sets + freebsd-update
  • pkgbase
ziaee added inline comments.Thu, Jun 11, 3:37 PM
website/content/en/releases/15.1R/relnotes.adoc
41

oops, i forgot this, this is a good catch and i will put it in, thank you

website/content/en/releases/15.1R/upgrading.adoc
39–40

wdym?

emaste added inline comments.Thu, Jun 11, 3:53 PM
website/content/en/releases/15.1R/upgrading.adoc
39–40

Right now it says there are two cases (dist, pkgbase) and you can use src for either case. I'd position it more as src is a third case.

michaelo requested changes to this revision.Thu, Jun 11, 5:27 PM
michaelo added inline comments.
website/content/en/releases/15.1R/upgrading.adoc
46

Why releng/ only? I used stable/ for the past 10+ years and it always worked in regards to major upgrades.

95

Attention: This has bit be once on release jails and I learned through pain that misc/compat14x might be required when coming from 14. In bad cases it can render software in /usr/local/ as unusable.

My notes when upgrading from 12 to 13 (same applies for newer ones):
• Upgrade from source will retain old libs from 12 (see misc/compat12x: https://github.com/freebsd/freebsd-ports/blob/main/misc/compat12x/pkg-plist.amd64). Ports are still linked against them. One must not clean up the system until ports are built against 13.
• Upgrade will remove old libs from 12. Ports are still linked against them. One must install misc/compat12x

I really would like to see mentioning of compat package.

129

Though there is %F for this, a name would make more sense since creation time of the snapshot is always listed with bectl list and somewhat redudant. E.g., bectl create -r before-151-upgrade, bectl create -r before-{releaseCurrent}-upgrade or something similar.

161

typo

212

This completely misses the issue I complained about in https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=295997 and https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=294338: It should be imperative to mount *all* ESPs and update all boot loaders to be on the safe side not just one.

224

I concur because this is a special case. The FS size is reported as like enough by gpart, but at the end it is tiny.
From an affected system:

root@deblndw011x:~
# gpart show
=>       40  585871888  da0  GPT  (279G)
         40     409600    1  efi  (200M)
root@deblndw011x:~
# df -h /mnt/
Filesystem    Size    Used   Avail Capacity  Mounted on
/dev/da0p1    779K    649K    130K    83%    /mnt
225

On an older system there is not entry explicitly for FreeBSD:

root@deblndw011x:~
# tree /mnt/
/mnt/
└── efi
    └── boot
        ├── BOOTx64.efi
        └── startup.nsh

3 directories, 2 files

The instructions should put this into account and say that this can be skipped of not present.

251

Should also mention that it could be CSM on UEFI, not necessarily an old system with BIOS only. I have several of these because the storage controllers only provide legacy OpROMs and not UEFI OpROMs.

257

Same as above for multiple freebsd-boot partitions.

272

ada0 in backticks?

285

Good start, maybe this should come earlier with gpart show...

This revision now requires changes to proceed.Thu, Jun 11, 5:27 PM
vladlen added inline comments.Thu, Jun 11, 6:15 PM
website/content/en/releases/15.1R/upgrading.adoc
46

Why releng/ only? I used stable/ for the past 10+ years and it always worked in regards to major upgrades.

I suppose this is instruction for specific release and it explain how to upgrade
to this release including the latest SA and EN issued after release date.
It is built from releng/{localRel} branch, that is almost frozen (except
new SA and EN during support time).

stable/ branch is similar, but not the same.

224

This case apeared, because FreeBSD before 13R created big standard EFI partition and then created FAT12 filesystem on it with tiny size (I do not remember details, it is like copied image of this small filesystem, It is like old small diskette image). Many production systems upgraded main OS but never touched EFI filesystem, because it just worked. But loader.efi grew bigger and bigger (includes lua engine now). It could fire on other production servers as soon as we recomvend upgrade the loader in all supported versions due last fixes.

ziaee updated this revision to Diff 179699.Sun, Jun 14, 1:18 AM

address most feedback, note there is still more feedback i intend to address and this is still not perfect

Harbormaster completed remote builds in B73856: Diff 179699.Sun, Jun 14, 1:19 AM
dch requested changes to this revision.Sun, Jun 14, 11:27 AM
dch added a subscriber: dch.

Modulo the OSVERSION footgun this is great, and a lot of fantastic improvements!

website/content/en/releases/15.1R/upgrading.adoc
144

This *must* be altered before shipping.

  1. Can somebody confirm if we require people to upgrade to latest patch version of their existing pkg base system before proceeding?
  1. the command above will just do (1) and not move you to 15.1. For that we need the kludgy incantation:
# pkg -oABI=FreeBSD:15:$(uname -p) -oOSVERSION=1501000 upgrade -r FreeBSD-base

We should probably add a warning:

If you have configured custom package repositories in /usr/local/etc/pkg/repos/ ensure that they do not conflict with the FreeBSD-base and FreeBSD-ports-kmods repositories, as they are required for the upgrade.

Users can check this via:

# pkg -oABI=FreeBSD:15:$(uname -p) -oOSVERSION=1501000 repos -e |grep FreeBSD:15
...
    url             : "pkg+https://pkg.FreeBSD.org/FreeBSD:15:amd64/kmods_latest_1",
    url             : "pkg+https://pkg.FreeBSD.org/FreeBSD:15:amd64/base_release_1",

obviously other arches with not have amd64 there.

This revision now requires changes to proceed.Sun, Jun 14, 11:27 AM
dch added inline comments.Sun, Jun 14, 11:37 AM
website/content/en/releases/15.1R/upgrading.adoc
157

ditto for the kmods:

# pkg -oABI=FreeBSD:15:$(uname -p) -oOSVERSION=1501000 upgrade -r FreeBSD-ports-kmods
176

only applies to amd64 and maybe i386 systems? Good question for irc.

won't work on aarch64 and no idea what it does on the esoteric arches.

michaelo added a comment.Sun, Jun 14, 5:51 PM

This is much better, though, there are still issues left I have commented before.

website/content/en/releases/15.1R/upgrading.adoc
46

I see, this makes sense if wer are talking about RELEASE only.

vladlen added inline comments.Sun, Jun 14, 7:02 PM
website/content/en/releases/15.1R/upgrading.adoc
144

This *must* be altered before shipping.

  1. Can somebody confirm if we require people to upgrade to latest patch version of their existing pkg base system before proceeding?
  1. the command above will just do (1) and not move you to 15.1. For that we need the kludgy incantation:
# pkg -oABI=FreeBSD:15:$(uname -p) -oOSVERSION=1501000 upgrade -r FreeBSD-base

I tested this command in 15.0-RELEASE and 15.0-RELEASE-p10 - both versions make a direct update to 15.1 by this command. It is what I looked for. It must go into the text.

pkg upgrade -r FreeBSD-ports-kmods does not require ABI and OSVERSION options, pkg already has been updated to 15.1 in the previous step and it defaults to 15.1 .

ziaee added inline comments.Mon, Jun 15, 10:30 AM
website/content/en/releases/15.1R/upgrading.adoc
46

correct, these instructions are specifically for upgrading to 15.1, but we will need to massage these words further to improve the template, maybe after the release.

129

great idea, fixed thanks

144

thank you so much. this is the biggest piece vladlen and I were looking for and didn't know. with the deadline pushing i was starting to get concerned :P

176

ah, excellent point. I didn't think of that. I'll work something in, but please review it carefully; it's basically my knowledge of hearsay, I've only ever had (working) x86 systems.

ziaee updated this revision to Diff 179822.Mon, Jun 15, 7:21 PM

address what i can. this needs to go out very soon. please just look it over in consideration of that and make sure nothing is glaringly wrong.

Harbormaster completed remote builds in B73891: Diff 179822.Mon, Jun 15, 7:21 PM
ziaee added inline comments.Mon, Jun 15, 7:22 PM
website/content/en/releases/15.1R/upgrading.adoc
176

irc consensus on arm bootloaders is that what we have is the best we can do.

ziaee updated this revision to Diff 179823.Mon, Jun 15, 7:32 PM
ziaee added a subscriber: fuz.

"systems running older releases must incrementally upgrade to one of these releases before performing this upgrade.", ty @fuz

Harbormaster completed remote builds in B73892: Diff 179823.Mon, Jun 15, 7:32 PM
ziaee updated this revision to Diff 179824.Mon, Jun 15, 7:36 PM

voice

Harbormaster completed remote builds in B73893: Diff 179824.Mon, Jun 15, 7:36 PM
vladlen added inline comments.Mon, Jun 15, 7:38 PM
website/content/en/releases/15.1R/relnotes.adoc
32

Feel free to ignore if you're in a hurry. Could you consider these options:
This document details
or
These release notes detail

The curtrent text also correct if we call 'the note' every file (the same as in the text if "updating" note).

38

hardware

41

The errata document contains

website/content/en/releases/15.1R/upgrading.adoc
25

relnotes

vladlen added inline comments.Mon, Jun 15, 7:52 PM
website/content/en/releases/15.1R/relnotes.adoc
36

full stop at the end for consistency is better.

38

full stop at the end for consistency is better.

website/content/en/releases/15.1R/upgrading.adoc
89

freebsd-update

207

preceded

ziaee updated this revision to Diff 179825.Mon, Jun 15, 7:55 PM
ziaee marked an inline comment as done.

thanks vladlen!

Harbormaster completed remote builds in B73894: Diff 179825.Mon, Jun 15, 7:55 PM
ziaee updated this revision to Diff 179826.Mon, Jun 15, 7:57 PM

thanks @vladlen!

Harbormaster completed remote builds in B73895: Diff 179826.Mon, Jun 15, 7:57 PM
vladlen added a comment.Mon, Jun 15, 8:01 PM

I do not see anything wrong, and my spell checker too.
LGFM.

ziaee updated this revision to Diff 179827.Mon, Jun 15, 8:26 PM
ziaee added a subscriber: cperciva.

fix compat link, thanks @cperciva!

Harbormaster completed remote builds in B73896: Diff 179827.Mon, Jun 15, 8:26 PM
ziaee updated this revision to Diff 179828.Mon, Jun 15, 8:27 PM

"pkgbase tech preview" > "packaged base system"

Harbormaster completed remote builds in B73897: Diff 179828.Mon, Jun 15, 8:27 PM
ziaee updated this revision to Diff 179829.Mon, Jun 15, 8:34 PM

more editorial fixes thanks to @cperciva

Harbormaster completed remote builds in B73898: Diff 179829.Mon, Jun 15, 8:34 PM
emaste added inline comments.Mon, Jun 15, 8:35 PM
website/content/en/releases/15.1R/upgrading.adoc
29

Maybe add a "binary updates can use xxx or yyy." here, to contrast with src updates below. This still seems to indicate pkg which /usr/bin/uname is the first step and later determine if you want src instead.

cperciva added inline comments.Mon, Jun 15, 8:39 PM
website/content/en/releases/15.1R/upgrading.adoc
29

Maybe "The procedure for binary upgrades depends on..."? I don't think we need to worry too much about src-upgraders; they generally know what to do already and aren't reading these instructions.

emaste added inline comments.Mon, Jun 15, 8:51 PM
website/content/en/releases/15.1R/upgrading.adoc
29

Ah yes, I like that - it clearly indicates what this applies to.

ziaee updated this revision to Diff 179830.Mon, Jun 15, 9:02 PM

yeah i like that too, that's a lot better, thanks!

Harbormaster completed remote builds in B73899: Diff 179830.Mon, Jun 15, 9:02 PM
This revision was not accepted when it landed; it landed in state Needs Review.Mon, Jun 15, 10:32 PM
Closed by commit R9:63927b02bb47: 15.1: Installation note -> Upgrading note (authored by ziaee). · Explain Why
This revision was automatically updated to reflect the committed changes.
ziaee added a commit: R9:63927b02bb47: 15.1: Installation note -> Upgrading note.

Revision Contents
Changeset List

PathSize
website/
content/
en/
releases/
15.1R/
49 lines
303 lines

Diff 179830

View Options

website/content/en/releases/15.1R/installation.adoc

Loading...
View Options

website/content/en/releases/15.1R/relnotes.adoc

Loading...
View Options

website/content/en/releases/15.1R/upgrading.adoc

Loading...