englisch | deutsch

Qualifizierter Fax-Sendebericht im PDF-Format mit HylaFAX

Faxen am VOIP-Anschluss mit Asterisk und HylaFAX unter Debian Wheezy auf einem Dockstar

IV. Individuelle HylaFAX-Anpassungen

HylaFAX ist sehr umfangreich dokumentiert, u.a. mit einem Handbuch, das viele Themen behandelt, sowie sehr ausführlichen man-pages. Ich empfehle in jedem Fall, sich über diese beiden Resourcen ein wenig mit den Möglichkeiten und den wesentlichen Abläufen von HylaFAX vertraut zu machen. Die Grundlagen sind durchaus schnell erfasst und überschaubar.

4.1 Grundlegende Anpassungsmöglichkeiten

Für die Anpassung von HylaFAX sind zunächste folgende Konfigurationsdateien interessant:

/etc/hylafax/hyla.conf
/etc/hylafax/hfaxd.conf
/etc/hylafax/config.ttyIAX0
/etc/hylafax/hosts.hfaxd

In 'hyla.conf' können einige Einstellungen vorgenommen werden, wie die Auswahl der Zeitzone (z.B. 'TimeZone: local'). In 'hfaxd.conf' kann unter anderem der zuständige 'Faxmaster' eingestellt werden. In 'config.ttyIAX0' sind die Einstellungen des Modems hinterlegt. Hier kann neben anderen Einstellungen z.B. das Format der am oberen Rand eingefügten Kopfzeile bei ausgehenden Faxen angepasst werden ('TagLineFormat').

In 'hosts.hfaxd' werden die Benutzer gespeichert, die auf HylaFAX zugreifen dürfen. Die Einträge können von Hand editiert werden. Zum Einrichten und Entfernen von Benutzern können aber auch die beiden Befehle 'faxadduser' und 'faxdeluser' verwendet werden. Neben den lokalen Benutzern auf dem Server kann so auch Netzwerk-Benutzern das Faxen gestattet werden. Dies ist bei Verwendung einer der zahlreichen Faxdrucker-Clients für HylaFAX relevant, mit denen ein Dokument aus einer Anwendung (z.B. Office oder PDF-Viewer) heraus direkt an den HylaFAX-Server übergeben und als Fax versendet werden kann. Fehlerfrei gelingt das in meinem Fall beispielsweise mit Winprint HylaFAX, von dem es auch eine erweiterte, neuere Version Winprint HylaFAX Reloaded gibt.

Überträgt HylaFAX ein Dokument, so werden anschließend, je nachdem ob ein Fax empfangen oder gesendet wurde, zwei verschiedene Shell-Skripte ausgeführt:

/var/spool/hylafax/bin/notify
/var/spool/hylafax/bin/faxrcvd

Bei ausgehenden Faxe wird 'notify' aufgerufen, bei einkommenden Faxen 'faxrcvd'. Diese Shell-Skripte binden weitere Skripte ein, wie:

/var/spool/hylafax/bin/common-functions

In 'common-functions' stehen Funktionen, die sowohl nach dem Faxempfang als auch nach dem Faxversand genutzt werden.

Beim Empfang von Faxen wird außerdem die Datei

/etc/hylafax/FaxDispatch

und beim Versenden von Faxen die Datei

/etc/hylafax/FaxNotify

als Shell-Skript eingebunden. Diese Dateien sind für individuelle Anpassungen vorgesehen. Über sie kann sehr einfach in die Abläufe nach dem Empfang oder Versand von Faxen eingegriffen werden. So kann zum Beispiel durch den Eintrag

RETURNFILETYPE=pdf

bestimmt werden, dass nach dem Versenden eines Faxes eine PDF-Kopie des Dokuments im Anhang einer E-Mail an den Absender geschickt wird, wenn dieser eine E-Mail-Adresse angegeben und eine Bestätigung per E-Mail angefordert hat. Als weitere Formate stehen TIFF, Postscript oder das Originalformat des übermittelten Dokuments zur Auswahl. Gibt man mehrere Formate durch Leerzeichen getrennt an, so werden mehrere Anhänge in den entspreched gewünschten Formaten erstellt:

RETURNFILETYPE="pdf ps"

Mit diesem Eintrag würde jeweils eine Kopie im PDF- und im Postscript-Format mit der Benachrichtigungs-E-Mail versendet. Eine Option für einen klassischen Sendebericht gibt es an dieser Stelle leider nicht. Diese habe ich daher selber hinzugefügt. Dazu später mehr.

Die Möglichkeiten, die sich mit 'FaxNotify' und 'FaxDispatch' bieten sind nahezu grenzenlos. So lassen sich Kopien der Faxe automatisch ausdrucken oder in eine Samba-Freigabe legen, individuelle E-Mail-Weiterleitungen je nach Status der Faxsendung einrichten, aber auch wesentlich komplexere Abläufe programmieren. Ich erwähne an dieser Stelle nur noch eine wichtige Option, bevor ich zu meiner Lösung für den Sendebericht übergehe.

Für die Erstellung der verschiedenen Benachrichtigungs-E-Mails greift HylaFAX auf Vorlagen zurück, die sich in folgendem Verzeichnis befinden:

/etc/hylafax/templates/

In diesem Verzeichnis liegen Unterverzeichnisse für verschiedene Sprachen, u.a. auch für deutsche Benachrichtigungen:

/etc/hylafax/templates/de

In diesen Unterverzeichnissen liegen wiederum Textdateien für verschiedene Ereignisse, die in der man-page für 'notify' genauer erläutert werden. Die Textdateien können sehr leicht angepasst werden. So können die Benachrichtigungs-E-Mails nach Belieben individualisiert und auch komplexe HTML-Mails umgesetzt werden.

In 'FaxNotify' und 'FaxDispatch' lässt sich auswählen, welche Vorlagen für die E-Mail-Benachrichtigungen verwendet werden sollen. Für die deutschen Standard-Vorlagen wäre der passende Eintrag:

TEMPLATE=de

Um hingegen individuelle Vorlagen aus einem eigenen Ordner

/etc/hylafax/templates/custom

zu verwenden, wäre stattdessen folgendes einzufügen:

TEMPLATE=custom

Es sei noch erwähnt, dass HylaFAX nicht auf Faxen beschränkt ist, sondern beispielsweise auch mit Pagernachrichten und SMS umgehen kann. Auch ein EMail2Fax-Gateway lässt sich leicht einrichten. Einige solcher Möglichkeiten beschreiben die How-Tos auf der HylaFAX-Webseite.

4.2 Qualifizierter Fax-Sendebericht im PDF-Format

Ich sende Faxe per Faxdrucker an den HylaFAX-Server (Übertragung im Postscript-Format) und lasse mir den erfolgreichen Versand per E-Mail bestätigen. An die E-Mail lasse ich eine PDF-Kopie des gesendeten Dokuments anhängen. Ankommende Faxe werden ebenfalls im PDF-Format im Anhang einer E-Mail zugestellt und außerdem als PDF-Kopie in einem Samba-Verzeichnis abgelegt.

HylaFAX bietet die Möglichkeit, Kopien versendeter Dokumente in den Formaten TIFF, Postscript und PDF oder im Originalformat anzuhängen. Dieselben Format-Optionen werden für die Zustellung empfangener Faxe angeboten.

Die für das Anhängen der Dateien verantwortlichen Funktionen liegen in einem Shell-Skript:

/var/spool/hylafax/bin/common-functions

Sowohl 'notify' (nach Faxversand) als auch 'faxrcvd' (nach Faxempang) binden dieses Shell-Skript ein und rufen die darin enthaltende Funktion 'BuildAttachArgs()' auf. Diese Funktion prüft, welche Formate z.B. über 'FaxNotify' oder 'FaxDispatch' angefordert wurden, und ruft bei Bedarf die in demselben Shell-Skript beschriebene Funktion 'ConvertFile()' auf, um die nötigen Konvertierungen vorzunehmen.

Die Funktionen 'BuildAttachArgs()' und 'ConvertFile()' unterscheiden nicht, ob sie von 'notify' oder 'faxrcvd' aufgerufen wurden.

Um zusätzlich zu den bereits beschriebenen Möglichkeiten einen qualifizierten Sendebericht und weitere neue Funktionen zu erhalten, habe ich folgende Anpassungen vorgenommen:

Nach Einrichtung dieser Änderungen steht in Hylafax ein zusätzlicher Dateityp REPORT zur Verfügung. In der hierfür vorgesehenen Datei 'FaxNotify' (siehe Abschnitt 4.1) kann nun durch einen entsprechenden Eintrag ein qualifizierter Sendebericht im Anhang an eine Benachrichtigungs-E-Mail angefordert werden:

RETURNFILETYPE=report

Das neue Dateiformat REPORT lässt sich mit den bisherigen Formaten PDF, TIFF, Postscript und RAW kombinieren. So kann man beim erfolgreichen Versand eines Faxes auf Wunsch sowohl eine Kopie des gesendeten Dokumentes in einem der verschiedenen Formate als auch einen PDF-Sendebericht erhalten. Soll dem Faxbericht in derselben Datei eine vollständige PDF-Kopie des gesendeten Dokumentes beigefügt werden, wählt man:

RETURNFILETYPE=report+

Um diese Erweiterung einzurichten, muss die zum Herunterladen bereitgestellte Datei 'custom-functions' im bin-Verzeichnis von HylaFAX abgelegt werden:

/var/spool/hylafax/bin/

Die Datei kann direkt über die Konsole heruntergeladen und im passenden Verzeichnis entpackt werden:

$ wget http://1024k.de/hylafax/scripts/HylaFAX_custom-functions.tar.gz
$ tar -xvzf HylaFAX_custom-functions.tar.gz -C /var/spool/hylafax/bin/ --strip-components 1
$ rm HylaFAX_custom-functions.tar.gz

In der 'notify'-Datei, die ebenfalls im bin-Verzeichnis von HylaFAX liegt, muss folgende Zeile idealerweise direkt nach der Einbindung von 'common-functions' eingefügt werden:

. bin/custom-functions

Hierdurch werden die neuen Funktionen integriert. Schließlich muss in der 'notify'-Datei der ursprüngliche Aufruf von 'BuildAttachArgs()'

ATTACH_ARGS="$ATTACH_ARGS "`BuildAttachArgs $ft`

auf die erweiterte neue Funktion 'BuildAttachArgsMod()' umgeleitet werden:

ATTACH_ARGS="$ATTACH_ARGS "`BuildAttachArgsMod $ft notify`

Die alte Zeile wird durch die neue Zeile ersetzt. Dabei wird auch der zusätzliche Parameter 'notify' hinzugefügt.

Durch das Wiederherstellen der alten Zeile und das Entfernen der zuvor hinzugefügten Zeile zur Einbindung von 'custom-functions' lassen sich die Erweiterungen jederzeit komplett abschalten und somit sehr leicht wieder das ursprüngliche HylaFAX herstellen. Man kann hierfür auch ein Backup der ursprünglichen Datei 'notify' anlegen und dieses bei Bedarf wiederherstellen.

An dieser Stelle sei auch darauf hingewiesen, dass die Datei 'notify' im Rahmen von HylaFAX-Updates durch eine neuere Version ersetzt werden kann. Die Änderung der beiden Zeilen geht in diesem Fall verloren und muss erneuert werden. Gleiches gilt für die Datei 'faxrcvd' (siehe Punkt 4.3)

Wenn REPORT oder REPORT+ als Dateityp angefordert wird, ruft 'ConvertFileMod()' die neue Funktion 'CreateFaxReport()' auf. Diese verkleinert die erste Seite einer an das Skript übergebenen PDF-Datei auf 60% der Originalgröße und fügt diese in einen Sendebericht ein. Der Sendebericht wird zunächst im Postscript-Format erstellt und mit den Informationen der Faxsendung ausgefüllt. Für die Ausgabe im PDF-Format werden anschließend die passenden Headerinformationen (u.a. der Faxzeitpunkt als Erstellungsdatum) ergänzt und schließlich der PDF-Sendebericht ausgegeben. Wird REPORT+ ausgewählt so wird an den Sendebericht noch eine vollständige PDF-Kopie des Originaldokuments angehängt.

Die Seiten-Ausmaße der zu verkleinernden PDF-Datei werden mit der Imagemagick-Funktion 'Identify()' ermittelt. Damit dies funktioniert, muss Imagemagick installiert sein:

$ apt-get install imagemagick

Wer das vermeiden möchte, kann stattdessen auch die Postscript-Datei 'pdf_info.ps' aus dem Ghostscript toolbin zusammen mit Ghostscript verwenden, um die Seitenmaße zu bestimmen. Dazu muss die Funktion 'PrepareReportCreation()' angepasst (und die Zeile mit dem Identify-Befehl entfernt) werden:

DIMENSIONS=($(gs -dNODISPLAY -q -sFile=$PDFIN -dDumpMediaSizes \
/var/spool/hylafax/bin/pdf_info.ps | \
grep MediaBox | sed "s/.*\[\(.*\)\].*/\1/"))
PGWIDTH=${DIMENSIONS[2]};PGHEIGHT=${DIMENSIONS[3]}

Ghostscript ist auf einem System mit HylaFAX standardmäßig mit installiert. Bei der obigen Anpassung wird 'pdf_info.ps' im bin-Verzeichnis von Hylafax erwartet. Möchte man die Postscript-Datei an einer anderen Stelle speichern, muss man den Pfad entsprechend anpassen.

Wurde alles richtig eingerichtet, schaut das Ergebnis, der Inhalt des ersehnten PDF-Faxreports im Anhang der Benachrichtigungs-E-Mail, schließlich wie folgt aus (die Schwärzungen von Namen und Rufnummern sind im Original natürlich nicht vorhanden):

Beispiel des ausgegebenen Fax-Sendeberichts

Schickt man ein Dokument direkt aus einer Textverarbeitung an den Faxserver, schaut die Fax-Kopie auf dem Faxreport erwartungsgemäß "perfekt" aus. Schickt man hingegen eine auf Faxniveau eingescannte Datei an den Faxserver, bekommt man logischwerweise auch den vom analogen Fax gewohnten Kopierer-Look auf dem Faxreport.

Die Zeitangabe oben rechts im Header des Faxreports gibt den Zeitpunkt der Erstellung des Berichts wieder, während weiter unten die Zeit des Faxversands angezeigt wird.

4.3 Ändern der Dateinamen von E-Mail-Anhängen

Mittels der Erweiterung lassen sich zusätzlich die Namen der E-Mail-Anhänge individuell einrichten. Soll dies nicht nur für gesendete sondern auch für empfangene Dokumente ermöglicht werden, so ist zunächst die Datei 'faxrcvd' anzupassen. Auch hier müssen, wie schon bei der Datei 'notify', die zusätzlichen Funktionen eingebunden werden, durch Ergänzen der Zeile:

. bin/custom-functions

Desweiteren muss auch hier der Aufruf von 'BuildAttachArgs()' auf die neue Funktion 'BuildAttachArgsMod()' umgeleitet werden:

ATTACH_ARGS="$ATTACH_ARGS "`BuildAttachArgsMod $ft faxrcvd`

Die Zeile mit dem alten Aufruf wird hierfür wiederum durch die neue ersetzt. Wichtig: hier wird nun nicht 'notify' sondern 'faxrcvd' als zusätzliches Argument übergeben.

Über die Dateien 'FaxNotify' und 'FaxDispatch' lassen sich daraufhin die Namen der E-Mail-Anhänge getrennt für ausgehende und einkommende Faxe einstellen. Fügt man folgendes ein:

CUSTOMNAME=Faxdokument

so wirkt sich das in dieser Weise aus:

Attachment-Name/alt: doc12.ps
Attachment-Name/neu: Faxdokument.12.ps
Attachment-Name/alt: fax000000012.tif
Attachment-Name/neu: Faxdokument.12.tif

Soll die HylaFAX-Nummerierung der Anhänge entfallen, so ermöglicht die Erweiterung auch dies:

FILENUMBERING=no

Die Angabe unter CUSTOMFILENAME wird als String eingelesen. Zulässige Zeichen sind Buchstaben und Ziffern, Punkte, Bindestriche und Unterstriche. Ungültige Zeichen werden durch Unterstriche ersetzt. Gültige Datumssequenzen, die mittels %-Zeichen gekennzeichnet sind, werden durch die Datums-/Zeitwerte der Faxübertragung ersetzt. Siehe dazu die man-page für 'date'. Gibt man z.B. folgendes an:

CUSTOMFILENAME=%Y-%d-%m_fax_%H-%M-%S

so schaut das Resultat für ein am 24. Dezember 1970 um 09:38:59 versendetes Fax wie folgt aus:

Attachment-Name/alt     : doc12.ps
Attachment-Name/neu     : 1970-12-24_fax_09-38-59.12.ps
Attachment-Name/ohne Nr.: 1970-12-24_fax_09-38-59.ps

Die Änderung der Namen betrifft ausschließlich die E-Mail-Anhänge. Die Namen der Originaldateien auf dem Server und die Einträge in Queue- und Logfiles bleiben unverändert. Dies ist beabsichtigt.

Die Sendeberichte im REPORT und im REPORT+ Format erhalten ein Suffix vor der PDF-Dateiendung, um sie auf Anhieb erkennen zu können. Die Standard-Endungen sind '.report.pdf' und '.report+.pdf'. Die Suffixe können über die Datei 'FaxNotify' individuell angepasst werden. So führen die Einträge

CUSTOMSUFFIXREPORT=simple
CUSTOMSUFFIXREPORT+=plus

beispielsweise zu folgendem Ergebnis:

doc12.simple.pdf
doc12.plus.pdf

Vollständig entfernen lassen sich die Suffixe mittels:

CUSTOMSUFFIXREPORT=""
CUSTOMSUFFIXREPORT+=""

Die Angaben unter CUSTOMSUFFIXREPORT und CUSTOMSUFFIXREPORT+ werden als String eingelesen. Zulässige Zeichen für die Einstellung der Suffixe sind Buchstaben und Ziffern, Punkte, Bindestriche, Unterstriche und das Pluszeichen. Ungültige Zeichen werden durch Unterstriche ersetzt.

4.4 Zusammenlegen der Dateien beim Versand mehrerer Dokumente

Versendet man mehrere Dokumente in einem Fax, so fügt HylaFAX der Bestätigungs-E-Mail normalerweise für jedes Dokument einen einzelnen Dateianhang bei. Die Erweiterung ermöglicht es, alle Anhänge eines Formats zu einer Datei zusammenfassen zu lassen. Dies wird mittels eines Eintrags in der Datei 'FaxNotify' aktiviert:

FILEMERGING=yes

Die Einstellung gilt automatisch für sämtliche Dateiformate bis auf RAW. Für das Format RAW wird angenommen, dass die Dokumente in möglichst ursprünglichem Zustand bleiben sollen, und es erfolgt keine Zusammenlegung der Dateien.

4.5 Abschließende Detailanpassungen

Um einen Sendebericht nur im Falle eines erfolgreichen Faxversands zu erhalten, habe ich in 'FaxNotify' noch die folgenden Eintragungen ergänzt:

if [ "$WHY" != "done" ]; then
 RETURNFILETYPE="pdf"
else
 RETURNFILETYPE="pdf report"
fi

Über die Variable '$WHY' wird der Faxstatus abgefragt und in allen Fällen außer 'done' kein Sendebericht angehängt. Stattdessen wird bei Fehlern, die eine Benachrichtigung mit Anhang auslösen, nur eine PDF-Kopie des (nicht) gesendeten Dokumentes angehängt. Man könnte alternativ im Fehlerfall z.B. auch vollständig auf einen Anhang verzichten und sich im Erfolgsfall nur einen REPORT+ senden lassen.

Weitere Ergänzungen habe ich in 'FaxDispatch' vorgenommen, um eine Kopie einkommender Faxe in ein Samba-Verzeichnis zu legen:

## PDF2Samba
##
## Creates a read accessible copy of incoming fax files in
## /smb/networkshares/fax

# example for website: original file name without file extension
# n=$(basename $FILE .tif)

# custom file name with transmission date/time
REGEXP="^[0-9]*:[0-9]*:[0-9]* [0-9]*:[0-9]*:[0-9]*$"
if [[ "$RECEIVED" =~ $REGEXP ]] ; then
 TXTIME=$(echo $RECEIVED | sed 's/^\([0-9]*\):\([0-9]*\):\([0-9]*\)/\1-\2-\3/')
else
 TXTIME=$(date +"%Y-%m-% %H:%M:%S")
fi
n=$(date +"%Y-%m-%d_fax_%H-%M-%S" -d "$TXTIME")

# defining target destination
t=/smb/networkshares/fax/$n

# creating PDF in target destination
$TIFF2PDF -o $t.pdf $FILE

# granting file access
chmod 644 $t.pdf

Damit ist meine FAX-Lösung mit Asterisk, IAXmodem und HylaFAX im Wesentlichen beschrieben und es bleiben hoffentlich keine Fragen offen.

Anfang | zurück | vor | Ende