608a39fbb62828b143ec2643558e1306c2ebfb35
[asterisk/asterisk.git] / 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 'c-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 Configure with ./configure --with-imap=/usr/src/imap
58 or where ever you built thfe UWashington IMAP Toolkit. This directory
59 will be searched for a source installation. If no source installation is
60 found there, then a package installation of the IMAP c-client will be 
61 searched for in this directory. If one is not found, then configure will fail.
62
63 A second configure option is to not specify a directory (i.e.
64 ./configure --with-imap). This will assume that you have the
65 imap-2004g source installed in the .. directory relative to the
66 Asterisk source. If you do not have this source, then configure will
67 default to the "system" option defined in the next paragraph
68
69 A third option is ./configure --with-imap=system. This will assume
70 that you have installed a dynamically linked version of the c-client
71 library (most likely via a package provided by your distro). This will
72 attempt to link agains -lc-client and will search for c-client headers
73 in your include path starting with the imap directory, and upon failure,
74 in the c-client directory.
75
76 When you run 'make menuselect', choose 'Voicemail Build Options' and the
77 IMAP\_STORAGE option should be available for selection.
78
79 After selecting the IMAP\_STORAGE option, use the 'x' key to exit
80 menuselect and save your changes, and the build/install Asterisk
81 normally.
82
83 \subsection{Modify voicemail.conf}
84
85 The following directives have been added to voicemail.conf:
86 \begin{astlisting}
87 \begin{verbatim}
88 imapserver=<name or IP address of IMAP mail server>
89 imapport=<IMAP port, defaults to 143>
90 imapflags=<IMAP flags, "novalidate-cert" for example>
91 imapfolder=<IMAP folder to store messages to>
92 imapgreetings=<yes or no>
93 greetingsfolder=<IMAP folder to store greetings in if imapgreetings is enabled>
94 expungeonhangup=<yes or no>
95 authuser=<username>
96 authpassword=<password>
97 opentimeout=<TCP open timeout in seconds>
98 closetimeout=<TCP close timeout in seconds>
99 readtimeout=<TCP read timeout in seconds>
100 writetimeout=<TCP write timeout in seconds>
101 \end{verbatim}
102 \end{astlisting}
103
104 The "imapfolder" can be used to specify an alternative folder on your IMAP server
105 to store voicemails in. If not specified, the default folder 'INBOX' will be used.
106
107 The "imapgreetings" parameter can be enabled in order to store voicemail greetings
108 on the IMAP server. If disabled, then they will be stored on the local file system
109 as normal.
110
111 The "greetingsfolder" can be set to store greetings on the IMAP server when
112 "imapgreetings" is enabled in an alternative folder than that set by "imapfolder"
113 or the default folder for voicemails.
114
115 The "expungeonhangup" flag is used to determine if the voicemail system should
116 expunge all messages marked for deletion when the user hangs up the phone.
117
118 Each mailbox definition should also have imapuser=$<$imap username$>$.
119 For example:
120 \begin{astlisting}
121 \begin{verbatim}
122 4123=>4123,James Rothenberger,jar@onebiztone.com,,attach=yes|imapuser=jar
123 \end{verbatim}
124 \end{astlisting}
125
126 The directives "authuser" and "authpassword" are not needed when using
127 Kerberos. They are defined to allow Asterisk to authenticate as a single
128 user that has access to all mailboxes as an alternative to Kerberos.
129
130
131 \subsection{IMAP Folders}
132
133 Besides INBOX, users should create "Old", "Work", "Family" and "Friends"
134 IMAP folders at the same level of hierarchy as the INBOX.  These will be
135 used as alternate folders for storing voicemail messages to mimic the
136 behavior of the current (file-based) voicemail system.
137
138
139 \subsection{Separate vs. Shared Email Accounts}
140
141 As administrator you will have to decide if you want to send the voicemail
142 messages to a separate IMAP account or use each user's existing IMAP mailbox
143 for voicemail storage.  The IMAP storage mechanism will work either way.
144
145 By implementing a single IMAP mailbox, the user will see voicemail messages
146 appear in the same INBOX as other messages.  The disadvantage of this method
147 is that if the IMAP server does NOT support UIDPLUS, Asterisk voicemail will
148 expunge ALL messages marked for deletion when the user exits the voicemail
149 system, not just the VOICEMAIL messages marked for deletion.
150
151 By implementing separate IMAP mailboxes for voicemail and email, voicemail
152 expunges will not remove regular email flagged for deletion.
153
154
155 \subsection{IMAP Server Implementations}
156
157 There are various IMAP server implementations, each supports a potentially
158 different set of features.
159
160
161 \subsubsection{UW IMAP-2005 or earlier}
162
163 UIDPLUS is currently NOT supported on these versions of UW-IMAP.  Please note
164 that without UID\_EXPUNGE, Asterisk voicemail will expunge ALL messages marked
165 for deletion when a user exits the voicemail system (hangs up the phone).
166
167 \subsubsection{UW IMAP-2006 Development Branch}
168
169 This version supports UIDPLUS, which allows UID\_EXPUNGE capabilities.  This
170 feature allow the system to expunge ONLY pertinent messages, instead of the
171 default behavior, which is to expunge ALL messages marked for deletion when
172 EXPUNGE is called.  The IMAP storage mechanism is this version of Asterisk
173 will check if the UID\_EXPUNGE feature is supported by the server, and use it
174 if possible.
175
176 \subsubsection{Cyrus IMAP}
177
178 Cyrus IMAP server v2.3.3 has been tested using a hierarchy delimiter of '/'.
179
180
181 \subsection{Quota Support}
182
183 If the IMAP server supports quotas, Asterisk will check the quota when
184 accessing voicemail.  Currently only a warning is given to the user that
185 their quota is exceeded.
186
187
188 \subsection{Application Notes}
189
190 Since the primary storage mechanism is IMAP, all message information that
191 was previously stored in an associated text file, AND the recording itself,
192 is now stored in a single email message.  This means that the .gsm recording
193 will ALWAYS be attached to the message (along with the user's preference of
194 recording format if different - ie. .WAV).  The voicemail message information
195 is stored in the email message headers.  These headers include:
196
197 \begin{verbatim}
198 X-Asterisk-VM-Message-Num
199 X-Asterisk-VM-Server-Name
200 X-Asterisk-VM-Context
201 X-Asterisk-VM-Extension
202 X-Asterisk-VM-Priority
203 X-Asterisk-VM-Caller-channel
204 X-Asterisk-VM-Caller-ID-Num
205 X-Asterisk-VM-Caller-ID-Name
206 X-Asterisk-VM-Duration
207 X-Asterisk-VM-Category
208 X-Asterisk-VM-Orig-date
209 X-Asterisk-VM-Orig-time
210 \end{verbatim}