Concept-module rules are too strict

[mjahoda]

Modular Docs Reference Guide is too strict regarding the context module definition. Prohibiting any action would result in creating separate procedure module files with just one command and making assemblies instead of just one module file.

I am suggesting to loose the definition to allow also commands or brief examples in concept. modules (when used to introduce or to illustrate a concept).

[msuchane]

I think that creating very short procedures, and as a result more assemblies, is perfectly fine. Short procedures have a potential to be reused elsewhere and the additional heading provides more structure.

However, I'd say there can be special cases where writing an example or a command directly in the concept module is the best way to proceed. I know that I've done it a couple of times.

Do you have any documentation examples that we could discuss here?

[mjahoda]

• https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/8/html/using_selinux/managing-confined-and-unconfined-users_using-selinux#confined-and-unconfined-users_managing-confined-and-unconfined-users
• https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/8/html/security_hardening/using-the-system-wide-cryptographic-policies_security-hardening#system-wide-crypto-policies_using-the-system-wide-cryptographic-policies

[IngridT1]

@mjahoda It seems like the procedures are buried in these examples and that they will be harder for our readers to find.

[mjahoda]

@IngridT1 In the first example, the second command could be useful as a procedure. The first one hardly and it serves well to explain the concept. However, this is not the point.

As you can see in the second example (crypto-policies), we have covered setting another policy level by a separate procedure. This way, we ensure findability, clarity but we can still satisfy readers who land on the page with the concept module.

My point is not about having actions in procedure modules but about strictly prohibiting them in concept modules. You have to check the examples I provided from this point of view.

[1] https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/8/html/security_hardening/using-the-system-wide-cryptographic-policies_security-hardening#switching-the-system-wide-crypto-policy-to-mode-compatible-with-previous-systems_using-the-system-wide-cryptographic-policies

[emmurphy1]

@mjahoda if we allowed actions in concept modules, there would be no need to have modules at all :-) The purpose of modularization is to group information by type so that users can digest it more easily.

But I don't entirely disagree with your idea. But instead of adding the action to the concept module, add the concept to the procedure module. There is no hard limit to the amount of concept information that a procedure module can contain. What is important is the order: Concept information (however long) .Prerequisites (optinonal) .Procedure

• Step 1

.Additional Resources

You would only want to do this if you do not want to reuse the concept information alone.

You can of course include short explanations with the steps, but in general try to keep these short.

[mjahoda]

@emmurphy1 From my perspective, the solution you are suggesting means following the current rules instead of focusing on reader's experience. Especially when I imagine it in the previously mentioned example sections. Yes, it is fine if the reader always reads just one page but it would be weird otherwise. Furthermore, your suggestion does not solve the case when a command (and its output) helps explain the concept.

[VladimirSlavik]

Looks like the actual part of the reference guide disputed here is this:

Do not include any instructions to perform an action, such as executing a command. Action items belong in procedure modules.

Personally I think interpretation of the above as "no commands in concepts, ever" is overzealous and putting cart before the horse. Obviously if one writes about commands, they must be present there somehow, as well as their output.

That said, I can see how eg. the first example (confined/unconfined users) could be just reshuffled to get a procedure with lots of conceptual information. It's not always possible, and sometimes the wrong choice, but YMMV. See an attempt at this below. For what it's worth, calling that a "procedure" seems totally wrong, but if you insist...

---

Checking which users are confined and which unconfined

Each Linux user is mapped to an SELinux user using SELinux policy. This allows Linux users to inherit the restrictions on SELinux users. Confined and unconfined Linux users are subject to executable and writable memory checks, and are also restricted by MCS or MLS.

If an unconfined Linux user executes an application that SELinux policy defines as one that can transition from the unconfined_t domain to its own confined domain, the unconfined Linux user is still subject to the restrictions of that confined domain. The security benefit of this is that, even though a Linux user is running unconfined, the application remains confined. Therefore, the exploitation of a flaw in the application can be limited by the policy.

Similarly, we can apply these checks to confined users. Each confined user is restricted by a confined user domain. The SELinux policy can also define a transition from a confined user domain to its own target confined domain. In such a case, confined users are subject to the restrictions of that target confined domain. The main point is that special privileges are associated with the confined users according to their role.

In Red Hat Enterprise Linux, Linux users are mapped to the SELinux default login by default, which is mapped to the SELinux unconfined_u user.

Prerequisites

• You must have the setools-console package installed

Procedure

1. To see the SELinux user mapping on your system, use the semanage login -l command as root: (...) The following line defines the default mapping: (...)
2. To list the available SELinux users, enter the following command: (...) Note that the seinfo command is provided by the setools-console package, which is not installed by default.

---

Thinking this way is so different it hurts a bit, but it is possible for lots of material. I like the organization of information this way, even if I would never call this a procedure, ever.

[mjahoda]

@VladimirSlavik As I already wrote in my reply to Ingrid [1], I am aware that in the first example, it is more about inconvenience and a hardly usable procedure than about anything else.

However, in the crypto-policies assembly [2], when you follow the current concept-module rules, you have to create a separate procedure for the short example despite already having a dedicated procedure covering this [3]. More importantly, you do not provide a useful information to the users that land on the concept (intro) [4] right on the page one just because you are following certain rules.

This is against one of the reasons why we switched to the FCC docs and this is what people get on stackoverflow, reddit, and so on. And I guess that we can find more examples supporting the topic of this issue.

[1] https://github.com/redhat-documentation/modular-docs/issues/119#issuecomment-654661640

[2] https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/8/html/security_hardening/using-the-system-wide-cryptographic-policies_security-hardening

[3] https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/8/html/security_hardening/using-the-system-wide-cryptographic-policies_security-hardening#switching-the-system-wide-crypto-policy-to-mode-compatible-with-previous-systems_using-the-system-wide-cryptographic-policies

[4] https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/8/html/security_hardening/using-the-system-wide-cryptographic-policies_security-hardening#system-wide-crypto-policies_using-the-system-wide-cryptographic-policies

[yzimmerm]

I agree that there should not be any instructions in concept modules. Short procedure modules are excellent, and easy to include in multiple assemblies where necessary. In corner cases, where it is necessary, try to create concept assemblies, with multiple concept modules and small procedure modules, where possible.

[emmurphy1]

I created a PR for this update. @sterobin @yzimmerm @fbolton @oraNod @Preeticp @rkratky @ncbaratta @rolfedh please comment. I'm open to suggestions for improvement.

[emmurphy1]

@adahms this issue is resolved and merged. Please add it to the decision register.