Bug 876394 - firewall-cmd help should be human-readable and explain what options do
Summary: firewall-cmd help should be human-readable and explain what options do
Keywords:
Status: CLOSED CURRENTRELEASE
Alias: None
Product: Fedora
Classification: Fedora
Component: firewalld
Version: rawhide
Hardware: Unspecified
OS: Unspecified
unspecified
unspecified
Target Milestone: ---
Assignee: Thomas Woerner
QA Contact: Fedora Extras Quality Assurance
URL:
Whiteboard:
Depends On:
Blocks: 879378
TreeView+ depends on / blocked
 
Reported: 2012-11-14 01:19 UTC by Matthew Miller
Modified: 2013-02-12 17:56 UTC (History)
3 users (show)

Fixed In Version:
Doc Type: Bug Fix
Doc Text:
Clone Of:
Environment:
Last Closed: 2013-01-18 20:39:31 UTC
Type: Bug


Attachments (Terms of Use)

Description Matthew Miller 2012-11-14 01:19:50 UTC
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?)

Comment 1 Jiri Popelka 2012-11-14 16:32:10 UTC
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.

Comment 2 Matthew Miller 2012-11-14 21:06:29 UTC
(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.

Comment 3 Richard W.M. Jones 2012-11-22 20:13:38 UTC
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.

Comment 4 Thomas Woerner 2012-11-23 12:53:08 UTC
More documentation and better man pages are in the works currently - will be available shortly.

Comment 5 Brian Lane 2012-11-24 18:15:02 UTC
The manpage also has a typo:

 [--zone=<zone>] --list-Iall

should be --list-all

Comment 6 Thomas Woerner 2012-12-11 19:57:39 UTC
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

Comment 7 Fedora Update System 2012-12-11 20:46:08 UTC
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

Comment 8 Fedora Update System 2012-12-11 23:29:38 UTC
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).

Comment 9 Fedora Update System 2013-01-14 16:20:51 UTC
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

Comment 10 Fedora Update System 2013-01-18 20:39:33 UTC
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.

Comment 11 Jiri Popelka 2013-02-01 13:21:00 UTC
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

Comment 12 Matthew Miller 2013-02-12 17:56:19 UTC
This is much better. And the bash completion is awesome indeed. Thanks all. :)


Note You need to log in before you can comment on or make changes to this bug.