I recognize that the optional vs mandatory designation of model options results from the fact that different models could require different mandatory options.  I think we should consider just documenting this in the specific case of 'net' model, since that's all we have right now.  Or alternatively, document the generic version and then _also_ the net version.

So for example:

    device add [<corosync-qdevice options>] model <model> <model mandatory options> [<corosync-qdevice configuration>]

        Add a quorum device to the cluster. A qnetd host should be configured
        first with 'pcs qdevice setup'.  It is not possible to use more
        than one quorum device in a cluster simultaneously. 

        corosync-qdevice(8) man page lists available corosync-qdevice options 
        and configuration.  Configuration entries can be specified in 
        name=value pairs.  

    device add [<corosync-qdevice options>] model net host=<corosync-qnetd host> algorithm=(lms|ffs) [<corosync-qdevice configuration>]
        Add a quorum device to the cluster. A corosync-qnetd host should be 
        configured first with 'pcs qdevice setup'.  It is not possible to use 
        more than one quorum device in a cluster simultaneously. 

        corosync-qdevice(8) man page lists available corosync-qdevice options 
        and configuration.  Configuration entries can be specified in 
        name=value pairs.  

        Example:  
           pcs quorum device add model net host=qnetd.internal.example.com algorithm=lms tls=required

Apparently tls is not an allowed model option, so change the example to use one of: 

   Error: invalid quorum device model option 'tls', allowed options are: algorithm, connect_timeout, force_ip_version, host, port, tie_breaker, use --force to override

Side-node: why no tls?  Its in the manpage.

Turns out my understanding of the generic options was inaccurate - which I think further supports clarifying the help output.

As a result: my suggested improved text is not valid.

(In reply to John Ruemker from comment #2)
> Apparently tls is not an allowed model option, so change the example to use
> one of: 
> 
>    Error: invalid quorum device model option 'tls', allowed options are:
> algorithm, connect_timeout, force_ip_version, host, port, tie_breaker, use
> --force to override
> 
> Side-node: why no tls?  Its in the manpage.

Pcs always sets qdevice with tls enabled.

This is worth mentioning in pcs help.

In the meantime the support for qdevice heuristics has been added which complicates the command even further. On the other hand, there is only one model supported, so we can drop the generic version and simplify the help text a bit.

John, what do you think about this:

device add [<generic options>] model <device model> [<model options>]
        [heuristics <heuristics options>]
    Add a quorum device to the cluster. Quorum device should be configured
    first with "pcs qdevice setup". It is not possible to use more than one
    quorum device in a cluster simultaneously.
    Currently the only supported model is 'net'. It requires model options
    'algorithm' and 'host' to be specified. Options are documented in
    corosync-qdevice(8) man page; generic options are 'sync_timeout' and
    'timeout', for model net options check the quorum.device.net section, for
    heuristics options see the quorum.device.heuristics section. Pcs
    automatically creates TLS certificates and sets the 'tls' model option to
    the default value 'on'.
    Example: pcs quorum device add model net host=qnetd.internal.example.com
        algorithm=lms

Looks good.  

Thanks

Created attachment 1447751 [details]
proposed fix

After Fix:

[ant ~] $ rpm -q pcs pcs-snmp
pcs-0.9.165-1.el7.x86_64
pcs-snmp-0.9.165-1.el7.x86_64

[ant ~] $ pcs quorum device add -h|grep "Currently the only supported model "
        Currently the only supported model is 'net'. It requires model options

[ant ~] $ man pcs|grep "Currently the only supported model "
              Currently the only supported model is 'net'. It requires model options 'algorithm' and 'host' to be specified. Options are documented in corosync-qdevice(8) man page; generic options are 'sync_timeout' and 'timeout', for model net options check the quo‐

Since the problem described in this bug report should be
resolved in a recent advisory, it has been closed with a
resolution of ERRATA.

For information on the advisory, and where to find the updated
files, follow the link below.

If the solution does not work for you, open a new bug report.

https://access.redhat.com/errata/RHBA-2018:3066