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