From e47c31784d02da27c838f554993369bc692f8a05 Mon Sep 17 00:00:00 2001 From: Vsevolod Stakhov Date: Fri, 27 Dec 2013 18:04:56 +0000 Subject: [PATCH] Migrate from pod to markdown+pandoc. --- doc/Makefile | 12 ++ doc/makeman.sh | 17 -- doc/rspamc.1 | 438 +++++++++++++++++++++--------------------------- doc/rspamc.1.md | 134 +++++++++++++++ doc/rspamc.pod | 138 --------------- doc/rspamd.8 | 316 +++++++++++++++------------------- doc/rspamd.8.md | 90 ++++++++++ doc/rspamd.pod | 79 --------- 8 files changed, 563 insertions(+), 661 deletions(-) create mode 100644 doc/Makefile delete mode 100755 doc/makeman.sh create mode 100644 doc/rspamc.1.md delete mode 100644 doc/rspamc.pod create mode 100644 doc/rspamd.8.md delete mode 100644 doc/rspamd.pod diff --git a/doc/Makefile b/doc/Makefile new file mode 100644 index 000000000..bcc5b3a9f --- /dev/null +++ b/doc/Makefile @@ -0,0 +1,12 @@ +# A simple makefile to generate documentation from .md using pandoc + +PANDOC ?= pandoc + +all: man + +man: rspamd.8 rspamc.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 diff --git a/doc/makeman.sh b/doc/makeman.sh deleted file mode 100755 index 176f37b25..000000000 --- a/doc/makeman.sh +++ /dev/null @@ -1,17 +0,0 @@ -#!/bin/sh -# Makes manual pages from pods - -POD2MAN="pod2man" -VERSION="unknown" -CMAKEFILE="../CMakeLists.txt" - -# Extract release version -if [ -f ${CMAKEFILE} ] ; then - _mjver=`fgrep 'SET(RSPAMD_VERSION_MAJOR' ${CMAKEFILE} | sed -e 's/^.*RSPAMD_VERSION_MAJOR \([0-9]\).*/\1/'` - _miver=`fgrep 'SET(RSPAMD_VERSION_MINOR' ${CMAKEFILE} | sed -e 's/^.*RSPAMD_VERSION_MINOR \([0-9]\).*/\1/'` - _pver=`fgrep 'SET(RSPAMD_VERSION_PATCH' ${CMAKEFILE} | sed -e 's/^.*RSPAMD_VERSION_PATCH \([0-9]\).*/\1/'` - VERSION="${_mjver}.${_miver}.${_pver}" -fi - -pod2man -c "Rspamd documentation" -n rspamd -s 8 -r "rspamd-${VERSION}" < rspamd.pod > rspamd.8 -pod2man -c "Rspamd documentation" -n rspamc -s 1 -r "rspamd-${VERSION}" < rspamc.pod > rspamc.1 diff --git a/doc/rspamc.1 b/doc/rspamc.1 index 3ca41ac98..73be9afb4 100644 --- a/doc/rspamc.1 +++ b/doc/rspamc.1 @@ -1,260 +1,212 @@ -.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.16) -.\" -.\" Standard preamble: -.\" ======================================================================== -.de Sp \" Vertical space (when we can't use .PP) -.if t .sp .5v -.if n .sp -.. -.de Vb \" Begin verbatim text -.ft CW -.nf -.ne \\$1 -.. -.de Ve \" End verbatim text -.ft R -.fi -.. -.\" Set up some character translations and predefined strings. \*(-- will -.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left -.\" double quote, and \*(R" will give a right double quote. \*(C+ will -.\" give a nicer C++. Capital omega is used to do unbreakable dashes and -.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, -.\" nothing in troff, for use with C<>. -.tr \(*W- -.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' -.ie n \{\ -. ds -- \(*W- -. ds PI pi -. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch -. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch -. ds L" "" -. ds R" "" -. ds C` "" -. ds C' "" -'br\} -.el\{\ -. ds -- \|\(em\| -. ds PI \(*p -. ds L" `` -. ds R" '' -'br\} -.\" -.\" Escape single quotes in literal strings from groff's Unicode transform. -.ie \n(.g .ds Aq \(aq -.el .ds Aq ' -.\" -.\" If the F register is turned on, we'll generate index entries on stderr for -.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index -.\" entries marked with X<> in POD. Of course, you'll have to process the -.\" output yourself in some meaningful fashion. -.ie \nF \{\ -. de IX -. tm Index:\\$1\t\\n%\t"\\$2" -.. -. nr % 0 -. rr F -.\} -.el \{\ -. de IX -.. -.\} -.\" -.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). -.\" Fear. Run. Save yourself. No user-serviceable parts. -. \" fudge factors for nroff and troff -.if n \{\ -. ds #H 0 -. ds #V .8m -. ds #F .3m -. ds #[ \f1 -. ds #] \fP -.\} -.if t \{\ -. ds #H ((1u-(\\\\n(.fu%2u))*.13m) -. ds #V .6m -. ds #F 0 -. ds #[ \& -. ds #] \& -.\} -. \" simple accents for nroff and troff -.if n \{\ -. ds ' \& -. ds ` \& -. ds ^ \& -. ds , \& -. ds ~ ~ -. ds / -.\} -.if t \{\ -. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" -. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' -. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' -. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' -. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' -. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' -.\} -. \" troff and (daisy-wheel) nroff accents -.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' -.ds 8 \h'\*(#H'\(*b\h'-\*(#H' -.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] -.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' -.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' -.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] -.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] -.ds ae a\h'-(\w'a'u*4/10)'e -.ds Ae A\h'-(\w'A'u*4/10)'E -. \" corrections for vroff -.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' -.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' -. \" for low resolution devices (crt and lpr) -.if \n(.H>23 .if \n(.V>19 \ -\{\ -. ds : e -. ds 8 ss -. ds o a -. ds d- d\h'-1'\(ga -. ds D- D\h'-1'\(hy -. ds th \o'bp' -. ds Th \o'LP' -. ds ae ae -. ds Ae AE -.\} -.rm #[ #] #H #V #F C -.\" ======================================================================== -.\" -.IX Title "rspamc 1" -.TH rspamc 1 "2013-02-02" "rspamd-0.5.4" "Rspamd documentation" -.\" For nroff, turn off justification. Always turn off hyphenation; it makes -.\" way too many mistakes in technical documents. -.if n .ad l -.nh -.SH "NAME" -rspamc \- a simple client for rspamd spam filtering system -.SH "SYNOPSIS" -.IX Header "SYNOPSIS" -rspamc [\fB\-h\fR \fIhost[:port]\fR] [\fB\-p\fR] [\fB\-v\fR] [\fB\-b\fR \fIbind_address\fR] [\fB\-u\fR \fIuser\fR] -[\fB\-F\fR \fIfrom\fR] [\fB\-r\fR \fIrcpt\fR] [\fB\-d\fR \fIdeliver-to\fR] -[\fB\-i\fR \fIip\fR] [\fB\-c\fR \fIclassifier\fR] [\fB\-w\fR \fIweight\fR] -[\fB\-P\fR \fIpassword\fR] [\fB\-f\fR \fIflag\fR] [\fB\-t\fR \fItimeout\fR] [command] [file [file ...]] +.TH RSPAMC 1 "" "Rspamd User Manual" +.SH NAME +.PP +rspamc - rspamd command line client +.SH SYNOPSIS +.PP +rspamc [\f[I]options\f[]] [\f[I]command\f[]] [\f[I]input-file\f[]]... +.PP +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: +.IP \[bu] 2 +Scan commands: +.RS 2 +.IP \[bu] 2 +\f[I]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 +.IP \[bu] 2 +\f[I]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]-w\f[] options for this command) +.IP \[bu] 2 +\f[I]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 +.IP \[bu] 2 +\f[I]stat_reset\f[]: show and reset rspamd statistics (useful for +graphs) +.IP \[bu] 2 +\f[I]counters\f[]: display rspamd symbols statistics +.IP \[bu] 2 +\f[I]uptime\f[]: show rspamd uptime +.IP \[bu] 2 +\f[I]add_symbol\f[]: add or modify symbol settings in rspamd +.IP \[bu] 2 +\f[I]add_action\f[]: add or modify action settings +.RE +.PP +Control commands that modifies rspamd state are considered as privileged +and basically requires a password to be specified with \f[C]-P\f[] +option (see \f[B]OPTIONS\f[], below, for details). +This depends on a controller\[aq]s settings and is discussed in +\f[C]rspamd-workers\f[] page. +.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. +Controller commands usually does not accept any input, however learn* +and fuzzy* commands requires input. +.SH OPTIONS +.PP +-h \f[I]host[:port]\f[], --connect=\f[I]host[:port]\f[] Specify host and +port +.PP +-P \f[I]password\f[], --password=\f[I]password\f[] Specify control +password +.TP +.B -c \f[I]name\f[], --classifier=\f[I]name\f[] +Classifier to learn spam or ham (bayes is used by default) +.RS +.RE +.TP +.B -w \f[I]weight\f[], --weight=\f[I]weight\f[] +Weight for fuzzy operations +.RS +.RE +.TP +.B -f \f[I]number\f[], --flag=\f[I]number\f[] +Flag for fuzzy operations +.RS +.RE +.TP +.B -p, --pass +Pass all filters +.RS +.RE +.TP +.B -v, --verbose +More verbose output +.RS +.RE +.TP +.B -i \f[I]ip address\f[], --ip=\f[I]ip address\f[] +Emulate that message was received from specified ip address +.RS +.RE +.TP +.B -u \f[I]username\f[], --user=\f[I]username\f[] +Emulate that message was from specified user +.RS +.RE +.TP +.B -d \f[I]user\@domain\f[], --deliver=\f[I]user\@domain\f[] +Emulate that message is delivered to specified user +.RS +.RE +.TP +.B -F \f[I]user\@domain\f[], --from=\f[I]user\@domain\f[] +Emulate that message is from specified user +.RS +.RE +.TP +.B -r \f[I]user\@domain\f[], --rcpt=\f[I]user\@domain\f[] +Emulate that message is for specified user +.RS +.RE +.TP +.B -t \f[I]seconds\f[], --timeout=\f[I]seconds\f[] +Timeout for waiting for a reply +.RS +.RE +.TP +.B -b \f[I]host:port\f[], --bind=\f[I]host:port\f[] +Bind to specified ip address +.RS +.RE +.TP +.B --commands +List available commands +.RS +.RE +.SH RETURN VALUE +.PP +On exit rspamc returns \f[C]0\f[] if operation was successfull and an +error code otherwise. +.SH EXAMPLES .PP -rspamc [\fB\-\-help\fR] -.SH "DESCRIPTION" -.IX Header "DESCRIPTION" -\&\fBRspamc\fR is a simple client for checking messages using rspamd or for learning rspamd by messages. -\&\fBRspamc\fR has several mandatory options for learning: \fIpassword\fR and \fIstatfile\fR. -.SH "OPTIONS" -.IX Header "OPTIONS" -.IP "\fB\-h\fR \fIhost[:port]\fR, \fB\-\-connect\fR \fIhost[:port]\fR" 4 -.IX Item "-h host[:port], --connect host[:port]" -Specify host and port for connecting to rspamd server. Default host is \fIlocalhost\fR and -default port is \fI11333\fR for checking messages and \fI11334\fR for learning and statistic. -Also it is possible to specify a unix socket for all operations (for example: -\&\fBrspamc\fR \fB\-h\fR /path/to/soket) -.IP "\fB\-b\fR \fIlocal_ip\fR, \fB\-\-bind\fR \fIlocal_ip\fR" 4 -.IX Item "-b local_ip, --bind local_ip" -Specify explicit \s-1IP\s0 address to bind a client for operations. -.IP "\fB\-u\fR \fIuser\fR, \fB\-\-user\fR \fIuser\fR" 4 -.IX Item "-u user, --user user" -Specify username for connection with rspamd server. -.IP "\fB\-F\fR \fIfrom_addr\fR, \fB\-\-from\fR \fIfrom_addr\fR" 4 -.IX Item "-F from_addr, --from from_addr" -Specify \s-1SMTP\s0 \s-1FROM\s0 address for connection with rspamd server. -.IP "\fB\-r\fR \fIrcpt_addr\fR, \fB\-\-rcpt\fR \fIrcpt_addr\fR" 4 -.IX Item "-r rcpt_addr, --rcpt rcpt_addr" -Specify \s-1SMTP\s0 \s-1RCPT\s0 \s-1TO\s0 address for connection with rspamd server. -.IP "\fB\-d\fR \fIdeliver_addr\fR, \fB\-\-deliver\fR \fIdeliver_addr\fR" 4 -.IX Item "-d deliver_addr, --deliver deliver_addr" -Specify real delivery address for connection with rspamd server. -.IP "\fB\-p\fR, \fB\-\-pass\-all\fR" 4 -.IX Item "-p, --pass-all" -Pass all filters when checking messages. Ignored in case of learning. -.IP "\fB\-v\fR, \fB\-\-verbose\fR" 4 -.IX Item "-v, --verbose" -Be more verbose while displaying results. For example show descriptions of symbols. -.IP "\fB\-P\fR \fIpassword\fR, \fB\-\-password\fR \fIpassword\fR" 4 -.IX Item "-P password, --password password" -Specify controller's password. Mandatory option for learning. -.IP "\fB\-c\fR \fIclassifier\fR, \fB\-\-classifier\fR \fIclassifier\fR" 4 -.IX Item "-c classifier, --classifier classifier" -Specify classifier to learn message. Mandatory option for learning. Bayes classifier is used by default if this option is omitted. -.IP "\fB\-i\fR \fIip\fR, \fB\-\-ip\fR \fIip\fR" 4 -.IX Item "-i ip, --ip ip" -Add \s-1IP\s0 header when scanning message. Useful for checking messages and emulating that client comes from -specific \s-1IP\s0 address. -.IP "\fB\-w\fR \fIweight\fR, \fB\-\-weight\fR \fIweight\fR" 4 -.IX Item "-w weight, --weight weight" -Weight of message for fuzzy operations. -.IP "\fB\-f\fR \fIflag\fR, \fB\-\-flag\fR \fIflag\fR" 4 -.IX Item "-f flag, --flag flag" -Flag of list for fuzzy operations. -.IP "\fB\-t\fR \fItimeout\fR, \fB\-\-timeout\fR \fItimeout\fR" 4 -.IX Item "-t timeout, --timeout timeout" -Timeout in seconds for all operations. Default value is 5 seconds. -.SH "RETURN VALUE" -.IX Header "RETURN VALUE" -On exit \fBrspamc\fR returns 0 if operation was successfull and error code otherwise. -.SH "EXAMPLES" -.IX Header "EXAMPLES" Check stdin: -.PP -.Vb 1 -\& rspamc < some_file -.Ve +.IP +.nf +\f[C] +rspamc\ <\ some_file +\f[] +.fi .PP Check files: -.PP -.Vb 1 -\& rspamc symbols file1 file2 file3 -.Ve +.IP +.nf +\f[C] +rspamc\ symbols\ file1\ file2\ file3 +\f[] +.fi .PP Learn files: -.PP -.Vb 1 -\& rspamc \-P pass learn_spam file1 file2 file3 -.Ve +.IP +.nf +\f[C] +rspamc\ -P\ pass\ learn_spam\ file1\ file2\ file3 +\f[] +.fi .PP Add fuzzy hash to set 2: -.PP -.Vb 1 -\& rspamc \-P pass \-f 2 \-w 10 fuzzy_add file1 file2 -.Ve +.IP +.nf +\f[C] +rspamc\ -P\ pass\ -f\ 2\ -w\ 10\ fuzzy_add\ file1\ file2 +\f[] +.fi .PP Delete fuzzy hash from other server: -.PP -.Vb 1 -\& rspamc \-P pass \-h hostname:11334 \-f 2 fuzzy_del file1 file2 -.Ve +.IP +.nf +\f[C] +rspamc\ -P\ pass\ -h\ hostname:11334\ -f\ 2\ fuzzy_del\ file1\ file2 +\f[] +.fi .PP Get statistics: -.PP -.Vb 1 -\& rspamc stat -.Ve +.IP +.nf +\f[C] +rspamc\ stat +\f[] +.fi .PP Get uptime: +.IP +.nf +\f[C] +rspamc\ uptime +\f[] +.fi .PP -.Vb 1 -\& rspamc uptime -.Ve -.PP -Add custom rule's weight: -.PP -.Vb 1 -\& rspamc add_symbol test 1.5 -.Ve -.PP -Add custom action's weight: +Add custom rule\[aq]s weight: +.IP +.nf +\f[C] +rspamc\ add_symbol\ test\ 1.5 +\f[] +.fi .PP -.Vb 1 -\& rspamc add_action reject 7.1 -.Ve -.SH "AUTHOR" -.IX Header "AUTHOR" -Vsevolod Stakhov -.SH "COPYRIGHT AND LICENSE" -.IX Header "COPYRIGHT AND LICENSE" -Copyright 2011\-2012 by Vsevolod Stakhov . +Add custom action\[aq]s weight: +.IP +.nf +\f[C] +rspamc\ add_action\ reject\ 7.1 +\f[] +.fi +.SH SEE ALSO .PP -This program is free software; you may redistribute it and/or modify it -under the terms of \s-1BSD\s0 license. +Rspamd documentation and source codes may be downloaded from +. diff --git a/doc/rspamc.1.md b/doc/rspamc.1.md new file mode 100644 index 000000000..531e0802d --- /dev/null +++ b/doc/rspamc.1.md @@ -0,0 +1,134 @@ +% RSPAMC(1) Rspamd User Manual + +# NAME + +rspamc - rspamd command line client + +# SYNOPSIS + +rspamc [*options*] [*command*] [*input-file*]... + +rspamc --help + +# DESCRIPTION + +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) +* 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 + +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 +from the standard input. Controller commands usually does not accept any input, however learn* and fuzzy* commands +requires input. + +# OPTIONS + +-h *host[:port]*, \--connect=*host[:port]* + Specify host and port + +-P *password*, \--password=*password* + Specify control password + +-c *name*, \--classifier=*name* +: Classifier to learn spam or ham (bayes is used by default) + +-w *weight*, \--weight=*weight* +: Weight for fuzzy operations + +-f *number*, \--flag=*number* +: Flag for fuzzy operations + +-p, \--pass +: Pass all filters + +-v, \--verbose +: More verbose output + +-i *ip address*, \--ip=*ip address* +: Emulate that message was received from specified ip address + +-u *username*, \--user=*username* +: Emulate that message was from specified user + +-d *user@domain*, \--deliver=*user@domain* +: Emulate that message is delivered to specified user + +-F *user@domain*, \--from=*user@domain* +: Emulate that message is from specified user + +-r *user@domain*, \--rcpt=*user@domain* +: Emulate that message is for specified user + +-t *seconds*, \--timeout=*seconds* +: Timeout for waiting for a reply + +-b *host:port*, \--bind=*host:port* +: Bind to specified ip address + +\--commands +: List available commands + +# RETURN VALUE + +On exit rspamc returns `0` if operation was successfull and an error code otherwise. + +# EXAMPLES + +Check stdin: + + rspamc < some_file + +Check files: + + rspamc symbols file1 file2 file3 + +Learn files: + + rspamc -P pass learn_spam file1 file2 file3 + +Add fuzzy hash to set 2: + + rspamc -P pass -f 2 -w 10 fuzzy_add file1 file2 + +Delete fuzzy hash from other server: + + rspamc -P pass -h hostname:11334 -f 2 fuzzy_del file1 file2 + +Get statistics: + + rspamc stat + +Get uptime: + + rspamc uptime + +Add custom rule's weight: + + rspamc add_symbol test 1.5 + +Add custom action's weight: + + rspamc add_action reject 7.1 + +# SEE ALSO + +Rspamd documentation and source codes may be downloaded from +. + +[rspamd-workers]: https://rspamd.com/doc/rspamd-workers.html \ No newline at end of file diff --git a/doc/rspamc.pod b/doc/rspamc.pod deleted file mode 100644 index 73b43b649..000000000 --- a/doc/rspamc.pod +++ /dev/null @@ -1,138 +0,0 @@ -=head1 NAME - -rspamc - a simple client for rspamd spam filtering system - -=head1 SYNOPSIS - -rspamc [B<-h> I] [B<-p>] [B<-v>] [B<-b> I] [B<-u> I] -[B<-F> I] [B<-r> I] [B<-d> I] -[B<-i> I] [B<-c> I] [B<-w> I] -[B<-P> I] [B<-f> I] [B<-t> I] [command] [file [file ...]] - -rspamc [B<--help>] - -=head1 DESCRIPTION - -B is a simple client for checking messages using rspamd or for learning rspamd by messages. -B has several mandatory options for learning: I and I. - -=head1 OPTIONS - -=over 4 - -=item B<-h> I, B<--connect> I - -Specify host and port for connecting to rspamd server. Default host is I and -default port is I<11333> for checking messages and I<11334> for learning and statistic. -Also it is possible to specify a unix socket for all operations (for example: -B B<-h> /path/to/soket) - -=item B<-b> I, B<--bind> I - -Specify explicit IP address to bind a client for operations. - -=item B<-u> I, B<--user> I - -Specify username for connection with rspamd server. - -=item B<-F> I, B<--from> I - -Specify SMTP FROM address for connection with rspamd server. - -=item B<-r> I, B<--rcpt> I - -Specify SMTP RCPT TO address for connection with rspamd server. - -=item B<-d> I, B<--deliver> I - -Specify real delivery address for connection with rspamd server. - -=item B<-p>, B<--pass-all> - -Pass all filters when checking messages. Ignored in case of learning. - -=item B<-v>, B<--verbose> - -Be more verbose while displaying results. For example show descriptions of symbols. - -=item B<-P> I, B<--password> I - -Specify controller's password. Mandatory option for learning. - -=item B<-c> I, B<--classifier> I - -Specify classifier to learn message. Mandatory option for learning. Bayes classifier is used by default if this option is omitted. - -=item B<-i> I, B<--ip> I - -Add IP header when scanning message. Useful for checking messages and emulating that client comes from -specific IP address. - -=item B<-w> I, B<--weight> I - -Weight of message for fuzzy operations. - -=item B<-f> I, B<--flag> I - -Flag of list for fuzzy operations. - -=item B<-t> I, B<--timeout> I - -Timeout in seconds for all operations. Default value is 5 seconds. - -=back - -=head1 RETURN VALUE - -On exit B returns 0 if operation was successfull and error code otherwise. - -=head1 EXAMPLES - -Check stdin: - - rspamc < some_file - -Check files: - - rspamc symbols file1 file2 file3 - -Learn files: - - rspamc -P pass learn_spam file1 file2 file3 - -Add fuzzy hash to set 2: - - rspamc -P pass -f 2 -w 10 fuzzy_add file1 file2 - -Delete fuzzy hash from other server: - - rspamc -P pass -h hostname:11334 -f 2 fuzzy_del file1 file2 - -Get statistics: - - rspamc stat - -Get uptime: - - rspamc uptime - -Add custom rule's weight: - - rspamc add_symbol test 1.5 - -Add custom action's weight: - - rspamc add_action reject 7.1 - -=head1 AUTHOR - -Vsevolod Stakhov - -=head1 COPYRIGHT AND LICENSE - -Copyright 2011-2012 by Vsevolod Stakhov . - -This program is free software; you may redistribute it and/or modify it -under the terms of BSD license. - -=cut diff --git a/doc/rspamd.8 b/doc/rspamd.8 index c34e553fd..37650ebaa 100644 --- a/doc/rspamd.8 +++ b/doc/rspamd.8 @@ -1,190 +1,138 @@ -.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.16) -.\" -.\" Standard preamble: -.\" ======================================================================== -.de Sp \" Vertical space (when we can't use .PP) -.if t .sp .5v -.if n .sp -.. -.de Vb \" Begin verbatim text -.ft CW +.TH RSPAMD 8 "" "Rspamd User Manual" +.SH NAME +.PP +rspamd - main daemon for rapid spam filtering system +.SH SYNOPSIS +.PP +rspamd [\f[I]options\f[]]... +.PP +rspamd --help +.SH DESCRIPTION +.PP +Rspamd filtering system is designed to be fast, modular and easily +scalable system. +Rspamd core is written in \f[C]C\f[] language using event driven +processing model. +Plugins for rspamd can be written in \f[C]Lua\f[] programming language. +Rspamd is designed to process connections completely asynchronous and do +not block anywhere in code. +.SH OPTIONS +.TP +.B -t, --config-test +Perform config test and exit +.RS +.RE +.TP +.B -f, --no-fork +Do not daemonize main process +.RS +.RE +.TP +.B -c \f[I]path\f[], --config=\f[I]path\f[] +Specify config file(s) +.RS +.RE +.TP +.B -u \f[I]username\f[], --user=\f[I]username\f[] +User to run rspamd as +.RS +.RE +.TP +.B -g \f[I]groupname\f[], --group=\f[I]groupname\f[] +Group to run rspamd as +.RS +.RE +.TP +.B -p \f[I]path\f[], --pid=\f[I]path\f[] +Path to pidfile +.RS +.RE +.TP +.B -C, --dump-cache +Dump symbols cache stats and exit +.RS +.RE +.TP +.B -d, --debug +Force debug output +.RS +.RE +.TP +.B -i, --insecure +Ignore running workers as privileged users (insecure) +.RS +.RE +.TP +.B --test-lua=\f[I]path\f[] +Specify lua file(s) to test +.RS +.RE +.TP +.B --sign-config=\f[I]path\f[] +Specify config file(s) to sign +.RS +.RE +.TP +.B --private-key=\f[I]path\f[] +Specify private key to sign +.RS +.RE +.TP +.B --convert-config=\f[I]path\f[] +Convert configuration to UCL +.RS +.RE +.SH EXAMPLES +.PP +Run rspamd daemon with default configuration: +.IP .nf -.ne \\$1 -.. -.de Ve \" End verbatim text -.ft R +\f[C] +rspamd +\f[] .fi -.. -.\" Set up some character translations and predefined strings. \*(-- will -.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left -.\" double quote, and \*(R" will give a right double quote. \*(C+ will -.\" give a nicer C++. Capital omega is used to do unbreakable dashes and -.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, -.\" nothing in troff, for use with C<>. -.tr \(*W- -.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' -.ie n \{\ -. ds -- \(*W- -. ds PI pi -. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch -. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch -. ds L" "" -. ds R" "" -. ds C` "" -. ds C' "" -'br\} -.el\{\ -. ds -- \|\(em\| -. ds PI \(*p -. ds L" `` -. ds R" '' -'br\} -.\" -.\" Escape single quotes in literal strings from groff's Unicode transform. -.ie \n(.g .ds Aq \(aq -.el .ds Aq ' -.\" -.\" If the F register is turned on, we'll generate index entries on stderr for -.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index -.\" entries marked with X<> in POD. Of course, you'll have to process the -.\" output yourself in some meaningful fashion. -.ie \nF \{\ -. de IX -. tm Index:\\$1\t\\n%\t"\\$2" -.. -. nr % 0 -. rr F -.\} -.el \{\ -. de IX -.. -.\} -.\" -.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). -.\" Fear. Run. Save yourself. No user-serviceable parts. -. \" fudge factors for nroff and troff -.if n \{\ -. ds #H 0 -. ds #V .8m -. ds #F .3m -. ds #[ \f1 -. ds #] \fP -.\} -.if t \{\ -. ds #H ((1u-(\\\\n(.fu%2u))*.13m) -. ds #V .6m -. ds #F 0 -. ds #[ \& -. ds #] \& -.\} -. \" simple accents for nroff and troff -.if n \{\ -. ds ' \& -. ds ` \& -. ds ^ \& -. ds , \& -. ds ~ ~ -. ds / -.\} -.if t \{\ -. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" -. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' -. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' -. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' -. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' -. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' -.\} -. \" troff and (daisy-wheel) nroff accents -.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' -.ds 8 \h'\*(#H'\(*b\h'-\*(#H' -.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] -.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' -.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' -.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] -.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] -.ds ae a\h'-(\w'a'u*4/10)'e -.ds Ae A\h'-(\w'A'u*4/10)'E -. \" corrections for vroff -.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' -.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' -. \" for low resolution devices (crt and lpr) -.if \n(.H>23 .if \n(.V>19 \ -\{\ -. ds : e -. ds 8 ss -. ds o a -. ds d- d\h'-1'\(ga -. ds D- D\h'-1'\(hy -. ds th \o'bp' -. ds Th \o'LP' -. ds ae ae -. ds Ae AE -.\} -.rm #[ #] #H #V #F C -.\" ======================================================================== -.\" -.IX Title "rspamd 8" -.TH rspamd 8 "2013-02-02" "rspamd-0.5.4" "Rspamd documentation" -.\" For nroff, turn off justification. Always turn off hyphenation; it makes -.\" way too many mistakes in technical documents. -.if n .ad l -.nh -.SH "NAME" -rspamd \- main daemon for rspamd spam filtering system -.SH "SYNOPSIS" -.IX Header "SYNOPSIS" -rspamd [\fB\-c\fR \fIconfig_file\fR] [\fB\-f\fR] -[\fB\-u\fR \fIuser\fR] [\fB\-g\fR \fIgroup\fR] [\fB\-p\fR \fIpidfile\fR] -[\fB\-t\fR] [\fB\-d\fR] .PP -rspamd [\fB\-\-help\fR] +Run rspamd in foreground with custom configuration: +.IP +.nf +\f[C] +rspamd\ -f\ -c\ ~/rspamd.conf +\f[] +.fi .PP -rspamd [\fB\-t\fR] +Run rspamd specifying user and group: +.IP +.nf +\f[C] +rspamd\ -u\ rspamd\ -g\ rspamd\ -c\ /etc/rspamd/rspamd.conf +\f[] +.fi .PP -rspamd [\fB\-C\fR] -.SH "DESCRIPTION" -.IX Header "DESCRIPTION" -\&\fBRspamd\fR filtering system is designed to be fast, modular and easily extendable system. -\&\fBRspamd\fR core is written in C language using event driven paradigma. -Plugins for \fBrspamd\fR can be written in lua. -\&\fBRspamd\fR is designed to process connections completely asynchronous and do not block anywhere in code. -.SH "OPTIONS" -.IX Header "OPTIONS" -.IP "\fB\-c\fR \fIconfig_file\fR, \fB\-\-config\fR \fIconfig_file\fR" 4 -.IX Item "-c config_file, --config config_file" -Specify the path where rspamd config is placed. Default is rspamd.xml. -.IP "\fB\-u\fR \fIuser\fR, \fB\-\-user\fR \fIuser\fR" 4 -.IX Item "-u user, --user user" -Specify user rspamd run as. It is possible only when rspamd is launched by super-user as it -calls \fIsetuid\fR\|(2) after spawning workers. -.IP "\fB\-g\fR \fIgroup\fR, \fB\-\-group\fR \fIgroup\fR" 4 -.IX Item "-g group, --group group" -Specify group rspamd run as. -.IP "\fB\-p\fR \fIpidfile\fR, \fB\-\-pidfile\fR \fIpidfile\fR" 4 -.IX Item "-p pidfile, --pidfile pidfile" -Path to pid file where rspamd pid would be stored. Directory containing pidfile must be -writeable by \fBrspamd\fR. -.IP "\fB\-f\fR, \fB\-\-no\-fork\fR" 4 -.IX Item "-f, --no-fork" -Do not daemonize after launch. Usable for debugging purposes. -.IP "\fB\-t\fR, \fB\-\-config\-test\fR" 4 -.IX Item "-t, --config-test" -Just perform test of configuration. Return zero exit code when configuration is \s-1OK\s0. -.IP "\fB\-C\fR, \fB\-\-counters\fR" 4 -.IX Item "-C, --counters" -Show counters for all symbols. Usable when symbols cache is saved. -.IP "\fB\-d\fR, \fB\-\-debug\fR" 4 -.IX Item "-d, --debug" -Turn on debugging mode in logging. -.SH "RETURN VALUE" -.IX Header "RETURN VALUE" -On exit \fBrspamd\fR returns 0 if operation was successfull and error code otherwise. -.SH "AUTHOR" -.IX Header "AUTHOR" -Vsevolod Stakhov -.SH "COPYRIGHT AND LICENSE" -.IX Header "COPYRIGHT AND LICENSE" -Copyright 2011 by Vsevolod Stakhov . +Test lua scripts using rspamd API: +.IP +.nf +\f[C] +rspamd\ --test-lua=~/test1.lua\ --test-lua=~/test2.lua +\f[] +.fi +.PP +Sign config files for \f[C].includes\f[] macro: +.IP +.nf +\f[C] +rspamd\ --private-key=sign.key\ --sign-config=rspamd.conf +\f[] +.fi +.PP +Convert old \f[C]XML\f[] config to the \f[C]UCL\f[] format (since +0.6.0): +.IP +.nf +\f[C] +rspamd\ -c\ /etc/rspamd.xml\ --convert-config=/etc/rspamd/rspamd.conf +\f[] +.fi +.SH SEE ALSO .PP -This program is free software; you may redistribute it and/or modify it -under the terms of \s-1BSD\s0 license. +Rspamd documentation and source codes may be downloaded from +. diff --git a/doc/rspamd.8.md b/doc/rspamd.8.md new file mode 100644 index 000000000..2e6d60b48 --- /dev/null +++ b/doc/rspamd.8.md @@ -0,0 +1,90 @@ +% RSPAMD(8) Rspamd User Manual + +# NAME + +rspamd - main daemon for rapid spam filtering system + +# SYNOPSIS + +rspamd [*options*]... + +rspamd --help + +# DESCRIPTION + +Rspamd filtering system is designed to be fast, modular and easily scalable system. +Rspamd core is written in `C` language using event driven processing model. +Plugins for rspamd can be written in `Lua` programming language. +Rspamd is designed to process connections completely asynchronous and do not block anywhere in code. + +# OPTIONS + +-t, \--config-test +: Perform config test and exit + +-f, \--no-fork +: Do not daemonize main process + +-c *path*, \--config=*path* +: Specify config file(s) + +-u *username*, \--user=*username* +: User to run rspamd as + +-g *groupname*, \--group=*groupname* +: Group to run rspamd as + +-p *path*, \--pid=*path* +: Path to pidfile + +-C, \--dump-cache +: Dump symbols cache stats and exit + +-d, \--debug +: Force debug output + +-i, \--insecure +: Ignore running workers as privileged users (insecure) + +\--test-lua=*path* +: Specify lua file(s) to test + +\--sign-config=*path* +: Specify config file(s) to sign + +\--private-key=*path* +: Specify private key to sign + +\--convert-config=*path* +: Convert configuration to UCL + +# EXAMPLES + +Run rspamd daemon with default configuration: + + rspamd + +Run rspamd in foreground with custom configuration: + + rspamd -f -c ~/rspamd.conf + +Run rspamd specifying user and group: + + rspamd -u rspamd -g rspamd -c /etc/rspamd/rspamd.conf + +Test lua scripts using rspamd API: + + rspamd --test-lua=~/test1.lua --test-lua=~/test2.lua + +Sign config files for `.includes` macro: + + rspamd --private-key=sign.key --sign-config=rspamd.conf + +Convert old `XML` config to the `UCL` format (since 0.6.0): + + rspamd -c /etc/rspamd.xml --convert-config=/etc/rspamd/rspamd.conf + +# SEE ALSO + +Rspamd documentation and source codes may be downloaded from +. \ No newline at end of file diff --git a/doc/rspamd.pod b/doc/rspamd.pod deleted file mode 100644 index 0e03d5c82..000000000 --- a/doc/rspamd.pod +++ /dev/null @@ -1,79 +0,0 @@ -=head1 NAME - -rspamd - main daemon for rspamd spam filtering system - -=head1 SYNOPSIS - -rspamd [B<-c> I] [B<-f>] -[B<-u> I] [B<-g> I] [B<-p> I] -[B<-t>] [B<-d>] - -rspamd [B<--help>] - -rspamd [B<-t>] - -rspamd [B<-C>] - -=head1 DESCRIPTION - -B filtering system is designed to be fast, modular and easily extendable system. -B core is written in C language using event driven paradigma. -Plugins for B can be written in lua. -B is designed to process connections completely asynchronous and do not block anywhere in code. - -=head1 OPTIONS - -=over 4 - -=item B<-c> I, B<--config> I - -Specify the path where rspamd config is placed. Default is rspamd.xml. - -=item B<-u> I, B<--user> I - -Specify user rspamd run as. It is possible only when rspamd is launched by super-user as it -calls setuid(2) after spawning workers. - -=item B<-g> I, B<--group> I - -Specify group rspamd run as. - -=item B<-p> I, B<--pidfile> I - -Path to pid file where rspamd pid would be stored. Directory containing pidfile must be -writeable by B. - -=item B<-f>, B<--no-fork> - -Do not daemonize after launch. Usable for debugging purposes. - -=item B<-t>, B<--config-test> - -Just perform test of configuration. Return zero exit code when configuration is OK. - -=item B<-C>, B<--counters> - -Show counters for all symbols. Usable when symbols cache is saved. - -=item B<-d>, B<--debug> - -Turn on debugging mode in logging. - -=back - -=head1 RETURN VALUE - -On exit B returns 0 if operation was successfull and error code otherwise. - -=head1 AUTHOR - -Vsevolod Stakhov - -=head1 COPYRIGHT AND LICENSE - -Copyright 2011 by Vsevolod Stakhov . - -This program is free software; you may redistribute it and/or modify it -under the terms of BSD license. - -=cut \ No newline at end of file -- 2.39.5