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? firewall-cmd panic enable|disable|status # controls panic mode list # returns space-separated information zones services [--zone=<zone>] icmptypes ports [--zone=<zone>] (and so on) get # returns information in specific formats interface [--zone=<zone>] active-zones add | remove [--zone=<zone>] [--timeout=#] # add or remove rules service=<service> port=<port> interface=<interface> (...) query [--verbose] # get status of a rule (same as add/remove) direct # more direct firewall control passthrough add-chain remove-chain (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: [--zone=<zone>] --list-Iall 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. https://admin.fedoraproject.org/updates/firewalld-0.2.11-1.fc18
Package firewalld-0.2.11-1.fc18: * 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: https://admin.fedoraproject.org/updates/FEDORA-2012-20206/firewalld-0.2.11-1.fc18 then log in and leave karma (feedback).
firewalld-0.2.12-1.fc18 has been submitted as an update for Fedora 18. https://admin.fedoraproject.org/updates/firewalld-0.2.12-1.fc18
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 [1]. If you want to try it out before it gets into distribution, just drop it into /etc/bash_completion.d/ Usage example: $ 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 ... ... etc. Isn't it awesome ? :-) [1] http://git.fedorahosted.org/cgit/firewalld.git/plain/shell-completion/firewall-cmd-bash-completion.sh
This is much better. And the bash completion is awesome indeed. Thanks all. :)