[Amavisadmin-svn] SF.net SVN: amavisadmin: [52] amavisadmin/trunk/docs
Status: Beta
Brought to you by:
streindl
Menu
▾
▴
[Amavisadmin-svn] SF.net SVN: amavisadmin: [52] amavisadmin/trunk/docs
|
From: <str...@us...> - 2007-01-25 20:39:11
|
Revision: 52
http://amavisadmin.svn.sourceforge.net/amavisadmin/?rev=52&view=rev
Author: streindl
Date: 2007-01-25 12:39:12 -0800 (Thu, 25 Jan 2007)
Log Message:
-----------
Merge from documentation
Modified Paths:
--------------
amavisadmin/trunk/docs/installationguide.xml
Added Paths:
-----------
amavisadmin/trunk/docs/user_guide.xml
Modified: amavisadmin/trunk/docs/installationguide.xml
===================================================================
--- amavisadmin/trunk/docs/installationguide.xml 2007-01-25 20:27:15 UTC (rev 51)
+++ amavisadmin/trunk/docs/installationguide.xml 2007-01-25 20:39:12 UTC (rev 52)
@@ -1,4 +1,4 @@
-<?xml version="1.0" encoding="US-ASCII"?>
+<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
<!ENTITY sreindl "Stephen Reindl">
@@ -15,9 +15,9 @@
<surname>Reindl</surname>
- <address><street>Langster Str. 28</street>
+ <address><street>Langster Straße 28</street>
<postcode>40668</postcode> <city>Meerbusch</city>
-<country>Germany></country></address>
+<country>Germany</country></address>
<email>sr...@sr...</email>
</author>
@@ -48,7 +48,17 @@
</legalnotice>
<revhistory>
- <revision><revnumber>0.1</revnumber><date>2007-01-20</date><authorinitials>sr</authorinitials><revdescription><para>Initial document</para></revdescription></revision>
+ <revision>
+ <revnumber>0.1</revnumber>
+
+ <date>2007-01-20</date>
+
+ <authorinitials>sr</authorinitials>
+
+ <revdescription>
+ <para>Initial document</para>
+ </revdescription>
+ </revision>
</revhistory>
</articleinfo>
@@ -85,6 +95,14 @@
</listitem>
<listitem>
+ <para>A Database server where the Amavisd-Server stores it's mails and
+ AmavisAdmin is doing the administration. For development <ulink
+ url="http://www.postgresql.org">PostgreSQL</ulink> version <ulink
+ url="http://www.postgresql.org/docs/8.1/static/index.html">8.1</ulink>
+ is used.</para>
+ </listitem>
+
+ <listitem>
<para><ulink
url="http://www.ijs.si/software/amavisd/">Amavisd-new</ulink> as the
SPAM and Virus filter engine. At least version 2.4.2 has to be
@@ -96,14 +114,6 @@
</listitem>
<listitem>
- <para>A Database server where the Amavisd-Server stores it's mails and
- AmavisAdmin is doing the administration. For development <ulink
- url="http://www.postgresql.org">PostgreSQL</ulink> version <ulink
- url="http://www.postgresql.org/docs/8.1/static/index.html">8.1</ulink>
- is used.</para>
- </listitem>
-
- <listitem>
<para>The JDBC-driver suitable for your database system. As mentioned
before the development is based on PostgreSQL, therefore the
appropriate driver for the database server is located at <ulink
@@ -187,36 +197,337 @@
</section>
<section>
+ <title>PostgreSQL database</title>
+
+ <para>This document does not describe how to setup the PostgreSQL
+ database. For most Microsoft <trademark
+ class="registered">Windows</trademark> and <trademark
+ class="registered">Linux</trademark>/<trademark
+ class="registered">Unix</trademark> distribitions there're binary
+ packages available (see <ulink
+ url="http://www.postgresql.org/ftp/binary/">http://www.postgresql.org/ftp/binary/<version></ulink>
+ for available systems and versions). They can be downloard If you want
+ (or need) to install PostgreSQL from scratch, the following section in
+ the PostgreSQL documentation might help: <ulink
+ url="http://www.postgresql.org/docs/8.1/interactive/installation.html">http://www.postgresql.org/docs/8.1/interactive/installation.html</ulink>.</para>
+
+ <para>For development and testing PostgreSQL release 8.1 has been used.
+ Other versions might work also but no tests have been done to ensure
+ working on different releases of PostgreSQL.</para>
+
+ <section>
+ <title>Creating the database for storing Amavisd-new data</title>
+
+ <para>It makes sense (from performance, sizing and other aspects like
+ security) to create a separate database that contains the data stored
+ by Amavisd-new and AmavisAdmin. The database should be accessable only
+ by superusers and a specific functional account for maximum security.
+ In addition PostgreSQL offers the possibility to move parts of the
+ data to other filesystems/paths by using tablespaces.</para>
+
+ <section>
+ <title>Creating a functional database user</title>
+
+ <para>It makes sense to create a functional user that is used by the
+ applications (amavisd-new and AmavisAdmin) to connect to the
+ database. This user created should be able to access the database
+ only from the IP-addresses used by the applications itself. This
+ gives some additional security. To create a user, two steps are
+ neccessary: First the user itself has to be created. Afterwards the
+ user has to be configured to connect to the database. The second
+ step depends on your local security, therfore please refer to <ulink
+ url="http://www.postgresql.org/docs/8.1/interactive/client-authentication.html">http://www.postgresql.org/docs/8.1/interactive/client-authentication.html</ulink>
+ for details. Creating a user can be done by using the command
+ <command>createuser</command> that is part of every PostgreSQL
+ distribution. The following example shows how to create the user
+ amavis that will be used for administrators and applications to
+ connect to the database (please replace
+ <replaceable>superuser</replaceable> with your superuser role
+ name):</para>
+
+ <screen xml:space="preserve"><prompt>sreindl@linux-fest:~> </prompt><userinput>sudo -u postgres createuser \
+</userinput><prompt>> </prompt><userinput> --no-superuser --no-createrole --no-createdb \
+</userinput><prompt>> </prompt><userinput> --pwprompt --username=<replaceable>superuser</replaceable> --password amavis
+</userinput><prompt>Enter password for new role: </prompt><userinput><replaceable><password></replaceable>
+</userinput><prompt>Enter it again: </prompt><userinput><replaceable><password></replaceable>
+</userinput><prompt>Password:</prompt> <userinput><replaceable><superuserpassword></replaceable>
+</userinput><computeroutput>CREATE ROLE
+</computeroutput><prompt>sreindl@linux-fest:~> </prompt></screen>
+
+ <para>The first two password prompts are asking for the password for
+ user <systemitem class="username">amavis</systemitem>, the last
+ password prompt is asking for the superuser password.</para>
+
+ <note>
+ <para>Please ensure to reload the configuration files by
+ restarting your postgres SQL server. Please refer to your local
+ PostgreSQL documentation for details about how to restart the
+ server.</para>
+ </note>
+ </section>
+
+ <section>
+ <title>Creating a tablespace</title>
+
+ <para>For maintainability I would suggest to create the database
+ used for Amavisd-new in a separate tablespace. Creating a tablespace
+ in PostgreSQL is done in two steps: At first you have to create a
+ directory in the file system which will contain the tablespace data.
+ With the Linux/Unix operating system the command might look like
+ this:</para>
+
+ <programlisting><prompt>$ </prompt><userinput>mkdir -p <replaceable>/srv/db/tablespaces/amavis</replaceable></userinput></programlisting>
+
+ <para>where the path given might even reside on a different machine
+ (i.e. network file server). On other operating systems this command
+ might look different or you might even use a graphical user
+ interface to create the path. After creating the path you have to
+ change the permissions that only the database server has access to
+ the created path. This is basically done for security
+ reasons:</para>
+
+ <programlisting><prompt>$ </prompt><userinput>chown <replaceable>postgres</replaceable> <replaceable>/srv/db/tablespaces/amavis</replaceable></userinput>
+<prompt>$ </prompt><userinput>chmod 0700 <replaceable>/srv/db/tablespaces/amavis</replaceable></userinput></programlisting>
+
+ <para>The first command assigns the user postgres (please provide
+ the user name which has been used to install the postgres database)
+ to the created path, i.e. change the owner of this path to the
+ database system. The second command changes the permissions of the
+ directory in a way that only the PostgreSQL system (and the system
+ administrator) can access the contents of the directory. Other
+ operating systems might need other commands to accomplish
+ this.</para>
+
+ <para>The second step is to actually create the tablespace. This is
+ done by using database commands. The following example creates a
+ tablespace <database class="table">tb_admin</database> which points
+ to the directory created above:</para>
+
+ <para><screen><prompt>sreindl@linux-fest:~></prompt>
+<prompt>sreindl@linux-fest:~> </prompt><userinput>psql --username=<replaceable>superuser</replaceable> \</userinput>
+<prompt>> </prompt> <userinput>--password postgres</userinput>
+<computeroutput>Password for user <replaceable>superuser</replaceable>:
+Welcome to psql 8.1.5, the PostgreSQL interactive terminal.
+
+Type: \copyright for distribution terms
+ \h for help with SQL commands
+ \? for help with psql commands
+ \g or terminate with semicolon to execute query
+ \q to quit
+
+</computeroutput><prompt>postgres=# </prompt><userinput>CREATE TABLESPACE <replaceable>tb_amavis</replaceable> </userinput>
+<prompt>postgres-# </prompt><userinput> OWNER amavis </userinput>
+<prompt>postgres-# </prompt><userinput> LOCATION '<replaceable>/srv/db/tablespaces/amavis</replaceable>';</userinput>
+<computeroutput>CREATE TABLE</computeroutput>
+<prompt>postgres=#</prompt></screen></para>
+ </section>
+
+ <section>
+ <title>Creating the database</title>
+
+ <para>After doing the preparation steps described in the sections
+ above, the final step is to create the actual database. This can be
+ done by using the command <command>createdb</command> or by using
+ SQL commands entered into the PostgreSQL frontent
+ <command>psql</command>. The database encoding can be of any type as
+ the mail text itself is stored as a binary field and therefore
+ there's no need to use binary encoding for the database. The
+ following command creates the database <database
+ class="name">amavis</database> for user <database
+ class="user">amavis</database> in tablespace <database
+ class="table">tb_amavis</database>:</para>
+
+ <screen><prompt>sreindl@linux-fest:~> </prompt><userinput>createdb --tablespace=tb_admin \
+</userinput><prompt>> </prompt><userinput> --owner=amavis \
+</userinput><prompt>> </prompt><userinput> --echo \
+</userinput><prompt>> </prompt><userinput> --user=superuser \
+</userinput><prompt>> </prompt><userinput> --password
+</userinput><prompt>Password:</prompt> <userinput><replaceable><password></replaceable></userinput>
+<computeroutput>CREATE DATABASE</computeroutput>
+<prompt>sreindl@linux-fest:~> </prompt>
+</screen>
+
+ <para>A similar command on the psql command line would be</para>
+
+ <screen><prompt>postgres=# </prompt><userinput>CREATE DATABASE amavis OWNER amavis TABLESPACE tb_amavis;</userinput>
+<computeroutput>CREATE DATABASE</computeroutput>
+<prompt>postgres=#</prompt></screen>
+ </section>
+ </section>
+
+ <section>
+ <title>Create SQL data model</title>
+
+ <para>With the Amavisd-new distribution, a README-file is distributed
+ that contains a sample data model. As this data model is mixed
+ together with MySQL comments, a clean version for PostgreSQL is
+ provided in the distribution of AmavisAdmin. To execute this file, you
+ can pass the filename directly to the <command>psql</command> command
+ on the command line:<screen><prompt>sreindl@linux-fest:~> </prompt><userinput>psql --username=amavis --password amavis <<replaceable>create_tables.sql</replaceable>
+</userinput><prompt>Password for user amavis: </prompt><replaceable><password></replaceable>
+<computeroutput>...</computeroutput> <lineannotation>lots of output.</lineannotation>
+<prompt>sreindl@linux-fest:~> </prompt></screen></para>
+
+ <para>The file can be found in
+ <filename>db/postgres/create_tables.sql</filename>. After creating the
+ data model, some initial data has to be loaded to let Amavisd-new
+ start over:</para>
+
+ <screen><prompt>sreindl@sreindl:~> </prompt><userinput>psql --username=amavis --password amavis <inital_load.sql</userinput>
+<prompt>Password for user amavis: </prompt><userinput><replaceable><password></replaceable></userinput>
+<computeroutput>...
+</computeroutput><prompt>sreindl@linux-fest:~></prompt> </screen>
+
+ <para>A more complete example with input data can be found in the
+ AmavisAdmin distribution in
+ <filename>db/postgres/initial_load.sql</filename>.</para>
+
+ <para>As there're no local users defined in the database, the messages
+ are stored according to the <emphasis>catchall</emphasis> user. After
+ finalizing this step your database should be ready to run
+ amavisd-new.</para>
+ </section>
+ </section>
+
+ <section>
<title>Amavisd-new</title>
<para>The Amavisd-new application can be downloaded from the <ulink
url="http://www.ijs.si/software/amavisd/">Amavisd-new home page</ulink>.
Please ensure to at least use version 2.4.1, as this version is at least
from documentation point of view SQL save according to the current data
- model. The following commands taken from the file
- <filename>INSTALL</filename> that is part of the Amavisd-new
- distribution explains how to download a particular version of the
- software:</para>
+ model. For installation of amavisd-new and about how to setup SQL
+ storage and lookup, please refer to the following documentation
+ files:</para>
- <screen><prompt>$ </prompt><userinput>curl -s -S -O http://www.ijs.si/software/amavisd/amavisd-new-<replaceable><version></replaceable></userinput><co id="sc-amavis-curl" />
-<prompt>$ </prompt><userinput>gzip -d -c amavisd-new-<replaceable><version></replaceable>.tar.gz | tar xvf -</userinput>
-<computeroutput >amavisd-new-2.4.4
-amavisd-new-2.4.4/README_FILES
-amavisd-new-2.4.4/helper-progs
-amavisd-new-2.4.4/test-messages
-amavisd-new-2.4.4/AAAREADME.first
-amavisd-new-2.4.4/INSTALL
+ <itemizedlist>
+ <listitem>
+ <para><ulink
+ url="http://www.ijs.si/software/amavisd/INSTALL.txt">http://www.ijs.si/software/amavisd/INSTALL.txt</ulink>
+ describes how to download and install Amavisd-new in general</para>
+ </listitem>
+
+ <listitem>
+ <para><ulink
+ url="http://www.ijs.si/software/amavisd/README.sql.txt">http://www.ijs.si/software/amavisd/README.sql.txt</ulink>
+ describes how to setup SQL access.</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>In addition, you have to make the PDP protocol available via
+ socket access. The PDP protocoll (see <ulink
+ url="http://www.ijs.si/software/amavisd/README.protocol.txt">http://www.ijs.si/software/amavisd/README.protocol.txt</ulink>
+ for reference) enables other applications to either perform SPAM/Virus
+ checks for mails or to release quarantined mails. To accomplish this,
+ the file <filename>/etc/amavisd.conf</filename> has to be adapted. The
+ following listing explains the changes in detail:</para>
+
+ <programlisting>...
+$inet_socket_port = (10024,<replaceable>10026</replaceable><co
+ id="pl-amavis-inet-socket-port" />); # listen on this local TCP port(s) (see $protocol)
...
-tar: Read 4608 bytes from -</computeroutput>
-<prompt>$ </prompt><userinput>cd amavisd-new-<replaceable><version></replaceable></userinput></screen>
+$protocol='AM.PDP';<co id="pl-amavis-conf-protocol" />
+...</programlisting>
- <calloutlist>
- <callout arearefs="sc-amavis-curl">
- <para>Other tools like <command>wget</command> or downloading via
- your favourite web browser should work also.</para>
- </callout>
- </calloutlist>
+ <calloutlist>
+ <callout arearefs="pl-amavis-inet-socket-port">
+ <para>Please add here the port that should be used for communication
+ between AmavisAdmin and amavisd-new. This port number should be
+ selected with caution as there might be some inteference with other
+ application if you would select a port that is already in use by
+ another application.</para>
+ </callout>
+ <callout arearefs="pl-amavis-inet-socket-port">
+ <para>This line defines the general protocol to be used for talking
+ to amavisd-new. As described above, the PDP-protocol is the right
+ value here.</para>
+ </callout>
+ </calloutlist>
+
+ <para>Another part that has to be updated is the lookup and storage
+ section. Both sections define how and where to lookup user and policy
+ informartion and in addition where to store mails (either quarantined or
+ not, depending on the settings). The following example shows how to
+ define database lookups (the perl module DBI::Pg needs to be installed
+ for this):</para>
+
+ <programlisting>...
+@lookup_sql_dsn =
+ ( ['DBI:Pg:database=amavis', 'amavis', 'amavis'] );
+ <lineannotation>The values used are matching the examples given above.</lineannotation>
+...
+@storage_sql_dsn = @lookup_sql_dsn; # none, same, or separate database
+</programlisting>
+
+ <para>Your settings might be different from the settings above,
+ especially if the database is located on a different host or other
+ settings might be different as well. For details please refer to the
+ Amavisd-new documentation.</para>
+
+ <para>In addition the storage of mails has to be defined. It can be
+ individually set if mails of specific types (e.g. clean mail, virus,
+ ...) should be stored with mail contents or not. This settings should be
+ adjusted by your needs and available disk space. As the table that
+ contains the mail contents (table <database
+ class="table">quarantine</database>) is not accessed for read access by
+ amavisd-new, the performance depends on your write throughput of your
+ database server. The following list describes the important
+ configuration settings available and values which seem
+ reasonable:</para>
+
+ <variablelist>
+ <varlistentry>
+ <term>$clean_quarantine_method</term>
+
+ <listitem>
+ <para>If this variable will be set to sql, all message texts of
+ mails that have passed all checks successfully are stored in the
+ database.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>$virus_quarantine_method</term>
+
+ <listitem>
+ <para>If this variable is set to sql, virus mail texts are stored
+ in the database. </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>$banned_files_quarantine_method</term>
+
+ <listitem>
+ <para>If this variable is set to sql, for mails that have been
+ rejected because of banned attachments (e.g. executable files,
+ ...), the mail text (including the attachments) is stored in the
+ database.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>$spam_quarantine_method</term>
+
+ <listitem>
+ <para>if this variable is set to sql, the mail text for mails that
+ have been marked as SPAM are stored in the database.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>Usually only for viruses, banned attachments and SPAM mails this
+ setting should be touched. In addition please check the legal impact of
+ storing each and every mail in a database that is not directly
+ accessable to the users.</para>
</section>
+
+ <section>
+ <title>AmavisAdmin</title>
+
+ <para>To install AmavisAdmin, you can download the distribtion file from
+ <?target aSAsAS?></para>
+ </section>
</section>
</article>
\ No newline at end of file
Copied: amavisadmin/trunk/docs/user_guide.xml (from rev 51, amavisadmin/branches/documentation_1_0/docs/user_guide.xml)
===================================================================
--- amavisadmin/trunk/docs/user_guide.xml (rev 0)
+++ amavisadmin/trunk/docs/user_guide.xml 2007-01-25 20:39:12 UTC (rev 52)
@@ -0,0 +1,86 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
+<article>
+ <articleinfo>
+ <title>AmavisAdmin</title>
+
+ <subtitle>User Manual</subtitle>
+
+ <author>
+ <firstname>Stephen</firstname>
+
+ <surname>Reindl</surname>
+
+ <address><street>Langster Str. 28</street>
+<postcode>40668</postcode> <city>Meerbusch</city>
+<country>Germany</country></address>
+
+ <email>sr...@sr...</email>
+ </author>
+
+ <pubdate>February 2007</pubdate>
+
+ <copyright>
+ <year>2006</year>
+
+ <year>2007</year>
+
+ <holder>Stephen Reindl</holder>
+ </copyright>
+
+ <legalnotice>
+ <para>Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License. You may
+ obtain a copy of the License at</para>
+
+ <para><ulink
+ url="http://www.apache.org/licenses/LICENSE-2.0">http://www.apache.org/licenses/LICENSE-2.0</ulink></para>
+
+ <para>Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an "AS IS"
+ BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+ implied. See the License for the specific language governing permissions
+ and limitations under the License.</para>
+ </legalnotice>
+
+ <revhistory>
+ <revision>
+ <revnumber>0.1</revnumber>
+
+ <date>2007-01-22</date>
+
+ <authorinitials>sr</authorinitials>
+
+ <revdescription>
+ <para>Initial document</para>
+ </revdescription>
+ </revision>
+ </revhistory>
+ </articleinfo>
+
+ <section>
+ <title>Preface</title>
+
+ <para>This document describes how to use AmavisAdmin from a user's
+ perspective. As the AmavisAdmin can be used by both, regular users and
+ adminstrators, there's no specific document for administration of
+ AmavisAdmin. Specific details about configuration and scheduling can be
+ found in the <citetitle id="ref-installation-manual">installation
+ manual</citetitle>.</para>
+
+ <section>
+ <title>Bibliography</title>
+
+ <bibliography>
+ <biblioentry id="maler96">
+ <title>From Text to Model to Markup</title>
+
+ <subtitle></subtitle>
+ </biblioentry>
+ </bibliography>
+
+ <para></para>
+ </section>
+ </section>
+</article>
\ No newline at end of file
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|
