trixbox-IMAP
IMAP hands are the devil's playthings: Getting IMAP working on trixbox and/or your RHEL/CentOS based asterisk/freepbx box.
Method to my madness.
Those of you who know me or know of me have probably heard me mention (I think) that I have the memory of a gnat. I write this sort of documentation not to help you, but because Google is never more than a few steps away from me and the Internet makes a great storage place for things I want to remember that my alcohol and drug addled mind just can't do after 30+ years of abuse. I say this only to explain why I write so informally. Future employers Googling my name: please take note of that. And I'm just kidding about the alcohol and drugs. I never inhaled.
Why the hell would I want to do this?
IMAP is nice if you want to keep your email client in sync with your "phone." From imapstorage.txt in the asterisk doc directory:
- Listening to a voicemail on the phone will set its state to "read" in a user's mailbox automatically. - Deleting a voicemail on the phone will delete it from the user's mailbox automatically. - Accessing a voicemail recording email message will turn off the message waiting indicator (MWI) on the user's phone. - Deleting a voicemail recording email will also turn off the message waiting indicator, and delete the message from the voicemail system.
Also, one of my goals is to have a fully solid state asterisk system for robustness. If I can offload the two things that are most HD intensive, logging and voice mail, then I can use flash storage and eliminate a moving part. Logging can use an external logging server, and by using IMAP I can offload the voice mail store, solving that particular issue, and still be able to have a reasonable amount of space for voice mail.
Ouch, that hurts.
I'd like to start with the gotchas, so nobody wastes any time.
I am using trixbox 2.4 as a test platform. Make mental adjustments as necessary.
First, the IMAP store appears to either be on or off for all users. It doesn't look like you can have some users go to the files and others go to IMAP. (You can, however, use the 'traditional' email to have the message sent to a non-imap email address if you want, or both.)
Second, from imapstorage.txt in the source:
- Forward With Comment advanced option is not currently supported. This feature will be added in the near future. - Message Waiting Indicator blinks off and back on when a message arrives. This should be fixed soon.
Third, even though the docs tell you to create other folders (Old, Family, Work and Friends) it doesn't look like they get used. I haven't investigated this very much, so I don't know if it's just because of how freePBX implements voice mail, or if it just plain doesn't work. You can mark messages as read and unread and it's reflected in both the IMAP client and on the phone, but if you move a message to "Old" on the phone the only thing that happens in the IMAP client is that the message gets marked as read, it doesn't actually get moved to the "Old" folder. If you change the folder on the phone it does manage to keep track of the folder a particular message is in, but it doesn't reflect it in the mail client.
Fourth, I ran into some instability when I first started doing this. Sometimes messages would go to the server, sometimes they wouldn't. It appears to have stabilized lately, but be warned. Test thoroughly.
Fifth, if you have some application that interacts with the voice mail files directly instead of using the manager port then it will stop working. This should be obvious, but I felt I needed to point it out. This includes ARI, by the way. You can log in and change options, but the voice mail does not show up.
Sixth, backing up your server won't back up your voice mail anymore. Another obvious thing that I'm pointing out.
Lastly, and possibly most importantly, compiling asterisk form source will cause RPM updates to "break" your system if you don't exclude asterisk in your yum configuration files. You will be responsible for updating asterisk by hand from that point on. As mentioned, IMAP is either on or off (as of asterisk 1.4.17, which is what I'm using to test with.) This may change in the future, but I've got absolutely no inside information on that. The only way around this at this point is for your maintainers to make the decision to switch to an IMAP store by default, a move that I'm sure would most likely cause a rift, especially in the particularly touchy communities (you know who you are.)
If you can live with these drawbacks, or if you want to know more, read on. If not stop right here. I'll know. I just will, OK?
My mission is to confuse you.
On to how to actually get it running. It's mostly simple, but there are a few things you'll have to watch out for, and since this is a test box I won't be covering specific cases -- you'll have to figure some of this out on your own.
Requirements.
I'm starting from a fresh install of trixbox, you may want to as well, at least until you know what you're doing and get a feel for the drawbacks.
Update and install all your modules for freePBX. Update your system using yum.
You'll need to install gcc, gcc-c++, pam-devel and openssl-devel and dovecot.
yum install gcc gcc-c++ pam-devel openssl-devel dovecot -y
Yum will install those packages plus some other dependencies.
Let's configure dovecot first.
Edit /etc/dovecot.conf and find this section:
#auth_master_user_separator =
Uncomment it and make the separator "*" like so:
auth_master_user_separator = *
(this may not be necessary, but more on this later.)
Next, find the section that starts with:
auth default {
and directly underneath that put:
auth default {
passdb passwd-file {
args = /etc/dovecot/dovecot.masterusers
master = yes
}
Now, let's create that file:
mkdir /etc/dovecot htpasswd -c /etc/dovecot/dovecot.masterusers astmaster input password input password again
Remember that password, you will need it again later.
Now we need to start dovecot, and make sure it runs at boot:
service dovecot start chkconfig --levels 2345 dovecot on
Let's add a system user so that we have a mailbox to send mail to later. I'm going to make an extension later called 5252 and I want the mailbox to be that same name -- you don't have to do this if you don't want, the name can be anything. We're using dovecot and we're using system accounts. This isn't strictly necessary, it's just easiest. You can define users and a mail store in /etc/dovecot.conf, or you can use another IMAP server entirely -- it's up to you, but also outside the scope of this document.
adduser -s /bin/false 5252 # I don't need these users to have interactive access, /bin/false keeps them from logging in. passwd 5252 input password input password again
Remember that one too.
Now you need the sources for UW IMAP and asterisk. As of this writing imap-2007 and asterisk 1.4.17 are current:
Preparation, first, stop asterisk:
amportal stop
BIG FLASHING LETTERS PLEASE TAKE NOTE: This is where you may have to do some custom stuff depending on your system. You'll probably want to build zap for this version of asterisk, and you may have to build g729 modules, or other custom modules if you have them. I won't be covering that. YOU HAVE BEEN WARNED.
Make a backup of the existing modules in case you need to revert:
mv /usr/lib/asterisk/modules /usr/lib/asterisk/modules.backup
Let's go get the source now:
cd /usr/local/src wget ftp://ftp.cac.washington.edu/imap/imap-2007.tar.Z wget http://downloads.digium.com/pub/asterisk/asterisk-1.4-current.tar...
Extract, configure and compile imap first:
tar zxvf imap-2007.tar.Z cd imap-2007
You need to specify some build options because imap can't find the required ssl libraries. The following worked for me:
make slx EXTRACFLAGS="-I/usr/include/openssl -fPIC"
You're done with imap, there's no need to install it -- asterisk will link with it statically.
Now, we're going to build asterisk with imap:
cd .. tar zxvf asterisk-1.4-current.tar.gz cd asterisk-1.4.17 ./configure --with-imap=/usr/local/src/imap-2007 make menuselect
Inside menuselect:
go down to "9. Voicemail Build Options" and press enter
go down to "2. IMAP_STORAGE" and press space to select it
Press escape twice, then press "S" to save your configuration.
make && make install
Now we need to configure asterisk so that it knows how to talk to the imap server. Edit /etc/asterisk/voicemail.conf and add these lines in the general section:
imapserver=localhost imapfolder=Inbox imapflags=notls # see notes below authuser=astmaster authpassword=passindovecotmasterusers pollmailboxes=yes pollfreq=30
Now we're ready to start asterisk and set up a user.
amportal start
Browse to your management page and add a user like normal. In the voicemail section all you need to do is enable it, then in "VM options" add "imapuser=username". Since I used the user 5252 this would be "imapuser=5252".
NOTE: you do not need to specify "email attachment" or an email address. If you do, the system will both put the message in IMAP and send an email -- which is probably not what you want. You can still do the pager email address if you want, though. The options "Play CID" and "Play Envelope" can be set to whatever you want. I didn't experiment with "Delete Vmail" but I'm sure it would do it, making this whole thing an exercise in futility.
You're all set. Point your imap client at your imap server (in this case, it would be the IP address of the trixbox, or the name if you've set up wins or DNS or something.) Send a test voice mail and enjoy IMAP.
Miscellaneous notes (ramblings that have no bearing on you getting this working, probably.)
In regards to the IMAP auth separator: dovecot uses "*" by default, and so does Asterisk. If your IMAP server needs a different separator then you'll have to edit either the asterisk or imap sources -- but I don't know exactly where. What I mean by this is that, in the examples above, when asterisk talks to the imap server it logs in like this:
login 5252*astmaster passindovecotmasterusers
If your IMAP server doesn't support a master user, or the separator isn't *, you can still use IMAP by also specifying the imap password in the voicemail options. You'd do "imapuser=5252|imappassword=passwordyoupicked". It's not exactly the most secure thing, but you already have your master password in plain text anyway -- so, yeah, whatever. :(
You can get around the whole master user thing by setting up kerberos, but, once again, that's outside the scope of this document.
Exchange has an IMAP store, but I don't know what the separator is, should you try to use a master user. I'm sure it can be done, but I avoid Exchange like the plague. If someone wants to donate a few servers and the proper licenses to me I'd take a crack at it though.
To get this to integrate with freePBX smoothly the freePBX devs would need to add a section to put in the extra required voicemail.conf options, and if they do that they might as well make a place to customize the voice mail email files too. They could have a dedicated field in the voice mail section on the extensions page for imapuser and imappassword.
The trixbox guys would have to either switch to an imap store by default, or offer a choice of imap or non-imap asterisk binaries -- which isn't exactly a stellar option.
If the asterisk developers could make it a .conf file option "useimapstore=yes|no" somewhere, then that would be perfect, then trixbox could just enable it when they compile and the end user can decide on the storage method.
When Asterisk can't talk to the IMAP server it says that everyone has one message, but then fails to retrieve. This is a weird failure state and should probably be addressed.
