Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Doc: Include better explainations of the effects various configurations (i.e. what does the setting do?) #1279

Open
mstovenour opened this issue Jan 16, 2024 · 0 comments
Labels
documentation Documentation only change. easy Effort is estimated to be easy.

Comments

@mstovenour
Copy link

What would you like to be added

Change the /doc/*.xml content to eliminate the "options" parameter by parameter reference material and link to the man pages where that information already exists in much better detail. Augment the top level content for each object with more information regarding "what" and "how" the various configuration objects affect the accessibility of the system. I don't think each section needs to be terribly long. For instance the "service" should describe how applying a service to a zone permits incoming connection requests from that zone to the host (i.e. input/output) and applying it to a policy permits connections from the source zone(s) to access the service in the target zone(s).

Why is this needed

Clearly a lot of work has been put into the documentation of firewalld. I actually find there to be a lot of duplicate documentation (e.g. man pages, doc "option" pages, and the github wiki) which is nearly but not quite all identical so it must be maintained separately. Yet, I can't really find an explanation of how the various config objects effect the access rules. I'm sure the "how" or "what" part of the config is really simple/obvious and so experts don't think it needs to be said. I have many years of experience designing firewall rule sets on cisco, aws, iptables, etc. When reading the docs here I can't definitively understand what various config objects are doing to the rule sets. Sure I can guess and might be 95% but I'm not going to do that with a firewall. I've resorted to trial and error; make a change, dump the nftables, vimdiff to an earlier dump, repeat. For instance enabling a service on a zone... does that permit others to access that service in the zone? or does it permit that zone to access the service? Trial and error says the latter, but nothing in the documentation clearly says that. I think the project would get a lot more use if it was easier and faster to grasp the concepts; otherwise people like me just keep making our own nftables rulesets by hand.

@mstovenour mstovenour added the feature New feature or enhancement. label Jan 16, 2024
@erig0 erig0 added documentation Documentation only change. easy Effort is estimated to be easy. and removed feature New feature or enhancement. labels Jan 18, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
documentation Documentation only change. easy Effort is estimated to be easy.
Projects
None yet
Development

No branches or pull requests

2 participants