Thread: [Amavisadmin-svn] SF.net SVN: amavisadmin: [52] amavisadmin/trunk/docs

SourceForge Headquarters 225 Broadway Suite 1600 San Diego, CA 92101 +1 (858) 422-6466

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&gt;</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/&lt;version&gt;</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:~&gt; </prompt><userinput>sudo -u postgres createuser \
+</userinput><prompt>&gt; </prompt><userinput>         --no-superuser --no-createrole --no-createdb \
+</userinput><prompt>&gt; </prompt><userinput>         --pwprompt --username=<replaceable>superuser</replaceable> --password amavis
+</userinput><prompt>Enter password for new role: </prompt><userinput><replaceable>&lt;password&gt;</replaceable>
+</userinput><prompt>Enter it again: </prompt><userinput><replaceable>&lt;password&gt;</replaceable>
+</userinput><prompt>Password:</prompt> <userinput><replaceable>&lt;superuserpassword&gt;</replaceable>
+</userinput><computeroutput>CREATE ROLE
+</computeroutput><prompt>sreindl@linux-fest:~&gt; </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:~&gt;</prompt>
+<prompt>sreindl@linux-fest:~&gt; </prompt><userinput>psql --username=<replaceable>superuser</replaceable> \</userinput>
+<prompt>&gt; </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:~&gt; </prompt><userinput>createdb --tablespace=tb_admin \
+</userinput><prompt>&gt; </prompt><userinput>                     --owner=amavis \
+</userinput><prompt>&gt; </prompt><userinput>                     --echo \
+</userinput><prompt>&gt; </prompt><userinput>                     --user=superuser \
+</userinput><prompt>&gt; </prompt><userinput>                     --password
+</userinput><prompt>Password:</prompt> <userinput><replaceable>&lt;password&gt;</replaceable></userinput>
+<computeroutput>CREATE DATABASE</computeroutput>
+<prompt>sreindl@linux-fest:~&gt; </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:~&gt; </prompt><userinput>psql --username=amavis --password amavis &lt;<replaceable>create_tables.sql</replaceable>
+</userinput><prompt>Password for user amavis: </prompt><replaceable>&lt;password&gt;</replaceable>
+<computeroutput>...</computeroutput>                               <lineannotation>lots of output.</lineannotation>
+<prompt>sreindl@linux-fest:~&gt; </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:~&gt; </prompt><userinput>psql --username=amavis --password amavis &lt;inital_load.sql</userinput>
+<prompt>Password for user amavis: </prompt><userinput><replaceable>&lt;password&gt;</replaceable></userinput>
+<computeroutput>...
+</computeroutput><prompt>sreindl@linux-fest:~&gt;</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>&lt;version&gt;</replaceable></userinput><co id="sc-amavis-curl" />
-<prompt>$ </prompt><userinput>gzip -d -c amavisd-new-<replaceable>&lt;version&gt;</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>&lt;version&gt;</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.




Thread: [Amavisadmin-svn] SF.net SVN: amavisadmin: [52] amavisadmin/trunk/docs

amavisadmin-svn