diff options
Diffstat (limited to 'trunk/doc/tex/imapstorage.tex')
-rw-r--r-- | trunk/doc/tex/imapstorage.tex | 196 |
1 files changed, 196 insertions, 0 deletions
diff --git a/trunk/doc/tex/imapstorage.tex b/trunk/doc/tex/imapstorage.tex new file mode 100644 index 000000000..3a952ce54 --- /dev/null +++ b/trunk/doc/tex/imapstorage.tex @@ -0,0 +1,196 @@ +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 both the 2004 and 2006 versions of c-client, however +mail\_expunge\_full is enabled in the 2006 version. + +Note that Asterisk only uses the '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} + +Once this completes you can proceed with the Asterisk build; there is no +need to run 'make install'. + +\subsubsection{Compiling Asterisk} + +To use the system c-client library, configure Asterisk with +./configure --with-imap=system. If you downloaded the c-client source +and compiled it according to the above instructions, configure +Asterisk with with ./configure --with-imap=/usr/src/imap or where ever +you built the UWashington IMAP Toolkit. 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). + +\subsubsection{UW IMAP-2006 Development Branch} + +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. + +\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} |