Installation notes for the mailbox-plugin and c-client-library
==============================================================
(last edited: $Date: 2004/01/24 15:11:39 $)

This file contains some information about installing of the
mailbox-plugin for vdr and the c-client-library.

Unfortunately there are significant differences on how the various
Linux-distributors build their packages and as I am not able to test
all these combinations at home, I depend on your valuable feedback
to update this file and the Makefile to make the installation of
the plugin more straightforward.

To make it as easy as possible to build/run the plugin on various
distributions I would like to add as many as possible distribution
dependent hints to this file. If you find any errors in this document
or can provide additional information I kindly ask you to drop me
a short personal mail with the following information:

- Linux distribution and version number on the VDR PC
- c-client package name and version (or compiled from source)
- used settings for IMAPINCDIR and IMAPLFLAGS
- parameters used in MailBox-string to connect to the imap-server
- name and version of the imap-server

Most of the following distribution dependent notes contain
information I received as mail from several users of the plugin.
Thank you all for that!

Contents:
=========

1.  General notes

2.  Distribution notes
2.1   Debian
2.2   Gentoo
2.3   SuSE
2.4   RedHat
2.5   compile the c-client-library from the original sources

3.  Installation of the plugin

4.  Troubleshooting
4.1   Compilation
4.1.1   "linkage.c" not found
4.2   Execution
4.2.1   unresolved externals when starting vdr with the plugin
4.2.2   getting more diagnostic output in case of errors
4.3   Testing mailbox access from command line...
4.3.1   ...with mbtest
4.3.2   ...with mtest

5. Test/Development-systems

6. Misc / FAQ

1. General notes
================

The mailbox-plugin relies on c-client-library for mailbox access.

To install the necessary header- and library-files you could use (in 
most cases) the packages of your distribution. If this is not possible
you will have to compile c-client yourself.

Note: The plugin needs only the c-client-library and headers, there's
no need to install the UW IMAP server on your PC. As an example I use
the c-client-library to connect to a Courier IMAP server.

The Makefile of the mailbox-plugin expects two variables pointing to
the place where the c-client-files are located and the linker flags
needed for the c-client library.

These two variables are:

  IMAPINCDIR
  IMAPLFLAGS

You could set these variables in the Makefile of the plugin or in the
Make.config in VDRs root directory.

Setting them in VDRs Make.config prevents you from having to modify
the Makefile of the plugin every time you install a new version of the
plugin.

2. Distribution notes
=====================
2.1 Debian
----------

The packages I used with Debian stable are:

  'libc-client2001' and 'libc-client2001-dev'

In this case the two variables should have the following values:

  IMAPINCDIR = /usr/include/c-client
  IMAPLFLAGS = -lc-client

Alternative: It's possible to install the packages

  'libc-client-ssl2001' and 'libc-client-ssl2001-dev'
  
In this case the two variables should have the following values:

  IMAPINCDIR = /usr/include/c-client
  IMAPLFLAGS = -lc-client -lssl

Some users reported to use the following packages with Debian
testing:

  'libc-client2002ddebian' and 'libc-client-dev'

2.2 Gentoo 1.4
--------------

As far as I can tell from the valuable feedback and help
of some users, there's now a working version of the c-client
library is in the ebuild 'net-libs/c-client' in the unstable
portage tree.

An easy way to install the plugin is to use the ebuild
provided on <http://vdr.gentoo.de/wiki>.

2.3 SuSE
--------
SuSE 8.2/9.0
------------

The simplest way to install the necessary files is to use the RPMs
from SuSE. These are called

  'imap-lib-<version>' and 'imap-devel-<version>'.

In this case the two variables should have the following values:

  IMAPINCDIR = /usr/include/imap
  IMAPLFLAGS = -lc-client -lssl -lpam

SuSE 8.1 and before
-------------------

The file "linkage.c" from the c-client-library is missing in the
imap-RPMs and therefore can't be used (see 4.1.1).

So you will have to compile the c-client-library from the
sources (see 2.5).

(One user reported to have successfully installed the src rpm
from SuSE 8.2 on a 8.0 installation, rebuilt the RPM's and
then installed the packages 'imap-lib-2002-36' and
'imap-devel-2002-36').

2.4 RedHat
----------
RedHat 7.3
----------

Install package imap-devel (eg from ftp.redhat.com) and set
the variables to the following values:

IMAPINCDIR = /usr/include/imap
IMAPLFLAGS = -lc-client -lssl -lpam -L/usr/kerberos/lib -lgssapi_krb5


2.5 compile the c-client-library from the original sources
---------------------------------------------------------

- Get the sources from http://www.washington.edu/imap/
  by clicking on the link "IMAP server source distribution"
  -> you'll get a file imap.tar.Z

- Change to a location where you want to install the sources,
  e.g. 'cd /usr/local/src'

- Unpack the sources

  $ tar xzf imap.tar.Z

  you'll get a directory called "imap-2002e"

- I prefer making a symbolic link with the name "imap"

  $ ln -s imap-2002e imap

- Change to the source directory

  $ cd imap

- Read the readme and execute step 1) and 2), there's no need to
  execute the following steps, if you only want to use c-client-library.

  In step 2) you will call make with your desired configuration,

  For SuSE 8.x e.g. you call 'make lsu'. This requires the packages
  'pam-devel' and 'openssl-devel' on your system.
  (Tested with SuSE 8.1 and 8.2, not tested with Debian)

- After you run 'make <your config>', you should have a static
  library 'c-client.a' in the subdirectory 'c-client'

If you installed the c-client-library from source, set the following
variables in $VDRDIR/Make.config or in the Makefile of the plugin to
the following values:

  IMAPDIR    = /usr/local/src/imap/c-client
  IMAPINCDIR = $(IMAPDIR)
  IMAPLFLAGS = $(IMAPDIR)/c-client.a -lssl -lpam

Don't forget to adjust the value in IMAPDIR to point to the directory
where you installed the imap sources.

3. Installation of the plugin
=============================

If you set the variables mentioned in the last sections in vdr's
Make.config the plugin can be installed like any other plugin.

In short:

$ cd $VDRDIR/PLUGINS/src
$ tar xzf vdr-mailbox-<version>.tgz
$ ln -s mailbox-<version> mailbox

and then either

$ cd mailbox
$ make

or

$ cd $VDRDIR
$ make plugins

Additionally you should install a small patch for vdr, which corrects
a display/refreshing problem when jumping to a mail before the first
visible mail in 'mail list view'.

To apply the patch change to vdr's source directory, apply the patch
and recompile vdr:

$ cd $VDRDIR
$ patch -p1 < PLUGINS/src/mailbox/patches/vdr-1.2.6-osdmenufix.diff
$ make

4.  Troubleshooting
===================
4.1   Compilation
-----------------
4.1.1   "linkage.c" not found
-----------------------------
The compiler complains about a missing file "linkage.c" while compiling
AxMail/src/AxMailBoxMgr.cpp although the c-client/imap-devel packages
are installed.

The file "linkage.c" is generated during the build-process of the
c-client library and therefore depends on the configuration during
the build-process.

If the binary package of your distribution doesn't contain "linkage.c"
you will have to install c-client from sources.

See section 2.5.

4.2 Execution
-------------
4.2.1 unresolved externals when starting vdr with the plugin
------------------------------------------------------------
If you get an unresolved external error when starting vdr with the
plugin you will have to add some libraries to the IMAPLDFLAGS
variable.

vdr[..]: loading plugin: /usr/../VDR/PLUGINS/lib/libvdr-mailbox.so.1.2.6
vdr[..]: ERROR: /usr/../VDR/PLUGINS/lib/libvdr-mailbox.so.1.2.6: undefined
symbol: <symbolname>

If <symbolname> is
- 'crypt' -> add '-lcrypt' to IMAPLDFLAGS

4.2.2   getting more diagnostic output in case of errors
--------------------------------------------------------
If the plugin is unable to connect to the mailbox or other errors
occur it's possible to increase the diagnostic output written
to /var/log/messages

With every of the following steps more information is written to
the syslog:

- start vdr with the option "-l 3"
- enable c-client-callback-logging in the "general settings" of the
  setup-menu of the plugin
- enable logging at protocol level by adding '/debug' to your
  mailbox-string, e.g. '{hostname/notls/norsh/debug}'.


4.3 Testing mailbox access from command line...
-----------------------------------------------
4.3.1 ...with mbtest
--------------------

There is a small command line test application 'mbtest' within the source
package of the plugin which can be used to test the access to the desired
mail-account.

To use this utility:
- enter the source directory of the plugin, e.g.
  $ cd $VDRDIR/PLUGINS/src/mailbox/

- compile mbtest:
  $ make mbtest
  -> you should get a small executable called 'mbtest'

If you start ./mbtest from command line you are asked for the user name,
password and the MailBox-string which is exactly the string you will
have to enter in the osd-settings of an account.

If the information you entered are correct mbtest displays all mails
within the account.

An execution of mbtest may look like the following:

  $./mbtest
  creating AxMailBoxSetup...
  User name: xxxxx
  Password : yyyyy
  MailBox  : {mailhost/imap/notls/norsh}
  creating AxMailBox...
  opening AxMailBox...
  requesting status from AxMailBox...
  0 recent  0 unseen  3 mails in TestAccount
  =====================================================================
  ... a dump of all mails in the account...

Please replace the strings xxxxx with your login-name, yyyyy with your
password and the line after 'MailBox:' with your settings.

If you get an error message like "Unable to open mailbox:
'{mailhost1/imap/notls/norsh}'", please check /var/log/messages for
further information

Some possible errors may look like:

[...] mbtest: mm_log: W: 'Login failed.'
[...] mbtest: mm_log: W: 'Login failed.'
[...] mbtest: mm_log: W: 'Login failed.'
[...] mbtest: mm_log: E: 'Too many login failures'
[...] mbtest:   MailBox::open() 'TestAccount' unable to open!

or

[...] mbtest: mm_log: E: 'Connection failed to v.w.x.y,143: No route to host'
[...] mbtest:   MailBox::open() 'TestAccount' unable to open!


As long as you aren't able to connect to the mail account using
mbtest you won't be able to use the plugin either.

If you are definitely sure that the information you entered in the
account-settings in the plugin and/or the mbtest-app is correct, there
is still the possibility to go one step deeper. mbtest and the mailbox-
plugin use a small and incomplete collection of C++-Wrapper classes
(located in the directory AxMail).

4.3.2 ...with mtest
-------------------

The author of the c-client-library implemented a small test application
called 'mtest' (note: there's no 'b' in the name).

If you installed the c-client/imap-library from the binary packages of
your distributions, please check if the mtest application is on your pc.

With the mtest application you are able to test directly if the
c-client library is able to connect to your mailbox.

When started from command line, the mtest application asks if you want
to debug at protocol level, the MailBox string, the login name and
the password.

A successful execution of mtest could look like the following:

  $ mtest
  MTest -- C client test program
  Debug protocol (y/n)? y
  
  Mailbox ('?' for help): {mailhost/imap/notls/norsh}
  [Trying IP address [v.w.x.y]]
  * OK [CAPABILITY IMAP4rev1 UIDPLUS CHILDREN NAMESPACE THREAD=ORDEREDSUBJECT 
    THREAD=REFERENCES SORT QUOTA IDLE STARTTLS] ...
  {mailhost/imap} username: xxxxx
  Password: yyyyy
  <suppressed>
  00000000 OK LOGIN Ok.
  00000001 CAPABILITY
  * CAPABILITY IMAP4rev1 UIDPLUS CHILDREN NAMESPACE THREAD=ORDEREDSUBJECT...
  00000001 OK CAPABILITY completed
  00000002 SELECT INBOX
  * FLAGS (\Draft \Answered \Flagged \Deleted \Seen \Recent)
  * OK [PERMANENTFLAGS (\* \Draft \Answered \Flagged \Deleted \Seen)] Limited
  * 3 EXISTS
  * 0 RECENT
  * OK [UIDVALIDITY 1060674450] Ok
  00000002 OK [READ-WRITE] Ok
  Mon, 8 Dec 2003 xx:xx:xx +0100 (CET)
  imap mailbox: {mailhost:143/imap/notls/user="xxxxx"}INBOX, 3 messages, 0 recent
  MTest>q
  
If you can't connect to the mailbox with 'mtest' then you will have no 
success with 'mbtest' and the plugin either.

5. Test/Development-systems
===========================

The plugin was developed with the following combinations of vdr-1.3.2,
with and without QuickAIO, output modules DVB/DXR3/xine/xinelibout,
c-client from source and from binary packages:

- vdr-1.3.2 + QuickAIO-1.3.1 + AC3overDVB with DVB-output
  - with SuSE 8.1 and c-client from source   (1)

- vdr-1.3.2 + QuickAIO-1.3.1 with streamdev-client and
  xine-0.0.3-output
  - with SuSE 8.2 and c-client from RPMs     (2)
  - with SuSE 8.2 and c-client from source   (2)

- vdr-1.3.2 + QuickAIO-1.3.1 with streamdev-client and DXR3-output
  - with SuSE 8.2 and c-client from RPMs     (3)
  - with SuSE 8.1 and c-client from source   (4a)
  - with Debian 3.0 and c-client from debs   (4b)

IMAP-server is Courier 2.2.0 running on (1), POP3-access tested
with ipop3 from courier (on (1)) and qpopper (on (2)).

(1) PIII, 600MHz, 256MB, 1x Nexus-S, 1x Nova-S, SuSE 8.1
    IMAP-server Courier 2.2.0
(2) P4, 2GHz, 512MB, SuSE 8.2, development system
(3) VIA EPIA ME-6000, 256MB, DXR3, diskless/PXE, SuSE 8.2
(4) K6-2, 300MHz, 128MB, DXR3
(4a) SuSE 8.1, diskless/EtherBoot
(4b) Debian 3.0

6. Misc / FAQ
-------------
Q: I get a message like "Can't get status of mailbox..."

- please check that your settings for the mail account are correct.
- please check that you have braces '{' and '}' around the
  Mailbox-string
- please check that spelling of all parameters (like '/imap/notls/norsh')
  is correct.
- increase diagnostic output as described in 4.2.2 to get further hints.
- use the mbtest-utility described in one of the following sections
  to check if you can access to your mail account at all.

Q: I configured/modified the settings of an account, but when I enter
   the plugin from vdr's main menu, these settings vanished.

- The settings are stored when you exit the settings-menu of the
  *plugin* with OK. So if you are in the dialog where you edit the
  settings of an account you will have to press OK for *two* times.
  -> first OK returns to the settings menu of the plugin (with
     the list of all accounts)
  -> second OK leaves the settings menu of the plugin and saves the
     settings to disk.

