Update the IMAP build documentation to show how to build on 64-bit platforms. (issue #16433) Reported by: shrift Tested by: lmadsen git-svn-id: https://origsvn.digium.com/svn/asterisk/trunk@234631 65c4cc65-6c06-0410-ace0-fbb531ad65f3
236 lines
9.1 KiB
TeX
236 lines
9.1 KiB
TeX
By enabling IMAP Storage, Asterisk will use native IMAP as the storage
|
|
mechanism for voicemail messages instead of using the standard file structure.
|
|
|
|
Tighter integration of Asterisk voicemail and IMAP email services allows
|
|
additional voicemail functionality, including:
|
|
|
|
\begin{itemize}
|
|
\item Listening to a voicemail on the phone will set its state to "read" in
|
|
a user's mailbox automatically.
|
|
\item Deleting a voicemail on the phone will delete it from the user's
|
|
mailbox automatically.
|
|
\item Accessing a voicemail recording email message will turn off the message
|
|
waiting indicator (MWI) on the user's phone.
|
|
\item Deleting a voicemail recording email will also turn off the message
|
|
waiting indicator, and delete the message from the voicemail system.
|
|
\end{itemize}
|
|
|
|
\subsection{Installation Notes}
|
|
|
|
\subsubsection{University of Washington IMAP C-Client}
|
|
|
|
If you do not have the University of Washington's IMAP c-client
|
|
installed on your system, you will need to download the c-client
|
|
source distribution (\url{http://www.washington.edu/imap/}) and compile it.
|
|
Asterisk supports the 2007 version of c-client as there appears to be issues
|
|
with older versions which cause Asterisk to crash in certain scenarios. It
|
|
is highly recommended that you utilize a current version of the c-client
|
|
libraries. Additionally, mail\_expunge\_full is enabled in the 2006 and later
|
|
versions.
|
|
|
|
Note that Asterisk only uses the 'c-client' portion of the UW IMAP toolkit,
|
|
but building it also builds an IMAP server and various other utilities.
|
|
Because of this, the build instructions for the IMAP toolkit are somewhat
|
|
complicated and can lead to confusion about what is needed.
|
|
|
|
If you are going to be connecting Asterisk to an existing IMAP server,
|
|
then you don't need to care about the server or utilities in the IMAP
|
|
toolkit at all. If you want to also install the UW IMAPD server, that
|
|
is outside the scope of this document.
|
|
|
|
Building the c-client library is fairly straightforward; for example, on a
|
|
Debian system there are two possibilities:
|
|
|
|
\begin{enumerate}
|
|
\item If you will not be using SSL to connect to the IMAP server:
|
|
\begin{verbatim}
|
|
$ make slx SSLTYPE=none
|
|
\end{verbatim}
|
|
\item If you will be using SSL to connect to the IMAP server:
|
|
\begin{verbatim}
|
|
$ make slx EXTRACFLAGS="-I/usr/include/openssl"
|
|
\end{verbatim}
|
|
\end{enumerate}
|
|
|
|
Additionally, you may wish to build on a 64-bit machine, in which case you
|
|
need to add -fPIC to EXTRACFLAGS. So, building on a 64-bit machine with
|
|
SSL support would look something like:
|
|
|
|
\begin{verbatim}
|
|
$ make slx EXTRACFLAGS="-fPIC -I/usr/include/openssl"
|
|
\end{verbatim}
|
|
|
|
Or without SSL support:
|
|
|
|
\begin{verbatim}
|
|
$ make slx SSLTYPE=none EXTRACFLAGS=-fPIC
|
|
\end{verbatim}
|
|
|
|
Once this completes you can proceed with the Asterisk build; there is no
|
|
need to run 'make install'.
|
|
|
|
\subsubsection{Compiling Asterisk}
|
|
|
|
Configure with ./configure --with-imap=/usr/src/imap
|
|
or wherever you built the UWashington IMAP Toolkit. This directory
|
|
will be searched for a source installation. If no source installation is
|
|
found there, then a package installation of the IMAP c-client will be
|
|
searched for in this directory. If one is not found, then configure will fail.
|
|
|
|
A second configure option is to not specify a directory (i.e.
|
|
./configure --with-imap). This will assume that you have the
|
|
imap-2007e source installed in the ../imap directory relative to the
|
|
Asterisk source. If you do not have this source, then configure will
|
|
default to the "system" option defined in the next paragraph
|
|
|
|
A third option is ./configure --with-imap=system. This will assume
|
|
that you have installed a dynamically linked version of the c-client
|
|
library (most likely via a package provided by your distro). This will
|
|
attempt to link agains -lc-client and will search for c-client headers
|
|
in your include path starting with the imap directory, and upon failure,
|
|
in the c-client directory.
|
|
|
|
When you run 'make menuselect', choose 'Voicemail Build Options' and the
|
|
IMAP\_STORAGE option should be available for selection.
|
|
|
|
After selecting the IMAP\_STORAGE option, use the 'x' key to exit
|
|
menuselect and save your changes, and the build/install Asterisk
|
|
normally.
|
|
|
|
\subsection{Modify voicemail.conf}
|
|
|
|
The following directives have been added to voicemail.conf:
|
|
\begin{astlisting}
|
|
\begin{verbatim}
|
|
imapserver=<name or IP address of IMAP mail server>
|
|
imapport=<IMAP port, defaults to 143>
|
|
imapflags=<IMAP flags, "novalidate-cert" for example>
|
|
imapfolder=<IMAP folder to store messages to>
|
|
imapgreetings=<yes or no>
|
|
greetingsfolder=<IMAP folder to store greetings in if imapgreetings is enabled>
|
|
expungeonhangup=<yes or no>
|
|
authuser=<username>
|
|
authpassword=<password>
|
|
opentimeout=<TCP open timeout in seconds>
|
|
closetimeout=<TCP close timeout in seconds>
|
|
readtimeout=<TCP read timeout in seconds>
|
|
writetimeout=<TCP write timeout in seconds>
|
|
\end{verbatim}
|
|
\end{astlisting}
|
|
|
|
The "imapfolder" can be used to specify an alternative folder on your IMAP server
|
|
to store voicemails in. If not specified, the default folder 'INBOX' will be used.
|
|
|
|
The "imapgreetings" parameter can be enabled in order to store voicemail greetings
|
|
on the IMAP server. If disabled, then they will be stored on the local file system
|
|
as normal.
|
|
|
|
The "greetingsfolder" can be set to store greetings on the IMAP server when
|
|
"imapgreetings" is enabled in an alternative folder than that set by "imapfolder"
|
|
or the default folder for voicemails.
|
|
|
|
The "expungeonhangup" flag is used to determine if the voicemail system should
|
|
expunge all messages marked for deletion when the user hangs up the phone.
|
|
|
|
Each mailbox definition should also have imapuser=$<$imap username$>$.
|
|
For example:
|
|
\begin{astlisting}
|
|
\begin{verbatim}
|
|
4123=>4123,James Rothenberger,jar@onebiztone.com,,attach=yes|imapuser=jar
|
|
\end{verbatim}
|
|
\end{astlisting}
|
|
|
|
The directives "authuser" and "authpassword" are not needed when using
|
|
Kerberos. They are defined to allow Asterisk to authenticate as a single
|
|
user that has access to all mailboxes as an alternative to Kerberos.
|
|
|
|
|
|
\subsection{IMAP Folders}
|
|
|
|
Besides INBOX, users should create "Old", "Work", "Family" and "Friends"
|
|
IMAP folders at the same level of hierarchy as the INBOX. These will be
|
|
used as alternate folders for storing voicemail messages to mimic the
|
|
behavior of the current (file-based) voicemail system.
|
|
|
|
|
|
\subsection{Separate vs. Shared Email Accounts}
|
|
|
|
As administrator you will have to decide if you want to send the voicemail
|
|
messages to a separate IMAP account or use each user's existing IMAP mailbox
|
|
for voicemail storage. The IMAP storage mechanism will work either way.
|
|
|
|
By implementing a single IMAP mailbox, the user will see voicemail messages
|
|
appear in the same INBOX as other messages. The disadvantage of this method
|
|
is that if the IMAP server does NOT support UIDPLUS, Asterisk voicemail will
|
|
expunge ALL messages marked for deletion when the user exits the voicemail
|
|
system, not just the VOICEMAIL messages marked for deletion.
|
|
|
|
By implementing separate IMAP mailboxes for voicemail and email, voicemail
|
|
expunges will not remove regular email flagged for deletion.
|
|
|
|
|
|
\subsection{IMAP Server Implementations}
|
|
|
|
There are various IMAP server implementations, each supports a potentially
|
|
different set of features.
|
|
|
|
|
|
\subsubsection{UW IMAP-2005 or earlier}
|
|
|
|
UIDPLUS is currently NOT supported on these versions of UW-IMAP. Please note
|
|
that without UID\_EXPUNGE, Asterisk voicemail will expunge ALL messages marked
|
|
for deletion when a user exits the voicemail system (hangs up the phone).
|
|
|
|
This version is *not* recommended for Asterisk.
|
|
|
|
\subsubsection{UW IMAP-2006}
|
|
|
|
This version supports UIDPLUS, which allows UID\_EXPUNGE capabilities. This
|
|
feature allow the system to expunge ONLY pertinent messages, instead of the
|
|
default behavior, which is to expunge ALL messages marked for deletion when
|
|
EXPUNGE is called. The IMAP storage mechanism is this version of Asterisk
|
|
will check if the UID\_EXPUNGE feature is supported by the server, and use it
|
|
if possible.
|
|
|
|
This version is *not* recommended for Asterisk.
|
|
|
|
\subsubsection{UW IMAP-2007}
|
|
|
|
This is the currently recommended version for use with Asterisk.
|
|
|
|
\subsubsection{Cyrus IMAP}
|
|
|
|
Cyrus IMAP server v2.3.3 has been tested using a hierarchy delimiter of '/'.
|
|
|
|
|
|
\subsection{Quota Support}
|
|
|
|
If the IMAP server supports quotas, Asterisk will check the quota when
|
|
accessing voicemail. Currently only a warning is given to the user that
|
|
their quota is exceeded.
|
|
|
|
|
|
\subsection{Application Notes}
|
|
|
|
Since the primary storage mechanism is IMAP, all message information that
|
|
was previously stored in an associated text file, AND the recording itself,
|
|
is now stored in a single email message. This means that the .gsm recording
|
|
will ALWAYS be attached to the message (along with the user's preference of
|
|
recording format if different - ie. .WAV). The voicemail message information
|
|
is stored in the email message headers. These headers include:
|
|
|
|
\begin{verbatim}
|
|
X-Asterisk-VM-Message-Num
|
|
X-Asterisk-VM-Server-Name
|
|
X-Asterisk-VM-Context
|
|
X-Asterisk-VM-Extension
|
|
X-Asterisk-VM-Priority
|
|
X-Asterisk-VM-Caller-channel
|
|
X-Asterisk-VM-Caller-ID-Num
|
|
X-Asterisk-VM-Caller-ID-Name
|
|
X-Asterisk-VM-Duration
|
|
X-Asterisk-VM-Category
|
|
X-Asterisk-VM-Orig-date
|
|
X-Asterisk-VM-Orig-time
|
|
\end{verbatim}
|