Bug 1728890 - RFE - Mention syntax changes in man / error output
Summary: RFE - Mention syntax changes in man / error output
Keywords:
Status: CLOSED ERRATA
Alias: None
Product: Red Hat Enterprise Linux 8
Classification: Red Hat
Component: pcs
Version: 8.0
Hardware: Unspecified
OS: Unspecified
high
medium
Target Milestone: rc
: 8.2
Assignee: Tomas Jelinek
QA Contact: cluster-qe@redhat.com
URL:
Whiteboard:
: 1829198 (view as bug list)
Depends On:
Blocks:
TreeView+ depends on / blocked
 
Reported: 2019-07-10 21:29 UTC by Madison Kelly
Modified: 2020-04-30 11:18 UTC (History)
8 users (show)

Fixed In Version: pcs-0.10.3-1.el8
Doc Type: Enhancement
Doc Text:
Feature: List changes compared to RHEL 7 in pcs man page. Make removed and changed commands print an explanatory error message pointing to that section for more details. Reason: To make it easier for the users to deal with changes done in pcs commands in RHEL 8. Result: Removed and changed commands print an error message pointing to a new man page section summarizing the changes.
Clone Of:
Environment:
Last Closed: 2020-04-28 15:27:56 UTC
Type: Bug
Target Upstream Version:


Attachments (Terms of Use)
proposed fix (20.12 KB, patch)
2019-09-10 11:41 UTC, Tomas Jelinek
no flags Details | Diff


Links
System ID Private Priority Status Summary Last Updated
Red Hat Product Errata RHEA-2020:1568 0 None None None 2020-04-28 15:28:35 UTC

Description Madison Kelly 2019-07-10 21:29:41 UTC
Description of problem:

The pcs commands mentioned in the upstream documentation (Clusters from Scratch - Section 2.6.3 as an example) mentions;

====
On either node, use pcs cluster auth to authenticate as the hacluster user:
-----------------------------------------------------------
| [root@pcmk-1 ~]# pcs cluster auth pcmk-1 pcmk-2         |
| Username: hacluster                                     |
| Password:                                               |
| pcmk-2: Authorized                                      |
| pcmk-1: Authorized                                      |
-----------------------------------------------------------
====

This generates the error;

====
Usage: pcs cluster auth...
    auth [-u <username>] [-p <password>]
        Authenticate pcs/pcsd to pcsd on nodes configured in the local cluster.
====

In the official Red Hat 8 High-Availability documentation, section 4.1 part 5 (https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/8/html/configuring_and_managing_high_availability_clusters/assembly_creating-high-availability-cluster-configuring-and-managing-high-availability-clusters#proc_installing-cluster-software-creating-high-availability-cluster), it shows the proper syntax;

====
Authenticate the pcs user hacluster for each node in the cluster on the node from which you will be running pcs.

The following command authenticates user hacluster on z1.example.com for both of the nodes in the example two-node cluster, z1.example.com and z2.example.com.

------------------------------------------------------------
| [root@z1 ~]# pcs host auth z1.example.com z2.example.com |
| Username: hacluster                                      |
| Password:                                                |
| z1.example.com: Authorized                               |
| z2.example.com: Authorized                               |
------------------------------------------------------------
====

The difference (cluster -> host) is easy to miss. There are also other subtle syntax changes, like;

====
# RHEL 7 / Upstream docs;
pcs cluster setup --name mycluster pcmk-1 pcmk-2
# RHEL 8
pcs cluster setup mycluster --start pcmk-1 pcmk-2
====

The old syntax generates the error;

====
Error: Specified options '--name' are not supported in this command
====

This is a bit more helpful, but still not very obvious.

Request For Enhancement;

Given that a lot of people experienced with RHEL 7 syntax will likely hit similar issues, I think it is worth putting specific messages in the output. Something like;

====
Usage: pcs cluster auth...
    auth [-u <username>] [-p <password>]
        Authenticate pcs/pcsd to pcsd on nodes configured in the local cluster.

Hint: Syntax has changed from previous versions. See 'man pcs -> Changes'
====

And then add to the man page a section on syntax changes that occurred between RHEL 7 and 8 (or a pointer to an online / Access article covering the changes).


Version-Release number of selected component (if applicable):

pcs v. 0.10.1


How reproducible:

n/a


Steps to Reproduce:
1. n/a
2.
3.

Actual results:

n/a


Expected results:

n/a


Additional info:

RFE, not a bug.

Comment 1 Tomas Jelinek 2019-07-16 07:34:06 UTC
All the changes are covered in pcs changelog. On the other hand, I guess users mostly read the man page only and they rarely go to the changelog. So it is worth covering the changes in the man page as well.

We also plan to update Clusters from Scratch, I'll coordinate with pacemaker team on when and how we can do that.

Comment 3 Tomas Jelinek 2019-09-10 11:41:02 UTC
Created attachment 1613553 [details]
proposed fix

Added a section in pcs man page. Affected commands print error messages pointing to that section. The list of changes is available in CHANGELOG.md as well.

Clusters from Scratch document has been updated upstream in https://github.com/ClusterLabs/pacemaker/commit/1a4e5c9fd2b15519ae17f2fdbd70ba483a31a736

Comment 4 Miroslav Lisik 2019-10-23 15:26:48 UTC
After fix:

[root@r81-node-01 ~]# rpm -q pcs
pcs-0.10.3-1.el8.x86_64

Pcs man page has new section "CHANGES IN PCS-0.10":

[root@r81-node-01 ~]# MANWIDTH=72 man pcs | grep -A 3 -i "CHANGES in PCS-0.10"
CHANGES IN PCS-0.10
       This section summarizes the most important changes in  commands
       done in pcs-0.10.x compared to pcs-0.9.x. For detailed descrip‐
       tion of current commands see above.


If old syntax is used in pcs command, then pcs adds a hit about pcs changes in an error message:

[root@r81-node-01 ~]# pcs cluster auth -u hacluster -p password r81-node-0{1,2}

Usage: pcs cluster auth...
    auth [-u <username>] [-p <password>]
        Authenticate pcs/pcsd to pcsd on nodes configured in the local cluster.

Hint: Syntax has changed from previous version. See 'man pcs' -> Changes in pcs-0.10.

[root@r81-node-01 ~]# pcs cluster setup --name TestCluster r81-node-0{1,2}
Error: Specified options '--name' are not supported in this command
Hint: Syntax has changed from previous version. See 'man pcs' -> Changes in pcs-0.10.

[root@r81-node-01 ~]# pcs stonith sbd enable --watchdog=/dev/watchdog0
<snip>

option --watchdog not recognized
Hint: Syntax has changed from previous version. See 'man pcs' -> Changes in pcs-0.10.

Comment 6 Tomas Jelinek 2019-11-26 09:15:12 UTC
Updated Clusters from Scratch document has been released.

Comment 10 errata-xmlrpc 2020-04-28 15:27:56 UTC
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/RHEA-2020:1568

Comment 11 Tomas Jelinek 2020-04-30 11:18:38 UTC
*** Bug 1829198 has been marked as a duplicate of this bug. ***


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