Ticket 50028 - Revise ds-replcheck usage

Description:  Revised the tools usage to be cleaner and more intuitive.
              Added a "-y" option to use a password file.
              Added a "state" function to just return an RUV comparison
              Moved all the process status messages to only be displayed in verbose mode.

https://pagure.io/389-ds-base/issue/50028

Reviewed by: spichugi(Thanks!)

dirsrvtests/tests/suites/ds_tools/replcheck_test.py

@@ -125,24 +125,48 @@ def replcheck_cmd_list(topo_tls_ldapi):
         inst.start()
 
     ds_replcheck_path = os.path.join(m1.ds_paths.bin_dir, 'ds-replcheck')
-    replcheck_cmd = [[ds_replcheck_path, '-b', DEFAULT_SUFFIX, '-D', DN_DM, '-w', PW_DM, '-l', '1',
-                      '-m', 'ldap://{}:{}'.format(m1.host, m1.port), '--conflict',
+
+    replcheck_cmd = [[ds_replcheck_path, 'online', '-b', DEFAULT_SUFFIX, '-D', DN_DM, '-w', PW_DM, '-l', '1',
+                      '-m', 'ldap://{}:{}'.format(m1.host, m1.port), '--conflicts',
                       '-r', 'ldap://{}:{}'.format(m2.host, m2.port)],
-                     [ds_replcheck_path, '-b', DEFAULT_SUFFIX, '-D', DN_DM, '-w', PW_DM, '-l', '1',
-                      '-m', 'ldaps://{}:{}'.format(m1.host, m1.sslport), '--conflict',
+                     [ds_replcheck_path, 'online', '-b', DEFAULT_SUFFIX, '-D', DN_DM, '-w', PW_DM, '-l', '1',
+                      '-m', 'ldaps://{}:{}'.format(m1.host, m1.sslport), '--conflicts',
                       '-r', 'ldaps://{}:{}'.format(m2.host, m2.sslport)],
-                     [ds_replcheck_path, '-b', DEFAULT_SUFFIX, '-D', DN_DM, '-w', PW_DM, '-l', '1',
+                     [ds_replcheck_path, 'online', '-b', DEFAULT_SUFFIX, '-D', DN_DM, '-w', PW_DM, '-l', '1',
                       '-m', 'ldap://{}:{}'.format(m1.host, m1.port), '-Z', m1.get_ssca_dir(),
-                      '-r', 'ldap://{}:{}'.format(m2.host, m2.port), '--conflict'],
-                     [ds_replcheck_path, '-b', DEFAULT_SUFFIX, '-D', DN_DM, '-w', PW_DM, '-l', '1',
+                      '-r', 'ldap://{}:{}'.format(m2.host, m2.port), '--conflicts'],
+                     [ds_replcheck_path, 'online', '-b', DEFAULT_SUFFIX, '-D', DN_DM, '-w', PW_DM, '-l', '1',
                       '-m', 'ldapi://%2fvar%2frun%2fslapd-{}.socket'.format(m1.serverid), '--conflict',
                       '-r', 'ldapi://%2fvar%2frun%2fslapd-{}.socket'.format(m2.serverid)],
-                     [ds_replcheck_path, '-b', DEFAULT_SUFFIX, '--conflict',
-                      '-M', '/tmp/export_{}.ldif'.format(m1.serverid),
-                      '-R', '/tmp/export_{}.ldif'.format(m2.serverid)]]
+                     [ds_replcheck_path, 'offline', '-b', DEFAULT_SUFFIX, '--conflicts', '--rid', '1',
+                      '-m', '/tmp/export_{}.ldif'.format(m1.serverid),
+                      '-r', '/tmp/export_{}.ldif'.format(m2.serverid)]]
     return replcheck_cmd
 
 
+def test_state(topo_tls_ldapi):
+    """Check "state" report
+
+    :id: 1cc6b28b-8a42-45fb-ab50-9552db0ac178
+    :setup: Two master replication
+    :steps:
+        1. Get the replication state value
+        2. The state value is as expected
+    :expectedresults:
+        1. It should be successful
+        2. It should be successful
+    """
+    m1 = topo_tls_ldapi.ms["master1"]
+    m2 = topo_tls_ldapi.ms["master2"]
+    ds_replcheck_path = os.path.join(m1.ds_paths.bin_dir, 'ds-replcheck')
+
+    tool_cmd = [ds_replcheck_path, 'state', '-b', DEFAULT_SUFFIX, '-D', DN_DM, '-w', PW_DM,
+                '-m', 'ldaps://{}:{}'.format(m1.host, m1.sslport),
+                '-r', 'ldaps://{}:{}'.format(m2.host, m2.sslport)]
+    result = subprocess.check_output(tool_cmd, encoding='utf-8')
+    assert (result.rstrip() == "Replication State: Master and Replica are in perfect synchronization")
+
+
 def test_check_ruv(topo_tls_ldapi):
     """Check that the report has RUV
 

man/man1/ds-replcheck.1

@@ -1,93 +1,163 @@
-.\"                                      Hey, EMACS: -*- nroff -*-
-.\" First parameter, NAME, should be all caps
-.\" Second parameter, SECTION, should be 1-8, maybe w/ subsection
-.\" other parameters are allowed: see man(7), man(1)
-.TH DS-REPLCHECK 1 "Feb 14, 2018"
-.\" Please adjust this date whenever revising the manpage.
-.\"
-.\" Some roff macros, for reference:
-.\" .nh        disable hyphenation
-.\" .hy        enable hyphenation
-.\" .ad l      left justify
-.\" .ad b      justify to both left and right margins
-.\" .nf        disable filling
-.\" .fi        enable filling
-.\" .br        insert line break
-.\" .sp <n>    insert n+1 empty lines
-.\" for manpage-specific macros, see man(7)
-.SH NAME 
-ds-replcheck - Performs replication synchronization report between two replicas
-
+.TH DS-REPLCHECK 1 "Nov 26, 2018"
+.SH NAME
+ds-replcheck
 .SH SYNOPSIS
-ds-replcheck [-h] [-o FILE] [-D BINDDN] [[-w BINDPW] [-W]] [-m MURL]
-             [-r RURL] [-b SUFFIX] [-l LAG] [-Z CERTDIR]
-             [-i IGNORE] [-p PAGESIZE] [-M MLDIF] [-R RLDIF]
-
+.B ds-replcheck
+[-h] [-v] {online,offline,state} ...
 .SH DESCRIPTION
-ds-replcheck has two operating modes: offline - which compares two LDIF files (generated by db2ldif -r), and online mode - which queries each server to gather the entries for comparisions.  The tool reports on missing entries, entry inconsistencies, tombstones, conflict entries, database RUVs, and entry counts.
-
+Replication Comparison Tool (v2.0). This script can be used to compare two
+.br
+replicas to see if they are in sync.
 .SH OPTIONS
+.SS
+\fBSub-commands\fR
+.TP
+\fBds-replcheck\fR \fI\,online\/\fR
+Compare two online replicas for differences
+.TP
+\fBds-replcheck\fR \fI\,offline\/\fR
+Compare two replication LDIF files for differences (LDIF file generated by 'db2ldif -r')
+.TP
+\fBds-replcheck\fR \fI\,state\/\fR
+Get the general state of replication between two replicas
 
-A summary of options is included below:
+.SH OPTIONS 'ds-replcheck state'
+usage: ds-replcheck online [-h] -m MURL -r RURL -b SUFFIX -D BINDDN
+                           [-w BINDPW] [-W] [-y PASS_FILE] [-Z CERTDIR] 
 
 .TP
-.B \fB\-h\fR
-.br
-Display usage
+\fB\-m\fR \fI\,MURL\/\fR, \fB\-\-master\-url\fR \fI\,MURL\/\fR
+The LDAP URL for the Master server
+
 .TP
-.B \fB\-D\fR \fIRoot DN\fR
-The Directory Manager DN, or root DN.a (online mode)
+\fB\-r\fR \fI\,RURL\/\fR, \fB\-\-replica\-url\fR \fI\,RURL\/\fR
+The LDAP URL for the Replica server
+
 .TP
-.B \fB\-w\fR \fIPASSWORD\fR
-The Directory Manager password (online mode)
+\fB\-b\fR \fI\,SUFFIX\/\fR, \fB\-\-suffix\fR \fI\,SUFFIX\/\fR
+Replicated suffix
+
 .TP
-.B \fB\-W\fR
-.br
-Prompt for the Directory Manager password (online mode)
+\fB\-D\fR \fI\,BINDDN\/\fR, \fB\-\-bind\-dn\fR \fI\,BINDDN\/\fR
+The Bind DN
+
+.TP
+\fB\-w\fR \fI\,BINDPW\/\fR, \fB\-\-bind\-pw\fR \fI\,BINDPW\/\fR
+The Bind password
+
 .TP
-.B \fB\-m\fR \fILDAP_URL\fR
-The LDAP Url for the first replica (online mode)
+\fB\-W\fR, \fB\-\-prompt\fR
+Prompt for the bind DN password
+
 .TP
-.B \fB\-r\fR \fILDAP URL\fR
-The LDAP Url for the second replica (online mode)
+\fB\-y\fR \fI\,PASS_FILE\/\fR, \fB\-\-pass\-file\fR \fI\,PASS_FILE\/\fR
+A text file containing the clear text password for the bind dn
+
 .TP
-.B \fB\-b\fR \fISUFFIX\fR
-The replication suffix.  (online & offline)
+\fB\-Z\fR \fI\,CERTDIR\/\fR, \fB\-\-cert\-dir\fR \fI\,CERTDIR\/\fR
+The certificate database directory for secure connections
+
+
+.SH OPTIONS 'ds-replcheck online'
+usage: ds-replcheck online [-h] -m MURL -r RURL --rid RID -b SUFFIX -D BINDDN
+                           [-w BINDPW] [-W] [-y PASS_FILE] [-l LAG] [-c]
+                           [-Z CERTDIR] [-i IGNORE] [-p PAGESIZE] [-o FILE]
+
+
 .TP
-.B \fB\-l\fR \fILag time\fR
-If an inconsistency is detected, and it is within this lag allowance it will *NOT* be reported.  (online mode)
+\fB\-m\fR \fI\,MURL\/\fR, \fB\-\-master\-url\fR \fI\,MURL\/\fR
+The LDAP URL for the Master server
+
 .TP
-.B \fB\-Z\fR \fICERT DIR\fR
-The directory containing a certificate database for StartTLS/SSL connections.  (online mode)
+\fB\-r\fR \fI\,RURL\/\fR, \fB\-\-replica\-url\fR \fI\,RURL\/\fR
+The LDAP URL for the Replica server
+
 .TP
-.B \fB\-i\fR \fIIGNORE LIST\fR
-Comma separated list of attributes to ignore in the report  (online & offline)
+\fB\-b\fR \fI\,SUFFIX\/\fR, \fB\-\-suffix\fR \fI\,SUFFIX\/\fR
+Replicated suffix
+
 .TP
-.B \fB\-c\fR
-.br
+\fB\-D\fR \fI\,BINDDN\/\fR, \fB\-\-bind\-dn\fR \fI\,BINDDN\/\fR
+The Bind DN
+
+.TP
+\fB\-w\fR \fI\,BINDPW\/\fR, \fB\-\-bind\-pw\fR \fI\,BINDPW\/\fR
+The Bind password
+
+.TP
+\fB\-W\fR, \fB\-\-prompt\fR
+Prompt for the bind DN password
+
+.TP
+\fB\-y\fR \fI\,PASS_FILE\/\fR, \fB\-\-pass\-file\fR \fI\,PASS_FILE\/\fR
+A text file containing the clear text password for the bind dn
+
+.TP
+\fB\-l\fR \fI\,LAG\/\fR, \fB\-\-lag\-time\fR \fI\,LAG\/\fR
+The amount of time to ignore inconsistencies (default 300 seconds)
+
+.TP
+\fB\-c\fR, \fB\-\-conflicts\fR
 Display verbose conflict entry information
+
 .TP
-.B \fB\-M\fR \fILDIF FILE\fR
-The LDIF file for the first replica  (offline mode)
+\fB\-Z\fR \fI\,CERTDIR\/\fR, \fB\-\-cert\-dir\fR \fI\,CERTDIR\/\fR
+The certificate database directory for secure connections
+
 .TP
-.B \fB\-R\fR \fILDIF FILE\fR
-The LDIF file for the second replica  (offline mode)
+\fB\-i\fR \fI\,IGNORE\/\fR, \fB\-\-ignore\fR \fI\,IGNORE\/\fR
+Comma separated list of attributes to ignore
+
 .TP
-.B \fB\-p\fR \fIPAGE SIZE\fR
-The page size used for the paged result searches that the tool performs.  The default is 500.  (online mode)
+\fB\-p\fR \fI\,PAGESIZE\/\fR, \fB\-\-page\-size\fR \fI\,PAGESIZE\/\fR
+The paged\-search result grouping size (default 500 entries)
+
 .TP
-.B \fB\-o\fR \fIOUTPUT FILE\fR
-The file to write the report to.  (online and offline)
+\fB\-o\fR \fI\,FILE\/\fR, \fB\-\-out\-file\fR \fI\,FILE\/\fR
+The output file
+
+.SH OPTIONS 'ds-replcheck offline'
+usage: ds-replcheck offline [-h] -m MLDIF -r RLDIF --rid RID -b SUFFIX [-c]
+                            [-i IGNORE] [-o FILE]
 
-.SH EXAMPLE
-ds-replcheck -D "cn=directory manager" -w PASSWORD -m ldap://myhost.domain.com:389 -r ldap://otherhost.domain.com:389 -b "dc=example,dc=com" -Z /etc/dirsrv/slapd-myinstance
 
-ds-replcheck -b dc=example,dc=com -M /tmp/replicaA.ldif -R /tmp/replicaB.ldif
+.TP
+\fB\-m\fR \fI\,MLDIF\/\fR, \fB\-\-master\-ldif\fR \fI\,MLDIF\/\fR
+Master LDIF file
+
+.TP
+\fB\-r\fR \fI\,RLDIF\/\fR, \fB\-\-replica\-ldif\fR \fI\,RLDIF\/\fR
+Replica LDIF file
+
+.TP
+\fB\-\-rid\fR \fI\,RID\/\fR
+The Replica Identifier (rid) for the "Master" server
+
+.TP
+\fB\-b\fR \fI\,SUFFIX\/\fR, \fB\-\-suffix\fR \fI\,SUFFIX\/\fR
+Replicated suffix
+
+.TP
+\fB\-c\fR, \fB\-\-conflicts\fR
+Display verbose conflict entry information
+
+.TP
+\fB\-i\fR \fI\,IGNORE\/\fR, \fB\-\-ignore\fR \fI\,IGNORE\/\fR
+Comma separated list of attributes to ignore
+
+.TP
+\fB\-o\fR \fI\,FILE\/\fR, \fB\-\-out\-file\fR \fI\,FILE\/\fR
+The output file
+
+.TP
+\fB\-v\fR, \fB\-\-verbose\fR
+Verbose output
 
 .SH AUTHOR
 ds-replcheck was written by the 389 Project.
+
 .SH "REPORTING BUGS"
 Report bugs to https://pagure.io/389-ds-base/new_issue
+
 .SH COPYRIGHT
 Copyright \(co 2018 Red Hat, Inc.
-