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 both the 2004 and 2006 versions of c-client, however
  26 mail\_expunge\_full is enabled in the 2006 version.
  27
  28 Note that Asterisk only uses the 'client' portion of the UW IMAP toolkit,
  29 but building it also builds an IMAP server and various other utilities.
  30 Because of this, the build instructions for the IMAP toolkit are somewhat
  31 complicated and can lead to confusion about what is needed.
  32
  33 If you are going to be connecting Asterisk to an existing IMAP server,
  34 then you don't need to care about the server or utilities in the IMAP
  35 toolkit at all. If you want to also install the UW IMAPD server, that
  36 is outside the scope of this document.
  37
  38 Building the c-client library is fairly straightforward; for example, on a
  39 Debian system there are two possibilities:
  40
  41 \begin{enumerate}
  42     \item If you will not be using SSL to connect to the IMAP server:
  43    \begin{verbatim}
  44         $ make slx SSLTYPE=none!
  45    \end{verbatim}
  46     \item If you will be using SSL to connect to the IMAP server:
  47    \begin{verbatim}
  48    $ make slx EXTRACFLAGS="-I/usr/include/openssl"
  49    \end{verbatim}
  50 \end{enumerate}
  51
  52 Once this completes you can proceed with the Asterisk build; there is no
  53 need to run 'make install'.
  54
  55 \subsubsection{Compiling Asterisk}
  56
  57 To use the system c-client library, configure Asterisk with
  58 ./configure --with-imap=system. If you downloaded the c-client source
  59 and compiled it according to the above instructions, configure
  60 Asterisk with with ./configure --with-imap=/usr/src/imap or where ever
  61 you built the UWashington IMAP Toolkit. When you run 'make
  62 menuselect', choose 'Voicemail Build Options' and the IMAP\_STORAGE
  63 option should be available for selection.
  64
  65 After selecting the IMAP\_STORAGE option, use the 'x' key to exit
  66 menuselect and save your changes, and the build/install Asterisk
  67 normally.
  68
  69 \subsection{Modify voicemail.conf}
  70
  71 The following directives have been added to voicemail.conf:
  72 \begin{astlisting}
  73 \begin{verbatim}
  74 imapserver=<name or IP address of IMAP mail server>
  75 imapport=<IMAP port, defaults to 143>
  76 imapflags=<IMAP flags, "novalidate-cert" for example>
  77 imapfolder=<IMAP folder to store messages to>
  78 imapgreetings=<yes or no>
  79 greetingsfolder=<IMAP folder to store greetings in if imapgreetings is enabled>
  80 expungeonhangup=<yes or no>
  81 authuser=<username>
  82 authpassword=<password>
  83 \end{verbatim}
  84 \end{astlisting}
  85
  86 The "imapfolder" can be used to specify an alternative folder on your IMAP server
  87 to store voicemails in. If not specified, the default folder 'INBOX' will be used.
  88
  89 The "imapgreetings" parameter can be enabled in order to store voicemail greetings
  90 on the IMAP server. If disabled, then they will be stored on the local file system
  91 as normal.
  92
  93 The "greetingsfolder" can be set to store greetings on the IMAP server when
  94 "imapgreetings" is enabled in an alternative folder than that set by "imapfolder"
  95 or the default folder for voicemails.
  96
  97 The "expungeonhangup" flag is used to determine if the voicemail system should
  98 expunge all messages marked for deletion when the user hangs up the phone.
  99
 100 Each mailbox definition should also have imapuser=$<$imap username$>$.
 101 For example:
 102 \begin{astlisting}
 103 \begin{verbatim}
 104 4123=>4123,James Rothenberger,jar@onebiztone.com,,attach=yes|imapuser=jar
 105 \end{verbatim}
 106 \end{astlisting}
 107
 108 The directives "authuser" and "authpassword" are not needed when using
 109 Kerberos. They are defined to allow Asterisk to authenticate as a single
 110 user that has access to all mailboxes as an alternative to Kerberos.
 111
 112
 113 \subsection{IMAP Folders}
 114
 115 Besides INBOX, users should create "Old", "Work", "Family" and "Friends"
 116 IMAP folders at the same level of hierarchy as the INBOX.  These will be
 117 used as alternate folders for storing voicemail messages to mimic the
 118 behavior of the current (file-based) voicemail system.
 119
 120
 121 \subsection{Separate vs. Shared Email Accounts}
 122
 123 As administrator you will have to decide if you want to send the voicemail
 124 messages to a separate IMAP account or use each user's existing IMAP mailbox
 125 for voicemail storage.  The IMAP storage mechanism will work either way.
 126
 127 By implementing a single IMAP mailbox, the user will see voicemail messages
 128 appear in the same INBOX as other messages.  The disadvantage of this method
 129 is that if the IMAP server does NOT support UIDPLUS, Asterisk voicemail will
 130 expunge ALL messages marked for deletion when the user exits the voicemail
 131 system, not just the VOICEMAIL messages marked for deletion.
 132
 133 By implementing separate IMAP mailboxes for voicemail and email, voicemail
 134 expunges will not remove regular email flagged for deletion.
 135
 136
 137 \subsection{IMAP Server Implementations}
 138
 139 There are various IMAP server implementations, each supports a potentially
 140 different set of features.
 141
 142
 143 \subsubsection{UW IMAP-2005 or earlier}
 144
 145 UIDPLUS is currently NOT supported on these versions of UW-IMAP.  Please note
 146 that without UID\_EXPUNGE, Asterisk voicemail will expunge ALL messages marked
 147 for deletion when a user exits the voicemail system (hangs up the phone).
 148
 149 \subsubsection{UW IMAP-2006 Development Branch}
 150
 151 This version supports UIDPLUS, which allows UID\_EXPUNGE capabilities.  This
 152 feature allow the system to expunge ONLY pertinent messages, instead of the
 153 default behavior, which is to expunge ALL messages marked for deletion when
 154 EXPUNGE is called.  The IMAP storage mechanism is this version of Asterisk
 155 will check if the UID\_EXPUNGE feature is supported by the server, and use it
 156 if possible.
 157
 158 \subsubsection{Cyrus IMAP}
 159
 160 Cyrus IMAP server v2.3.3 has been tested using a hierarchy delimiter of '/'.
 161
 162
 163 \subsection{Quota Support}
 164
 165 If the IMAP server supports quotas, Asterisk will check the quota when
 166 accessing voicemail.  Currently only a warning is given to the user that
 167 their quota is exceeded.
 168
 169
 170 \subsection{Application Notes}
 171
 172 Since the primary storage mechanism is IMAP, all message information that
 173 was previously stored in an associated text file, AND the recording itself,
 174 is now stored in a single email message.  This means that the .gsm recording
 175 will ALWAYS be attached to the message (along with the user's preference of
 176 recording format if different - ie. .WAV).  The voicemail message information
 177 is stored in the email message headers.  These headers include:
 178
 179 \begin{verbatim}
 180 X-Asterisk-VM-Message-Num
 181 X-Asterisk-VM-Server-Name
 182 X-Asterisk-VM-Context
 183 X-Asterisk-VM-Extension
 184 X-Asterisk-VM-Priority
 185 X-Asterisk-VM-Caller-channel
 186 X-Asterisk-VM-Caller-ID-Num
 187 X-Asterisk-VM-Caller-ID-Name
 188 X-Asterisk-VM-Duration
 189 X-Asterisk-VM-Category
 190 X-Asterisk-VM-Orig-date
 191 X-Asterisk-VM-Orig-time
 192 \end{verbatim}