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
 109 The "expungeonhangup" flag is used to determine if the voicemail system should
 110 expunge all messages marked for deletion when the user hangs up the phone.
 111
 112 Each mailbox definition should also have imapuser=<imap username>.
 113 For example:
 114
 115 4123=>4123,James Rothenberger,jar@onebiztone.com,,attach=yes|imapuser=jar
 116
 117 The directives "authuser" and "authpassword" are not needed when using
 118 Kerberos. They are defined to allow Asterisk to authenticate as a single
 119 user that has access to all mailboxes as an alternative to Kerberos.
 120
 121 --------------
 122 IMAP Folders
 123 --------------
 124 Besides INBOX, users should create "Old", "Work", "Family" and "Friends"
 125 IMAP folders at the same level of hierarchy as the INBOX.  These will be
 126 used as alternate folders for storing voicemail messages to mimic the
 127 behavior of the current (file-based) voicemail system.
 128
 129
 130 ==================================
 131 Separate vs. Shared Email Accounts
 132 ==================================
 133 As administrator you will have to decide if you want to send the voicemail
 134 messages to a separate IMAP account or use each user's existing IMAP mailbox
 135 for voicemail storage.  The IMAP storage mechanism will work either way.
 136
 137 By implementing a single IMAP mailbox, the user will see voicemail messages
 138 appear in the same INBOX as other messages.  The disadvantage of this method
 139 is that if the IMAP server does NOT support UIDPLUS, Asterisk voicemail will
 140 expunge ALL messages marked for deletion when the user exits the voicemail
 141 system, not just the VOICEMAIL messages marked for deletion.
 142
 143 By implementing separate IMAP mailboxes for voicemail and email, voicemail
 144 expunges will not remove regular email flagged for deletion.
 145
 146 ===========================
 147 IMAP Server Implementations
 148 ===========================
 149 There are various IMAP server implementations, each supports a potentially
 150 different set of features.
 151
 152 -----------------------
 153 UW IMAP-2005 or earlier
 154 -----------------------
 155 UIDPLUS is currently NOT supported on these versions of UW-IMAP.  Please note
 156 that without UID_EXPUNGE, Asterisk voicemail will expunge ALL messages marked
 157 for deletion when a user exits the voicemail system (hangs up the phone).
 158
 159 -------------------------------
 160 UW IMAP-2006 Development Branch
 161 -------------------------------
 162 This version supports UIDPLUS, which allows UID_EXPUNGE capabilities.  This
 163 feature allow the system to expunge ONLY pertinent messages, instead of the
 164 default behavior, which is to expunge ALL messages marked for deletion when
 165 EXPUNGE is called.  The IMAP storage mechanism is this version of Asterisk
 166 will check if the UID_EXPUNGE feature is supported by the server, and use it
 167 if possible.
 168
 169 ----------
 170 Cyrus IMAP
 171 ----------
 172 Cyrus IMAP server v2.3.3 has been tested using a hierarchy delimiter of '/'.
 173
 174
 175 =============
 176 Quota Support
 177 =============
 178 If the IMAP server supports quotas, Asterisk will check the quota when
 179 accessing voicemail.  Currently only a warning is given to the user that
 180 their quota is exceeded.
 181
 182
 183 =================
 184 Application Notes
 185 =================
 186 Since the primary storage mechanism is IMAP, all message information that
 187 was previously stored in an associated text file, AND the recording itself,
 188 is now stored in a single email message.  This means that the .gsm recording
 189 will ALWAYS be attached to the message (along with the user's preference of
 190 recording format if different - ie. .WAV).  The voicemail message information
 191 is stored in the email message headers.  These headers include:
 192
 193 X-Asterisk-VM-Message-Num
 194 X-Asterisk-VM-Server-Name
 195 X-Asterisk-VM-Context
 196 X-Asterisk-VM-Extension
 197 X-Asterisk-VM-Priority
 198 X-Asterisk-VM-Caller-channel
 199 X-Asterisk-VM-Caller-ID-Num
 200 X-Asterisk-VM-Caller-ID-Name
 201 X-Asterisk-VM-Duration
 202 X-Asterisk-VM-Category
 203 X-Asterisk-VM-Orig-date
 204 X-Asterisk-VM-Orig-time
 205
 206 =================
 207 Known Issues
 208 =================
 209
 210  - Forward With Comment advanced option is not currently supported.
 211    This feature will be added in the near future.
 212  - Message Waiting Indicator blinks off and back on when a message arrives.
 213    This should be fixed soon.