Add preliminary documentation for rspamadm.

6 files changed, 231 insertions, 36 deletions

diff --git a/CMakeLists.txt b/CMakeLists.txt
index e7a143b36..6248a85b2 100644
--- a/CMakeLists.txt
+++ b/CMakeLists.txt
@@ -1095,6 +1095,7 @@ ENDIF(CMAKE_SYSTEM_NAME STREQUAL "Linux" AND WANT_SYSTEMD_UNITS MATCHES "ON")
 # Manual pages
 INSTALL(FILES "doc/rspamd.8" DESTINATION ${MANDIR}/man8)
 INSTALL(FILES "doc/rspamc.1" DESTINATION ${MANDIR}/man1)
+INSTALL(FILES "doc/rspamadm.1" DESTINATION ${MANDIR}/man1)
 
 # Install webui
 IF(INSTALL_WEBUI MATCHES "ON")
diff --git a/doc/Makefile b/doc/Makefile
index 5b5107e65..f24fc2551 100644
--- a/doc/Makefile
+++ b/doc/Makefile
@@ -5,12 +5,14 @@ LUADOC ?= doxydown/doxydown.pl
 
 all: man
 
-man: rspamd.8 rspamc.1
+man: rspamd.8 rspamc.1 rspamadm.1
 
 rspamd.8: rspamd.8.md
 	$(PANDOC) -s -f markdown -t man -o rspamd.8 rspamd.8.md 
 rspamc.1: rspamc.1.md
-	$(PANDOC) -s -f markdown -t man -o rspamc.1 rspamc.1.md 
+	$(PANDOC) -s -f markdown -t man -o rspamc.1 rspamc.1.md
+rspamadm.1: rspamadm.1.md
+	$(PANDOC) -s -f markdown -t man -o rspamadm.1 rspamadm.1.md
 	
 lua-doc: lua_regexp lua_ip lua_config lua_task lua_ucl lua_http lua_trie \
 	lua_dns lua_redis lua_upstream lua_expression lua_mimepart lua_logger lua_url \
diff --git a/doc/rspamadm.1 b/doc/rspamadm.1
new file mode 100644
index 000000000..0c7bbaeec
--- /dev/null
+++ b/doc/rspamadm.1
@@ -0,0 +1,113 @@
+.TH "RSPAMADM" "1" "" "Rspamd User Manual" ""
+.SH NAME
+.PP
+rspamadm \- rspamd administration utility
+.SH SYNOPSIS
+.PP
+rspamadm [\f[I]global_options\f[]] [\f[I]command\f[]]
+[\f[I]command_options\f[]]...
+.PP
+rspamadm \-l
+.PP
+rspamadm help
+.PP
+rspamadm help
+.PP
+rspamadm \-\-help
+.SH DESCRIPTION
+.PP
+\f[C]rspamadm\f[] is a routine to manage rspamd spam filtering system.
+It is intended to perform such actions as merging databases, performing
+configuration tests, encrypting passwords, signing configurations and so
+on.
+You can get a list of available commands by running
+.IP
+.nf
+\f[C]
+rspamadm\ \-l
+\f[]
+.fi
+.SH OPTIONS
+.TP
+.B \-h, \-\-help
+Show help message
+.RS
+.RE
+.TP
+.B \-v, \-\-verbose
+Enable verbose output
+.RS
+.RE
+.TP
+.B \-l, \-\-list\-commands
+List available commands
+.RS
+.RE
+.TP
+.B \-\-version
+Show version
+.RS
+.RE
+.TP
+.B \-\-var=\f[I]value\f[]
+Redefine ucl variable in format \f[C]VARIABLE=VALUE\f[]
+.RS
+.RE
+.SH RETURN VALUE
+.PP
+On exit \f[C]rspamadm\f[] returns \f[C]0\f[] if operation was
+successfull and an error code otherwise.
+.SH EXAMPLES
+.PP
+Get help for pw command:
+.IP
+.nf
+\f[C]
+rspamadm\ help\ pw
+rspamadm\ pw\ \-\-help
+\f[]
+.fi
+.PP
+Encrypt controller\[aq]s password:
+.IP
+.nf
+\f[C]
+rspamadm\ pw\ encrypt
+\f[]
+.fi
+.PP
+Merge fuzzy databases:
+.IP
+.nf
+\f[C]
+rspamadm\ fuzzy_merge\ \-s\ data1.sqlite\ \-s\ data2.sqlite\ \-t\ dest.sqlite
+\f[]
+.fi
+.PP
+Perform configuration test:
+.IP
+.nf
+\f[C]
+rspamadm\ configtest\ \-c\ rspamd.conf
+\f[]
+.fi
+.PP
+Test configuration strictly and redefine some ucl vars:
+.IP
+.nf
+\f[C]
+rspamadm\ \-\-var=DBDIR=/tmp\ configtest\ \-c\ ./rspamd.conf\ \-s
+\f[]
+.fi
+.PP
+Generate a keypair to use for HTTPCrypt encryption:
+.IP
+.nf
+\f[C]
+rspamadm\ keypair
+\f[]
+.fi
+.SH SEE ALSO
+.PP
+Rspamd documentation and source codes may be downloaded from
+<https://rspamd.com/>.
diff --git a/doc/rspamadm.1.md b/doc/rspamadm.1.md
new file mode 100644
index 000000000..97c5d5146
--- /dev/null
+++ b/doc/rspamadm.1.md
@@ -0,0 +1,79 @@
+% RSPAMADM(1) Rspamd User Manual
+
+# NAME
+
+rspamadm - rspamd administration utility
+
+# SYNOPSIS
+
+rspamadm [*global_options*] [*command*] [*command_options*]...
+
+rspamadm -l
+
+rspamadm help
+
+rspamadm help <command>
+
+rspamadm --help
+
+# DESCRIPTION
+
+`rspamadm` is a routine to manage rspamd spam filtering system. It is intended to perform
+such actions as merging databases, performing configuration tests, encrypting passwords,
+signing configurations and so on. You can get a list of available commands by running
+
+    rspamadm -l
+
+# OPTIONS
+
+-h, \--help
+:   Show help message
+
+-v, \--verbose
+:   Enable verbose output
+
+-l, \--list-commands
+:   List available commands
+
+\--version
+:   Show version
+
+\--var=*value*
+:   Redefine ucl variable in format `VARIABLE=VALUE`
+
+# RETURN VALUE
+
+On exit `rspamadm` returns `0` if operation was successfull and an error code otherwise.
+
+# EXAMPLES
+
+Get help for pw command:
+
+    rspamadm help pw
+    rspamadm pw --help
+
+Encrypt controller's password:
+
+    rspamadm pw encrypt
+
+Merge fuzzy databases:
+
+    rspamadm fuzzy_merge -s data1.sqlite -s data2.sqlite -t dest.sqlite
+
+Perform configuration test:
+
+    rspamadm configtest -c rspamd.conf
+
+Test configuration strictly and redefine some ucl vars:
+
+    rspamadm --var=DBDIR=/tmp configtest -c ./rspamd.conf -s
+
+
+Generate a keypair to use for HTTPCrypt encryption:
+
+    rspamadm keypair
+
+# SEE ALSO
+
+Rspamd documentation and source codes may be downloaded from
+<https://rspamd.com/>.
\ No newline at end of file
diff --git a/doc/rspamc.1 b/doc/rspamc.1
index fe2f67b2c..d33f71bab 100644
--- a/doc/rspamc.1
+++ b/doc/rspamc.1
@@ -1,7 +1,7 @@
 .TH "RSPAMC" "1" "" "Rspamd User Manual" ""
 .SH NAME
 .PP
-rspamc \- rspamd command line client
+\f[C]rspamc\f[] \- rspamd command line client
 .SH SYNOPSIS
 .PP
 rspamc [\f[I]options\f[]] [\f[I]command\f[]] [\f[I]input\-file\f[]]...
@@ -9,41 +9,41 @@ rspamc [\f[I]options\f[]] [\f[I]command\f[]] [\f[I]input\-file\f[]]...
 rspamc \-\-help
 .SH DESCRIPTION
 .PP
-Rspamc is a simple client for checking messages using rspamd or for
-learning rspamd by messages.
-Rspamc supports the following commands:
+\f[C]rspamc\f[] is a simple client for checking messages using rspamd or
+for learning rspamd by messages.
+\f[C]rspamc\f[] supports the following commands:
 .IP \[bu] 2
 Scan commands:
 .RS 2
 .IP \[bu] 2
-\f[I]symbols\f[]: scan message and show symbols (default command)
+\f[C]symbols\f[]: scan message and show symbols (default command)
 .RE
 .IP \[bu] 2
 Control commands
 .RS 2
 .IP \[bu] 2
-\f[I]learn_spam\f[]: learn message as spam
+\f[C]learn_spam\f[]: learn message as spam
 .IP \[bu] 2
-\f[I]learn_ham\f[]: learn message as ham
+\f[C]learn_ham\f[]: learn message as ham
 .IP \[bu] 2
-\f[I]fuzzy_add\f[]: add message to fuzzy storage (check \f[C]\-f\f[] and
+\f[C]fuzzy_add\f[]: add message to fuzzy storage (check \f[C]\-f\f[] and
 \f[C]\-w\f[] options for this command)
 .IP \[bu] 2
-\f[I]fuzzy_del\f[]: delete message from fuzzy storage (check
+\f[C]fuzzy_del\f[]: delete message from fuzzy storage (check
 \f[C]\-f\f[] option for this command)
 .IP \[bu] 2
-\f[I]stat\f[]: show rspamd statistics
+\f[C]stat\f[]: show rspamd statistics
 .IP \[bu] 2
-\f[I]stat_reset\f[]: show and reset rspamd statistics (useful for
+\f[C]stat_reset\f[]: show and reset rspamd statistics (useful for
 graphs)
 .IP \[bu] 2
-\f[I]counters\f[]: display rspamd symbols statistics
+\f[C]counters\f[]: display rspamd symbols statistics
 .IP \[bu] 2
-\f[I]uptime\f[]: show rspamd uptime
+\f[C]uptime\f[]: show rspamd uptime
 .IP \[bu] 2
-\f[I]add_symbol\f[]: add or modify symbol settings in rspamd
+\f[C]add_symbol\f[]: add or modify symbol settings in rspamd
 .IP \[bu] 2
-\f[I]add_action\f[]: add or modify action settings
+\f[C]add_action\f[]: add or modify action settings
 .RE
 .PP
 Control commands that modifies rspamd state are considered as privileged
@@ -54,7 +54,7 @@ This depends on a controller\[aq]s settings and is discussed in
 .PP
 \f[C]Input\ files\f[] may be either regular file(s) or a directory to
 scan.
-If no files are specified rspamc reads from the standard input.
+If no files are specified \f[C]rspamc\f[] reads from the standard input.
 Controller commands usually does not accept any input, however learn*
 and fuzzy* commands requires input.
 .SH OPTIONS
@@ -189,8 +189,8 @@ List available commands
 .RE
 .SH RETURN VALUE
 .PP
-On exit rspamc returns \f[C]0\f[] if operation was successfull and an
-error code otherwise.
+On exit \f[C]rspamc\f[] returns \f[C]0\f[] if operation was successfull
+and an error code otherwise.
 .SH EXAMPLES
 .PP
 Check stdin:
diff --git a/doc/rspamc.1.md b/doc/rspamc.1.md
index 4e723fe51..f4d089bc1 100644
--- a/doc/rspamc.1.md
+++ b/doc/rspamc.1.md
@@ -2,7 +2,7 @@
 
 # NAME
 
-rspamc - rspamd command line client
+`rspamc` - rspamd command line client
 
 # SYNOPSIS
 
@@ -12,28 +12,28 @@ rspamc --help
 
 # DESCRIPTION
 
-Rspamc is a simple client for checking messages using rspamd or for learning rspamd by messages.
-Rspamc supports the following commands:
+`rspamc` is a simple client for checking messages using rspamd or for learning rspamd by messages.
+`rspamc` supports the following commands:
 
 * Scan commands:
-	* *symbols*: scan message and show symbols (default command)
+	* `symbols`: scan message and show symbols (default command)
 * Control commands
-	* *learn_spam*: learn message as spam
-	* *learn_ham*: learn message as ham
-	* *fuzzy_add*: add message to fuzzy storage (check `-f` and `-w` options for this command)
-	* *fuzzy_del*: delete message from fuzzy storage (check `-f` option for this command)
-	* *stat*: show rspamd statistics
-	* *stat_reset*: show and reset rspamd statistics (useful for graphs)
-	* *counters*: display rspamd symbols statistics
-	* *uptime*: show rspamd uptime
-	* *add_symbol*: add or modify symbol settings in rspamd
-	* *add_action*: add or modify action settings
+	* `learn_spam`: learn message as spam
+	* `learn_ham`: learn message as ham
+	* `fuzzy_add`: add message to fuzzy storage (check `-f` and `-w` options for this command)
+	* `fuzzy_del`: delete message from fuzzy storage (check `-f` option for this command)
+	* `stat`: show rspamd statistics
+	* `stat_reset`: show and reset rspamd statistics (useful for graphs)
+	* `counters`: display rspamd symbols statistics
+	* `uptime`: show rspamd uptime
+	* `add_symbol`: add or modify symbol settings in rspamd
+	* `add_action`: add or modify action settings
 
 Control commands that modifies rspamd state are considered as privileged and basically requires a password
 to be specified with `-P` option (see **OPTIONS**, below, for details). 
 This depends on a controller's settings and is discussed in `rspamd-workers` page.
 
-`Input files` may be either regular file(s) or a directory to scan. If no files are specified rspamc reads
+`Input files` may be either regular file(s) or a directory to scan. If no files are specified `rspamc` reads
 from the standard input. Controller commands usually does not accept any input, however learn* and fuzzy* commands
 requires input. 
 
@@ -116,7 +116,7 @@ requires input.
 
 # RETURN VALUE
 
-On exit rspamc returns `0` if operation was successfull and an error code otherwise.
+On exit `rspamc` returns `0` if operation was successfull and an error code otherwise.
 
 # EXAMPLES