etcupdate usage

[Erwan David]

Hello,

I do not understand how to use etcupdate. I am lost in the different options.
s there somewhere a tutorial on its usage ?

PS: on a machine that juste went from 14.2 to 14.3, etcuodate diff shows diff, but etcupdate says
Failed to build new tree.

Is it because src is not on the machine ? (not enough disk)

I soon will upgrade another machine (with /usr/src this one), and I'd prefer to be sure to be able to use etcupdate on it
(especially if I need to to a extract or build before upgrade)

--
Erwan David

[Sad Clouds]

On Tue, 14 Oct 2025 09:03:40 +0200
Erwan David <er...@rail.eu.org> wrote:

> Hello,
>
> I do not understand how to use etcupdate. I am lost in the different options.
> s there somewhere a tutorial on its usage ?

Not sure about tutorials, but you may find this post useful:
https://lists.freebsd.org/archives/freebsd-questions/2024-September/005666.html

I think NetBSD etcupdate is much better.

[Dag-Erling Smørgrav]

Erwan David <er...@rail.eu.org> writes:
> I do not understand how to use etcupdate. [...] Is it because src is

> not on the machine ?

If you didn't upgrade from source, you don't need etcupdate.

> I soon will upgrade another machine (with /usr/src this one), and I'd
> prefer to be sure to be able to use etcupdate on it
> (especially if I need to to a extract or build before upgrade)

If and only if upgrading your machine from source, run `etcupdate -B`
after `make installworld`. This will update every file that isn't
conflicted and tell you of any that are, in which case you will have to
run `etcupdate resolve` to resolve the conflicts.

Once in a great while (the last time it happened was in 2020), `make
installworld` will fail due to a missing user or group. In that case,
you need to run `etcupdate -p` (and possibly `etcupdate resolve -p`) to
update the user and group databases before retrying `make installworld`.
When doing so, you will still have to run `etcupdate -B` afterwards to
update everything else.

DES
--
Dag-Erling Smørgrav - d...@FreeBSD.org

[Erwan David]

On Tue, Oct 14, 2025 at 01:26:06PM CEST, Dag-Erling Smørgrav <d...@FreeBSD.org> said:
> Erwan David <er...@rail.eu.org> writes:
> > I do not understand how to use etcupdate. [...] Is it because src is
> > not on the machine ?
>
> If you didn't upgrade from source, you don't need etcupdate.

Thanks, I upgrade through freebsd-update thus no worry to have.

--
Erwan David

[Steve Rikli]

On Tue, Oct 14, 2025 at 09:03:40AM +0200, Erwan David wrote:
> Hello,
>
> I do not understand how to use etcupdate. I am lost in the different options.
> s there somewhere a tutorial on its usage ?

The general reference I use for updating FreeBSD, which discusses several
different methods (src, binary, etc):

https://docs.freebsd.org/en/books/handbook/cutting-edge/

For upgrading systems from src (*not* pkgbase or freebsd-update) I use
this as a reference:

"26.6. Updating FreeBSD from Source"
https://docs.freebsd.org/en/books/handbook/cutting-edge/#makeworld

There are several examples and walk-thru, both quickstart and more
thorough + annotated. For etcupdate in particular, there is this
specific section:

"26.6.6.1. Merging Configuration Files with etcupdate(8)"
https://docs.freebsd.org/en/books/handbook/cutting-edge/#updating-src-completing-merge-etcupdate

in general, in my experience there isn't usually a lot you need to do
most times for etcupdate to work. I run it with every world src upgrade
procedure as advised, so my /etc/ doesn't grow stale or drift from the
installed binaries and such.

> PS: on a machine that juste went from 14.2 to 14.3, etcuodate diff
> shows diff, but etcupdate says
> Failed to build new tree.
>
> Is it because src is not on the machine ? (not enough disk)

That's a possibility; etcupdate is for upgrading systems from src
(not freebsd-update binary upgrades) and it constructs its list of
diffs and changes from /usr/src/etc/ for reference.

> I soon will upgrade another machine (with /usr/src this one), and I'd
> prefer to be sure to be able to use etcupdate on it (especially if I
> need to to a extract or build before upgrade)

If you're just getting started building FreeBSD from src, it's worth
reading that whole Handbook chapter 26.6 IME.

sr.

[Erwan David]

I use freebsd-update thus, I do not need /etc/update.

Except maybe for jails : I use thin jails with a shared world using
nullfs (as in
https://docs.freebsd.org/en/books/handbook/jails/#creating-thin-jail-nullfs
). When updating them with freebsd-update, following
https://docs.freebsd.org/en/books/handbook/jails/#upgrading-thin-jail I
then update the sahred part. However /etc is not shared, thus cannot be
updated. Should I use etcupdate then ?