Asterisk 1.4 - 1.6

Buch bei Amazon kaufen

21.1. Faxserver mit IAXmodem und HylaFax

Die Software IAXmodem emuliert ein Modem, das von einer beliebigen Faxsoftware angesteuert werden kann. Als Faxserversoftware nehmen wir das populäre HylaFax (http://www.hylafax.org/) oder HylaFax+ (http://hylafax.sourceforge.net/). Als Plattform benutzen wir für diese Installationsanleitung das im restlichen Buch ebenfalls verwendete Debian Linux mit einem Asterisk 1.4 (siehe Abschnitt A.1, „Installation von Asterisk 1.4.x auf Debian Linux“).

Installation von IAXmodem

IAXmodem ist eine Software, die ein Modem simuliert und dieses Asterisk mit dem IAX2-Protokoll zur Verfügung stellt. Alle Schritte in diesem Kapitel werden als User root ausgeführt.
Um IAXmodem installieren zu können, benötigen wir noch einige Debian-Pakete:
debian:~# aptitude -y install g++ libtiff-tools libtiff4 libtiff4-dev
[...]
Richte zlib1g-dev ein (1.2.2-4.sarge.2) ...
Richte libtiff4-dev ein (3.7.2-7) ...
debian:~#
Zum Installieren der Sourcen wechseln wir wieder in das entsprechende Verzeichnis:
debian:~# cd /usr/src/
debian:/usr/src#
Die Sourcen zu IAXmodem können mit einem normalen Browser auf der Webseite http://iaxmodem.sourceforge.net heruntergeladen werden (in diesem Beispiel ist es die Version 1.2.0, Sie können aber auch eine andere Version nehmen). Nach dem Download muss der Tarball entpackt werden:
debian:/usr/src# wget http://downloads.sourceforge.net/iaxmodem/iaxmodem-1.2.0.tar.gz
[...]
debian:/usr/src# tar -xvzf iaxmodem-1.2.0.tar.gz 
iaxmodem-1.2.0/
iaxmodem-1.2.0/iaxmodem.c
iaxmodem-1.2.0/iaxmodem.init.debian
[...]
debian:/usr/src#
Nun wechseln wir in das neue Verzeichnis:
debian:/usr/src# cd iaxmodem-1.2.0
debian:/usr/src/iaxmodem-1.2.0#
Und kompilieren es danach:
debian:/usr/src/iaxmodem-1.2.0# ./configure && make
checking for a BSD-compatible install... /usr/bin/install -c
checking whether build environment is sane... yes
checking for gawk... no
checking for mawk... mawk
checking whether make sets $(MAKE)... yes
checking for gcc... gcc
[...]
debian:/usr/src/iaxmodem-1.2.0#
Das dabei entstehende Binary iaxmodem kopieren wir zum Schluss in das Verzeichnis /usr/bin/:
debian:/usr/src/iaxmodem-1.2.0# cp iaxmodem /usr/bin/
debian:/usr/src/iaxmodem-1.2.0#
Jetzt kommen wir zur Konfiguration des Modems. IAXmodem sucht seine Konfiguration im Verzeichnis /etc/iaxmodem/. Dieses müssen wir jetzt anlegen:
debian:/usr/src/iaxmodem-1.2.0# cd
debian:~# mkdir /etc/iaxmodem
debian:~#
Und eine Datei erzeugen, in der die Konfiguration stehen soll, schreiben wir:
debian:~# cd /etc/iaxmodem/
debian:/etc/iaxmodem# touch ttyIAX0
debian:/etc/iaxmodem#
In dieser Datei müssen folgende Parameter angegeben werden:
device
Das ist das Device (Gerät), das im Verzeichnis /dev angelegt wird. Über dieses Device kann Hylafax später auf das Modem zugreifen. Der Name des Devices ist frei wählbar, wir halten uns aber an die allgemeinen Konventionen und nennen es ttyIAX0 – äquivalent zum Device für die serielle Schnittstelle.
owner
Das ist der Eigentümer des Devices in der Form user:group. Es sollte derselbe User und dieselbe Gruppe sein, unter der Hylafax laufen soll.
port
Der Port, auf dem das IAXmodem lauscht. Da Asterisk auf Port 4569 auf „normale“ IAX2-Verbindungen hört, sollte man hier einen anderen Port verwenden, z. B. 4570.
refresh
Das Intervall, nach dem sich das Modem erneut bei Asterisk registriert. Wenn dieses auf 0 steht, registriert sich das Modem nicht bei Asterisk, und man müsste dem IAX-Peer in Asterisk eine feste IP-Adresse zuweisen.
server
Der Server, auf dem Asterisk läuft. Wenn der Server derselbe ist, auf dem auch das IAXmodem läuft, steht hier die lokale Adresse 127.0.0.1.
peername
Der Name, unter dem sich das IAXmodem bei Asterisk registriert.
secret
Das Passwort zur Registrierung an Asterisk
codec
Der Codec, der vom IAXmodem verwendet wird. Erlaubt sind hier alaw, ulaw und slinear. Andere machen hier auch wenig Sinn, da diese komprimieren und die Übertragung dadurch nicht verlustfrei ist. Bei reiner Sprachübertragung wirkt sich das für einen Menschen nicht negativ aus, bei Faxübertragungen aber hätte es störende Fehler zur Folge.
Mit einem beliebigen Editor (z. B. vi oder vim) schreiben wir die folgende Konfiguration in die Datei /etc/iaxmodem/ttyIAX0
device          /dev/ttyIAX0
owner           uucp:uucp
mode            660
port            4570
refresh         50
server          127.0.0.1
peername        iaxmodem
secret          password
codec           alaw
Jetzt ist das IAXmodem fertig konfiguriert und muss gestartet werden. Dies geschieht am besten über den init-Prozess. Also fügen wir den folgenden Eintrag am Ende der Datei /etc/inittab hinzu (in vi oder vim):
IA00:23:respawn:/usr/bin/iaxmodem ttyIAX0
Dabei ist ttyIAX0 der Name der Konfigurationsdatei unter /etc/iaxmodem/.
Zum Faxempfang benötigt man einen getty, der am IAXmodem auf Verbindungen lauscht. Das erreicht man ganz einfach durch einen weiteren Eintrag in der Datei /etc/inittab:
mo00:23:respawn:/usr/local/sbin/faxgetty ttyIAX0
Damit IAXmodem in die Logdateien schreiben kann, legen wir den Ordner /var/log/iaxmodem an und erstellen die Logdateien ttyIAX0 und iaxmodem:
debian:~# mkdir /var/log/iaxmodem
debian:~# cd /var/log/iaxmodem/
debian:/var/log/iaxmodem# touch ttyIAX0
debian:/var/log/iaxmodem# touch iaxmodem
debian:/var/log/iaxmodem#
Um ganz sicherzugehen, rebooten wir jetzt noch einmal den Rechner, damit init auch das IAXmodem richtig startet.
debian:~# shutdown -r now
[...]
The system is going down for reboot NOW!
debian:~#

Installation von HylaFax

Um die Installation zu vereinfachen, installieren wir den Faxserver aus dem Debian-Repository. Abhängigkeiten werden automatisch aufgelöst:
debian:~# aptitude -y install hylafax-server
[...]
Die folgenden NEUEN Pakete werden installiert:
  enscript gs-common gs-esp hylafax-client 
  hylafax-server libcupsimage2 libcupsys2 
  mailx metamail psmisc
[...]

Update /var/spool/hylafax/status/any.info.

        HylaFAX configuration parameters are:

        [1] Init script starts faxq:            yes
        [2] Init script starts hfaxd            yes
        [3] Start old protocol:                 no
        [4] Start paging protocol:              no
Are these ok [yes]? Enter
Modem support functions written to /var/spool/hylafax/etc/setup.modem.
Configuration parameters written to /var/spool/hylafax/etc/setup.cache.

Restarting HylaFAX server processes.

Should I restart the HylaFAX server processes [yes]? Enter
You do not appear to have any modems configured for use.  Modems are
configured for use with HylaFAX with the faxaddmodem(8) command.
Do you want to run faxaddmodem to configure a modem [yes]? Enter
Done verifying system setup.
Updating /etc/hylafax/setup.cache from /var/spool/hylafax/etc/setup.cache.
Updating /etc/hylafax/setup.modem from /var/spool/hylafax/etc/setup.modem.
/var/spool/hylafax
Starting HylaFAX: faxq hfaxd faxgetty.

debian:~#
Der nächste Schritt ist das Setup des Faxservers. Hierzu rufen wir das Programm faxsetup auf:
debian:~# faxsetup
[...]

Update /var/spool/hylafax/status/any.info.

        HylaFAX configuration parameters are:

        [1] Init script starts faxq:            yes
        [2] Init script starts hfaxd            yes
        [3] Start old protocol:                 no
        [4] Start paging protocol:              no

Are these ok [yes]? Enter
Fragen über Fragen, aber nur die wenigsten sind wirklich wichtig.[113] Wichtig sind natürlich die Faxnummer und der sogenannte LocalIdentifier. Das ist der Text, der auf jedem gesendeten Fax in der obersten Zeile steht.
Bei den folgenden 2 bis 3 Fragen drücken wir einfach immer Enter.
You have a HylaFAX scheduler process running.  faxq will be
restarted shortly, as soon as some other work has been completed.
Can I terminate this faxq process (4048) [yes]?
Should I restart the HylaFAX server processes [yes]?
/etc/init.d/hylafax start
Not starting HylaFAX daemons since they are already running.
[...]
Modems are configured for use with HylaFAX with the faxaddmodem(8) command.
Do you want to run faxaddmodem to configure a modem [yes]?
Wir bestätigen den Restart des Serverprozesses zweimal mit yes und werden gefragt, ob wir ein Modem installieren wollen. Da unser IAXmodem bereits eingerichtet ist, können wir hier direkt weitermachen und bestätigen wieder mit yes.
Hier geben wir das Modem an und bestätigen es mit Enter.
Serial port that modem is connected to [ttyS0]? ttyIAX0

Ok, time to setup a configuration file for the modem.  The manual
page config(5) may be useful during this process.  Also be aware
that at any time you can safely interrupt this procedure.

Reading scheduler config file /var/spool/hylafax/etc/config.
Bei den folgenden Einstellungen müssen Sie die für Ihre Installation geeigneten Werte (also z. B. die Internationale Vorwahl 49 für Deutschland) eingeben. Dabei sind bei den meisten Installationen nur die ersten sechs Fragen wichtig. Die erste betrifft die Landesvorwahl als zweistellige Zahl, für Deutschland also die 49. Dann folgt die Ortsnetznummer ohne führende Null, in diesem Beispiel die 69 für Frankfurt am Main. Daraufhin folgt die Faxnummer mit Vorwahl. Dann kommt eine Null für Ferngespräche und zwei Nullen für internationale Gespräche. Am Schluss bestätigen Sie mit yes.
No existing configuration, let's do this from scratch.

Country code [1]? 49
Area code []? 69
Phone number of fax modem [+1.999.555.1212]? +49 69 12345678
Local identification string (for TSI/CIG) ["NothingSetup"]? 
Long distance dialing prefix [1]? 0
International dialing prefix [011]? 00
Dial string rules file (relative to /var/spool/hylafax) [etc/dialrules]? 
Tracing during normal server operation [1]? 
Tracing during send and receive sessions [11]? 
Protection mode for received facsimile [0600]? 
Protection mode for session logs [0600]? 
Protection mode for ttyIAX0 [0600]? 
Rings to wait before answering [1]? 
Modem speaker volume [off]? 
Command line arguments to getty program ["-h %l dx_%s"]? 
Pathname of TSI access control list file (relative to /var/spool/hylafax) [""]? 
Pathname of Caller-ID access control list file (relative to /var/spool/hylafax) [""]? 
Tag line font file (relative to /var/spool/hylafax) [etc/lutRS18.pcf]? 
Tag line format string ["From %%l|%c|Page %%P of %%T"]? 
Time before purging a stale UUCP lock file (secs) [30]? 
Hold UUCP lockfile during inbound data calls [Yes]? 
Hold UUCP lockfile during inbound voice calls [Yes]? 
Percent good lines to accept during copy quality checking [95]? 
Max consecutive bad lines to accept during copy quality checking [5]? 
Max number of pages to accept in a received facsimile [25]? 
Syslog facility name for ServerTracing messages [daemon]?
Set UID to 0 to manipulate CLOCAL [""]? 
Use available priority job scheduling mechanism [""]?
Es folgt eine Übersichtsseite, auf der Sie nochmals die Daten bestätigen können:
The non-default server configuration parameters are:

CountryCode:            49
AreaCode:               69
FAXNumber:              +49 69 12345678
LongDistancePrefix:     0
InternationalPrefix:    00
DialStringRules:        etc/dialrules
SessionTracing:         11
RingsBeforeAnswer:      1
SpeakerVolume:          off
GettyArgs:              "-h %l dx_%s"
LocalIdentifier:        "NothingSetup"
TagLineFont:            etc/lutRS18.pcf
TagLineFormat:          "From %%l|%c|Page %%P of %%T"
MaxRecvPages:           25

Are these ok [yes]?
Yes bringt uns weiter zur Modem-Erkennung:
Now we are going to probe the tty port to figure out the type
of modem that is attached.  This takes a few seconds, so be patient.
Note that if you do not have the modem cabled to the port, or the
modem is turned off, this may hang (just go and cable up the modem
or turn it on, or whatever).

Probing for best speed to talk to modem: 38400 OK.

About fax classes:

The difference between fax classes has to do with how HylaFAX interacts
with the modem and the fax protocol features that are used when sending
or receiving faxes.  One class isn't inherently better than another;
however, one probably will suit a user's needs better than others.
    
Class 1 relies on HylaFAX to perform the bulk of the fax protocol.
Class 2 relies on the modem to perform the bulk of the fax protocol.
Class 2.0 is similar to Class 2 but may include more features.
Class 1.0 is similar to Class 1 but may add V.34-fax capability.
Class 2.1 is similar to Class 2.0 but adds V.34-fax capability.
      
HylaFAX generally will have more features when using Class 1/1.0 than
when using most modems' Class 2 or Class 2.0 implementations.  Generally
any problems encountered in Class 1/1.0 can be resolved by modifications
to HylaFAX, but usually any problems encountered in Class 2/2.0/2.1 will
require the modem manufacturer to resolve it.

If you're unsure and your modem supports it, use Class 1.

This modem looks to have support for Class 1 and 1.0.
How should it be configured [1]? 

Hmm, this looks like a Class 1 modem.
Product code (ATI0) is "spandsp".
Other information (ATI3) is "www.soft-switch.org".
DTE-DCE flow control scheme [default]? 
Modem manufacturer is "spandsp".
Modem model is "IAXmodem".

Using prototype configuration file iaxmodem...

The modem configuration parameters are:

ModemResetCmds:         "ATH1\nAT+VCID=1"

Are these ok [yes]?
Das Modem wurde erkannt, und wir werden gefragt, ob es ein Class-1-Modem ist. Da dies genau das ist, was wir wollen, bestätigen wir. Auch das Reset-Kommando für das Modem können wir so übernehmen. Wenn alles in Ordnung ist, bestätigen wir mit yes.
Im folgenden Dialog wird die erste Frage mit no beantwortet, da es kein weiteres Modem zu konfigurieren gibt. Die zweite Frage wird mit enter bestätigt, was das Neustarten des Fax-Servers bewirkt.
Creating new configuration file /var/spool/hylafax/etc/config.ttyIAX0...
Creating fifo /var/spool/hylafax/FIFO.ttyIAX0 for faxgetty... done.
Done setting up the modem configuration.
[...]
Do you want to run faxaddmodem to configure another modem [yes]? no
[...]
Should I run faxmodem for each configured modem [yes]? 
/usr/sbin/faxmodem ttyIAX0

Done verifying system setup.
/var/spool/hylafax

debian:~#
Jetzt ist Hylafax zum Senden von Faxen eingerichtet.

Faxe empfangen

Jetzt muss diese Faxlösung noch in Asterisk integriert werden. Dazu müssen wir Asterisk das IAXmodem bekannt machen. Dies erreichen wir, indem wir es als IAX-Peer definieren. Die dazu erforderliche Datei heißt /etc/asterisk/iax.conf (siehe auch Abschnitt 8.7, „IAX“):
[general]
bindport = 4569           
bindaddr = 0.0.0.0    
disallow = all
allow = alaw
allow = ulaw

[iaxmodem]
type = friend
secret = password
port = 4570
host = dynamic
context = fax-out
disallow = all
allow = alaw
Im Abschnitt general sind die globalen IAX2-Daten abgelegt. In diesem Beispiel wird der Bind-Port auf den Standard für IAX 4569 gesetzt. Die Bind-Adresse gibt das Interface an, auf dem IAX lauscht; in diesem Falle lauscht es auf allen Interfaces.
In der Konfiguration für das IAXmodem wird der type auf friend gesetzt, d.h. es sind eingehende und ausgehende Verbindungen erlaubt. secret und port entsprechen der Konfiguration des IAXmodems, der context ist der, der bei einer ausgehenden Verbindung angesprochen wird.
Wir können jetzt in der Asterisk-Console (CLI) unser IAXmodem sehen:
debian:~# asterisk -rx 'reload'
debian:~# asterisk -r
*CLI> iax2 show peers
Name/Username   Host             Mask             Port   Status
iaxmodem        127.0.0.1   (D)  255.255.255.255  4570   Unmonitored
1 iax2 peers [0 online, 0 offline, 1 unmonitored]
*CLI>
Damit Asterisk weiß, was es mit einem ankommenden Fax anstellen soll, müssen wir eine entsprechende Extension schreiben. Das Ziel soll sein, dass ein ankommendes Fax direkt an das Hylafax weitergeleitet wird. In diesem Beispiel gehen wir davon aus, dass alle Faxe über einen SIP-Provider-Anschluss hereinkommen. Eine entsprechende Konfiguration in der sip.conf kann wie folgt aussehen (die entsprechenden Einstellungen müssen natürlich an die jeweilige Installation und den SIP-Provider angepasst werden):
[...]

[123456]
type = friend
insecure = port,invite
nat = yes
username = 123456
fromuser = 123456
fromdomain = mein-voip-provider.de
secret = geheim
host = mein-voip-provider.de
qualify = yes
context = fax-in

[...]
Der entsprechende Context in der extensions.conf sieht dann so aus:
[fax-in]
exten => _X.,1,Dial(IAX2/iaxmodem)
Jetzt wird das Fax vom Asterisk an Hylafax über IAXmodem übergeben und per Mail an den User gesendet, auf den das Mail-Alias faxmaster zeigt.

Faxe versenden

Der nächste Schritt ist das Versenden von Faxen. Auch hierfür brauchen wir einen Context (diesmal [fax-out]) in der extension.conf. Wenn das virtuelle IAXmodem ein Fax versenden will, kommt es automatisch in diesen Context. Sollen die Faxe dann über unsere Beispiel-SIP-Verbindung 123456 gefaxt werden, so sieht der Eintrag in der extensions.conf wie folgt aus:
[fax-out]
exten => _X.,1,Dial(SIP/123456/${EXTEN})
Testen können wir das Senden mit sendfax -n -d <Faxnummer> <datei.txt>:
debian:~# sendfax -n -d 06912345678 /etc/issue.net
Im CLI sollten wir jetzt Folgendes sehen:
 -- Accepting AUTHENTICATED call from 127.0.0.1:
       > requested format = alaw,
       > requested prefs = (),
       > actual format = alaw,
       > host prefs = (alaw),
       > priority = mine
    -- Executing Answer("IAX2/iaxmodem-3", "") in new stack
    -- Executing Dial("IAX2/iaxmodem-3", "SIP/123456/06912345678") in new stack
    -- Called 123456/06912345678
    -- SIP/123456-0818f630 is making progress passing it to IAX2/iaxmodem-3
    -- SIP/123456-0818f630 answered IAX2/iaxmodem-3
    -- parse_srv: SRV mapped to host mein-voip-provider.de, port 5060
  == Spawn extension (fax-out, 06912345678, 2) exited non-zero on 'IAX2/iaxmodem-3'
    -- Executing Hangup("IAX2/iaxmodem-3", "") in new stack
  == Spawn extension (fax-out, h, 1) exited non-zero on 'IAX2/iaxmodem-3'
    -- Hungup 'IAX2/iaxmodem-3'
Das Kommando faxstat -s gibt während des Sendens folgende Zeilen aus:
debian:~# faxstat -s
HylaFAX scheduler on w077.example.com: Running
Modem ttyIAX0 (123456): Sending job 7

JID  Pri S  Owner Number       Pages Dials     TTS Status
7    127 R   root 06912345678  0:1   0:12
debian:~#
Fertig! Jetzt können Sie über Asterisk mit Hylafax Faxe versenden und empfangen.
Auf der Hylafax-Webseite http://www.hylafax.org finden Sie viele Hinweise und Howtos, wie Sie Ihren neuen Faxserver möglichst einfach in Ihre bestehende Büro-Infrastruktur einbinden.

Empfangene Faxe als E-Mail versenden

Im Folgenden wird die Hylafax-Konfiguration so angepasst, dass der Faxserver eingehende Faxe an eine vorgegebene E-Mail-Adresse versendet.[114] Der Empfänger soll das Fax als E-Mail Anhang erhalten.
Dazu müssen in der Datei /var/spool/hylafax/etc/FaxDispatch die folgende Parameter angegeben werden:
SENDTO
Empfänger der eingehenden Faxe
FILETYPE
Format der Anhänge. Neben dem Format pdf kann auch tiff oder ps gewählt werden.
SENDTO=fax-incoming@company.com
FILETYPE=pdf
Nachdem die Datei abgespeichert ist, muss der Faxserver mit /etc/init.d/hylafax restart neu gestartet werden:
debian:~# /etc/ini.d/hylafax restart
Starting HylaFAX: faxq hfaxd.
debian:~#
Testen können wir es, in wir uns z. B. selbst mit sendfax -n -d <Faxnummer> <datei.txt> ein Fax senden:
debian:~# sendfax -n -d 06912345678 /etc/issue.net
Nach kurzer Zeit sollten Sie eine E-Mail in der folgenden Form empfangen:
 recvq/fax000000016.tif (ftp://debian:4559/recvq/fax000000016.tif):                                  
          Sender: IAXmodem
           Pages: 4
         Quality: Normal
            Size: North American Letter
        Received: 2007:06:02 02:49:45
 Time To Receive: 1:58
     Signal Rate: 9600 bit/s
     Data Format: 2-D MMR
   Error Correct: Yes
         CallID1: 2007
         CallID2: IAXmodem 1
     Received On: ttyIAX0
          CommID: 000000033 (ftp://debian:4559/log/c000000033)

[...]

Jun 02 02:51:46.99: [ 3320]: RECV FAX: bin/faxrcvd "recvq/fax000000016.tif" "ttyIAX0" "000000033" "COMREC received DCN" "2007" "IAXmodem 1" "<NONE>" "s"
Jun 02 02:51:47.00: [ 3320]: RECV FAX: end
Jun 02 02:51:47.00: [ 3320]: SESSION END
Jun 02 02:51:47.01: [ 3320]: RECV FAX (000000033): recvq/fax000000016.tif from IAXmodem, route to <unspecified>, 4 pages in 2:08
Im Anhang finden Sie dann eine PDF-Datei, die in diesem Beispiel fax000000016.pdf heißen würde.
Fertig! Jetzt können Sie über Asterisk mit Hylafax Faxe versenden und empfangene Faxe nun auch als E-Mail Anhang erhalten.

Hylafax-FAQ

F:

Wo legt Hylafax die empfangenen Faxe ab?

A:

Diese liegen im Ordner /var/spool/hylafax/recvq .

F:

Kann man anstatt Hylafax auch andere Faxserversoftware einsetzen?

A:

Ja. Allerdings hat sich Hylafax sehr bewährt.

F:

Gibt es einen einfachen Fax-Client für Windows?

A:

Ja, bitte schauen Sie für eine Liste aller Clients (auch für andere Betriebssysteme) unter http://www.hylafax.org/content/Client_Software nach.

F:

Gibt es zu Hylafax ein eigenes FAQ?

A:

Ja, dieses finden Sie unter http://www.hylafax.org/content/FAQ.

[113] Diejenigen, die schon einmal ein Hylafax „getunt“ haben, mögen uns verzeihen, aber für den Anfang reichen die Defaults.

[114] Wir setzen einen richtig konfigurierten MTA (z. B. Sendmail oder Postfix) voraus.