Skip to content
Snippets Groups Projects
imapstorage.tex 9.5 KiB
Newer Older
  • Learn to ignore specific revisions
  • 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.
    
    \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"
    
    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{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>
    
    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$>$.
    
    \begin{verbatim}
    
    4123=>4123,James Rothenberger,jar@onebiztone.com,,attach=yes|imapuser=jar
    
    
    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.
    
    
    Leif Madsen's avatar
    Leif Madsen committed
    Please note that it is not recommended to store your voicemails in the top
    level folder where your users will keep their emails, especially if there
    are a large number of emails. A large number of emails in the same folder(s)
    that you're storing your voicemails could cause a large delay as Asterisk must
    parse through all the emails. For example a mailbox with 100 emails in it could
    take up to 60 seconds to receive a response.
    
    \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
    
    
    \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
    
    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