# HG changeset patch
# User Matti Hamalainen <ccr@tnsp.org>
# Date 1252277345 -10800
# Node ID f24388499e6633aa4a2c5cd3efce98646221baff
# Parent  df68cf1eaf3936d8c485bd1f93beae35ad07c739
Update documentation.

diff -r df68cf1eaf39 -r f24388499e66 README
--- a/README	Sun Sep 06 22:07:22 2009 +0300
+++ b/README	Mon Sep 07 01:49:05 2009 +0300
@@ -6,6 +6,10 @@
 Distributed under the modified ("3-clause") BSD license. Please see
 included file COPYING for more information.
 
+
+Homepage: http://www.tnsp.org/maltfilter.php
+
+
 About
 =====
 Maltfilter is daemon script written in Perl, which continuously scans various
@@ -54,41 +58,73 @@
 in memory at once is smaller.
 
 
-Installation
-============
-Copy maltfilter script to /usr/sbin and set permissions
+Manual installation
+===================
+1) Copy maltfilter script to /usr/sbin and set permissions
+
+   $ cp maltfilter /usr/sbin/maltfilter
+   $ chmod 755 /usr/sbin/maltfilter
+   $ chown root:root /usr/sbin/maltfilter
+
+2) Copy example configuration under /etc (you may not want to have the
+   configuration readable to regular users, so below example sets mode
+   0600 to it.)
 
-$ cp maltfilter /usr/sbin/maltfilter
-$ chmod 755 /usr/sbin/maltfilter
-$ chown root:root /usr/sbin/maltfilter
+   $ cp example.conf /etc/maltfilter.conf
+   $ chmod 600 /etc/maltfilter.conf
+   $ chown root:root /etc/maltfilter.conf
 
-Copy example configuration under /etc (you may not want to
-to have the configuration readable to regular users, so below
-example sets mode 600 to it.)
+3) Additionally you can set up the provided Debian style init script
+   for starting Maltfilter at boot.  You may need to edit the script,
+   if you didn't install the configuration and maltfilter script to
+   paths described above.
+
+   $ cp example.init /etc/init.d/maltfilter
+   $ chmod 755 /etc/init.d/maltfilter
+   $ chown root:root /etc/init.d/maltfilter
 
-$ cp example.conf /etc/maltfilter.conf
-$ chmod 600 /etc/maltfilter.conf
-$ chown root:root /etc/maltfilter.conf
+   After that you should run rcconf(8) or chkconfig(8) or similar SysV
+   runlevel configuration utility to enable the script on desired
+   runlevels.
 
+4) You will also most likely want to set up Maltfilter to be SIGHUP'd/
+   restarted when logfiles are rotated via logrotate (because Maltfilter
+   does not automatically notice if logfiles are switched while it is
+   running).
 
-Optional
-========
-Additionally you can set up the provided Debian style init script:
+   There are several ways this can be done, most of which are distribution
+   specific. If you are using Debian-based distribution or something close
+   enough, you can try following:
 
-$ cp example.init /etc/init.d/maltfilter
-$ chmod 755 /etc/init.d/maltfilter
-$ chown root:root /etc/init.d/maltfilter
+   a) Use the included 'logrotate.example' logrotate script. This may not
+      as reliable method as below, however, but it is somewhat easier and
+      much more maintainable.
+
+      $ cp logrotate.example /etc/logrotate.d/maltfilter
+      $ chmod 644 /etc/logrotate.d/maltfilter
+      $ chown root:root /etc/logrotate.d/maltfilter
 
-You need to edit the script, if you didn't install the configuration
-and maltfilter to paths described in installation section.
+   b) Alternatively you can edit /etc/logrotate.conf or relevant file(s)
+      under /etc/logrotate.d/ and add reloading or restarting maltfilter
+      in the script's postrotate section.
 
-Also a simple example HTML CSS stylesheet is provided for your convenience.
+      For example, if you are using Debian with rsyslog, there should be
+      /etc/logrotate.d/rsyslog, which takes care of rotating most system
+      logs, such as auth.log. Add following line in postrotate section:
+
+      invoke-rc.d maltfilter reload > /dev/null
 
 
 Configuration and usage
 =======================
-See example.conf for documentation about settings. Start maltfilter
-either via the init script or through commandline:
+See example.conf for documentation about settings. After editing your
+configuration, you should do a preliminary test run via report mode to
+see if most settings are sane.
+
+$ maltfilter -f /etc/maltfilter.conf
+
+After that, you can start maltfilter either via the init script
+(recommended) or through commandline:
 
 $ maltfilter /var/run/maltfilter.pid /etc/maltfilter.conf
 
@@ -102,5 +138,6 @@
 Automatic report generation can be enabled from configuration.
 You can also run "full" report generation via the "-f" option, in this
 special mode, no automatic weeding is performed, resulting in
-more data being shown.
+more data being shown. In report mode Maltfilter will only parse files
+once, generate reports (if enabled) and quit.
 
diff -r df68cf1eaf39 -r f24388499e66 logrotate.example
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/logrotate.example	Mon Sep 07 01:49:05 2009 +0300
@@ -0,0 +1,10 @@
+/var/log/maltfilter
+{
+	rotate 7
+	daily
+	missingok
+	notifempty
+	postrotate
+		invoke-rc.d maltfilter reload > /dev/null
+	endscript
+}