[Bug]: Docs incorrectly describe relationship between "host" and "host-os"/"host-etc" permissions

mikix commented 3 months ago

Checklist

[X] I agree to follow the Code of Conduct that this project adheres to.
[X] I have searched the issue tracker for a bug that matches the one I want to file, without success.
[X] If this is an issue with a particular app, I have tried filing it in the appropriate issue tracker for the app (e.g. under https://github.com/flathub/) and determined that it is an issue with Flatpak itself.
[X] This issue is not a report of a security vulnerability (see here if you need to report a security issue).

Flatpak version

1.14.6

What Linux distribution are you using?

Ubuntu

Linux distribution version

24.04

What architecture are you using?

x86_64

How to reproduce

Go to https://docs.flatpak.org/en/latest/sandbox-permissions.html
Search for host-etc and read all the host* permission descriptions

Expected Behavior

The docs would say that host includes host-etc and host-os, which each turn on specific exposures.

Actual Behavior

Instead, they give the impression that host-etc includes host and that host does not include host-etc. That's the reverse of what's actually the case, afaict from testing and looking at the code.

Additional Information

No response

smcv commented 3 months ago

docs.flatpak.org is https://github.com/flatpak/flatpak-docs/, please could someone with suitable permissions move this issue to that project? [edited: never mind, looks like I can do this myself]

smcv commented 3 months ago

The docs would say that host includes host-etc and host-os, which each turn on specific exposures.

I confirm that that is how they work, and flatpak-docs is documenting this wrong. flatpak-metadata(5) in https://github.com/flatpak/flatpak describes the situation correctly:

"host: The entire host file system, except for directories that are handled specially by Flatpak. … Additionally, this keyword provides all of the same directories in /run/host as the host-os and host-etc keywords."

So host-os and host-etc are each "less powerful" than host. That's why I added them: I didn't want to have to add the host permission, which is usually a sandbox escape, just to be able to read the host's /etc and /usr.

flatpak / flatpak-docs