amavis documentation

[Patrick Ben Koetter]

Good Morning,

I'm still short on time, but I've been working on amavis documentation now and
then when time permitted to do so. There are a few changes I want to discuss
before I take this further:

== Subproject

I'd like documentation to become a subproject of the main amavis branch. Being
reduced to the documentation code only will make it easier to handle all the
transformation that doc code needs to go through before it becomes available
in various formats.

This said I created <https://gitlab.com/amavis/docs.amavis.org> a few minutes
ago. It holds what I am currently are working on.

Does anyone feel uncomfortable with the docs becoming a subproject?


== Coverage

There already is quite a lot of documentation available. It is focussed on
functionality and how it was implemented, with a few exceptions (e.g. DKIM)
where it also explains how to get things done.

I'd like to put a stronger emphasis on "getting things done". My intent is to
provide at least as much information as it takes to mobilize people to a point
where they think: "Hey, I can do that."


== Structure

This said I've begun to work on a general "amavis" document that states what
amavis is and then tries to route readers into the right directions. Ideally
this will become the main starting point in the future.

The main directions I'm currently thinking of are:

Setup::
    How to install and run amavis on a computer.
Configuration::
    How to configure specific aspects of amavis.
Integration::
    How to integrate amavis into an MTA.
Operation::
    How to work with amavis on a server.
Understanding amavis::
    How amavis processes email.


=== Setup

The setup section will cover what it takes to install amavis on your server if
you download the sources from our website/repos. Before that it should point
people to the various distribution specific packages that provide amavis as
they will probably provide better/simplier integration that works with the
system from the start.


=== Configuration

The Configuration section should explain the syntax used to configure amavis.
It should also tell people how to use routines that help e.g. to read in
external data (read_hash).

Now that readers would know about the means they have at hands they should set
their mind on what they want to do. I'd like to give them $something to read
into "content policies". Maybe thoughts on filtering, a collection of best
practices and/or architectural examples to get this or that done. I haven't
really set my mind on a particular approach yet and I'm open to suggestions.

Then there should be a part that deals with amavisd.conf. It should explain
the sections this config file will consist of and what they configure.


=== Integration

This section should address how people can integrate amavis into their mail
flow. There are serveral documents there already, but they are very different
in depth and how much they explain. Some are plain cut & paste from Mailing
list threads.

I'd like to update all of them. Working on integration into Postfix myself
seems natural to me. If someone wants to join in, please raise your voice. As
for the other MTAs I will try to reach out to others. I've no idea how to
integrate amavis with Exim. The website says " The last 3.x release was 3.36.
It is obsolete and should not be used." So I will remove all docs pointing to
3.x soon.

How many people are still using Sendmail? I really don't know and I'd like to
find out if we should maintain documentation for Sendmail. (If you are a
Sendmail user, speak up. I'll be happy to maintain docs if it makes sense.)

Any other MTAs we should address?


=== Operation

This section deals with daily routines. Stale files in $TMPDIR, reading and
interpreting LOG, database cleanup/stats etc. pp.

If you know of something you'd like to find in here, drop me a note or create
an issue at <https://gitlab.com/amavis/docs.amavis.org/issues>.


=== Understanding amavis

Understanding amavis aims to give the reader an idea how amavis works. What's
amavis' system metaphor? What are the steps each message handed over to amavis
goes through? Why, for example, would amavis unpack a message and it's MIME
parts *before* it hands it down to various content classifiers?

Speaking of "classifiers". This section should also set and explain the
terminology we want to use throughout the project: content filte framework,
classifier, content classes, policy bank etc. pp.

One of the goals of this section is to help people create an inner model of
amvis workings. When things go wrong and they need to debug they should be
able to walk that inner model and think: "It should be doing this at the
moment, but it doesn't. What could be the reason why it fails at exactly this
step?"


That's it for know. I'm curious about feedback.

p at rick

-- 
[*] sys4 AG
 
https://sys4.de, +49 (89) 30 90 46 64
Schleißheimer Straße 26/MG,80333 München
 
Sitz der Gesellschaft: München, Amtsgericht München: HRB 199263
Vorstand: Patrick Ben Koetter, Marc Schiffbauer, Wolfgang Stief
Aufsichtsratsvorsitzender: Florian Kirstein
 
-------------- next part --------------
A non-text attachment was scrubbed...
Name: smime.p7s
Type: application/pkcs7-signature
Size: 4460 bytes
Desc: not available
URL: <https://lists.amavis.org/pipermail/amavis-devel/attachments/20190311/2393a91a/attachment.bin>