Merged revisions 57364 via svnmerge from
[asterisk/asterisk.git] / doc / imapstorage.txt
1 ======================
2 IMAP Voicemail Storage
3 ======================
4
5 03-01-2006 - James Rothenberger <jar@onebiztone.com>
6
7 By enabling IMAP Storage,  Asterisk will use native IMAP as the storage
8 mechanism for voicemail messages instead of using the standard file structure.
9
10 Tighter integration of Asterisk voicemail and IMAP email services allows
11 additional voicemail functionality, including:
12
13  - Listening to a voicemail on the phone will set its state to "read" in
14    a user's mailbox automatically.
15  - Deleting a voicemail on the phone will delete it from the user's
16    mailbox automatically.
17  - Accessing a voicemail recording email message will turn off the message
18    waiting indicator (MWI) on the user's phone.
19  - Deleting a voicemail recording email will also turn off the message 
20    waiting indicator, and delete the message from the voicemail system.
21
22 =====================
23 Contents of this file
24 =====================
25
26  - Installation Notes
27  - Separate vs. Shared Email Accounts
28  - IMAP Server Implementations
29  - Quota Support
30  - Application Notes
31  - Known Issues
32
33
34 ==================
35 Installation Notes
36 ==================
37
38 --------------------------------------
39 University of Washington IMAP C-Client
40 --------------------------------------
41 You will need a source distribution of University of Washington's IMAP
42 c-client (http://www.washington.edu/imap/).  Asterisk supports both the
43 2004 and 2006 versions of c-client, however mail_expunge_full is enabled
44 in the 2006 version.
45
46 Note that Asterisk only uses the 'client' portion of the UW IMAP toolkit,
47 but building it also builds an IMAP server and various other utilities.
48 Because of this, the build instructions for the IMAP toolkit are somewhat
49 complicated and can lead to confusion about what is needed.
50
51 If you are going to be connecting Asterisk to an existing IMAP server,
52 then you don't need to care about the server or utilities in the IMAP
53 toolkit at all. If you want to also install the UW IMAPD server, that
54 is outside the scope of this document.
55
56 Building the c-client library is fairly straightforward; for example, on a
57 Debian system there are two possibilities:
58
59 1) if you will not be using SSL to connect to the IMAP server:
60    $ make slx SSLTYPE=none
61
62 2) if you will be using SSL to connect to the IMAP server:
63    $ make slx EXTRACFLAGS="-I/usr/include/openssl"
64
65 Once this completes you can proceed with the Asterisk build; there is no
66 need to run 'make install'.
67
68 ------------------
69 Compiling Asterisk 
70 ------------------
71
72 Configure with ./configure --with-imap=/usr/src/imap
73 or where ever you built thfe UWashington IMAP Toolkit. When you run
74 'make menuselect', choose 'Voicemail Build Options' and the
75 IMAP_STORAGE option should be available for selection.
76
77 Note that the --with-imap option will NOT search your system for an
78 installed copy of the IMAP Toolkit c-client library; the Asterisk
79 Makefiles and configure script are designed to build against an
80 unpacked and compiled source tree of the IMAP Toolkit, not a binary
81 distribution.
82
83 After selecting it, use the 'x' key to exit menuselect and save
84 your changes, and the build/install Asterisk normally.
85
86 ---------------------
87 Modify voicemail.conf
88 ---------------------
89 The following directives have been added to voicemail.conf:
90
91 imapserver=<name or IP address of IMAP mail server>
92 imapport=<IMAP port, defaults to 143>
93 imapflags=<IMAP flags, "novalidate-cert" for example>
94 expungeonhangup=<yes or no>
95 authuser=<username>
96 authpassword=<password>
97
98 The "expungeonhangup" flag is used to determine if the voicemail system should
99 expunge all messages marked for deletion when the user hangs up the phone. 
100
101 Each mailbox definition should also have imapuser=<imap username>.
102 For example:
103
104 4123=>4123,James Rothenberger,jar@onebiztone.com,,attach=yes|imapuser=jar
105
106 The directives "authuser" and "authpassword" are not needed when using
107 Kerberos. They are defined to allow Asterisk to authenticate as a single 
108 user that has access to all mailboxes as an alternative to Kerberos.
109
110 --------------
111 IMAP Folders
112 --------------
113 Besides INBOX, users should create "Old", "Work", "Family" and "Friends" 
114 IMAP folders at the same level of hierarchy as the INBOX.  These will be 
115 used as alternate folders for storing voicemail messages to mimic the 
116 behavior of the current (file-based) voicemail system.
117
118
119 ==================================
120 Separate vs. Shared Email Accounts
121 ==================================
122 As administrator you will have to decide if you want to send the voicemail
123 messages to a separate IMAP account or use each user's existing IMAP mailbox
124 for voicemail storage.  The IMAP storage mechanism will work either way. 
125
126 By implementing a single IMAP mailbox, the user will see voicemail messages
127 appear in the same INBOX as other messages.  The disadvantage of this method
128 is that if the IMAP server does NOT support UIDPLUS, Asterisk voicemail will
129 expunge ALL messages marked for deletion when the user exits the voicemail 
130 system, not just the VOICEMAIL messages marked for deletion.
131
132 By implementing separate IMAP mailboxes for voicemail and email, voicemail 
133 expunges will not remove regular email flagged for deletion.
134
135 ===========================
136 IMAP Server Implementations
137 ===========================
138 There are various IMAP server implementations, each supports a potentially
139 different set of features.  
140
141 -----------------------
142 UW IMAP-2005 or earlier
143 -----------------------
144 UIDPLUS is currently NOT supported on these versions of UW-IMAP.  Please note
145 that without UID_EXPUNGE, Asterisk voicemail will expunge ALL messages marked
146 for deletion when a user exits the voicemail system (hangs up the phone).
147
148 -------------------------------
149 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 ----------
159 Cyrus IMAP
160 ----------
161 Cyrus IMAP server v2.3.3 has been tested using a hierarchy delimiter of '/'.  
162
163
164 =============
165 Quota Support
166 =============
167 If the IMAP server supports quotas, Asterisk will check the quota when
168 accessing voicemail.  Currently only a warning is given to the user that 
169 their quota is exceeded. 
170
171
172 =================
173 Application Notes
174 =================
175 Since the primary storage mechanism is IMAP, all message information that 
176 was previously stored in an associated text file, AND the recording itself,
177 is now stored in a single email message.  This means that the .gsm recording
178 will ALWAYS be attached to the message (along with the user's preference of
179 recording format if different - ie. .WAV).  The voicemail message information
180 is stored in the email message headers.  These headers include:
181
182 X-Asterisk-VM-Message-Num
183 X-Asterisk-VM-Server-Name
184 X-Asterisk-VM-Context
185 X-Asterisk-VM-Extension
186 X-Asterisk-VM-Priority
187 X-Asterisk-VM-Caller-channel
188 X-Asterisk-VM-Caller-ID-Num
189 X-Asterisk-VM-Caller-ID-Name
190 X-Asterisk-VM-Duration
191 X-Asterisk-VM-Category
192 X-Asterisk-VM-Orig-date
193 X-Asterisk-VM-Orig-time
194
195 =================
196 Known Issues
197 =================
198
199  - Forward With Comment advanced option is not currently supported.
200    This feature will be added in the near future.
201  - Message Waiting Indicator blinks off and back on when a message arrives.
202    This should be fixed soon.