Bug 1476862
| Summary: | pcs quorum help: Improve 'device add' syntax guidance | ||||||
|---|---|---|---|---|---|---|---|
| Product: | Red Hat Enterprise Linux 7 | Reporter: | John Ruemker <jruemker> | ||||
| Component: | pcs | Assignee: | Tomas Jelinek <tojeline> | ||||
| Status: | CLOSED ERRATA | QA Contact: | cluster-qe <cluster-qe> | ||||
| Severity: | medium | Docs Contact: | |||||
| Priority: | medium | ||||||
| Version: | 7.4 | CC: | cfeist, cluster-maint, idevat, jpokorny, jruemker, omular, rsteiger, tojeline | ||||
| Target Milestone: | rc | ||||||
| Target Release: | --- | ||||||
| Hardware: | All | ||||||
| OS: | Linux | ||||||
| Whiteboard: | |||||||
| Fixed In Version: | pcs-0.9.165-1.el7 | Doc Type: | Bug Fix | ||||
| Doc Text: |
Make the man page and usage for the 'pcs quorum device add' command more comprehensible. Clarify which parameters are mandatory and which are optional. Provide pointers to corosync man page.
|
Story Points: | --- | ||||
| Clone Of: | Environment: | ||||||
| Last Closed: | 2018-10-30 08:05:31 UTC | Type: | Bug | ||||
| Regression: | --- | Mount Type: | --- | ||||
| Documentation: | --- | CRM: | |||||
| Verified Versions: | Category: | --- | |||||
| oVirt Team: | --- | RHEL 7.3 requirements from Atomic Host: | |||||
| Cloudforms Team: | --- | Target Upstream Version: | |||||
| Embargoed: | |||||||
| Attachments: |
|
||||||
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 |
Description of problem: 'pcs quorum help' currently includes this: device add [<generic options>] model <device model> [<model options>] Add a quorum device to the cluster. Quorum device needs to be created first by "pcs qdevice setup" command. It is not possible to use more than one quorum device in a cluster simultaneously. Generic options, model and model options are all documented in corosync-qdevice(8) man page. It mentions vaguely the generic options and model options, but gives no information and lists them in [] which tends to imply optional. Yet: # pcs quorum device add model net Error: required options 'algorithm', 'host' are missing The manpage doesn't make any distinction of "generic options" vs "model options", so the user would have to guess which ones apply to each category. And the help content doesn't give any reference for the syntax either. A first-time user is unlikely to get this right, and would likely need some other reference to guide them through this. That makes for a challenging user experience. We should improve the help output so first-time users can get through this based on the help output alone. Version-Release number of selected component (if applicable): pcs-0.9.157-1.el7.x86_64