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. This directory
  74 will be searched for a source installation. If no source installation is
  75 found there, then a package installation of the IMAP c-client will be
  76 searched for in this directory. If one is not found, then configure will fail
  77
  78 A second configure option is to not specify a directory (i.e.
  79 ./configure --with-imap). This will assume that you have the
  80 imap-2004g source installed in the .. directory relative to the
  81 Asterisk source. If you do not have this source, then configure will
  82 default to the "system" option defined in the next paragraph
  83
  84 A third option is ./configure --with-imap=system. This will assume
  85 that you have installed a dynamically linked version of the c-client
  86 library (most likely via a package provided by your distro). This will
  87 attempt to link agains -lc-client and will search for c-client headers
  88 in your include path starting with the imap directory, and upon failure,
  89 in the c-client directory.
  90
  91 When you run 'make menuselect', choose 'Voicemail Build Options' and the
  92 IMAP_STORAGE option should be available for selection.
  93
  94 After selecting it, use the 'x' key to exit menuselect and save
  95 your changes, and the build/install Asterisk normally.
  96
  97 ---------------------
  98 Modify voicemail.conf
  99 ---------------------
 100 The following directives have been added to voicemail.conf:
 101
 102 imapserver=<name or IP address of IMAP mail server>
 103 imapport=<IMAP port, defaults to 143>
 104 imapflags=<IMAP flags, "novalidate-cert" for example>
 105 expungeonhangup=<yes or no>
 106 authuser=<username>
 107 authpassword=<password>
 108 imapopentimeout=<TCP open timeout in seconds>
 109 imapclosetimeout=<TCP close timeout in seconds>
 110 imapreadtimeout=<TCP read timeout in seconds>
 111 imapwritetimeout=<TCP write timeout in seconds>
 112
 113 The "expungeonhangup" flag is used to determine if the voicemail system should
 114 expunge all messages marked for deletion when the user hangs up the phone.
 115
 116 Each mailbox definition should also have imapuser=<imap username>.
 117 For example:
 118
 119 4123=>4123,James Rothenberger,jar@onebiztone.com,,attach=yes|imapuser=jar
 120
 121 The directives "authuser" and "authpassword" are not needed when using
 122 Kerberos. They are defined to allow Asterisk to authenticate as a single
 123 user that has access to all mailboxes as an alternative to Kerberos.
 124
 125 --------------
 126 IMAP Folders
 127 --------------
 128 Besides INBOX, users should create "Old", "Work", "Family" and "Friends"
 129 IMAP folders at the same level of hierarchy as the INBOX.  These will be
 130 used as alternate folders for storing voicemail messages to mimic the
 131 behavior of the current (file-based) voicemail system.
 132
 133
 134 ==================================
 135 Separate vs. Shared Email Accounts
 136 ==================================
 137 As administrator you will have to decide if you want to send the voicemail
 138 messages to a separate IMAP account or use each user's existing IMAP mailbox
 139 for voicemail storage.  The IMAP storage mechanism will work either way.
 140
 141 By implementing a single IMAP mailbox, the user will see voicemail messages
 142 appear in the same INBOX as other messages.  The disadvantage of this method
 143 is that if the IMAP server does NOT support UIDPLUS, Asterisk voicemail will
 144 expunge ALL messages marked for deletion when the user exits the voicemail
 145 system, not just the VOICEMAIL messages marked for deletion.
 146
 147 By implementing separate IMAP mailboxes for voicemail and email, voicemail
 148 expunges will not remove regular email flagged for deletion.
 149
 150 ===========================
 151 IMAP Server Implementations
 152 ===========================
 153 There are various IMAP server implementations, each supports a potentially
 154 different set of features.
 155
 156 -----------------------
 157 UW IMAP-2005 or earlier
 158 -----------------------
 159 UIDPLUS is currently NOT supported on these versions of UW-IMAP.  Please note
 160 that without UID_EXPUNGE, Asterisk voicemail will expunge ALL messages marked
 161 for deletion when a user exits the voicemail system (hangs up the phone).
 162
 163 -------------------------------
 164 UW IMAP-2006 Development Branch
 165 -------------------------------
 166 This version supports UIDPLUS, which allows UID_EXPUNGE capabilities.  This
 167 feature allow the system to expunge ONLY pertinent messages, instead of the
 168 default behavior, which is to expunge ALL messages marked for deletion when
 169 EXPUNGE is called.  The IMAP storage mechanism is this version of Asterisk
 170 will check if the UID_EXPUNGE feature is supported by the server, and use it
 171 if possible.
 172
 173 ----------
 174 Cyrus IMAP
 175 ----------
 176 Cyrus IMAP server v2.3.3 has been tested using a hierarchy delimiter of '/'.
 177
 178
 179 =============
 180 Quota Support
 181 =============
 182 If the IMAP server supports quotas, Asterisk will check the quota when
 183 accessing voicemail.  Currently only a warning is given to the user that
 184 their quota is exceeded.
 185
 186
 187 =================
 188 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 X-Asterisk-VM-Message-Num
 198 X-Asterisk-VM-Server-Name
 199 X-Asterisk-VM-Context
 200 X-Asterisk-VM-Extension
 201 X-Asterisk-VM-Priority
 202 X-Asterisk-VM-Caller-channel
 203 X-Asterisk-VM-Caller-ID-Num
 204 X-Asterisk-VM-Caller-ID-Name
 205 X-Asterisk-VM-Duration
 206 X-Asterisk-VM-Category
 207 X-Asterisk-VM-Orig-date
 208 X-Asterisk-VM-Orig-time
 209
 210 =================
 211 Known Issues
 212 =================
 213
 214  - Forward With Comment advanced option is not currently supported.
 215    This feature will be added in the near future.
 216  - Message Waiting Indicator blinks off and back on when a message arrives.
 217    This should be fixed soon.