Re: Not happy about firewalld man pages

[Jiri Popelka]

Replying to Firewalld users discussion list.
Please use this list for further communication.
thanks

On 02/16/2013 08:51 PM, "Jørgen Thomsen" wrote:
> Hi
>
> After fighting for some hours with the new Fedora 18 firewall I am really dissatisfied with the
> documentation of this new feature.
>
> It is lacking definitions and simple howto examples.
>
> It is paramount to provide a way of simple transition to a completely new system using
> user-unfriendly XML-files, which I never understood the need for in very simple configuration
> files. But that unfortunately is the current trend in anything, whether it adds value or not.
>
> man firewalld
>
> a) there is a too simplified explanation on the structure of the configuration files and how
>
> they are used both by the program and by the user.

There's also a note:
"For more information on icmptypes, please have a look at the 
firewalld.icmptype(5) man page, for services at firewalld.service(5) and 
for zones at firewalld.zone(5)."
> b) iptables --list are displaying a set of rules. From where are they loaded ?

I'm not sure I understand the question.
The rules are loaded from the above mentioned XML configuration files.
For example:
/usr/lib/firewalld/zones/public.xml
contains
<service name="ssh"/>
which is defined in /usr/lib/firewalld/services/ssh.xml
as
<port protocol="tcp" port="22"/>
so when firewalld loads public.xml it runs the following command
iptables -A IN_ZONE_public_allow -p tcp -m tcp --dport 22 -m conntrack 
--ctstate NEW -j ACCEPT
> c) a simple example of adding/deleting a new permanent rule is missing e.g how to use one of
>    the predefined rules. Howto and the result of this command. This would increase the
>    understanding of how firewalld is working very much

Permanent rules are added into the XML configuration files and should be 
described in firewalld.zone(5).

All man pages point to the home page at
http://fedorahosted.org/firewalld/
which points to documentation at
https://fedoraproject.org/wiki/FirewallD/
where are the examples of adding permanent rules with 'firewall-cmd 
--permanent'
https://fedoraproject.org/wiki/FirewallD#Permanent.2Fpersistent_zone_handlin...
> man firewall-cmd
>  [--zone=<zone>] --add-ACTION [--timeout=<seconds>]
>
> What is ACTION ? No definition is provided
>  This does not help at all:
>    For the possible actions, please have a look at the action options further down.

I tried to improve this a little with
http://git.fedorahosted.org/cgit/firewalld.git/commit/?id=3ca05d170cd70ce0ac...
> Again simple examples are providing much more information than long lists of options (which of
> course must be present, too)
>
> Please, sit down and forget everything you know about firewalld and then improve the
> documentation, or better ask somebody who never used it, do some simple firewalld tasks and then
> based on his experience write the documentation so he can do it within a few minutes without
> asking you.

Yes, the documentation is far from being perfect and few examples or at 
least pointer to
https://fedoraproject.org/wiki/FirewallD#Using_firewall-cmd
would be good.
> Jørgen Thomsen
>
> Kontaktinfo: http://jth.tel

--
Jiri