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.