Thread: [Amavisadmin-svn] SF.net SVN: amavisadmin: [42] amavisadmin/branches/documentation_1_0/docs

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

Revision: 42
          http://amavisadmin.svn.sourceforge.net/amavisadmin/?rev=42&view=rev
Author:   streindl
Date:     2007-01-22 14:59:12 -0800 (Mon, 22 Jan 2007)

Log Message:
-----------
docs/user_guide.xml:
  Added first draft user user guide
docs/installationguide.xml:
  Several additions related to PostgreSQL

Modified Paths:
--------------
    amavisadmin/branches/documentation_1_0/docs/installationguide.xml

Added Paths:
-----------
    amavisadmin/branches/documentation_1_0/docs/user_guide.xml

Modified: amavisadmin/branches/documentation_1_0/docs/installationguide.xml
===================================================================

--- amavisadmin/branches/documentation_1_0/docs/installationguide.xml	2007-01-22 17:33:48 UTC (rev 41)
+++ amavisadmin/branches/documentation_1_0/docs/installationguide.xml	2007-01-22 22:59:12 UTC (rev 42)
@@ -17,7 +17,7 @@
 
       <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>
@@ -197,6 +197,172 @@
     </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>
+        </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 appendix <xref linkend="app-postgres-ddl" />. To apply
+        this file, please use the <command>\i</command> command while
+        executing <command>psql</command>:<screen><prompt>postgres=# </prompt><userinput>\i ddlfile.sql</userinput>
+<computeroutput>...</computeroutput>
+<prompt>postgres=#</prompt></screen></para>
+      </section>
+    </section>
+
+    <section>
       <title>Amavisd-new</title>
 
       <para>The Amavisd-new application can be downloaded from the <ulink
@@ -253,4 +419,183 @@
       </calloutlist>
     </section>
   </section>
+
+  <appendix id="app-postgres-ddl">
+    <title>Sample PostgreSQL DDL script</title>
+
+    <para><screen linenumbering="numbered" width="132">-- local users
+CREATE TABLE users (
+  id         SERIAL NOT NULL,  -- unique id
+  priority   integer      NOT NULL DEFAULT '7',  -- sort field, 0 is low prior.
+  policy_id  integer unsigned NOT NULL DEFAULT '1',  -- JOINs with policy.id
+  email      varchar(255) NOT NULL UNIQUE,
+  fullname   varchar(255) DEFAULT NULL,    -- not used by amavisd-new
+  local      char(1),      -- Y/N  (optional field, see note further down)
+  PRIMARY KEY (id);
+);
+
+-- any e-mail address (non- rfc2822-quoted), external or local,
+-- used as senders in wblist
+CREATE TABLE mailaddr (
+  id         INT UNSIGNED NOT NULL AUTO_INCREMENT PRIMARY KEY,
+  priority   integer      NOT NULL DEFAULT '7',  -- 0 is low priority
+  email      varchar(255) NOT NULL UNIQUE
+);
+
+-- per-recipient whitelist and/or blacklist,
+-- puts sender and recipient in relation wb  (white or blacklisted sender)
+CREATE TABLE wblist (
+  rid        integer unsigned NOT NULL,  -- recipient: users.id
+  sid        integer unsigned NOT NULL,  -- sender: mailaddr.id
+  wb         varchar(10)  NOT NULL,  -- W or Y / B or N / space=neutral / score
+  PRIMARY KEY (rid,sid)
+);
+
+CREATE TABLE policy (
+  id  INT UNSIGNED NOT NULL AUTO_INCREMENT PRIMARY KEY,
+                                    -- 'id' this is the _only_ required field
+  policy_name      varchar(32),     -- not used by amavisd-new, a comment
+
+  virus_lover          char(1) default NULL,     -- Y/N
+  spam_lover           char(1) default NULL,     -- Y/N
+  banned_files_lover   char(1) default NULL,     -- Y/N
+  bad_header_lover     char(1) default NULL,     -- Y/N
+
+  bypass_virus_checks  char(1) default NULL,     -- Y/N
+  bypass_spam_checks   char(1) default NULL,     -- Y/N
+  bypass_banned_checks char(1) default NULL,     -- Y/N
+  bypass_header_checks char(1) default NULL,     -- Y/N
+
+  spam_modifies_subj   char(1) default NULL,     -- Y/N
+
+  virus_quarantine_to      varchar(64) default NULL,
+  spam_quarantine_to       varchar(64) default NULL,
+  banned_quarantine_to     varchar(64) default NULL,
+  bad_header_quarantine_to varchar(64) default NULL,
+  clean_quarantine_to      varchar(64) default NULL,
+  other_quarantine_to      varchar(64) default NULL,
+
+  spam_tag_level  float default NULL, -- higher score inserts spam info headers
+  spam_tag2_level float default NULL, -- inserts 'declared spam' header fields
+  spam_kill_level float default NULL, -- higher score triggers evasive actions
+                                      -- e.g. reject/drop, quarantine, ...
+                                     -- (subject to final_spam_destiny setting)
+  spam_dsn_cutoff_level        float default NULL,
+  spam_quarantine_cutoff_level float default NULL,
+
+  addr_extension_virus      varchar(64) default NULL,
+  addr_extension_spam       varchar(64) default NULL,
+  addr_extension_banned     varchar(64) default NULL,
+  addr_extension_bad_header varchar(64) default NULL,
+
+  warnvirusrecip      char(1)     default NULL, -- Y/N
+  warnbannedrecip     char(1)     default NULL, -- Y/N
+  warnbadhrecip       char(1)     default NULL, -- Y/N
+  newvirus_admin      varchar(64) default NULL,
+  virus_admin         varchar(64) default NULL,
+  banned_admin        varchar(64) default NULL,
+  bad_header_admin    varchar(64) default NULL,
+  spam_admin          varchar(64) default NULL,
+  spam_subject_tag    varchar(64) default NULL,
+  spam_subject_tag2   varchar(64) default NULL,
+  message_size_limit  integer     default NULL, -- max size in bytes, 0 disable
+  banned_rulenames    varchar(64) default NULL  -- comma-separated list of ...
+        -- names mapped through %banned_rules to actual banned_filename tables
+);
+
+-- R/W part of the dataset (optional)
+--   May reside in the same or in a separate database as lookups database;
+--   REQUIRES SUPPORT FOR TRANSACTIONS; specified in @storage_sql_dsn
+--
+--  Please create additional indexes on keys when needed, or drop suggested
+--  ones as appropriate to optimize queries needed by a management application.
+--  See your database documentation for further optimization hints. 
+
+-- provide unique id for each e-mail address, avoids storing copies
+CREATE TABLE maddr (
+  id         INT UNSIGNED NOT NULL AUTO_INCREMENT PRIMARY KEY,
+  email      varchar(255) NOT NULL UNIQUE, -- full mail address
+  domain     varchar(255) NOT NULL     -- only domain part of the email address
+                                       -- with subdomain fields in reverse
+) ENGINE=InnoDB;
+
+-- information pertaining to each processed message as a whole;
+-- NOTE: records with NULL msgs.content should be ignored by utilities,
+--   as such records correspond to messages just being processes, or were lost
+-- NOTE: with PostgreSQL, instead of a character field time_iso, please use:
+--   time_iso TIMESTAMP WITH TIME ZONE NOT NULL,
+-- NOTE: with MySQL, instead of a character field time_iso, one might prefer:
+--   time_iso TIMESTAMP NOT NULL DEFAULT 0,
+--   but the following MUST then be set in amavisd.conf: $timestamp_fmt_mysql=1
+CREATE TABLE msgs (
+  mail_id    varchar(12)   NOT NULL PRIMARY KEY,  -- long-term unique mail id
+  secret_id  varchar(12)   DEFAULT '',  -- authorizes release of mail_id
+  am_id      varchar(20)   NOT NULL,    -- id used in the log
+  time_num   integer unsigned NOT NULL, -- rx_time: seconds since Unix epoch
+  time_iso   char(16)      NOT NULL,    -- rx_time: ISO8601 UTC ascii time
+  sid        integer unsigned NOT NULL, -- sender: maddr.id
+  policy     varchar(255)  DEFAULT '',  -- policy bank path (like macro %p)
+  client_addr varchar(255) DEFAULT '',  -- SMTP client IP address (IPv4 or v6)
+  size       integer unsigned NOT NULL, -- message size in bytes
+  content    char(1),                   -- content type: V/B/S/s/M/H/O/C:
+                                        -- virus/banned/spam(kill)/spammy(tag2)
+                                        -- /bad mime/bad header/oversized/clean
+                                        -- is NULL on partially processed mail
+  quar_type  char(1),                   -- quarantined as: ' '/F/Z/B/Q/M
+                                        --  none/file/zipfile/bsmtp/sql/mailbox
+  quar_loc   varchar(255)  DEFAULT '',  -- quarantine location (e.g. file)
+  dsn_sent   char(1),                   -- was DSN sent? Y/N/q (q=quenched)
+  spam_level float,                     -- SA spam level (no boosts)
+  message_id varchar(255)  DEFAULT '',  -- mail Message-ID header field
+  from_addr  varchar(255)  DEFAULT '',  -- mail From header field,    UTF8
+  subject    varchar(255)  DEFAULT '',  -- mail Subject header field, UTF8
+  host       varchar(255)  NOT NULL,    -- hostname where amavisd is running
+  FOREIGN KEY (sid) REFERENCES maddr(id) ON DELETE RESTRICT
+) ENGINE=InnoDB;
+CREATE INDEX msgs_idx_sid      ON msgs (sid);
+CREATE INDEX msgs_idx_time_num ON msgs (time_num);
+-- alternatively when purging based on time_iso (instead of msgs_idx_time_num):
+-- CREATE INDEX msgs_idx_time_iso ON msgs (time_iso);
+
+-- per-recipient information related to each processed message;
+-- NOTE: records in msgrcpt without corresponding msgs.mail_id record are
+--  orphaned and should be ignored and eventually deleted by external utilities
+CREATE TABLE msgrcpt (
+  mail_id    varchar(12)   NOT NULL,     -- (must allow duplicates)
+  rid        integer unsigned NOT NULL,  -- recipient: maddr.id (dupl. allowed)
+  ds         char(1)       NOT NULL,     -- delivery status: P/R/B/D/T
+                                         -- pass/reject/bounce/discard/tempfail
+  rs         char(1)       NOT NULL,     -- release status: initialized to ' '
+  bl         char(1)       DEFAULT ' ',  -- sender blacklisted by this recip
+  wl         char(1)       DEFAULT ' ',  -- sender whitelisted by this recip
+  bspam_level float,                     -- spam level + per-recip boost
+  smtp_resp  varchar(255)  DEFAULT '',   -- SMTP response given to MTA
+  FOREIGN KEY (rid)     REFERENCES maddr(id)     ON DELETE RESTRICT,
+  FOREIGN KEY (mail_id) REFERENCES msgs(mail_id) ON DELETE CASCADE
+) ENGINE=InnoDB;
+CREATE INDEX msgrcpt_idx_mail_id  ON msgrcpt (mail_id);
+CREATE INDEX msgrcpt_idx_rid      ON msgrcpt (rid);
+
+-- mail quarantine in SQL, enabled by $*_quarantine_method='sql:'
+-- NOTE: records in quarantine without corresponding msgs.mail_id record are
+--  orphaned and should be ignored and eventually deleted by external utilities
+CREATE TABLE quarantine (
+  mail_id    varchar(12)   NOT NULL,    -- long-term unique mail id
+  chunk_ind  integer unsigned NOT NULL, -- chunk number, starting with 1
+  mail_text  blob NOT NULL,  -- store mail as chunks (in PostgreSQL use: bytea)
+  PRIMARY KEY (mail_id,chunk_ind),
+  FOREIGN KEY (mail_id) REFERENCES msgs(mail_id) ON DELETE CASCADE
+) ENGINE=InnoDB;
+
+-- field msgrcpt.rs is primarily intended for use by quarantine management
+-- software; the value assigned by amavisd is a space;
+-- a short _preliminary_ list of possible values:
+--   'V' =&gt; viewed (marked as read)
+--   'R' =&gt; released (delivered) to this recipient
+--   'p' =&gt; pending (a status given to messages when the admin received the
+--                   request but not yet released; targeted to banned parts)
+--   'D' =&gt; marked for deletion; a cleanup script may delete it
+
+</screen></para>
+  </appendix>
 </article>
\ No newline at end of file

Added: amavisadmin/branches/documentation_1_0/docs/user_guide.xml
===================================================================
--- amavisadmin/branches/documentation_1_0/docs/user_guide.xml	                        (rev 0)
+++ amavisadmin/branches/documentation_1_0/docs/user_guide.xml	2007-01-22 22:59:12 UTC (rev 42)
@@ -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: [42] amavisadmin/branches/documentation_1_0/docs

amavisadmin-svn