[Amavisadmin-svn] SF.net SVN: amavisadmin: [42] amavisadmin/branches/documentation_1_0/docs
Status: Beta
Brought to you by:
streindl
Menu
▾
▴
[Amavisadmin-svn] SF.net SVN: amavisadmin: [42] amavisadmin/branches/documentation_1_0/docs
|
From: <str...@us...> - 2007-01-22 22:59:21
|
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></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/<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>
+ </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 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' => viewed (marked as read)
+-- 'R' => released (delivered) to this recipient
+-- 'p' => pending (a status given to messages when the admin received the
+-- request but not yet released; targeted to banned parts)
+-- 'D' => 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.
|
