diff options
Diffstat (limited to 'doc/tex/imapstorage.tex')
-rw-r--r-- | doc/tex/imapstorage.tex | 241 |
1 files changed, 0 insertions, 241 deletions
diff --git a/doc/tex/imapstorage.tex b/doc/tex/imapstorage.tex deleted file mode 100644 index 3d6c80559..000000000 --- a/doc/tex/imapstorage.tex +++ /dev/null @@ -1,241 +0,0 @@ -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. - -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 -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} |