[Amavisadmin-svn] SF.net SVN: amavisadmin: [51] amavisadmin/branches/documentation_1_0/docs/ instal
Status: Beta
Brought to you by:
streindl
Menu
▾
▴
[Amavisadmin-svn] SF.net SVN: amavisadmin: [51] amavisadmin/branches/documentation_1_0/docs/ installationguide.xml
|
From: <str...@us...> - 2007-01-25 20:27:19
|
Revision: 51
http://amavisadmin.svn.sourceforge.net/amavisadmin/?rev=51&view=rev
Author: streindl
Date: 2007-01-25 12:27:15 -0800 (Thu, 25 Jan 2007)
Log Message:
-----------
installationguide.xml:
* More text for the
Modified Paths:
--------------
amavisadmin/branches/documentation_1_0/docs/installationguide.xml
Modified: amavisadmin/branches/documentation_1_0/docs/installationguide.xml
===================================================================
--- amavisadmin/branches/documentation_1_0/docs/installationguide.xml 2007-01-25 20:25:43 UTC (rev 50)
+++ amavisadmin/branches/documentation_1_0/docs/installationguide.xml 2007-01-25 20:27:15 UTC (rev 51)
@@ -95,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
@@ -106,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
@@ -257,6 +257,13 @@
<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>
@@ -354,11 +361,31 @@
<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>
+ 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>
@@ -417,185 +444,90 @@
value here.</para>
</callout>
</calloutlist>
- </section>
- </section>
- <appendix id="app-postgres-ddl">
- <title>Sample PostgreSQL DDL script</title>
+ <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>
- <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);
-);
+ <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>
--- 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
-);
+ <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>
--- 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)
-);
+ <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>
-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
+ <variablelist>
+ <varlistentry>
+ <term>$clean_quarantine_method</term>
- 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
+ <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>
- 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
+ <varlistentry>
+ <term>$virus_quarantine_method</term>
- spam_modifies_subj char(1) default NULL, -- Y/N
+ <listitem>
+ <para>If this variable is set to sql, virus mail texts are stored
+ in the database. </para>
+ </listitem>
+ </varlistentry>
- 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,
+ <varlistentry>
+ <term>$banned_files_quarantine_method</term>
- 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,
+ <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>
- 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,
+ <varlistentry>
+ <term>$spam_quarantine_method</term>
- 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
-);
+ <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>
--- 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.
+ <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>
--- 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;
+ <section>
+ <title>AmavisAdmin</title>
--- 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>
+ <para>To install AmavisAdmin, you can download the distribtion file from
+ <?target aSAsAS?></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.
|
