doc: add doc for rsgtutil

3 files changed, 55 insertions, 17 deletions

diff --git a/configure.ac b/configure.ac
index 650def0f..f444e5eb 100644
--- a/configure.ac
+++ b/configure.ac
@@ -28,6 +28,7 @@ fi
 AC_DISABLE_STATIC
 AC_PROG_LIBTOOL
 AC_CANONICAL_HOST
+AC_PATH_PROG([RST2MAN], [rst2man])
 
 PKG_PROG_PKG_CONFIG
 
diff --git a/tools/Makefile.am b/tools/Makefile.am
index 2501331e..21a32868 100644
--- a/tools/Makefile.am
+++ b/tools/Makefile.am
@@ -43,6 +43,10 @@ rsyslogd_CPPFLAGS =  $(PTHREADS_CFLAGS) $(RSRT_CFLAGS)
 rsyslogd_LDADD = ../grammar/libgrammar.la ../runtime/librsyslog.la $(ZLIB_LIBS) $(PTHREADS_LIBS) $(RSRT_LIBS) $(SOL_LIBS) $(LIBEE_LIBS) $(LIBLOGNORM_LIBS) $(LIBUUID_LIBS)
 rsyslogd_LDFLAGS = -export-dynamic
 
+EXTRA_DIST = $(man_MANS) \
+	rsgtutil.rst \
+	recover_qi.pl
+
 if ENABLE_DIAGTOOLS
 sbin_PROGRAMS += rsyslog_diag_hostname msggen zpipe
 rsyslog_diag_hostname_SOURCES = gethostn.c
@@ -67,8 +71,10 @@ bin_PROGRAMS += rsgtutil
 rsgtutil = rsgtutil.c
 rsgtutil_CPPFLAGS =  $(RSRT_CFLAGS) $(GUARDTIME_CFLAGS)
 rsgtutil_LDADD = ../runtime/librsgt.la $(GUARDTIME_LIBS)
+rsgtutil.1: rsgtutil.rst
+	$(AM_V_GEN) $(RST2MAN) $< $@
+man1_MANS = rsgtutil.1
+CLEANFILES = rsgtutil.1
+EXTRA_DIST+= rsgtutil.1
 endif
 endif
-
-EXTRA_DIST = $(man_MANS) \
-	recover_qi.pl
diff --git a/tools/rsgtutil.rst b/tools/rsgtutil.rst
index f2b097dc..c5782c5a 100644
--- a/tools/rsgtutil.rst
+++ b/tools/rsgtutil.rst
@@ -79,7 +79,43 @@ unpredictable.
 dump
 ----
 
-This dump a the TLV header.
+The provided *signature* files are dumped. For each top-level record, the*u
+type code is printed as well as q short description. If there is additional
+information available, it will be printed in tab-indented lines below the
+main record dump. The actual *log* files need not to be present.
+
+verify
+------
+
+This mode does not work with stdin. On the command line, the *log* file names
+are specified. The corresponding *signature* files (ending on ".gtsig") must also
+be preset at the same location as the log file. In verify mode, both the log
+and signature file is read and the validity of the log file checked. If verification
+errors are detected these are printed and processing of the file aborted. By default,
+each file is verified individually, without taking cross-file hash chains into
+account (so the order of files on the command line does not matter).
+
+Note that the actual amount of what can be verified depends on the parameters with
+which the signature file was written. If record and tree hashes are present, they
+will be verified and thus fine-granular error reporting is possible. If they are
+not present, only the block signature itself is verified.
+
+By default, only errors are printed. To also print successful verifications, use the
+**--show-verified** option.
+
+
+detect-file-type
+----------------
+This mode is used to detect the type of some well-know files used inside the 
+signature system. The detection is based on the file header. This mode is
+primarily a debug aid.
+
+
+show-sigblock-params
+--------------------
+This mode is used to print signature block parameters. It is similar to *dump*
+mode, but will ignore everything except signature blocks. Also, some additional
+meta information is printed. This mode is primarily a debug aid.
 
 EXIT CODES
 ==========
@@ -91,22 +127,17 @@ other code in case of failures.
 EXAMPLES
 ========
 
-::
-
-    rsgtutil --verify logfile
+**rsgtutil --verify logfile**
 
-    This verifies the file "logfile" via its associated signature file
-    "logfile.gtsig". If errors are detected, these are reported to stderr.
-    Otherwise, rsgtutil terminates without messages.
-
-
-::
+This verifies the file "logfile" via its associated signature file
+"logfile.gtsig". If errors are detected, these are reported to stderr.
+Otherwise, rsgtutil terminates without messages.
 
-    rsgtutil --dump logfile.gtsig
+**rsgtutil --dump logfile.gtsig**
 
-    This dumps the content of the signature file "logfile.gtsig". The
-    actual log file is not being processed and does not even need to be
-    present.
+This dumps the content of the signature file "logfile.gtsig". The
+actual log file is not being processed and does not even need to be
+present.
 
 SEE ALSO
 ========