#--------------------------------------------------------
# Kurzbeschreibung OPT_MSMTP v0.9.7 (2011-01-05)
#--------------------------------------------------------

Das OPT_MSMTP dient dazu, eine RFC-konforme Mail ueber einen beliebigen SMTP-Server zu versenden.
Gegenueber opt_smtpclient bietet dieses Paket im wesentlichen zwei Vorteile:

   - Unterstuetzung von SMTP-Auth und POP3-before-SMTP
   - Wiederholung fehlgeschlagener Sendeversuche
   
Als Eingabe wird entweder

- eine RFC-2822-konforme (Text)datei erwartet, die gemaess RFC-2821 innerhalb der
  DATA-Sequenz an den Empfaenger gesendet wird oder
- die Parametersequenz
  From, To, [Reply-To], Subject, Body, [CC], [BCC], [Directory [regex_pos] [regex_neg]], [[MIME-Type:]Attachment], [CHARSET]

erwartet.

#--------------------------------------------------------
# Erforderliche Soft- und Hardware
#--------------------------------------------------------

- FLI4L 3.2.x/3.3.x/3.4.x
- SMTP-Server (lokal oder remote)
- optional OPT_EASYCRON
- optional OPT_SSL
- Festplatteninstallation empfohlen

#--------------------------------------------------------
# Hinweise zur Architektur
#--------------------------------------------------------
Das Paket ist sehr modular aufgebaut. Der urspruengliche Gedanke bei der
Konstruktion dieses Pakets war es einerseits, die mittlerweile recht hohe
Zahl von Paketen, die sich primaer um den Mailversand kuemmern, durch ein
wirklich umfassendes Paket zu ersetzen, andererseits die vielen 
Spezialloesungen zum Mailversand, wie sie Pakete mitbringen, bei denen
der Mailversand nur Mittel zum Zweck ist (opt_faxmailpro, opt_vbox, etc.),
ueberfluessig zu machen.
Damit wird sowohl der Anwender (er braucht nur noch ein einziges
Paket zu konfigurieren) als auch der OPT-Entwickler (er kann sich
auf sein Kernproblem konzentrieren) entlastet.

Diese Fuelle verschiedentlicher Einsatzszenarien fuehrt unweigerlich
zu einem relativ groen Paket, vergleicht man es z.B. mit
opt_msmtpclient und wuerde es daher ungeeignet fuer Disketteninstallationen
machen. Deshalb besteht das opt_msmtp eigentlich aus drei Paketen: einem
opt_msmtp, einem opt_msmtppro und einem opt_msmtpidna.

opt_msmtppro bietet folgende zusaetzliche Funktionen:
- automatische Erkennung des Contenttypes von EMailanhaengen
- erweiterte Datei-Namensfilterfunktionen
- erzeugt 100% eindeutige Message-ID

opt_msmtpdina bietet folgende zusaetzliche Funktionen:
- IDN-support (international domain names)

Zwischen den drei Paketen kann innerhalb der Datei
/config/msmtp.txt gewaehlt werden.

OPT_MSMTP implementiert eine persistente Warteschlange. Nach dem Aufruf
von 'msmtp.sh' kann der Anwenderprozess die uebergebenen Dateien ("Attachments")
gefahrlos loeschen, da sie entweder bereits erfolgreich versand wurden
oder sich zumindest in Kopie in einem spool-Verzeichnis befinden.
Der eigentliche Versand der Mails erfolgt mittels einer gepatchten Version
von 'msmtp' (gepatcht deshalb, weil msmtp normalerweise fehlgeschlagene Mails als
'dead.letter' im Homeverzeichnis des aktuellen Benutzers speichert. Da dies bei
FLI4L in der Ramdisk liegt, waeren Speicherueberlaeufe an der Tagesordnung.)

Schematisch sieht der Ablauf folgendermaen aus:

----------------------      /--------------------\               ----------------
| msmtp.sh <options> | ---> | sofortiger Versand | ---- ja ----> | cp spool_dir |
----------------------      \--------------------/               ----------------
                                       |                                 |
                                       |                                 |
                                      nein                       -------------------------------------
                                       |                         | Versand / evtl. Verbindungsaufbau |
                                       |                         -------------------------------------
                                ----------------                         |
               ---------------  | cp spool-dir |  <------                |
               |                ----------------        |        /--------------\
               |                       |              nein ----  |     ok ?     |
               |                       |                |        \--------------/
               |                       |                |                |
            ip.up        cron stoesst Sendevorgang an   |                |  x------ Verbindungsabbau
               |                       |                |                |          ueber Timeout
               |                       |                |                ja
               |                       |                |                |
               |                       |                |                |
               |             ----------------------     |      ----------------------
               |             | Verbinsdungsaufbau |     |      | spoolfile loeschen |
               |             ----------------------     |      ----------------------
               |                       |                |                |
               |                       |                |                |
               |                       |                |                |
               |                 -----------            |          --------------
               --------------->  | Versand |            |          |   fertig   |
                                 -----------            |          --------------
                                       |                |
                                       |                |
                               /--------------\         |
                               |     ok ?     | --------- 
                               \--------------/
                                       |
                                       |
                                      ja
                                       |  x------ Verbindungsabbau ueber Timeout
                                       |          
                                       |          
                                       |          
                             ---------------------- 
                             | spoolfile loeschen |         
                             ----------------------         
                                       | 
                                       | 
                                 --------------
                                 |   fertig   |
                                 --------------


Ist kein sofortiger Versand gewuenscht (z.B. weil sich der Mailserver ausserhalb des lokalen Netzes
befindet und kein Internet-Pauschaltarif besteht), werden die Mails im Spoolverzeichnis so lange
gelagert, bis - je nach Einstellung - eine der folgenden Bedingungen eintritt:

   - Eine Internetverbindung wird aufgebaut
   - ein cron-Job hat den Mailversand angestossen

Mit Hilfe des cron-Jobs kann verhindert werden, dass sich Mails auf dem Router zu lange ansammeln,
weil keine Internetverbindung aufgebaut wird. Falls eine Internetverbindung aufgebaut wird, bevor
der cron-Job den periodischen Versand der Mails angestossen hat, werden selbstverstaendlich die Mails
beim Verbindungsaufbau versand.
Scheitert der Versand, bleiben die Mails weiterhin im retry-Verzeichnis. Die Anzahl der gescheiterten
Sendeversuche sind direkt aus dem Namen des Spoolfiles ersichtlich; die letzten Ziffern des Dateinamens
geben die Anzahl der bisher gescheiterten Sendeversuche an.

Hinweis: Liegt der SMTP-Server innerhalb des lokalen Netzes, sollte der Versand immer sofort erfolgen.

#---------------------
# Achtung !!!
#---------------------
Wie aus dieser Grafik ersichtlich ist, erfolgt der Verbindungsabbau zeitgesteuert.
Gerade bei FLI4L-Versionen < 2.1 koennen vom Internet eintreffende Pakete einen
Verbindungsabbau verhindern, obwohl vom Router in Richtung Internet keinerlei
Pakete mehr flieen. OPT_MSMTP adressiert diese Problematik NICHT. Insbesondere wer
einen zeitbasierten Internetzugangstarif benutzt, sollte sich deshalb das Paket
OPT_HANGUP naeher anschauen.


#--------------------------------------------------------
# Beschreibung der Konfigurationsparameter
#--------------------------------------------------------
OPT_MSMTP='no'                                # if yes opt_msmtp should be activated
OPT_MSMTPPRO='no'                             # enable additional features (see documentation)

MSMTP_SEND_AT_ONCE='no'                       # deliver mail at once or not

MSMTP_HOSTNAME='router.mydomain.de'           # the full qualified domain name of the machine this OPT is running on

MSMTP_SPOOL_DIR='/data/mail/spool'            # directory, files are stored before send, location on a harddisk recommended

MSMTP_SMTP_AUTH='no'                          # possible values:
                                              # 'no'         : no authentification required
                                              # 'pop'        : POP3-before-smtp
                                              # 'login'      : login
                                              # 'cram-md5'   : cram-md5
MSMTP_SMTP_FROM=''                            # mail address used for SMTP 'MAIL FROM'. if emtpy, USERNAME is used
                                              # use this if your smtp server requires a real mail address (containing '@')
                                              # but your username doesn't contain one (e.g. '123456')
                                              # and your mail address won't work as username
MSMTP_SMTP_USERNAME='test'                    # username for SMTP AUTH (required if your provider uses SMTP AUTH)
MSMTP_SMTP_PASSWORD='geheim'                  # password for SMTP AUTH
MSMTP_POP3_USERNAME='test'                    # username for POP3 login (required if your provider uses POP3-before-smtp)
MSMTP_POP3_PASSWORD='geheim'                  # password for POP3 login
                                              # password and username only need to be provided if authentication is required

MSMTP_POP3_PORT='110'                         # POP3 port number, normally 110
MSMTP_POP3_SERVER='pop3.mydomain.de'          # POP3 server, can also be an IP address
                                              # only needed if MSMTP_SMTP_AUTH='pop'

MSMTP_SMTP_PORT='25'                          # SMTP port number, usually 25
MSMTP_SMTP_SERVER='smtp.mydomain.de'          # SMTP server, can also be an IP address

MSMTP_USE_STARTTLS='no'                       # method to encrypt communication between
                                              # opt_msmtp and your mta
                                              # !!!If "yes", opt_ssl must be installed!!!
                                              
MSMTP_USE_TLS='no'                            # alternativ encryption method
                                              # !!!If "yes", opt_ssl must be installed!!!

                                              # hint: you can choose only one encryption method
                                              
MSMTP_USE_TLS_CERT='no'                       # Use SSL/TLS certificate to authenticate against smtp host
MSMTP_TLS_CERT='/path/to/file.pem'            # Use this RSA certificate. (not tested)
MSMTP_LOGFILE='/path/to/logfile'              # leave empty, if no logfile should be written
                                              # set to 'syslog' if you want to log to the system log

MSMTP_CHARSET='ISO-8859-1'                      # codepage strings are encoded in


+ die neuen Befehle fr msmtp

#--------------------------------------------------------
# Funktionsweise
#--------------------------------------------------------

Der Mailversand wird mit dem Kommando

   msmtp.sh -m <rfc2822_mail.txt>
   msmtp.sh -f <from_address> -t <to_address> -r <reply-to> -s <subject> -b <bodytext | bodytextfile> 
               [-d <directory_to_include> [-rp <regexpos>] [-rn <regexneg>]] [[MIME-Type:]attachment] ...
   
gestartet. Parameter MUESSEN in Anfuehrungszeichen eingegeben werden, sofern sie
Leer- oder Sonderzeichen enthalten!

Der Raw-Modus: msmtp.sh -m <rfc2822_mail.txt>
---------------------------------------------
Erwartet als Parameter den Pfad einer rfc2822-konformen Textdatei zum Versenden.
Manimale Flexibilitaet fuer alle opt-Entwickler, ihre eigenen Mails zu gestalten.
Absender wie Empfaenger werden aus den entsprechenden Feldern innerhalb der
angegebenen Datei (also z.B. 'To:', 'From:') gewonnen.
Siehe Anwendungsbeispiel 5.

Der Komfort-Modus: msmtp.sh -f <from_address> -t <to_address> [-r <reply-to>] -s <subject> -b <bodytext | bodytextfile> 
                   [-c CHARSET] [-d <directory_to_include> [-rp <regexpos>] [-rn <regexneg>]] [[MIME-Type:]attachment] ...
---------------------------------------------------------------------------------------------------------------------
-f   : Absender der Mail in der Form
       myname@mydomain.tld
       <myname@mydomain.tld>
       My Name <myname@mydomain.tld>
       (jeweils in Anfuehrungszeichen)
       
-t   : ein (!) Empfaenger der Mail in der Form 
       myname@mydomain.tld
       <myname@mydomain.tld>
       My Name <myname@mydomain.tld>
       (jeweils in Anfuehrungszeichen)

-r   : optionaler Parameter
       Antwortadresse in der Form 
       myname@mydomain.tld
       <myname@mydomain.tld>
       My Name <myname@mydomain.tld>
       (jeweils in Anfuehrungszeichen)

-cc  : optionaler Parameter, Carbon-Copy-Empfaenger
       Kommaseparierte Liste von Empfaengeradressen der Form
       myname@mydomain.tld,yourname@yourdomain.tld,...
       
-bcc : optionaler Parameter, Blind-Carbon-Copy-Empfaenger
       Kommaseparierte Liste von Empfaengeradressen der Form
       myname@mydomain.tld,yourname@yourdomain.tld,...
       
-s   : Subject / Betreff der Mail
       Bei Sonderzeichen / Leerzeichen Zeile in einfache Anfuehrungszeichen einschliessen!
       
-b   : Bodytext bzw. Bodytext-Datei
       Text, der als eigentliche Nachricht uebermittelt werden soll.
       Bei Sonderzeichen / Leerzeichen Zeile in einfache Anfuehrungszeichen einschliessen!
       Alternativ kann auch eine Datei angegeben werden, die den Nachrichtentext
       enthaelt. Eine Dateiangabe wird daran erkannt, dass als Parameter ein absoluter
       Pfad angegeben wird, der Parameter also mit "/" beginnt.
       
-d   : optionaler Parameter
       Haengt als Attachments alle Dateien an, die sich im angegebenen Verzeichnis befinden.
       
-rp  : optionaler Parameter, nur wirksam, falls Parameter zu "-d" spezifiziert.
       Filtert die Dateinamen, die sich im angegebenen Directory befinden, nach dem angegebenen
       regulaeren Ausdruck, Nur solche Dateien, deren Namen den angegebenen Ausdruck erfuellen,
       koennen versendet werden.
       Wird "-rp" nicht spezifiziert, werden alle Dateien im Verzeichnis zum Versand zugelassen.
       Hinweis: fuer komplexe regulaere Ausdruecke opt_msmtppro aktivieren. Anwendungsbeispiel 4
       
-rn  : optionaler Parameter, nur wirksam, falls Parameter zu "-d" spezifiziert.
       Filtert die Dateinamen, die sich im angegebenen Directory befinden, nach dem angegebenen
       regulaeren Ausdruck, Dateien, deren Namen den angegebenen Ausdruck erfuellen,
       werden vom Versand ausgeschlossen.
       Wird "-rn" nicht spezifiziert, wird keine Datei vom Versand ausgeschlossen.
       Hinweis: fuer komplexe regulaere Ausdruecke opt_msmtppro aktivieren. Anwendungsbeispiel 4
       Eine Kombination von "-rn" und "-rp" ist moeglich und je nach Anwendungszweck auch sinnvoll.
       
[[MIME-Type:]attachment] ...
       optionaler Parameter
       hier koennen einzelne Attachments an Hand Ihres Dateinamens spezifiziert werden.
       Optional kann auch der Content-Type angegeben werden. Dies ist insb. dann sinnvoll,
       wenn opt_msmtppro nicht aktiviert ist.
       Anwendungsbeispiel 1 und 2

-c   : Charset, in dem die Zeichenketten (From, To, Subject, Body, etc.) abgelegt sind.
       Wird benoetigt fr die korrekte IDN- und QuotedPrintable-Kodierung.
       Falls vorhanden, ueberschreibt diese Angabe diejenige aus der Config-Datei.
       

#--------------------------------------------------------
# Dateityp-Erkennung
#--------------------------------------------------------
Werden Dateien an eine Email angehaengt, stellt sich immer die Frage nach dem sog. Content-Type. opt_msmtp
bietet mehrere Moeglichkeiten, diesen zu spezifizieren:

a) Man ueberlaesst diese Aufgabe dem integrierten Hilfsprogramm "file". Als Parameter ist dann lediglich der
   (absolute oder relative) Pfad der anzuhaengenden Datei anzugeben (Vorsicht! Dieser Name darf dann KEINEN
   Doppelpunkt enthalten)
b) Man gibt den zu benutzenden Content-Type manuell vor. Die Syntax dazu lautet:
   MIME-Type:filename
   Also zum Beispiel "application/pdf:/data/docs/document.pdf"

Der Nachteil der Komfort-Variante ist der hohe Speicherbedarf des OPT-Pakets. Deshalb ist diese
Komfort-Variante nur bei aktiviertem opt_msmtppro verfuegbar. Ist opt_msmtppro deaktiviert und
kein Content-Type angegeben, wird der Standardwert "application/octet-stream" verwendet.

Der Content-Type kann bei der Option "-d" nicht spezifiziert werden!

#--------------------------------------------------------
# Sendewiederholung
#--------------------------------------------------------
Falls der Mailversand gescheitert ist, besteht die Moeglichkeit, diesen periodisch
wiederholen zu lassen. Zur Realisierung dieser Funktionalitaet wird das cron-Kommando
benutzt.
Falls Sie OPT_EASYCRON benutzen, legen Sie bitte in dessen Konfigurationsdatei den folgenden
Eintrag an:
EASYCRON_X_CUSTOM=''                               # EASYCRON: eigene Einstellungen wie Umgebungsvariablen
EASYCRON_X_COMMAND='/usr/local/bin/msmtp_retry.sh' # EASYCRON: auszufuehrender Befehl
EASYCRON_X_TIME='0 * * * *'                        # EASYCRON: Zeitpunkt: min h Tag Monat Wochentag
                                                   # hier: zu jeder vollen Stunde wiederholen

#--------------------------------------------------------
# SMTP Authentifizierung
#--------------------------------------------------------
OPT_MSMTP unterstuetzt sowohl "login" als auch "cram-md5" als Authentifizierungsmethode.
Welche davon, wenn ueberhaupt, der konkrete SMTP-Server verwendet, kann man mit folgendem Kommando
feststellen:
    telnet <smtp_server> <port>
    EHLO client
    quit
Als Ausgabe das EHLO - Kommandos erhaelt man u.a. die unterstuetzten Authentifizierungsmechanismen.
SMTP-Server, die das EHLO-Kommando nicht unterstuetzen, erfordern i.d.R. auch keine
Authentifizierung.

Alternativ wird auch POP3-Before-SMTP unterstuetzt.

#--------------------------------------------------------
# verschluesselte Uebertragung
#--------------------------------------------------------
Zur verschluesselten Uebertragung muss entweder der Parameter "msmtp_use_starttls"
oder "msmtp_use_tls" auf "yes" gesetzt werden.
In diesem Fall muss das Zusatzpaket "opt_ssl" ebenfalls installiert werden!

Fuer folgenden Hinweis danke ich Steffen Sledz:
Bei der STARTTLS-Methode verbindet sich der ausliefernde MTA mit dem
regulaeren SMTP-Port 25, landet also direkt bei Mailprogramm des
empfangenden MTA. Erst nach Absetzen des STARTTLS Kommandos wird ein
verschlsselter Kanal verwendet.
Als man begonnen hatte, Mails verschluesselt zu uebertragen, beherrschten die
Mailprogramme selber noch keine TLS Verschluesselung. Deswegen benutzte
man externe Programme (z.B. stunnel), die auf einem anderen Port lauschen
(beim Mail ist das der SMTPS Port 465) und die eigentliche Ver- und Entschluesselung
dann fr das eigentliche Programm voellig transparent machen.

#--------------------------------------------------------
# Wichtige Hinweise zur Textkodierung
#--------------------------------------------------------
Die verwendete Textkodierung kann ueber den Parameter MSMTP_CHARSET eingestellt werden.
Bei Problemen wie nicht zustellbare Mails oder unleserlichen Bodytexten ist wahrscheinlich
der eingestellte Charset falsch.

#--------------------------------------------------------
# Anwendungsbeispiele
#--------------------------------------------------------
1)
msmtp.sh -f absender@domaene.de -t empfaenger@domaene.de -s "Wichtige Mitteilung" -b "Im Anhang die Wegebeschreibung" /irgendein/Pfad/anfahrtsskizze.pdf

Bestimmung des Content-Types des Attachments ueber das "file"-Kommando, falls vorhanden,
andernfalls "application/octet-stream".
Typisches Einsatzszenario bei einer Festplatten basierten Installation.

2)
msmtp.sh -f absender@domaene.de -t empfaenger@domaene.de -s "Wichtige Mitteilung" -b "Im Anhang die Wegebeschreibung" application/pdf:/irgendein/Pfad/anfahrtsskizze.pdf

Manuelle Angabe des Content-Types hat Vorrang vor der Bestimmung
durch das "file"-Kommando. Typisches Einsatzszenario bei einer
Disketten basierten Installation.

3)
msmtp.sh -f absender@domaene.de -t empfaenger@domaene.de -s "Wichtige Mitteilung" -b "/hier/steht/der/bodytext.txt" /irgendein/Pfad/anfahrtsskizze.pdf

Wichtig: Soll der Bodytext einer Datei entnommen werden, so ist als Parameter
         der Option "-b" der absolute (!) Pfad der entsprechenden Datei anzugeben.
         Es muss sich dabei um eine reine Textdatei handeln
         (siehe auch "Hinweise zur Textkodierung").

4)
msmtp.sh -f absender@domaene.de -t empfaenger@domaene.de -s "Wichtige Mitteilung" -b "/hier/steht/der/bodytext.txt" -d /data/docs -rp '^.*pdf$' -rn '^.*test.*$'

Wie 4), nur das hier alle Dateien aus dem Verzeichnis /data/docs angehaengt werden,
die auf "pdf" enden und NICHT die Zeichenfolge "test" im Namen enthalten.
Hinweis: Zur Ueberpruefung der regulaeren Ausdruecke wird der Befehl "grep" benutzt.
         Der standardmaessige FLI4L-grep-Befehl unterstuetzt jedoch nicht
         den vollen Funktionsumfang regulaerer Ausdruecke. Liefert der angegebene
         regulaere Ausdruck also nicht die gewuenschten Dateien oder werden auf
         der Konsole bei der Befehlsausfuehrung Fehler ausgegeben, sollte die
         Option "opt_msmtppro='yes'" aktiviert werden, da diese einen grep-Befehl
         mit vollwertiger Unterstuetzung regulaerer Ausdruecke enthaelt.
5)
msmtp.sh -m /irgendein/Pfad/mail.txt

wobei "mail.txt" folgende Struktur besitzt:
// Beginn mail.txt
    From: <absender@domaene.de>
    To: <empfaenger@domaene.de>
    Subject: Wichtige Mitteilung
    Date: Mon May 19 14:01:15 CEST 2003
    MIME-Version: 1.0
    Content-Type: multipart/mixed;    boundary="----=_NextPart_000_000D_01C31590.BBDD9200"
    
    This is a multi-part message in MIME format.
    
    ------=_NextPart_000_000D_01C31590.BBDD9200
    Content-Type: text/plain; charset="iso-8859-1"
    Content-Transfer-Encoding: 8bit
    
    Im Anhang die Wegebeschreibung
    
    ------=_NextPart_000_000D_01C31590.BBDD9200
    Content-Type: application/pdf;    name="anfahrtsskizze.pdf"
    Content-Transfer-Encoding: x-uuencode
    Content-Disposition: attachment; filename="anfahrtsskizze.pdf"
    
    <...schnipp...>
    
    ------=_NextPart_000_000D_01C31590.BBDD9200--
// Ende mail.txt

6)
msmtp.sh -f absender@domne.de -t empfaenger@domne.de -s "Wichtige Mitteilung" -b "Im Anhang die Wegebeschreibung" /irgendein/Pfad/anfahrtsskizze.pdf

wie 1), nur dass hier eine Domaene mit Umlauten verwendet wird. Benoetigt OPT_MSMTPIDN='yes'


#--------------------------------------------------------
# Achtung!
#--------------------------------------------------------
Der mit Version 1.4.20 von msmtp eingefhrte Authentifizierungsmechansismus 
SCRAM-SHA-1 via GNU SASL (http://www.gnu.org/software/gsasl/) funktioniert im
fli4l noch nicht, da es mit noch nicht gelungen ist, GNU SASL fr fli4l zu kompilieren.


#--------------------------------------------------------
# Zum Schluss ...
#--------------------------------------------------------
Lob und konstruktive Kritik bitte per Mail an
Christoph Fritsch <fli4l@dechristo.net>
