Create usage examples that display more detailed errors

[n0toose]

After a century of debugging the following CI output and assuming that there was some sort of a problem with the untested (and comparatively undocumented) from_file function (leading to the creation of #92), I came to the conclusion that CompatLevel::HardRequirement actually fails on a self-hosted Ubuntu 22.04 LTS-based runner (which is supposedly supported) as Landlock is, actually, disabled on that system (perhaps because of a minor version update.

In my opinion, what the following excerpt from the example does (and expresses)...

https://github.com/landlock-lsm/rust-landlock/blob/main/examples/sandboxer.rs#L133-L135

should be done when the user is trying to enforce a set of Landlock rulesets that will fail anyway because of CompatLevel::HardRequirement causing an "unrecoverable" incompatibility. Because weird things happen, and clear errors help.

[n0toose]

Hope that comments such as "comparatively undocumented" or "supposedly supported" do not come across as passive aggressive (in all cases, I'd be more than happy to send in a contribution!) - I used those terms so as to paint a better picture of my perspective, so as to show where I am coming from.

If you agree that the issue (as well as the other points I've raised) is an actual problem, I'd be happy to send in a few more patches wherever possible. :)

[l0kod]

I came to the conclusion that CompatLevel::HardRequirement actually fails on a self-hosted Ubuntu 22.04 LTS-based runner (which is supposedly supported) as Landlock is, actually, disabled on that system (perhaps because of a minor version update.

Ubuntu 22.04 supports Landlock as you can see in our tests: https://github.com/landlock-lsm/rust-landlock/actions

Without a link to the tested code and the CI it's difficult to guess what's happening, but I think you set the test variable LANDLOCK_CRATE_TEST_ABI to the wrong version. Ubuntu got a newer kernel, see fd46eaf and https://ubuntu.com/kernel/lifecycle

In my opinion, what the following excerpt from the example does (and expresses)...

https://github.com/landlock-lsm/rust-landlock/blob/main/examples/sandboxer.rs#L133-L135

should be done when the user is trying to enforce a set of Landlock rulesets that will fail anyway because of CompatLevel::HardRequirement causing an "unrecoverable" incompatibility. Because weird things happen, and clear errors help.

What do you mean? This library enables developers to choose the behavior that fits best with their use case. A library should never panic. CompatLevel::HardRequirement is mostly dedicated to tests and should rarely be used in production because that's not what most users want nor expect. The default CompatLevel::BestEffort should be use in most cases. See documentation: https://landlock.io/rust-landlock/landlock/trait.Compatible.html#method.set_compatibility

[n0toose]

Ubuntu 22.04 supports Landlock as you can see in our tests

CompatLevel::HardRequirement is mostly dedicated to tests and should rarely be used in production because that's not what most users want nor expect

Sorry, what I wrote yesterday was not a good issue - I had a long day and did not have a clear head. Please allow me to start over.

Ok, so: In my half-broken, weird setup (namely, Ubuntu 22.04 LTS that missed a couple of minor updates - caused Landlock problems which are not a problem of Landlock) the error RulesetError was raised - particularly a RestrictSelfError. As I was tired when I was making the issue, I basically forgot that this was a "me problem", in the sense that I oriented myself after the example too much.

Because the example only uses a "catch-all" for RulesetError and I hadn't considered the possibility of my minor version being too old, I initially thought that the error I got was because of IoctlDev - introduced in ABI v5 - but that was not the case:

rust-landlock/src/ruleset.rs

Lines 131 to 150 in 07f2a9a

	/// # Generic example
	///
	/// More generic helper handling a set of file hierarchies
	/// and multiple types of error (i.e. [`RulesetError`](crate::RulesetError)
	/// and [`PathFdError`](crate::PathFdError).
	///
	/// ```
	/// use landlock::{
	/// Access, AccessFs, PathBeneath, PathFd, PathFdError, RestrictionStatus, Ruleset,
	/// RulesetAttr, RulesetCreatedAttr, RulesetError, ABI,
	/// };
	/// use thiserror::Error;
	///
	/// #[derive(Debug, Error)]
	/// enum MyRestrictError {
	/// #[error(transparent)]
	/// Ruleset(#[from] RulesetError),
	/// #[error(transparent)]
	/// AddRule(#[from] PathFdError),
	/// }

The example shown in sandboxer.rs could have alleviated this ambiguity for me:

rust-landlock/examples/sandboxer.rs

Lines 133 to 135 in 07f2a9a

	if status.ruleset == RulesetStatus::NotEnforced {
	bail!("Landlock is not supported by the running kernel.");
	}

To an implementer, no matter the CompatLevel set (writing that on the title was wrong), RulesetError as a 'catch-all' can cause confusion. The term "Display" was wrong, as the crate is not responsible for displaying anything! The only thing in this repository that "displays" anything is in the examples.

---

With all of that being said, this is my actual proposal: I would like for the usage examples to be refined - as in, introduce "end user"-like examples and tests for those examples - so as to demonstrate how rust-landlock should be integrated in applications and make it easier for users to do so. (If you allow me, I would also like to work on this - but on a "best effort" basis.)

[l0kod]

With all of that being said, this is my actual proposal: I would like for the usage examples to be refined - as in, introduce "end user"-like examples and tests for those examples - so as to demonstrate how rust-landlock should be integrated in applications and make it easier for users to do so.

Your confusion is legitimate and we should indeed improve the documentation and examples. I'd just like this example to be kept in sync with the C example. I think that should not be an issue to improve the related documentation, but if needed, we could add other simpler examples.

(If you allow me, I would also like to work on this - but on a "best effort" basis.)

Sure! I plan to work on #57 in the coming days at least to have a base integration test framework, and that could be leveraged to test the example as well. I'll update the related issue. Feel free to chime in.

[n0toose]

Your confusion is legitimate and we should indeed improve the documentation and examples. I'd just like this example to be kept in sync with the C example. I think that should not be an issue to improve the related documentation, but if needed, we could add other simpler examples.

Totally get why you'd want some degree of consistency there, note taken. I'll reconsider my approach.

I'll update the related issue. Feel free to chime in.

I have a few examples of tests that I could contribute, but I need to fix up my test suites which falsely do not use std::thread::spawn. I can be an imposter syndrome sufferer sometimes - I'd like to share them with you and adjust them when they're "ready" from my POV. :)