F43 Change Proposal: Man-DB cache directory change (self-contained)

Project Discussion Change Proposals
,
1

:link: Fontconfig cache directory change

This is a proposed Change for Fedora Linux.
This document represents a proposed Change. As part of the Changes process, proposals are publicly announced in order to receive community feedback. This proposal will only be implemented if approved by the Fedora Engineering Steering Committee.

Wiki
Announced

:link: Summary

The man-db cache files are placed in/var/cache/man now. This seems incompatible with the ostree model, so this is a proposal to move it to /usr/lib/man/cache. This is also heavily requested for image-mode

:link: Owner

:link: Detailed Description

Currently, the man-db cache files are stored in /var/cache/man, which works fine in traditional setups. However, this location doesn’t play well with the OSTree model, where /var is often treated differently or even shared across deployments. To make man-db more compatible with OSTree-based systems, this proposal suggests moving the cache files to /usr/lib/man/cache instead. That way, the cache can live alongside the rest of the read-only system content managed by the image, avoiding issues with /var. This change is also something that’s been heavily requested by people working with image-mode deployments, where managing everything within /usr is generally preferred.

:link: Feedback

:link: Benefit to Fedora

Image-Mode is requesting this so it can make use of it since the /var directory is restricted for other use.

Similar approach was done in the fontconfig package (described in this Fedora Change.

:link: Scope

  • Proposal owners: Rebuild the man-db package with the changes to the proposed cache directory.

  • Other developers: N/A (not a System Wide Change)

  • Release engineering: N/A (not a System Wide Change)

  • Policies and guidelines: N/A (not needed for this Change)

  • Trademark approval: N/A (not needed for this Change)

  • Alignment with the Fedora Strategy: YES

:link: Upgrade/compatibility impact

:link: How To Test

The /usr/lib/man/cache should exist and be used for the man-db cache. The previously used /var/cache/man should not be used at all.

:link: User Experience

N/A (not a System Wide Change)

:link: Dependencies

N/A (not a System Wide Change)

:link: Contingency Plan

Revert the changes to place the caches at /var/cache/man.

  • Contingency mechanism: N/A (not a System Wide Change)
  • Contingency deadline: N/A (not a System Wide Change)
  • Blocks release? N/A (not a System Wide Change)

:link: Documentation

N/A (not a System Wide Change)

N/A (not a System Wide Change)

:link: Release Notes

The place of the man-db caches has been moved from /var/cache/man to /usr/lib/man/cache.

Last edited by @decathorpe 2025-08-08T14:43:48Z

Last edited by @decathorpe 2025-08-08T14:43:48Z

2

How do you feel about the proposal as written?

  • Strongly in favor
  • In favor, with reservations
  • Neutral
  • Opposed, but could be convinced
  • Strongly opposed
0 voters

If you are in favor but have reservations, or are opposed but something could change your mind, please explain in a reply.

We want everyone to be heard, but many posts repeating the same thing actually makes that harder. If you have something new to say, please say it. If, instead, you find someone has already covered what you’d like to express, please simply give that post a :heart: instead of reiterating. You can even do this by email, by replying with the heart emoji or just “+1”. This will make long topics easier to follow.

Please note that this is an advisory “straw poll” meant to gauge sentiment. It isn’t a vote or a scientific survey. See About the Change Proposals category for more about the Change Process and moderation policy.

3

I’m guessing this Change was copy-pasted from the old Fontconfig one, but it really needs a s/Fontconfig/ManDB/ across it.

1 Like
4

Correct, I’ve already fixed it and asked Aoife for a new announcement, so the email thread is also correct.

5

Just to clarify here: the current state of things is not incompatible; it has downsides. Details and workaround in:

+1 for this change. Thanks

6

This change proposal has now been submitted to FESCo with ticket #3462 for voting.

To find out more, please visit our Changes Policy documentation.

7

I missed this discussion because of the title. I’m not sure this makes sense. This would break any third-party or local software man page caching. Also, what even uses the man-db cache? It’s not man itself, so what uses it?

8

Actually, the man itself is provided by this package. And several others like apropos, whatis, … and they all use the cache for faster browsing through the manual pages.

What exactly do you believe would break after this change?

9

I tried to build it and use it in fresh Fedora machine and it worked just fine.

MR: PR#21: [Fedora Change] Move cache dir to /usr/lib/man/cache - rpms/man-db - src.fedoraproject.org

Build: build (f43-candidate, man-db-2.13.1-3.fc43.src.rpm) | Task Info | koji

11

It almost feels like we need to adjust some terminology, because a readonly cache is… well, I don’t know what it is, but it’s not a cache. I guess it’s closer to… prerendered content?

Are there really systems where /var might be shared, but /usr is guaranteed NOT to be? That seems bass-ackwards to me. The purpose of “var” is right there in its name, and caching would be one example of the sort of variable information that it’d typically hold. But I’m old and yell at both types of cloud, so don’t let me stand in the way of progress.

12

Reading the change, this also doesn’t make sense to me.

Isn’t that cache populated by a systemd service that runs regularly (man-db-cache-update.service)? How would that work on a system where contents of /usr is only supposed to get updated externally?

13

Would this require the “cache” to be shipped over the internet together with the primary man pages instead of being computed client-side? Does /var/cache/man index any man pages that don’t come from the system RPMs? How would those man pages be indexed with the change proposal?

14

Replying to this in concert with:

On a mutable package-mode system, the functionality is unchanged AFAICS. Because arbitrary other software might write man pages, indeed we probably still want the systemd service.

On an image-based system, the systemd service is unnecessary and should probably be disabled by e.g. ConditionPathIsReadWrite=/usr/lib/man/cache or so.

There’s definitely a corner case in that on some image based systems one might to install binaries in /usr/local/bin with man pages in /usr/local/man or so (where /usr/local → /var/usrlocal or so) - that’s the setup on systems like CoreOS and Silverblue. Whereas the default for the Fedora bootc base image is that /usr/local is lifecycle bound with the base OS image and it’s intended to be a base image where users/customers derive from and build on.

We should probably again look at fontconfig as a reference as there’s a similar use case for local user-installed fonts even on an image-based OS. However, most of that tends to happen in user home directories, which fontconfig supports well. There’s of course ~/.local/bin but I don’t think man knows about ~/.local/share/man (though I could be wrong).

15

This was discussed yesterday in the FESCo meeting, and a question arise:

How would it work with layered packages and packages overrides in immutable installations?
How would the cache for those packages man pages be updated?

16

I’m not sure what you mean by that, can you please elaborate or give some examples? However, this change only changes the directory of the cache, not its functionality. So how does this affect your use case?

Same as it is done right now. Using the systemd unit man-db-cache-update, or you can do it manually using mandb -c

17

A cache is meant to be regenerated, be it by package installs (in post) or by a service. I don’t think /usr/lib is the proper place for this. /var/cache is, by definition, and if the OSTree model has a problem with this it’s appropriate to question the model’s use of and assumptions about the file system structure.

I do understand that switching /usr back and forth (by switching deployments) does not go well together with a /var that’s independent of the deployment technically (it does not get switched) but whose content depends on the deployment. That’s a structural problem of an “immutable system” which needs mutable parts, and “doing something for man” does not take us anywhere conceptually. The structural problem needs be solved structurally.

18

So that systemd unit is supposed to modify content under /usr? Isn’t that completely counter to how image-based systems are supposed to work (or even can work, if /usr is indeed mounted read-only)?

19

Are you talking specifically about rpm-ostree package layering? That has always operated like a “local build”. RPM packages, ostree commits | rpm-ostree

If you’re talking about something not through rpm-ostree, I think I already covered that above.

Again, there’s nothing different here about man-db vs other similar “cache files” like fontconfig, gtk-update-icon-cache, ldconfig etc. I think it’s really worth re-emphasizing the point that this is just aligning man-db with other systems with these cache files.

There are of course some details - not every one of these has a systemd service for example; some just require running a binary that might be done via RPM file triggers or manually, some do both etc. That’s mostly a consequence of organic evolution from disparate upstreams.

(BTW another big example of such a thing is update-ca-trust - the resulting files are definitely not a cache in the sense that some tools only know how to read the merged ones. Also upstream it doesn’t include a systemd unit, but we ship one in FCOS and derivatives because it makes things Just Work to write files there)

20

I believe we can take a look at some other packages that already implemented similar type of change and there are no issues:

21

That was the question, yes. Thanks a lot for clarifying this point :slight_smile: