		** ABOUT IAXMODEM **

IAXmodem is a software modem written in C that uses an IAX channel
(commonly provided by an Asterisk PBX system) instead of a traditional
phone line and uses a DSP library instead of DSP hardware chipsets.

To accomplish this, then, IAXmodem interfaces an IAX library known as
libiax2 with a DSP library known as spandsp, and then IAXmodem interfaces
the DSP library with a tty device node for interfacing with modem (fax)
applications.

IAXmodem comes with a copy of both libiax2 and spandsp.  Both of these
libraries have had bugs fixed and enhancements added for specific use
with IAXmodem.  All of these changes have been submitted to the
library authors and may be committed to those source repositories
eventually.  However, the versions here should be used.

If you are using other applications that require a different libiax2 or
spandsp version then iaxmodem can be statically linked to the libraries
after building the versions here (but not installing them).  See the
part about "build static" below.

Currently supported platforms are GNU/Linux on x86 hardware.

The libiax2 source was pulled from iaxclient CVS on February 22, 2006.

The spandsp source is spandsp-0.0.3 snapshot 20060829.

IAXmodem should usually be installed either on the same machine as the
Asterisk server or on a system that is very close to the Asterisk server
on a controlled network.  Do not even bother trying to use IAXmodem to
send faxes through your IAX-supporting VoIP provider, it won't work
reliably, if at all.

Please see the FAQ file for more information regarding IAXmodem.


		** INSTALLING IAXMODEM **

There are two ways to build IAXmodem.  One way uses dynamic libraries;
the other way uses static libraries.  If you already have an installation
of an incompatible spandsp or libiax2 on the system, then you should
probably build using static libraries.

To install libiax2:  (if you're not going to 'build static')

# cd lib/libiax2
# ./configure
# make
# make install

To install spandsp:  (if you're not going to 'build static')

# cd lib/spandsp
# ./configure
# make
# make install

If you're building with dynamic libraries, make sure that your linker
can find these libraries by having a line in your /etc/ld.so.conf file
that is "/usr/local/lib" and running 'ldconfig' afterwards.

To build IAXmodem with dynamic linking:

# ./build

To build IAXmodem with static linking:

# ./build static

This will create the iaxmodem binary.  You may run the binary from
its present location, or you may copy it to any location that you may
choose.

Alternatively you can build IAXmodem with static linking by running
the more traditional:

# ./configure
# make

Create the /etc/iaxmodem directory.  The modem configuration files will
be stored in here.  With your favorite editor edit the prototype modem
configuration file, iaxmodem-cfg.ttyIAX.  Alter the configuration lines
as needed and desired.

The "device" entry is the full name of the device that you will be using
in your modem application.  If running multiple instances of iaxmodem then
you will need a different device for each instance.

The "owner" entry (formatted "user:group") is the system user and group
that IAXmodem should use for the created device.

The "mode" entry is the permissions mode for the created device.

The "port" entry refers to the preferred port number on which to listen
for communications from the Asterisk server (so if you're using more than
one IAXmodem on a single IP address you will need to have each IAXmodem
configuration use a different port).  You should not use "4569" if Asterisk
is already listening on port 4569.

The "refresh" entry indicates the preference on how frequently to refresh
the registration with the Asterisk server.  (However, the actual refresh
value that is used will be negotiated between IAXmodem and the Asterisk
server.)  By setting this to a value of "0" (zero), IAXmodem will not
register with the server, and thus the server should be configured to
communicate with IAXmodem on a static address.

The "server", "peername", and "secret" entries refer to the server name
(or address), the registered peer name for the IAXmodem client, and the
registered secret (password) for the IAXmodem client.

The entries "cidname" and "cidnumber" refer to the Caller*ID presentation
that will be made by IAXmodem to the Asterisk server.

The "codec" entry refers to the preferred audio codec. This can be 
"slinear", "ulaw", or "alaw".

The "record" entry causes audio files to be recorded (see below).

The "replay" entry causes the audio files to be replayed back (see below).

Comments can be placed into the IAXmodem configuration files by beginning
them with a semicolon (";").

Now copy this file to the /etc/iaxmodem directory with a unique file name.  
The name of the file will serve as the identifier, if you choose to launch 
iaxmodem in non-daemon mode (see below).


		** RUNNING IAXMODEM **

Now you are ready to start IAXmodem.  IAXmodem can be run in two manners,
daemon mode, or non-daemon.  Initially you should probably run iaxmodem
at least once in non-daemon mode, just to make sure things are working 
(that iaxmodem registers).

                      ----------

In non-daemon mode, IAXmodem is started by supplying the configuration 
identifier as the only command-line parameter, like this:

  /path/to/iaxmodem ttyIAX

In this example the modem configuration file is expected to be:

  /etc/iaxmodem/ttyIAX

You should probably run IAXmodem like this at least once to check
to see that registration occurs properly (then press ^C to exit).

In non-daemon mode IAXmodem does not detach itself from the controlling 
tty, and it does send logging data both to standard output (informational 
items) and to standard error (errors).  As this logging can be a bit 
verbose, you may choose to ignore all of it by starting IAXmodem like 
this:

  /path/to/iaxmodem ttyIAX >/dev/null 2>&1

Alternatively, if you wish to record this into rotated log files:

  /path/to/iaxmodem ttyIAX >/tmp/iaxmodem.stdout 2>/tmp/iaxmodem.stderr

You may also choose to run IAXmodem from init by placing an entry into
the /etc/inittab file like this (and then restarting init):

  IAX:2345:respawn:/path/to/iaxmodem ttyIAX

                      ----------

In daemon mode, IAXmodem is started by not supplying a configuration 
identifier on the command-line, like this:

  /path/to/iaxmodem

This will cause iaxmodem to detach itself from the controlling tty and
launch a separate iaxmodem instance for every modem configuration file
found in /etc/iaxmodem.

In daemon mode IAXmodem sends logging data to files in the 
/var/log/iaxmodem directory, if available.  (The /var/log/iaxmodem 
directory will need to be created.)

You may wish to run iaxmodem in daemon mode and start it with a standard
init.d script.  The provided iaxmodem.init files should serve this
purpose.  (Choose the appropriate one for your distribution.)


		** USING IAX MODEM **

Once IAXmodem is running you are ready to use it with your application.

If your application is HylaFAX, there is a HylaFAX modem configuration
file included with IAXmodem (config.ttyIAX).  The config file is for
HylaFAX version 4.2.2 and later.  Instead of running faxaddmodem,
simply edit this config file to your liking and then copy it to
/var/spool/hylafax/etc/.  (Run faxgetty and the rest of HylaFAX as
usual.)

If using the "record" option, IAXmodem will create two audio files in
the /tmp/ directory.  These files are overwritten by each new audio
call.  The file "ttyIAX-dsp.raw" is the audio that was received by
IAXmodem from the DSP library (which IAXmodem delivered to the IAX
library), and the file "ttyIAX-iax.raw" is the audio that was received
by IAXmodem from the IAX library (which IAXmodem delivered to the DSP 
library).  These audio files can be converted by sox into playable WAV
files in this way:

  sox -s -w -r 8000 -c 1 ttyIAX-iax.raw playable.wav

If using the "replay" option, IAXmodem will replay the audio in the
audio files previously recorded by "record".  So the audio that is 
passed to the DSP comes from "ttyIAX-iax.raw" instead of from the IAX
channel, and the audio that is passed to the IAX channel comes from
"ttyIAX-dsp.raw" instead of from the DSP.  This feature is indended
to provide a simple and reliable way to methodically repeat a call 
session for debugging.  Use of "replay" will disable "record".

Modems typically should be reset and reinitialized after each call 
(in case something within the call put the modem into a bad state).
During initialization it is difficult, if not impossible, to properly
handle incoming calls.  For this reason IAXmodem is "busied-out" for
five seconds after going on-hook (ATH0 or ATZ).  If the initialization
sequence can last longer than that time it would be advisable, then,
to take the modem off-hook (ATH1) at the outset of initialization and
to place it back on-hook (ATH0) when done (in which case the modem
will be busied out during the entire initialization sequence plus
five seconds after it finishes).  For HylaFAX the five-second 
automatic busy-out should be sufficient.


		** CONTRIBUTING **

* Bug Reports - If you use IAXmodem and encounter a problem please do
  report it, even if you can work around the problem and even if you
  do not intend to fix the problem.
* Patches - If you develop a patch (bug fix or enhancement) please do
  share it.  If you would like to develop, but don't know what to do,
  please look at the list of items in the TODO file.
* Commission Work - If you use or would like to use IAXmodem and need
  some work done, hire someone to do it (the author can provide
  suggestions) and share that work.
* Donations - The author is always happy to accept donations of just
  about any kind.


		** CONTACTS and SUPPORT **

Original Author:  Lee Howard <faxguy@howardsilvan.com>
        Website:  http://iaxmodem.sourceforge.net
   Mailing List:  iaxmodem-users@lists.sourceforge.net
