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