The IMAP Subsystem

Document created by resplin Employee on Jun 6, 2015
Version 1Show Document
  • View in full screen mode

Obsolete Pages{{Obsolete}}

The official documentation is at: http://docs.alfresco.com



3.2ConfigurationSubsystemsIMAPEmail


Introduction


The IMAP Subsystem provides the IMAP service that allows access to the Alfresco server via the IMAP protocol. The protocol allows email applications that support IMAP (including Outlook, Apple Mail, Thunderbird, etc.) to connect to and interact with Alfresco repositories directly from the mail application.


Configuration


Enabling the IMAP Protocol


The IMAP protocol server is disabled by default. To enable the protocol, set the following configuration properties in alfresco-global.properties:

imap.server.enabled=true
imap.server.port=143
imap.server.host=localhost

Important: You should not use localhost as the imap.server.host - update this value with the IP address (or corresponding DNS address) of your external IP interface. A value of 0.0.0.0 in Unix will make it listen on the specified port on all IP interfaces.

Note: You will need to restart your Alfresco server for the new configuration to take effect.

Since the IMAP server only has one instance you should make configuration changes to <extension root>alfresco-global.properties although since this is the imap subsystem you can also make your changes to <extension root>\alfresco\extension\subsystems\imap\default\default in which case the subsystem configuration will take precedence.

The following settings change the configuration of the IMAP service.


imap.server.enabled: Enables or disables the IMAP subsystem.
imap.server.port=143: IMAP has a reserved port number of 143 although you can change it here
imap.server.host=<your host name>

Important: You should not use localhost as the imap.server.host - update this value with the IP address (or corresponding DNS address) of your external IP interface. A value of 0.0.0.0 in Unix will make it listen on the specified port on all IP interfaces.


  • Version 3.3.1 and later: configure these properties of the sysAdmin subsystem
    alfresco.protocol: The protocol component of the alfresco web application URL, e.g. http
    alfresco.host: The externally resolvable host name of the alfresco web application URL. Use ${localname} for the locally-configured host name.
    alfresco.port: The externally resolvable port number of the alfresco web application URL. E.g. 8080
    alfresco.context: The context path component of the alfresco web application URL. Typically alfresco

  • Earlier Versions
    web.application.context.url:your web application context. Typically: http://alfrescoserver.foo:8080/alfresco

Configuration of the IMAP Home space which will be used to store user's maiboxes in ARCHIVE mode, in particular the user's INBOX.


imap.config.home.store=${spaces.store}
imap.config.home.rootPath=/${spaces.company_home.childname}
imap.config.home.folderPath=Imap Home

The imap.config.home.rootPath property may also be configured using an XPath query syntax

imap.config.home.rootPath=/app:company_home

To add your own folder to this path, add the name of your folder path using the data model names. For example: /app:company_home/cm:Houses. If your folder has a space in the name, include this character where the space should be: '_x0020_' e.g. /app:company_home/cm:Home_x0020_Town. Stop and start the IMAP subsystem for the changes to take effect.


Enabling IMAPS


IMAPS is a secure IMAP encrypted via SSL.  By default IMAPS is assigned to port number 993.

Once the Imap subsystem is enabled, There are two pieces of extra configuration for IMAPS.

The first is to configure the default java keystore, this may already have been done for other parts of alfresco.


javax.net.ssl.keyStore=mySrvKeystore:
javax.net.ssl.keyStorePassword=123456:

The second is to enable IMAPS


imap.server.imaps.enabled=true :
imap.server.imaps.port=993 :

Attachment extraction


An IMAP message may contain a message and a set of attachments.   The IMAP server can split the attachments into separate content nodes.


imap.server.attachments.extraction.enabled: Enables or disables attachment extraction

Mount Points


The files and folders available to the IMAP interfaces are 'mounted' from the repository.  Using mount points allows you to control which bits of an alfresco repository are exposed.    By default a single mount point is defined called 'AlfrescoIMAP' and you can change this or add more mount points.

The IMAP integration offers the following three different access Modes.


  • ARCHIVE - Allows emails to be written to and read from Alfresco by the IMAP client by dragging/dropping, copy/pasting etc from the email client.
  • VIRTUAL - Documents managed by Alfresco may be viewed as 'emails' from the IMAP client. Documents are shown as virtual emails with the ability to view metadata and trigger actions on the document using links included in the email body.
  • MIXED - A combination of both archive & virtual modes i.e. both document access and email management are available.

imap.config.server.mountPoints is a composite property which you add to list the names of your imap mount points.

Then for each mount point you need to specify the following settings. 

   * beanName
   * store
   * rootPath
   * mode

We use the format

<property>.default.<component property>

Example 1, the default provided out f the box.



imap.config.server.mountPoints=AlfrescoIMAP
imap.config.server.mountPoints.default.mountPointName=IMAP
imap.config.server.mountPoints.default.modeName=ARCHIVE
imap.config.server.mountPoints.default.store=${spaces.store}
imap.config.server.mountPoints.default.rootPath=/${spaces.company_home.childname}
imap.config.server.mountPoints.value.AlfrescoIMAP.mountPointName=Alfresco IMAP
imap.config.server.mountPoints.value.AlfrescoIMAP.modeName=MIXED

In the above example a single mount point with the name AlfrescoIMAP is defined, In MIXED  mode, showing files below Company Home.



to specify default values for each component property. For example:

imap.config.server.mountPoints.default.store=${spaces.store}
imap.config.server.mountPoints.default.rootPath=/${spaces.company_home.childname}
imap.config.server.mountPoints.default.mode=virtual

First, we set the master composite property using a comma-separated list of the individual mount point names.

imap.config.server.mountPoints=Repository_virtual,Repository_archive

Note that in a JMX dump, the presentation will be slightly different:



** Object Name Alfresco:Type=Configuration,Category=imap,id1=default,id2=imap.config.server.mountPoints,id3=Sites
** Object Type imap$default$imap.config.server.mountPoints$Sites
folderNames    [Sites]
folderPath     /Sites
mode           MIXED
modeName       MIXED
mountPointName Alfresco Sites
rootPath       /app:company_home
store          workspace://SpacesStore
storeRef       workspace://SpacesStore

TODO - More complex example.


IMAP Limitations


You have to be careful when deciding what mount points you provide.
Indeed, an IMAP client when mounting a mount point issue a


LSUB '' *

command, which retrieves the *whole* tree of folders below the mount point.
For instance, if the tree contains 1000 folders the server could take 15 seconds (depending on the hardware) to start pushing the folder list to the client.
For 2000 folders it could take twice that time. The time increase can be considered linear at first approximation.





Back to Server Configuration

Attachments

    Outcomes