Bug 1728890
| Summary: | RFE - Mention syntax changes in man / error output | ||||||
|---|---|---|---|---|---|---|---|
| Product: | Red Hat Enterprise Linux 8 | Reporter: | Madison Kelly <mkelly> | ||||
| Component: | pcs | Assignee: | Tomas Jelinek <tojeline> | ||||
| Status: | CLOSED ERRATA | QA Contact: | cluster-qe <cluster-qe> | ||||
| Severity: | medium | Docs Contact: | |||||
| Priority: | high | ||||||
| Version: | 8.0 | CC: | cfeist, cluster-maint, idevat, mlisik, mmazoure, omular, rnandanw, tojeline | ||||
| Target Milestone: | rc | Keywords: | FutureFeature | ||||
| Target Release: | 8.2 | ||||||
| Hardware: | Unspecified | ||||||
| OS: | Unspecified | ||||||
| Whiteboard: | |||||||
| 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.
|
Story Points: | --- | ||||
| Clone Of: | Environment: | ||||||
| Last Closed: | 2020-04-28 15:27:56 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: |
|
||||||
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. 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 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.
Updated Clusters from Scratch document has been released. 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 *** Bug 1829198 has been marked as a duplicate of this bug. *** |
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.