Clarify effects of some commands in the man page

[the-sun-will-rise-tomorrow]

Fixes #617.

RFC on wording, maybe "permanent" is not the best way to describe it, but it would address the confusion I had.

[smcv]

bwrap.xml: Place the --perms details in their own paragraph

This commit looks fine, I might cherry-pick it.

[smcv]

Please add a Signed-off-by to the commits to indicate your acceptance of the Developer Certificate of Origin (basically declaring that we can use your contribution in the obvious ways).

[smcv]

I don't think it scales very well to repeat this for every option that might alter the filesystem, because there are a lot:

• everything that mounts a directory will create an empty directory as a mount point if necessary
• everything that mounts a non-directory will create an empty regular file as a mount point if necessary
• --symlink will modify the real filesystem if its destination is a writeable file system
• so will --chmod

This is really a fact about mounting filesystems, not a fact about the command-line options that modify the filesystem. Would it perhaps be clearer what is going on if we say something similar in --bind instead of this? Maybe like this:

        <para>If a process inside the sandbox or a later command-line option
          modifies the contents of <arg choice="plain">DEST</arg>, those
          modifications will affect <arg choice="plain">SRC</arg>
          outside the sandbox.</p>

If --bind said this, would you have assumed that the same was true for --bind-try, --dev-bind and --dev-bind-try without needing it to be said explicitly?

(We certainly don't need to add this to --ro-bind and --ro-bind-try because those are read-only mounts.)

[smcv]

I think it's valuable to use essentially the same language to talk about what happens if a process inside the sandbox does a filesystem write (whether that's symlink() or chmod() or a file overwrite or whatever), and what happens if a subsequent command-line option tells bwrap to do a filesystem write, because they're fundamentally the same operation.

I wouldn't want anyone to get the mistaken idea that a --symlink or --chmod or --file is permanent, but the COMMAND doing an equivalent symlink() or chmod() or open() somehow wouldn't be permanent.

[the-sun-will-rise-tomorrow]

Would it make sense to somehow group the options that modify the filesystem, and add such a notice at the top of that section?

[smcv]

Would it make sense to somehow group the options that modify the filesystem, and add such a notice at the top of that section?

That's about half of the options, though! For example, --bind and friends will create an empty directory or an empty regular file as a mount point if necessary. So it seems to me that the new section you propose would be sufficiently long that it isn't immediately obvious which options it contains.

I still think that the approach you've taken here scales poorly: if you document "this can modify the filesystem" on half the options, it would be very easy to miss one; and it would be very easy for a user to assume that anything that isn't documented that way can't modify the filesystem, which is untrue if we've missed one.

And, there is nothing magic about --symlink that makes it somehow more powerful than having the COMMAND call symlink(). They are both equally able to write to the filesystem.

I still think what I said before: this is really a fact about mounting filesystems from outside the container, not a fact about the command-line options that modify the filesystem, so the place to document "if anything writes to DEST, the write changes SRC" is the documentation of --bind, rather than the documentation of e.g. --dir.

I asked: "If --bind said [what I suggested above], would you have assumed that the same was true for --bind-try, --dev-bind and --dev-bind-try without needing it to be said explicitly?" Please answer that?

[the-sun-will-rise-tomorrow]

Doing my best to remember the original motivations that led me to propose this improvement, I recall that the surprise wasn't in how --bind worked, but how --symlink etc. worked - as you mentioned above, my misinterpretation was that I thought these worked by way of some kind of overlay on top of any filesystems. I think the path that led me to this misbelief was that, for a long time, the only time I used options such as --symlink was when the target was the implicit tmpfs created at /, so when I used it on a bind-mount of a real filesystem, I was surprised that it had a permanent effect.

So, a note on --bind would not have helped me in this situation, unless I would have read it when I first used the program and then remembered that bit at the moment of confusion.

Same goes for --bind-try and family.

Hope this helps.

[the-sun-will-rise-tomorrow]

Please add a Signed-off-by to the commits to indicate your acceptance of the Developer Certificate of Origin (basically declaring that we can use your contribution in the obvious ways).

Is it OK if I do this pseudonymously (using my GitHub username)?

[smcv]

Is it OK if I do this pseudonymously (using my GitHub username)?

Hmm. I would personally be fine with that, but it isn't my project or my policy, and https://github.com/containers/common/blob/main/CONTRIBUTING.md does say no anonymous or pseudonymous contributions.

@cgwalters, @alexlarsson, do you intend to be enforcing that policy for this project?

[smcv]

Is it OK if I do this pseudonymously (using my GitHub username)?

I've run out of patience for #627 being blocked, and project owners @alexlarsson and @cgwalters haven't made a decision one way or the other, so I'm very tempted to say that pseudonymous contributions are OK and start merging them.

In the case of this particular PR, there are other changes needed, so please could you update it as suggested?

[smcv]

Please add a Signed-off-by to the commits to indicate your acceptance of the Developer Certificate of Origin (basically declaring that we can use your contribution in the obvious ways).

Is it OK if I do this pseudonymously (using my GitHub username)?

The official answer is now: yes, see https://github.com/cncf/foundation/blob/main/dco-guidelines.md.

Please rebase this branch (which will involve fixing some conflicts) and add the Signed-off-by. Until you do, the CI will fail and this branch will not be available for merging.

[smcv]

Would it make sense to somehow group the options that modify the filesystem, and add such a notice at the top of that section?

That's about half of the options, though! For example, --bind and friends will create an empty directory or an empty regular file as a mount point if necessary. So it seems to me that the new section you propose would be sufficiently long that it isn't immediately obvious which options it contains.

I still think that the approach you've taken here scales poorly: if you document "this can modify the filesystem" on half the options, it would be very easy to miss one; and it would be very easy for a user to assume that anything that isn't documented that way can't modify the filesystem, which is untrue if we've missed one.

And, there is nothing magic about --symlink that makes it somehow more powerful than having the COMMAND call symlink(). They are both equally able to write to the filesystem.

I still think what I said before: this is really a fact about mounting filesystems from outside the container, not a fact about the command-line options that modify the filesystem, so the place to document "if anything writes to DEST, the write changes SRC" is the documentation of --bind, rather than the documentation of e.g. --dir.

I asked: "If --bind said [what I suggested above], would you have assumed that the same was true for --bind-try, --dev-bind and --dev-bind-try without needing it to be said explicitly?" Please answer that?

[smcv]

I think this part does make sense to add, because it clarifies the difference between --file and --bind-data.

[the-sun-will-rise-tomorrow]

Apologies, but I am going to retract this pull request.

No hard feelings (I hope!), but the motivation for this change occurred many months ago, and I should probably get my Internet identity sorted out first anyway.

Insofar as legally possible, I disclaim any and all rights to anything in this pull request for which I can do so.