doc/tex/imapstorage.tex

   1 By enabling IMAP Storage,  Asterisk will use native IMAP as the storage
   2 mechanism for voicemail messages instead of using the standard file structure.
   3
   4 Tighter integration of Asterisk voicemail and IMAP email services allows
   5 additional voicemail functionality, including:
   6
   7 \begin{itemize}
   8  \item Listening to a voicemail on the phone will set its state to "read" in
   9    a user's mailbox automatically.
  10  \item Deleting a voicemail on the phone will delete it from the user's
  11    mailbox automatically.
  12  \item Accessing a voicemail recording email message will turn off the message
  13    waiting indicator (MWI) on the user's phone.
  14  \item Deleting a voicemail recording email will also turn off the message
  15    waiting indicator, and delete the message from the voicemail system.
  16 \end{itemize}
  17
  18 \subsection{Installation Notes}
  19
  20 \subsubsection{University of Washington IMAP C-Client}
  21
  22 If you do not have the University of Washington's IMAP c-client
  23 installed on your system, you will need to download the c-client
  24 source distribution (\url{http://www.washington.edu/imap/}) and compile it.
  25 Asterisk supports the 2007 version of c-client as there appears to be issues
  26 with older versions which cause Asterisk to crash in certain scenarios. It
  27 is highly recommended that you utilize a current version of the c-client
  28 libraries. Additionally, mail\_expunge\_full is enabled in the 2006 and later
  29 versions.
  30
  31 Note that Asterisk only uses the 'c-client' portion of the UW IMAP toolkit,
  32 but building it also builds an IMAP server and various other utilities.
  33 Because of this, the build instructions for the IMAP toolkit are somewhat
  34 complicated and can lead to confusion about what is needed.
  35
  36 If you are going to be connecting Asterisk to an existing IMAP server,
  37 then you don't need to care about the server or utilities in the IMAP
  38 toolkit at all. If you want to also install the UW IMAPD server, that
  39 is outside the scope of this document.
  40
  41 Building the c-client library is fairly straightforward; for example, on a
  42 Debian system there are two possibilities:
  43
  44 \begin{enumerate}
  45     \item If you will not be using SSL to connect to the IMAP server:
  46    \begin{verbatim}
  47         $ make slx SSLTYPE=none
  48    \end{verbatim}
  49     \item If you will be using SSL to connect to the IMAP server:
  50    \begin{verbatim}
  51    $ make slx EXTRACFLAGS="-I/usr/include/openssl"
  52    \end{verbatim}
  53 \end{enumerate}
  54
  55 Once this completes you can proceed with the Asterisk build; there is no
  56 need to run 'make install'.
  57
  58 \subsubsection{Compiling Asterisk}
  59
  60 Configure with ./configure --with-imap=/usr/src/imap
  61 or wherever you built the UWashington IMAP Toolkit. This directory
  62 will be searched for a source installation. If no source installation is
  63 found there, then a package installation of the IMAP c-client will be
  64 searched for in this directory. If one is not found, then configure will fail.
  65
  66 A second configure option is to not specify a directory (i.e.
  67 ./configure --with-imap). This will assume that you have the
  68 imap-2007e source installed in the ../imap directory relative to the
  69 Asterisk source. If you do not have this source, then configure will
  70 default to the "system" option defined in the next paragraph
  71
  72 A third option is ./configure --with-imap=system. This will assume
  73 that you have installed a dynamically linked version of the c-client
  74 library (most likely via a package provided by your distro). This will
  75 attempt to link agains -lc-client and will search for c-client headers
  76 in your include path starting with the imap directory, and upon failure,
  77 in the c-client directory.
  78
  79 When you run 'make menuselect', choose 'Voicemail Build Options' and the
  80 IMAP\_STORAGE option should be available for selection.
  81
  82 After selecting the IMAP\_STORAGE option, use the 'x' key to exit
  83 menuselect and save your changes, and the build/install Asterisk
  84 normally.
  85
  86 \subsection{Modify voicemail.conf}
  87
  88 The following directives have been added to voicemail.conf:
  89 \begin{astlisting}
  90 \begin{verbatim}
  91 imapserver=<name or IP address of IMAP mail server>
  92 imapport=<IMAP port, defaults to 143>
  93 imapflags=<IMAP flags, "novalidate-cert" for example>
  94 imapfolder=<IMAP folder to store messages to>
  95 imapgreetings=<yes or no>
  96 greetingsfolder=<IMAP folder to store greetings in if imapgreetings is enabled>
  97 expungeonhangup=<yes or no>
  98 authuser=<username>
  99 authpassword=<password>
 100 opentimeout=<TCP open timeout in seconds>
 101 closetimeout=<TCP close timeout in seconds>
 102 readtimeout=<TCP read timeout in seconds>
 103 writetimeout=<TCP write timeout in seconds>
 104 \end{verbatim}
 105 \end{astlisting}
 106
 107 The "imapfolder" can be used to specify an alternative folder on your IMAP server
 108 to store voicemails in. If not specified, the default folder 'INBOX' will be used.
 109
 110 The "imapgreetings" parameter can be enabled in order to store voicemail greetings
 111 on the IMAP server. If disabled, then they will be stored on the local file system
 112 as normal.
 113
 114 The "greetingsfolder" can be set to store greetings on the IMAP server when
 115 "imapgreetings" is enabled in an alternative folder than that set by "imapfolder"
 116 or the default folder for voicemails.
 117
 118 The "expungeonhangup" flag is used to determine if the voicemail system should
 119 expunge all messages marked for deletion when the user hangs up the phone.
 120
 121 Each mailbox definition should also have imapuser=$<$imap username$>$.
 122 For example:
 123 \begin{astlisting}
 124 \begin{verbatim}
 125 4123=>4123,James Rothenberger,jar@onebiztone.com,,attach=yes|imapuser=jar
 126 \end{verbatim}
 127 \end{astlisting}
 128
 129 The directives "authuser" and "authpassword" are not needed when using
 130 Kerberos. They are defined to allow Asterisk to authenticate as a single
 131 user that has access to all mailboxes as an alternative to Kerberos.
 132
 133
 134 \subsection{IMAP Folders}
 135
 136 Besides INBOX, users should create "Old", "Work", "Family" and "Friends"
 137 IMAP folders at the same level of hierarchy as the INBOX.  These will be
 138 used as alternate folders for storing voicemail messages to mimic the
 139 behavior of the current (file-based) voicemail system.
 140
 141
 142 \subsection{Separate vs. Shared Email Accounts}
 143
 144 As administrator you will have to decide if you want to send the voicemail
 145 messages to a separate IMAP account or use each user's existing IMAP mailbox
 146 for voicemail storage.  The IMAP storage mechanism will work either way.
 147
 148 By implementing a single IMAP mailbox, the user will see voicemail messages
 149 appear in the same INBOX as other messages.  The disadvantage of this method
 150 is that if the IMAP server does NOT support UIDPLUS, Asterisk voicemail will
 151 expunge ALL messages marked for deletion when the user exits the voicemail
 152 system, not just the VOICEMAIL messages marked for deletion.
 153
 154 By implementing separate IMAP mailboxes for voicemail and email, voicemail
 155 expunges will not remove regular email flagged for deletion.
 156
 157
 158 \subsection{IMAP Server Implementations}
 159
 160 There are various IMAP server implementations, each supports a potentially
 161 different set of features.
 162
 163
 164 \subsubsection{UW IMAP-2005 or earlier}
 165
 166 UIDPLUS is currently NOT supported on these versions of UW-IMAP.  Please note
 167 that without UID\_EXPUNGE, Asterisk voicemail will expunge ALL messages marked
 168 for deletion when a user exits the voicemail system (hangs up the phone).
 169
 170 This version is *not* recommended for Asterisk.
 171
 172 \subsubsection{UW IMAP-2006}
 173
 174 This version supports UIDPLUS, which allows UID\_EXPUNGE capabilities.  This
 175 feature allow the system to expunge ONLY pertinent messages, instead of the
 176 default behavior, which is to expunge ALL messages marked for deletion when
 177 EXPUNGE is called.  The IMAP storage mechanism is this version of Asterisk
 178 will check if the UID\_EXPUNGE feature is supported by the server, and use it
 179 if possible.
 180
 181 This version is *not* recommended for Asterisk.
 182
 183 \subsubsection{UW IMAP-2007}
 184
 185 This is the currently recommended version for use with Asterisk.
 186
 187 \subsubsection{Cyrus IMAP}
 188
 189 Cyrus IMAP server v2.3.3 has been tested using a hierarchy delimiter of '/'.
 190
 191
 192 \subsection{Quota Support}
 193
 194 If the IMAP server supports quotas, Asterisk will check the quota when
 195 accessing voicemail.  Currently only a warning is given to the user that
 196 their quota is exceeded.
 197
 198
 199 \subsection{Application Notes}
 200
 201 Since the primary storage mechanism is IMAP, all message information that
 202 was previously stored in an associated text file, AND the recording itself,
 203 is now stored in a single email message.  This means that the .gsm recording
 204 will ALWAYS be attached to the message (along with the user's preference of
 205 recording format if different - ie. .WAV).  The voicemail message information
 206 is stored in the email message headers.  These headers include:
 207
 208 \begin{verbatim}
 209 X-Asterisk-VM-Message-Num
 210 X-Asterisk-VM-Server-Name
 211 X-Asterisk-VM-Context
 212 X-Asterisk-VM-Extension
 213 X-Asterisk-VM-Priority
 214 X-Asterisk-VM-Caller-channel
 215 X-Asterisk-VM-Caller-ID-Num
 216 X-Asterisk-VM-Caller-ID-Name
 217 X-Asterisk-VM-Duration
 218 X-Asterisk-VM-Category
 219 X-Asterisk-VM-Orig-date
 220 X-Asterisk-VM-Orig-time
 221 \end{verbatim}