1Quick installation guide for amavis-stats on FreeBSD
2----------------------------------------------------
3(c) Loic Pefferkorn (pef) <loic AT dev DOT erodia DOT net>
4
5The original document can be found here : http://www.erodia.net/doc/
6
7This file contains the following informations :
8
91.Introduction
101.1 About this document
111.2 What is amavis-stats ?
121.3 Requirements
132.Installation
142.1 Getting sources and installing them
152.2 Setting up Apache
162.3 Setting permissions
172.4 Creating user amavis
182.5 Modifying files
193.Final steps
203.1 Checking if all is ok
213.2 Cron job
224.Misc
23
24
251.Introdution
26-------------
27
281.1 About this document
29-----------------------
30This is a little guide which explains you how to get amavis-stats working on
31FreeBSD. I have STABLE-4.9 release, with others releases or *BSD, instructions may change.
32
33Since there is no package for amavis-stats, all is done "by hand".
34
351.2 What is Amavis-stats ?
36--------------------------
37Amavis-stats is a simple AMaViS statistics generator based on rrdtool.
38It produces graphs of clean emails, spam emails and infected emails broken
39down by virus, from amavis log entries.
40
41You can see example graphs on the screenshots page.
42http://rekudos.net/amavis-stats/node/view/7
43
441.3 Requirements
45----------------
46Amavis-stats needs some perl modules provided by the rrdtool package.
47
48You can install it by source :
49	cd /usr/ports/net/rrdtool ; make all && make install
50
51Or if you prefer binary package :
52	pkg_add ftp://ftp.freebsd.org/pub/FreeBSD/ports/i386/packages-4-stable/net/rrdtool-1.0.45.tgz
53
54
55note : please use a FreeBSD mirror http://mirrorlist.freebsd.org/
56
57You also need a running apache webserver, with php enabled.
58
59My system :
60-apache2 with mod_php4 enabled.
61-Postfix-2
62-Amavis-new
63-Clamav-0.65
64
65I consider Amavisd is configured as follow :
66-$DO_SYSLOG = 1;
67
68note : this setting can be modified in amavisd.conf file, usually located in /usr/local/etc/
69
70You can use a separate log file, just check that Amavis user can read it.
71
722.Installation
73--------------
74
752.1 Getting sources and installing them
76----------------------------------------
77Download the latest sources tarball :
78	wget http://rekudos.net/download/amavis-stats.tar.gz
79
80Uncompress it :
81	tar xvzf amavis-stats.tar.gz
82	cd amavis-stats-xx
83
84Copy amavis-stats to /usr/local/sbin :
85	cp amavis-stats /usr/local/sbin
86
87Create the necessary directories :
88	mkdir  /usr/local/www/amavis-stats
89	mkdir -p /usr/local/lib/amavis-stats/img
90	ln -s /usr/local/lib/amavis-stats/img /usr/local/www/amavis-stats/img
91
92Copy amavis-stats.php to /usr/local/www/amavis-stats and make an index link :
93	cp amavis-stats.php /usr/local/www/amavis-stats
94	cd /usr/local/www/amavis-stats && ln -s amavis-stats.php index.php
95
96note : index.php is an index file, specified by "DirectoryIndex" in apache configuration.
97
98
992.2 Setting up Apache
100---------------------
101
102In the apache.conf provided change the paths to our :
103
104Alias /amavis-stats /usr/local/www/amavis-stats
105
106<Directory /usr/local/www/amavis-stats>
107(...)
108
109Add this to your real httpd.conf file :
110	cat apache.conf >> /usr/local/etc/apache2/httpd.conf
111
112note : 	instead of adding it, you can include it, rename apache.conf in amavis.httpd.conf,
113	move it to /usr/local/etc/apache2, and put in apache's httpd.conf file:
114	Include etc/apache2/amavis-stats.httpd.conf
115
116Restart apache
117	apachectl restart
118
119
1202.3 Set permissions
121-------------------
122
123Getting the user and the group whom apache is running under :
124	grep ^User\  /usr/local/etc/apache2/httpd.conf (2 spaces after User\)
125	grep ^Group\  /usr/local/etc/apache2/httpd.conf (2 spaces after User\)
126
127
128I found www as user and www as group. If you don't have the same,
129just remplace www:www by YourUser:YourGroup in the chown command.
130
131Modify permissions for img directory with user and group you had just found :
132(the php file will wrote img files on it, so apache must have write access)
133	chown www:www /usr/local/lib/amavis-stats/img
134
135
1362.4 Creating user amavis
137------------------------
138We need an amavis user, who will run cron job to update the data.
139
140Now creating him with adduser or sysinstall
141	useradd amavis
142
143Choose defaults values, for home choose /usr/local/lib/amavis-stats
144
145note : additionnal group wheel is necessary for being able to read /var/maillog file,
146       if you have setup amavisd for sending logs to syslog.
147
148Permissions for other directories, where amavis user must have write access for running his cron job :
149	chown amavis /usr/local/lib/amavis-stats
150	chown amavis /usr/local/www/amavis-stats
151
152
1532.5 Modifying files
154------------------
155Now we have to edit files :
156
157Edit amavis-stats and change :
158line 79 to :
159	$lockfile = "/var/tmp/$pkg";
160line 80 to :
161	$libdir = "/usr/local/lib/$pkg";
162
163
164Edit amavis-stats.php and change :
165line 282 to :
166	$as_libdir = "/usr/local/lib/amavis-stats";
167
168
1693.Final steps
170-------------
171
1723.1 Checking if all is ok
173-------------------------
174note : for the following instructions, put /var/maillog only if amavis send logs to syslog,
175       otherwise put the filelog you defined.
176
177Su as amavis user, and check if all is ok :
178	su amavis
179	/usr/local/sbin/amavis-stats /var/log/maillog
180
181Now you must have the following files in /usr/local/lib/amavis-stats :
182
1831.rrd                   amavis-stats.count      amavis-stats.state
1842.rrd                   amavis-stats.names      img
1853.rrd                   amavis-stats.seen
186
187
188Now check if the php page works, go to http://YourServerName/amavis-stats with your favorite browser.
189If "denied errors" is written you, check the permissions on directories. (see 2.3 Setting permissions)
190
191
1923.2 Cron job
193------------
194We put a cronjob now for having data up to date :
195	crontab -e -u amavis
196
197Write this :
198
199*/5 * * * * /usr/local/sbin/amavis-stats /var/log/maillog 2>&1 > /dev/null
200
201
202
203Amavis user doesn't need a valid shell, for more security you can disable it :
204	chsh -s /sbin/nologin amavis
205
206
2074.Misc
208------
209
210Feedbacks
211---------
212I am interested in any feedback, positive or negative, regarding the content of this document via e-mail.
213Definitely contact me if you find errors or obvious omissions.
214
215
216<loic AT dev DOT erodia DOT net>
217
218
219Version history
220---------------
221v 1.0 (Jan 31 2004 ) initial release
222v 1.1 (Feb  2 2004 ) minor changes and language corrections
223v 1.2 (Feb  6 2004 ) layout improvements, minor changes
224
225
226Copyright
227---------
228(c) 2004 Loic Pefferkorn
229
230This documentation may be reproduced in whole or in part, without fee, subject to the following restrictions:
231
232    * The copyright notice above and this permission notice must be preserved complete on all complete or partial copies.
233    * Any translation or derived work must be approved by the author in writing before distribution.
234    * If you distribute this work in part, instructions for obtaining the complete version of this documentation must be included,
235      and a means for obtaining a complete version provided.
236    * This document is placed under the GNU General Public License (see http://www.gnu.org/licenses/gpl.html)
237
238
239Thanks
240------
241-Authors of amavisd.
242-Mark Lawrence, for amavis-stats.
243-Bosco L Parisi for his very usefull advices ;)
244
245