Compare the output of `iptables --help` to that of `firewall-cmd --help`.
firewall-cmd just gives a big dump of options, in the BNF style which is great for specifications but not so useful for help. None of the options are explained, and many of them are not mnemonic. (Quick! Which gives a list of services, --list-services or --get-services? What does --state do?)
Don't know about Thomas but in my case I was using for example 'ip help' or 'nmcli con help' as a template when writing the help for firewall-cmd. Both of them have less options and none explained.
firewall-cmd has too much options to describe them in help (it would be several pages long). That's why we have the man page - which I admit is outdated at the moment, see e.g. bug #806511, comment #7
I like how that ip or nmcli divide the help into several helps each describing different command, see
ip addr help
ip link help
nmcli con help
nmcli dev help
so it'd be better to have for example something like
'firewall-cmd --permanent --help' describing only the permanent changes.
Unfortunatelly firewall-cmd does not have any commands (like ip or nmcli) so I'm not sure how to devide it.
(In reply to comment #1)
> Don't know about Thomas but in my case I was using for example 'ip help' or
> 'nmcli con help' as a template when writing the help for firewall-cmd. Both
> of them have less options and none explained.
I don't think "other things are also terrible" is helpful here. :)
> firewall-cmd has too much options to describe them in help (it would be
> several pages long). That's why we have the man page - which I admit is
> outdated at the moment, see e.g. bug #806511, comment #7
The man page is also really hard to read. BNF is good for specifications, and terrible for end-user documentation. I know that other programs use it -- notably sudo, but search for "worst man page ever" and see what comes up.
> Unfortunatelly firewall-cmd does not have any commands (like ip or nmcli) so
> I'm not sure how to devide it.
I wonder if it would be useful to refactor it so it does?
panic enable|disable|status # controls panic mode
list # returns space-separated information
(and so on)
get # returns information in specific formats
add | remove [--zone=<zone>] [--timeout=#] # add or remove rules
query [--verbose] # get status of a rule
(same as add/remove)
direct # more direct firewall control
(and so on)
(That's not complete, of course, but it's the idea.)
Right now, if I want to learn how to enable a certain service, I have to figure out that service=(something) is part of an ACTION, and then discover that "-add" is a MODE which gets prepended to an ACTION (which is linguistically odd, since "add" is an action, while "service" is a noun).
Ideally, this should be ordered so simple things that people are going to want to do will be easy to find without looking back and forth. I'm likely to be looking at the help because I want to add or remove a service. With something like the above, I can quickly look through and see "oh -- there's the add command, and there's the things I can add".
Of course, the program doesn't need to be restructured around commands like this, but I think it might help if the documentation (including help output) were.
In bug 879378 [RHEL 7, but should be visible to everyone
and also applicable upstream], I make the point that there
are no examples I can find. For example: task #1 is
to open a hole in the firewall on a particular port number.
It took me extensive searching on Google before I could
even find out how to do that -- there were several wrong
turns, wrong information, and even now I'm not sure that
I've done it properly.
firewalld needs a lot more documentation before it can
possibly be the default in Fedora.
More documentation and better man pages are in the works currently - will be available shortly.
The manpage also has a typo:
should be --list-all
Fixed in GIT: http://git.fedorahosted.org/cgit/firewalld.git/commit/?id=9be6a1f626bc01774738a24f831175009425e1aa
Update firewall.cmd man page, use man page as firewall-cmd usage
firewalld-0.2.11-1.fc18 has been submitted as an update for Fedora 18.
* should fix your issue,
* was pushed to the Fedora 18 testing repository,
* should be available at your local mirror within two days.
Update it with:
# su -c 'yum update --enablerepo=updates-testing firewalld-0.2.11-1.fc18'
as soon as you are able to.
Please go to the following url:
then log in and leave karma (feedback).
firewalld-0.2.12-1.fc18 has been submitted as an update for Fedora 18.
firewalld-0.2.12-1.fc18 has been pushed to the Fedora 18 stable repository. If problems still persist, please make note of it in this bug report.
I've just added firewall-cmd bash completion script .
If you want to try it out before it gets into distribution,
just drop it into /etc/bash_completion.d/
$ firewall-cmd --zone=<TAB>
block dmz drop external home internal public trusted work
select let's say 'external' zone and continue
$ firewall-cmd --zone=external --add<TAB>
--add-forward-port= --add-icmp-block= --add-interface= --add-masquerade --add-port= --add-service=
and now you'll know what you can add to external zone
what next ?
$ firewall-cmd --zone=external --add-service=<TAB>
amanda-client cluster-suite ftp imaps ipsec mdns ntp ...
Isn't it awesome ? :-)
This is much better. And the bash completion is awesome indeed. Thanks all. :)