Open-Xchange - User contributions [en]

Dovecot Mailpush

2018-08-03T15:19:52Z

Norbert.weinhold: /* IMAP METADATA */

= Setup of the Dovecot Push =

== Prerequisites ==

Dovecot customers can use the special PUSH plugin without any additional costs. The plugin will be provided via the Dovecot software repository for Dovecot Pro and community edition. '''Please Note, the installation of the latest Dovecot v2.2.19 release is required'''

== IMAP METADATA ==

Dovecot Push plug-in requires METADATA support on Dovecot side, but it should only be enabled for OX IMAP sessions and not for any other IMAP clients directly. Enabling can be done with e.g. the remote directive "remote 1.2.3.0/24 { imap_metadata = yes }" and specifying the IP ranges of OX.

Dovecot supports the [[https://tools.ietf.org/html/rfc5464|IMAP METADATA extension (RFC 5464)]], which allows per-mailbox, per-user data to be stored and accessed via IMAP commands.

To activate metadata storage, a [[Dictionary|dictionary]] needs to be configured in the Dovecot configuration using the mail_attribute_dict option.

To activate the IMAP METADATA commands, the imap_metadata and mail_attribute_dict options need to be activated.

Example:

# Store METADATA information within user's Maildir directory
mail_attribute_dict = file:%h/Maildir/dovecot-attributes

remote 1.2.3.0/24 {
protocol imap {
imap_metadata = yes
}
}

The following picture should demonstrate how the overall communication flow between Mail App, Open-Xchange Middleware, and the Dovecot Push plug-in takes place. That communication flow requires the "open-xchange-push-dovecot" and "open-xchange-rest" packages to be installed on the Open-Xchange Middleware nodes and the Dovecot "http-notify" plug-in.

[[Image:ox_mail_push_configuration_4.png|500px]]

Once the Open-Xchange Mail App is installed on the user’s mobile device and it is allowed to show notifications about a new message delivery, the Mail App performs a subscription call to the Open-Xchange Middleware Servers using a fully authenticated session.

When the "open-xchange-push-dovecot" package is installed, the previous subscribe call requests it to spawn a permanent listener. Such a listener simply tells the Dovecot server to notify about new message delivery events for the associated user by executing a special SETMETADATA command. Hence, it does not open or use any resources other than firing a single IMAP command to the Dovecot IMAP Server.

Whenever a "new message delivery" event occurs, the Dovecot Server performs a HTTP callback against a configurable HTTP end-point of the Open-Xchange Middleware providing crucial information about the newly delivered message with a simple JSON body. That incoming HTTP callback is then turned into an appropriate OSGi event with topic "com/openexchange/push".

That event is in turn handled by the Mobile Push event handler, which uses the event’s information to request an APN/GCM push to the mobile device.

== Configuration of Dovecot "http-notify" plug-in ==

To use push notifications, both the "notify" and the "push_notification" plugins need to be activated. For LMTP delivery, this is required:

protocol lmtp {
mail_plugins = $mail_plugins notify push_notification
}

If you also want push notifications to work for LDA-based delivery, you would need additional configuration:

protocol lda {
mail_plugins = $mail_plugins notify push_notification
}

The HTTP end-point (URL + authentication information) to use is configured in the Dovecot configuration file. The appropriate configuration options will contain the HTTP URL denoting the end-point to connect to as well as the authentication information for Basic Authentication as configured by properties "com.openexchange.rest.services.basic-auth.login" and "com.openexchange.rest.services.basic-auth.password".
The URL to configure in Dovecot configuration follows this pattern.
<http|https> + "://" + <login> + ":" + <password> + "@" + <host> + ":" + <port> + "/preliminary/http-notify/v1/notify"

Please note that SSL endpoints are only supported from Dovecot >= 2.3.

E.g.
plugin {
push_notification_driver = ox:url=http://login:pass@node1.domain.tld:8009/preliminary/http-notify/v1/notify
}

Furthermore, it is also possible to specify more than one HTTP end-point to connect to if a new message delivery occurs. Thus the configuration section mentioned above may be extended by additional "push_notification_driver" entries; e.g. push_notification_driver2, push_notification_driver3, etc.

Please note that the path "/preliminary/http-notify/v1/notify" denotes the internal REST API of the Open-Xchange Middleware, which must not be publicly accessible. The administrator can decide whether to add that path to the Apache configuration (see also [[AppSuite:Apache_Configuration]] and [[AppSuite:Grizzly]]) through a Location/ProxyPass directive:

<Location /preliminary>
Order Deny,Allow
Deny from all
# Only allow access from servers within the network. Do not expose this
# location outside of your network. In case you use a load balancing service in front
# of your Apache infrastructure you should make sure that access to /preliminary will
# be blocked from the internet / outside clients. Examples:
# Allow from 192.168.0.1
# Allow from 192.168.1.1 192.168.1.2
# Allow from 192.168.0.
ProxyPass /preliminary balancer://oxcluster/preliminary
</Location>

In a scenario where Dovecot Push is also supposed to be used for websockets based browser notifications the OX property '''com.openexchange.push.allowedClients''' needs to be extended with "open-xchange-appsuite".

In case the "user=" sent by OX in the push_notification_driver url data does not match the IMAP login of a user, Dovecot ignores it. This can be overridden by defining "user_from_metadata" in the push_notification_driver url, e.g.

push_notification_driver = ox:url=http://example.com/ user_from_metadata

Caldav carddav Bundles

2015-08-11T15:18:23Z

Norbert.weinhold:

= Installation and Configuration of the CalDAV- and CardDAV-bundles =

The Open-Xchange server can be accessed via it's CalDAV- and CardDAV-interfaces to allow the synchronization of Calendar- and Contact-data with external applications like the Mac OS X iCal and Address Book clients. The synchronization protocols are available starting with Version 6.20.1 Rev5.

CalDAV and CardDAV are standard protocols for the exchange of calendar data and address data respectively. The CalDAV interface publishes all the user's calendar folders via CalDAV so the user can subscribe to them in a client application. Similarly, the CardDAV interface publishes the user's contact folders. Depending on the used client, the user can either subscribe one or more folders, or access all available data in an aggregated way.

== User Guide and Client Configuration ==
Please find further information regarding the client configuration at [[CalDAVClients]] and [[CardDAVClients]].

== Webserver Configuration ==
In order to redirect DAV requests to the appropiate servlets, the webserver's configuration may need to be adjusted using one of the following alternatives. Please be aware that for a working Mavericks auto configuration setup you need to have SSL enabled on the server. The non-SSL variant described below only works if you use the advanced CalDav configuration in Mavericks and enter the path by hand. If you just want to enter the hostname SSL is required. The same applies to iOS7 where SSL is always required.

=== Alternative 1: Apache vhost (recommended) ===
Please edit your site configuration file for OX so that ''' the existing OX configuration as well as the CalDAV/CardDav configuration are placed inside their own virtual hosts sections.'''.

Please add the following entries before you existing VirtualHost entry. This is an <b>example</b> where MYSERVER.TLD is the domain-name of the ox-server:

NameVirtualHost *:80
<VirtualHost *:80>
ServerName dav.<MYSERVER.TLD>
ErrorLog /tmp/dav.err.log
TransferLog /tmp/dav.access.log

<Proxy balancer://oxserver-sync>
Order deny,allow
Allow from all

# for grizzly http service
BalancerMember http://localhost:8009 timeout=100 smax=0 ttl=60 retry=60 loadfactor=50 route=OX1
# uncomment this entry if you have a clustered setup and want to use the other nodes too
#BalancerMember http://<ip-of-other-host>:8009 timeout=100 smax=0 ttl=60 retry=60 loadfactor=50 route=OX2
SetEnv proxy-initial-not-pooled
SetEnv proxy-sendchunked
</Proxy>

<Proxy />
Order allow,deny
Allow from all
ProxyPass balancer://oxserver-sync/servlet/dav/
</Proxy>
</VirtualHost>

If you use this method, you have to make sure that dav.<MYSERVER.TLD> is reachable, your dns configuration need an entry for this name. Take care of the the dav.* logfiles, the example writes them without logrotation to /tmp.

Please note the <code>NameVirtualHost</code> directive is needed to be able to specify multiple virtual hosts for the same IP. The differentiation is only done by the given <code>ServerName</code>. This implies that you need two server names, so the virtual host entry for the existing ox site configuration needs to be also enriched by a <code>ServerName</code> if not already present. If you access the system without one of the given <code>ServerName</code>s so e.g. via the IP the system will pick the corresponding one by order (in this case the DAV part first. If you want it to work differently please change the order accordingly.

=== Alternative 2: Apache useragent detection ===
For environments where it is inconvenient to setup a vhost there is the possibility to redirect to relevant servlets another way: Via useragent detection. This is not recommended for the following reason: Per definition this is a whitelist-approach and any client sending a useragent-string not explicitly listed in the configuration will not be able to connect . Useragent-strings may also change between different versions of an application or may even be actively changed into something non-standard.

$ vi <your-ox-site-configuration-file>

RewriteEngine On
RewriteCond %{HTTP_USER_AGENT} Calendar [OR]
RewriteCond %{HTTP_USER_AGENT} DataAccess [OR]
RewriteCond %{HTTP_USER_AGENT} DAVKit [OR]
RewriteCond %{HTTP_USER_AGENT} Lightning [OR]
RewriteCond %{HTTP_USER_AGENT} Adresboek [OR]
RewriteCond %{HTTP_USER_AGENT} dataaccessd [OR]
RewriteCond %{HTTP_USER_AGENT} Preferences [OR]
RewriteCond %{HTTP_USER_AGENT} Adressbuch [OR]
RewriteCond %{HTTP_USER_AGENT} AddressBook [OR]
RewriteCond %{HTTP_USER_AGENT} Address%20Book [OR]
RewriteCond %{HTTP_USER_AGENT} CalendarStore [OR]
RewriteCond %{HTTP_USER_AGENT} accountsd [OR]
RewriteCond %{HTTP_USER_AGENT} CoreDAV
RewriteRule (.*) http://localhost:8009/servlet/dav$1 [P] # for grizzly http service

'''Note:''' The address book app on OSX 10.6 uses a localized user-agent string. If you're expecting clients with non-english language settings, you need to add the translated user-agent string to these rewrite rules. For example: "Adressbuch" for german OSX clients.

== Autodiscovery ==

By providing some DNS service name registrations for your domain and adding an additional rewrite-rule to the webserver's configuration, it's possible for some clients to automatically discover the account settings by just providing the user's e-mail address and password. The procedure is specified in [http://tools.ietf.org/html/rfc6764 RFC 6764].

The following example illustrates the DNS entries where MYSERVER.TLD would be the domain name of the ox-server, both for CalDAV and CardDAV via HTTP and HTTPS on the virtual host dav.MYSERVER.TLD:

_caldavs._tcp.MYSERVER.TLD. 10800 IN SRV 10 1 443 dav.MYSERVER.TLD.
_caldav._tcp.MYSERVER.TLD. 10800 IN SRV 10 1 80 dav.MYSERVER.TLD.
_carddavs._tcp.MYSERVER.TLD. 10800 IN SRV 10 1 443 dav.MYSERVER.TLD.
_carddav._tcp.MYSERVER.TLD. 10800 IN SRV 10 1 80 dav.MYSERVER.TLD.

Additionally, a rewrite-rule similar to the following example should be added to the webserver configuration of the virtual host to enable the bootstrapping process:

RewriteEngine On
RewriteCond %{REQUEST_URI} ^/\.well-known/caldav [OR]
RewriteCond %{REQUEST_URI} ^/\.well-known/carddav
RewriteRule (.*) / [L,R]

== Which packages do I need? ==
To get CalDAV and CardDAV up and running you need the following packages:

In v6.20 and earlier:
* open-xchange-webdav-directory - Assembles the *DAV interfaces into a common tree. This is needed for publishing certain properties so clients accept the OX is a WebDAV Server.
* open-xchange-webdav-acl - The WebDAV equivalent of the /ajax/user interface. Allows clients to discover the current and other users and their addressbooks and calendars.
* open-xchange-carddav - The CardDAV interface exposing the users addressbook via carddav
* open-xchange-caldav - The CalDAV inteface exposing the users calendars via caldav

With v6.22 we have significantly reduced the number of packages necessary to install Open-Xchange Server.
In v6.22 and later only one package is needed:
* open-xchange-dav

== Installation on OX App Suite ==
If there are any differences from for the Open-Xchange App Suite product family from version 6.22 they will be listed here

{{InstallPlugin|pluginname=open-xchange-caldav open-xchange-carddav open-xchange-webdav-acl open-xchange-webdav-directory |sopath=updates}}

{{InstallPlugin|pluginname=open-xchange-dav|sopath=6.22/updates/backend|version=v6.22.x}}

== CalDAV Configuration ==

The following configuration options are available in the configuration files caldav.properties and caldav.yml:

===com.openexchange.caldav.enabled===
The property '''com.openexchange.caldav.enabled''' governs whether a user has access to the CalDAV interface. This can be configured along the config cascade, in the default setting, everyone that has access to the infostore also has access to caldav. This is achieved in the following way:

In v6.20 and earlier:

/opt/open-xchange/etc/groupware/caldav.properties:
com.openexchange.caldav.enabled=false

/opt/open-xchange/etc/groupware/contextSets/caldav.yml
premium:
com.openexchange.caldav.enabled: true
withTags: ucInfostore

With v6.22 and up:

/opt/open-xchange/etc/caldav.properties:
com.openexchange.caldav.enabled=false

/opt/open-xchange/etc/contextSets/caldav.yml
premium:
com.openexchange.caldav.enabled: true
withTags: ucInfostore

This means: In general CalDAV is turned off, but using the contextSets feature of the config cascade it is turned on for everyone that has infostore access.

===com.openexchange.caldav.tree===
Configures the ID of the folder tree used by the CalDAV interface. Currently, this should be set to the default value of '0'.

===com.openexchange.caldav.interval.start===
Defines the minimum end time of appointments to be synchronized via the CalDAV interface, relative to the current date. Possible values are "one_month" (default), "one_year" and "six_months".

===com.openexchange.caldav.interval.end===
Defines the maximum start time of appointments to be synchronized via the CalDAV interface, relative to the current date. Possible values are "one_year" (default) and "two_years".

===com.openexchange.caldav.url===
Tells users where to find a caldav folder. This can be displayed in frontends. You can use the variables [hostname] and [folderId]. If you chose to deploy caldav as a virtual host (say 'dav.open-xchange.com') use https://dav.open-xchange.com/caldav/[folderId] as the value. If you are using user-agent sniffing use https://[hostname]/caldav/[folderId].

== CardDAV Configuration ==

The following configuration options are available in the configuration files carddav.properties and carddav.yml:

===com.openexchange.carddav.enabled===
Similarly to CalDAV, the property '''com.openexchange.carddav.enabled''' governs whether CardDAV is available for a certain user. This is configured exactly like CalDAV with the config cascade only enabling this for users that have access to the infostore:

/opt/open-xchange/etc/groupware/carddav.properties:
com.openexchange.carddav.enabled=false

/opt/open-xchange/etc/groupware/contextSets/carddav.yml
premium:
com.openexchange.carddav.enabled: true
withTags: ucInfostore

===com.openexchange.carddav.ignoreFolders===
A comma-separated list of folder IDs to exclude from the synchronization. Use this to disable syncing of very large folders (e.g. the global address list in large contexts, which always has ID 6). By default, no folders are excluded.

===com.openexchange.carddav.tree===
Configures the ID of the folder tree used by the CardDAV interface. Currently, this should be set to the default value of '0'.

===com.openexchange.carddav.exposedCollections===
Controls which collections are exposed via the CardDAV interface. Possible values are '0', '1' and '2'. A value of '1' makes each visible folder available as a resource collection, while '2' only exposes an aggregated collection containing all contact resources from all visible folders. The default value '0' exposes either an aggregated collection or individual collections for each folder, depending on the client's user-agent that is matched against the pattern in 'userAgentForAggregatedCollection'.

===com.openexchange.carddav.userAgentForAggregatedCollection===
Regular expression to match against the client's user-agent to decide whether the aggregated collection is exposed or not. The default pattern matches all known varieties of the Mac OS Addressbook client, that doesn't support multiple collections. Only used if 'exposedCollections' is set to '0'. The pattern is used case insensitive.

===com.openexchange.carddav.reducedAggregatedCollection===
Specifies if all visible folders are used to create the aggregated collection, or if a reduced set of folders only containing the global addressbook and the personal contacts folders should be used. This setting only influences the aggregated collection that is used for clients that don't support multiple collections. Possible values are 'true' and 'false.

[[Category: Clients]]
[[Category: Administrator]]
[[Category: AppSuite]]

AppSuite:Capabilities

2014-03-14T13:59:15Z

Norbert.weinhold: /* Set a capability */

'''Synopsis:''' How to use capabilities so that your new AppSuite plugin can be enabled or disabled.

__TOC__

== What are capabilities? ==

'''Usecase'''

You write a new UI app or plugin (chat module, for example) and in addition, you want to make sure that only a specific set of users or contexts within the system are allowed to use it.

''Example:'' Your chat app should only be available after a user has bought it in your online shop. To do so, you will need to implement the capabilities logic within your UI app or plugin and restrict it to a user or context marked accordingly (called "premium" in further examples).

== Set a capability ==

First, disable it for everyone as default (or enable it for everyone, depending on what your aim is).

In <tt>/opt/open-xchange/etc/[myproduct].properties</tt>:

com.openexchange.capability.[myproduct]=false # off for everyone

Then restart the OX Application Server and afterwards use the general OX AppSuite commandline tools to enable the capability/capabilities.

The commandline tools used in the following examples are located in:

/opt/open-xchange/sbin

In this example, only for a specific user:

changeuser ... --config/com.openexchange.capability.[myproduct]=true

...or for a full context:
changecontext -c ... --config/com.openexchange.capability.[myproduct]=true

...or set the capability to a context set:

changecontext -c ... --taxonomy/types=premium

To get the capability/capabilities working for context sets (like above), you also need to edit the contextSet files in:

<tt>/opt/open-xchange/etc/contextSets/premium.yml</tt>

And add the corresponding capability/capabilities:

premium:
com.openexchange.capability.[myproduct]: true
withTags: premium

Then restart the OX Application Server!

== Query capabilities via the HTTP API ==

Query:
GET /appsuite/api/capabilities?action=all&session=991fd40f635b45...
Response:
{"data":[{"id":"oauth","attributes":{}},{"id":"webmail","attributes":{}},{"id":"document_preview","attributes":{}},{"id":"printing","attributes":{}},{"id":"spreadsheet","attributes":{}},{"id":"gab","attributes":{}},{"id":"multiple_mail_accounts","attributes":{}},{"id":"publication","attributes":{}},{"id":"rss_bookmarks","attributes":{}},{"id":"linkedin","attributes":{}},{"id":"filestore","attributes":{}},{"id":"ical","attributes":{}},{"id":"rt","attributes":{}},{"id":"olox20","attributes":{}},{"id":"forum","attributes":{}},{"id":"active_sync","attributes":{}},{"id":"conflict_handling","attributes":{}},{"id":"rss_portal","attributes":{}},{"id":"oxupdater","attributes":{}},{"id":"infostore","attributes":{}},{"id":"contacts","attributes":{}},{"id":"collect_email_addresses","attributes":{}},{"id":"facebook","attributes":{}},{"id":"drive","attributes":{}},{"id":"rss","attributes":{}},{"id":"pinboard_write_access","attributes":{}},{"id":"mobility","attributes":{}},{"id":"calendar","attributes":{}},{"id":"participants_dialog","attributes":{}},{"id":"edit_public_folders","attributes":{}},{"id":"text","attributes":{}},{"id":"groupware","attributes":{}},{"id":"msisdn","attributes":{}},{"id":"carddav","attributes":{}},{"id":"tasks","attributes":{}},{"id":"portal","attributes":{}},{"id":"mailfilter","attributes":{}},{"id":"read_create_shared_folders","attributes":{}},{"id":"vcard","attributes":{}},{"id":"pim","attributes":{}},{"id":"caldav","attributes":{}},{"id":"projects","attributes":{}},{"id":"usm","attributes":{}},{"id":"webdav","attributes":{}},{"id":"dev","attributes":{}},{"id":"delegate_tasks","attributes":{}},{"id":"freebusy","attributes":{}},{"id":"subscription","attributes":{}},{"id":"linkedinPlus","attributes":{}},{"id":"autologin","attributes":{}},{"id":"webdav_xml","attributes":{}},{"id":"twitter","attributes":{}}]}

Here <tt>id</tt> is the name of the capability.

== Query capabilities in the UI ==
require(['io.ox/core/capabilities'], function (cap) { if cap.has('[myproduct]' { ... } );

== Require the capabilities in your UI manifest file ==
{
namespace: ...
requires: '[myproduct]'
}

Now your plugin will only be loaded if the capability '[myproduct]' is set for a specific user, context, context set.

== Testing the capabilities ==

* For testing purposes use an URL parameter to test capabilities.

Add the following parameter to your AppSuite URL in the browser to activate:

&cap=[myproduct]

or use

&disableFeature=[myproduct]

to disable a certain capability.

In general, after adding those URL parameters, you need to reload the UI to temporarly test/enable the set capability.

== Further informations ==
* See the dedicated wiki page of the [[ConfigCascade]] mechanism for more details.
* If you want to know about existing capabilities and the way they are used for upsell, see [[AppSuite:Upsell#Capabilities_and_Upsell_triggers]]

[[Category: AppSuite]]
[[Category: Upsell]]

[[Category: Developer]]
[[Category: Custom development]]

OXaaS FAQ

2013-05-16T12:52:18Z

Norbert.weinhold: /* Which MX records do i need to add? */

= OX Cloud Service - Technical FAQ =

== Can I create my users in the default domain and change later to my own domain? ==

Yes, you can create the users and add aliases for another domain later.

== What are MX records for? ==

MX records are needed for email senders to identify where the mails should go to.

== Do I need to update MX records? ==

If you want to receive mails for your own domain in the ox cloud service, the domain MX records must point to the service

== How can I add MX records to my domain? ==

You need to ask the DNS administrator who is in control of the domain configuration to perform the change.

== Which MX records do I need to add? ==

Please follow instructions within Parallels. The needed MX records are listed when creating a App Suite resource.

OXaaS FAQ

2013-05-16T11:57:53Z

Norbert.weinhold: /* Can i create my users in the default domain and change later to my own domain? */

= OX Cloud Service - Technical FAQ =

== Can I create my users in the default domain and change later to my own domain? ==

Yes, you can create the users and add aliases for another domain later.

== What are MX records for? ==

MX records are needed for email senders to identify where the mails should go to.

== Do I need to update MX records? ==

If you want to receive mails for your own domain in the ox cloud service, the domain MX records must point to the service

== How can I add MX records to my domain? ==

You need to ask the DNS administrator which hosts the domain configuration to perform the change.

== Which MX records do i need to add? ==

Please follow instructions within the POA frontend. The needed MX records are listed when creating a App Suite resource

OXaaS FAQ

2013-05-16T11:57:34Z

Norbert.weinhold: /* Do i need to update MX records? */

= OX Cloud Service - Technical FAQ =

== Can i create my users in the default domain and change later to my own domain? ==

Yes, you can create the users and add aliases for another domain later.

== What are MX records for? ==

MX records are needed for email senders to identify where the mails should go to.

== Do I need to update MX records? ==

If you want to receive mails for your own domain in the ox cloud service, the domain MX records must point to the service

== How can I add MX records to my domain? ==

You need to ask the DNS administrator which hosts the domain configuration to perform the change.

== Which MX records do i need to add? ==

Please follow instructions within the POA frontend. The needed MX records are listed when creating a App Suite resource

OXaaS FAQ

2013-05-16T11:57:23Z

Norbert.weinhold: /* How can i add MX records to my domain? */

= OX Cloud Service - Technical FAQ =

== Can i create my users in the default domain and change later to my own domain? ==

Yes, you can create the users and add aliases for another domain later.

== What are MX records for? ==

MX records are needed for email senders to identify where the mails should go to.

== Do i need to update MX records? ==

If you want to receive mails for your own domain in the ox cloud service, the domain MX records must point to the service

== How can I add MX records to my domain? ==

You need to ask the DNS administrator which hosts the domain configuration to perform the change.

== Which MX records do i need to add? ==

Please follow instructions within the POA frontend. The needed MX records are listed when creating a App Suite resource