Open-Xchange - User contributions [en]

AppSuite:PushToUI 8

2025-07-09T10:43:50Z

WolfgangRosenauer:

= Howto configure push into the App Suite Web UI and PWA for App Suite 8 =

__TOC__

== Introduction ==
This HOWTO should provide a guideline to configure a push mechanism into the App Suite UI based on websockets and webpush. The push implementation in the current version of App Suite can provide push methods for email and calendar events.

== Setup ==
The general method to transport push to the UI is based on [https://en.wikipedia.org/wiki/WebSocket websockets] which is a web-technology to allow a web page to communicate with the web server full duplex.

This also means that any loadbalancers or reverse proxies in front of the kubernetes environment used for App Suite need to support websockets transparently.

Implementing this part already allows the system to push appointment updates via push to the webinterface.

In addition to websocket based push App Suite 8 also supports [https://developer.mozilla.org/en-US/docs/Web/API/Push_API WebPush] alternatively. Especially for the PWA this is a requirement.

In order to support new mail notifications and direct appearance of new mails in the mailbox there are the following components to be configured:

=== Mail push implementation ===
There needs to be a suitable [https://documentation.open-xchange.com/8/middleware/mail/mail_push.html push implementation]. It is highly recommended to use the Dovecot push integration described here: https://documentation.open-xchange.com/8/middleware/mail/dovecot/dovecot_push.html

=== Push Notification Service ===
In addition it is required to install and configure the generic push notifications and webhook support
* in the middleware: [https://documentation.open-xchange.com/8/middleware/push_notifications/push_notification_service.html PNS] and [https://documentation.open-xchange.com/8/middleware/push_notifications/webhooks.html Webhooks]
Example
packages:
status:
open-xchange-pns-impl: enabled

properties:
com.openexchange.pns.transport.webhooks.enabled: "true"
com.openexchange.pns.transport.webhooks.allowLocalWebhooks: "true"
com.openexchange.pns.transport.webhooks.httpsOnly: "false"
com.openexchange.pns.transport.webhooks.allowTrustAll: "true"
com.openexchange.webhooks.enabledIds: switchboard
com.openexchange.push.credstorage.enabled: "true"

* in the UI:
io.ox/core//features/pns: "true"

=== Switchboard ===
Websockets and webpush events in App Suite 8 are managed via the switchboard component instead of the Java middleware.
You can find the documentation how to setup websockets for switchboard here: https://documentation.open-xchange.com/appsuite/releases/8.39/helmdocs/switchboard.html#webhook-and-push-notifications

Specifically it adds the requirement for a MySQL database for switchboard and the creation of vapids.

=== Enabling the webinterface to request mail push ===
The client '''open-xchange-appsuite''' needs to be added to the property '''com.openexchange.push.allowedClients''' (typically in the file /opt/open-xchange/etc/mail-push.properties).

e.g.
com.openexchange.push.allowedClients="USM-EAS*", "open-xchange-appsuite"

AppSuite:PushToUI 8

2025-07-09T10:42:54Z

WolfgangRosenauer: Created page with "= Howto configure push into the App Suite Web UI and PWA for App Suite 8 = __TOC__ == Introduction == This HOWTO should provide a guideline to configure a push mechanism into the App Suite UI based on websockets and webpush. The push implementation in the current version of App Suite can provide push methods for email and calendar events. == Setup == The general method to transport push to the UI is based on [https://en.wikipedia.org/wiki/WebSocket websockets] which i..."

= Howto configure push into the App Suite Web UI and PWA for App Suite 8 =

__TOC__

== Introduction ==
This HOWTO should provide a guideline to configure a push mechanism into the App Suite UI based on websockets and webpush. The push implementation in the current version of App Suite can provide push methods for email and calendar events.

== Setup ==
The general method to transport push to the UI is based on [https://en.wikipedia.org/wiki/WebSocket websockets] which is a web-technology to allow a web page to communicate with the web server full duplex.

This also means that any loadbalancers or reverse proxies in front of the kubernetes environment used for App Suite need to support websockets transparently.

Implementing this part already allows the system to push appointment updates via push to the webinterface.

In addition to websocket based push App Suite 8 also supports [https://developer.mozilla.org/en-US/docs/Web/API/Push_API WebPush] alternatively. Especially for the PWA this is a requirement.

In order to support new mail notifications and direct appearance of new mails in the mailbox there are the following components to be configured:

=== Mail push implementation ===
There needs to be a suitable [https://documentation.open-xchange.com/8/middleware/mail/mail_push.html push implementation]. It is highly recommended to use the Dovecot push integration described here: https://documentation.open-xchange.com/8/middleware/mail/dovecot/dovecot_push.html

=== Push Notification Service ===
In addition it is required to install and configure the generic push notifications and webhook support
* in the middleware: [https://documentation.open-xchange.com/8/middleware/push_notifications/push_notification_service.html PNS] and [https://documentation.open-xchange.com/8/middleware/push_notifications/webhooks.html Webhooks]
Example
packages:
status:
open-xchange-pns-impl: enabled

properties:
com.openexchange.pns.transport.webhooks.enabled: "true"
com.openexchange.pns.transport.webhooks.allowLocalWebhooks: "true"
com.openexchange.pns.transport.webhooks.httpsOnly: "false"
com.openexchange.pns.transport.webhooks.allowTrustAll: "true"
com.openexchange.webhooks.enabledIds: switchboard
com.openexchange.push.allowedClients: '"USM-EAS*", "open-xchange-appsuite"'
com.openexchange.push.credstorage.enabled: "true"

* in the UI:
io.ox/core//features/pns: "true"

=== Switchboard ===
Websockets and webpush events in App Suite 8 are managed via the switchboard component instead of the Java middleware.
You can find the documentation how to setup websockets for switchboard here: https://documentation.open-xchange.com/appsuite/releases/8.39/helmdocs/switchboard.html#webhook-and-push-notifications

Specifically it adds the requirement for a MySQL database for switchboard and the creation of vapids.

=== Enabling the webinterface to request mail push ===
The client '''open-xchange-appsuite''' needs to be added to the property '''com.openexchange.push.allowedClients''' (typically in the file /opt/open-xchange/etc/mail-push.properties).

e.g.
com.openexchange.push.allowedClients="USM-EAS*", "open-xchange-appsuite"

AppSuite:OX System Requirements

2022-04-11T12:03:55Z

WolfgangRosenauer: /* Java */

= OX App Suite Requirements - Open-Xchange supported components overview =

The following table provides an overview about the supported components of OX App Suite and further products. This overview makes no claim to be complete.

Information about Maintenance expiries of components, versions and browser support, can be found in the [[AppSuite:Versioning_and_Numbering#Maintenance_expires|Maintenance Expires Table]]

== Hardware Requirements ==

=== General Assumptions ===

Open-Xchange App Suite Server (middleware services) is designed to run on physical servers or virtual machines of the same flavor. Cloud environments might be used in terms of Infrastructure as a Service (IaaS), meaning that all components need to be deployed in a classical manner on virtual machines.

This means in particular, but not only:

* Infrastructure is supposed to be "quasi-static". Automatic replacement of broken nodes is fine as long as this is always an exceptional case. Scaling out or reducing number of nodes must always be a conscious task and closely monitored.
* The only supported "Database as a service" solution is AWS RDS for MariaDB as defined by belows compatibility table.

Especially we expect the virtual hardware to be not over-provisioned. Each VM must have dedicated resources with respect to CPU cores, RAM, IOPS, storage, network bandwidth, network latency, etc.

Network is expected to be flat, inside one datacenter, no multi-datacenter, no segments. No packet loss, low latency.

'''Disclaimer: All recommendations below are without guarantee and can differ for specific deployments. For mid- and large-scale setups a detailed deployment planning and sizing tests are mandatory and should be agreed on with OX Professional Services.'''

=== High Level Design / OS setup ===

Operate services separately (USM, Document/Image Converters) as described in [https://oxpedia.org/wiki/index.php?title=AppSuite:Running_a_cluster Cluster Setup].

Clocks between all nodes must be synchronized (e.g. via NTP).

Open file/max process limits need to be adjusted properly. Based on the used Linux distribution and init system configuration will differ, see Resource Limits for further explanation.

Platform Architecture: 64 bit versions (x84_64) of the supported [[#Software Requirements | Linux distributions]]

=== Node Sizing ===

==== OX App Suite Middleware ====

* Max. 8 GB heap per JVM + 4 GB system memory for other daemons and the OS (buffers, caches)
* 4 CPU cores (virtual, physical or hyperthreads) for plain HTTP connections. If TLS is terminated on application nodes this might need to be doubled.
* Disk space
** 8 GB for OS and software
** Some services like Document Converter need SWAP partitions (~1 * RAM)
** 2 * system memory of free disk space (i.e. 12 GB RAM => 24 GB free disk space) for file spooling, log files, heap and core dumps

=== Untested/Unsupported Deployments ===

* Changes to Garbage Collector settings
* Running in containerized environments (Docker, rkt)
* Elasticity/High velocity of nodes going up and down: Services are sometimes stateful and demand static configuration
* Cloud platform services (PaaS) that promise to replacements for certain supported technologies but have not been verified by OX for these regards
* Multi-site active-active

== Software Requirements ==

=== Linux Distributions ===

OX App Suite is available as Linux packages for the following distributions:

{|border="2" rules="all" align="left">
|'''Distribution'''
|'''Versions'''
|'''Remarks'''
|-
| 
| 
| 
|-
|Red Hat Enterprise Linux
|7
|
|-
|CentOS
|7
|Install from RHEL package repositories
|-
|Debian
|9 (Stretch), 10 (Buster)
|
|-
|Univention Corporate Server
|4.4, 5.0
|
|-
|Amazon Linux
|2
|Discontinued Support with end of life of OX App Suite v7.10.5
|-
|}

=== Java ===

OX App Suite Middleware requires OpenJDK headless JRE 8 or 9. Linux distributions might offer only packages for OpenJDK 11 JRE or higher, which are not suitable for OX App Suite. It is in those cases required to install Eclipse Temurin 8 JRE with HotSpot VM (successor of Adoptium). A comprehensive installation guide can be found at https://adoptium.net/de/installation/linux/. The correct JRE package is '''temurin-8-jdk'''.

=== Databases ===

OX App Suite uses MySQL/MariaDB with the InnoDB storage engine as its primary data store. The following vendors and products are supported.

{|border="2" rules="all" align="left">
|'''Vendor'''
|'''Product'''
|'''Versions'''
|-
| 
| 
| 
|-
|Oracle
|MySQL Community Edition, Standard Edition, Enterprise Edition
|v5.6.x, v5.7.x
|-
|MariaDB
|MariaDB Server, Galera Cluster
|v10.1.x, v10.2.x, v10.4.x, v10.5.x.
|-
|Amazon
|AWS RDS for MariaDB
|10.2.x<br>Discontinued Support with end of life of OX App Suite v7.10.5
|-
|}

==== Important Notes ====

* Open-Xchange does not plan to support '''MySQL 8 or higher'''. As MariaDB and MySQL are diverging and cannot be assumed drop-in replacements anymore, Open-Xchange will focus on MariaDB Server and MariaDB Galera Cluster. Future App Suite releases '''> 7.10.x''' might rely on features only available in '''MariaDB'''.
* Open-Xchange supports '''Percona XtraDB Cluster''' for existing customers with initial deployments done using '''App Suite 7.8.x or earlier'''. Those customers can continue to use Percona XtraDB Cluster throughout the 7.10.x release series. Like for MySQL, 7.10.x supports only versions 5.6 and 5.7. It is not planned to support Percona XtraDB Cluster beyond 7.10.x.

* For some Linux distributions the included MySQL/MariaDB packages are too old to be used with App Suite. It is mandatory then to install a supported version from '''upstream package sources'''. Possible sources are the official vendor repositories of MySQL or MariaDB as well as for example Red Hat Software Collections.
* Required '''MySQL/MariaDB configuration''' configuration differs between '''App Suite 7.8.4 and 7.10.x''' and also between the different database systems in terms of SQL modes. See [[My.cnf]] for details.
* For upgrades from App Suite <= 7.8.2 to >= 7.10.0 a comprehensive '''database upgrade guide''' exists: [[AppSuite:7_10_Database_Migration]]

== HTTP Reverse Proxy ==

An HTTP server with reverse proxy and load balancing capabilities is required in front of App Suite application servers. TLS termination, virtual hosts, path-based routing, sticky sessions and X-Forwarded headers are typical required features. OX strongly recommends [https://httpd.apache.org/ Apache httpd 2.x] for that. Configuration examples can be found in the quickinstall guides.

'''Important:''' For websocket support Apache httpd 2.4.x is needed, 2.2.x does not support the required ws_tunnel module. Websockets are mandatory for OX Documents starting with v7.10.3. Like with JRE and MySQL/MariaDB it might be necessary to use 3rd party packages to get the needed Linux packages. Especially for RHEL6 we recommend using Red Hat Software Collections.

== Webserver ==

[https://httpd.apache.org/ Apache httpd 2.x] is required as webserver to serve static App Suite UI content. Configuration examples can be found in the quickinstall guides.

== File Storage ==

=== Temporary Data ===

OX App Suite stores temporary files in the local file system, e.g. for spooling of uploaded data. Any file system supported by the installed JRE is suitable.

=== Persistent Data ===

Persistent data like OX Drive files, PIM attachments etc. and temporary attachment data need to be stored in a distributed file system as registered filestore that is available from all server nodes. For single-node setups a local file system mount point can be used, small to mid-scale setups can be powered by NFS. For large-scale setups object storages should be considered.

==== Object Storages ====

OX App Suite ships with different optional adapters to support object storages.

{|border="2" rules="all" align="left">
|'''Vendor'''
|'''Product'''
|'''API'''
|'''Remarks'''
|-
| 
| 
| 
| 
|-
|Amazon
|AWS S3
|S3 HTTP API
|See also [[AppSuite:S3_File_Store]]
|-
|CEPH
|RadosGW
|S3 HTTP API
|See also [[AppSuite:S3_File_Store]]
|-
|Scality
|Scality RING
|Sproxyd HTTP API
|See also [[AppSuite:Scality_File_Store]]
|-
|}

== Desktop Browser (Minimum display resolution: 1024 x 768)==

{|border="2" rules="all" align="left">
|'''Browser'''
|'''OX App Suite User Front-End'''
|-
| 
| 
|-
|Google Chrome (latest & previous version)
|v7.10.5, v7.10.6
|-
|Mozilla Firefox (latest & current ESR-Version)
|v7.10.5, v7.10.6
|-
|Apple Safari (latest & previous version; macOS only)
|v7.10.5, v7.10.6
|-
|Microsoft Edge (Chromium-based)
|v7.10.5, v7.10.6
|-
|Microsoft Internet Explorer 10/11
|v7.6.3
|-
|}

== Mobile Device Support==

{|border="2" rules="all" align="left">
|'''Mobile Device'''
|'''Supported Browser'''
|'''OX App Suite User Front-End'''
|'''Minimum Speed Requirements'''
|-
| 
| 
| 
| 
|-
|iPhone on iOS 14 / iOS 15 / iPad OS
|Safari
|v7.10.5, v7.10.6
|3G connections (512/256kBit/s, 350ms latency)
|-
|Smartphone on Android 4.1 or later
|Chrome (latest & previous version)
|v7.10.5, v7.10.6
|3G connections (512/256kBit/s, 350ms latency)
|}

== Tablet Support==

{|border="2" rules="all" align="left">
|'''Tablet'''
|'''Supported Browser'''
|'''OX App Suite User Front-End'''
|'''Minimum Speed Requirements'''
|-
| 
| 
| 
| 
|-
|Apple iPad (all devices) on iOS 14 / iOS 15 / iPad OS
|Safari
|v7.10.5, v7.10.6
|3G connections (512/256kBit/s, 350ms latency)
|-
|Tablets on Android 4.1 or later
|Chrome (latest & previous version)
|v7.10.5, v7.10.6
|3G connections (512/256kBit/s, 350ms latency)
|}

== Calendar/Contact synchronization Apple macOS ==

{|border="2" rules="all" align="left">
|'''Requirement'''
|Calendar synchronization with CalDAV
|Contacts synchronization with CardDAV
|-
| 
| 
| 
|-
|macOS 11.0 (Big Sur)
|[[File:check.gif]]
|[[File:check.gif]]
|-
|macOS 12.0 (Monterey)
|[[File:check.gif]]
|[[File:check.gif]]
|-
|}

== Calendar/Contact synchronization Apple iOS ==

{|border="2" rules="all" align="left">
|'''Requirement'''
|Calendar synchronization with CalDAV
|Contacts synchronization with CardDAV
|-
| 
| 
| 
|-
|Apple iOS 14 / iOS 15 / iPad OS
|[[File:check.gif]]
|[[File:check.gif]]
|-
|}

== Mobility Solution - Supported- Platforms, Features and Devices ==

{|border="2" rules="all" align="left">
|'''Feature/Technology/Device'''
|[http://oxpedia.org/wiki/index.php?title=OXtender_for_Business_Mobility '''OXtender for Business Mobility'''] (availalble for App Suite, OXHE, OXSE)
|-
| 
| 
|-
|Exchange Active Sync 2.5
|[[File:check.gif]]
|-
|Exchange Active Sync 12.1
|[[File:check.gif]]
|-
| 
| 
|-
|Access and creation of emails
|[[File:check.gif]]
|-
|Personal PIM folder
|[[File:check.gif]]
|-
|Public and Shared PIM folder
|[[File:cross.gif]]
|-
|Global address book
|[[File:check.gif]]
|-
|Push E-Mail
|[[File:check.gif]]
|-
| 
| 
|-
|Apple iOS 14 / iOS 15 / iPad OS
|[[File:check.gif]]
|-
|Android 8 (Oreo) or later with latest Gmail app.
|[[File:check.gif]]
|-
|}

== OX Drive Clients ==

{|border="2" rules="all" align="left">
|'''Requirement'''
|'''System / Platform'''
|-
| 
| 
|-
|OX Drive for Windows
|OX App Suite 7.10.5, OX App Suite 7.10.6<br>Latest versions of Windows 10 (no support of macOS clients with emulators and Windows RT)
|-
|OX Drive for Apple macOS
|OX App Suite 7.10.5, OX App Suite 7.10.6<br>macOS Big Sur 11, macOS Monterey 12, Intel- and Apple Silicon-based devices are both supported
|-
|OX Drive v2 for Apple iOS
|OX App Suite 7.10.5, OX App Suite 7.10.6<br>iOS / iPadOS 14 and above
|-
|OX Drive v3 for Apple iOS
|OX App Suite 7.10.6<br>iOS / iPadOS 14 and above
|-
|OX Drive for Android
|OX App Suite 7.10.5, OX App Suite 7.10.6<br>Smartphones and tablets running Android 7.0 (API level 24) and above.
|-
|}

== OX Sync App ==

{|border="2" rules="all" align="left">
|'''Requirement'''
|'''System / Platform / User Interface'''
|-
| 
| 
|-
|OX App Suite
|OX App Suite 7.10.5, OX App Suite 7.10.6
|-
|OX Sync App for Android
|Smartphone on Android 5.0 or later
|-
|}

== OX Guard ==

{|border="2" rules="all" align="left">
|'''Requirement'''
|'''System / Platform / User Interface'''
|-
| 
| 
|-
|OX App Suite
|OX Guard since v2.10.5: OX App Suite v7.10.5<br>OX Guard since v2.10.6: OX App Suite v7.10.6
|-
|Mobile Device and Tablet Support
|Apple iPhone on iOS 14 / iOS 15 / iPad OS: Safari (latest version & previous version)<br>Smartphone on Android 4.1 or later: Chrome (latest & previous version)<br>Apple iPad (all devices) on iOS 14 / iOS 15 / iPad OS: Safari Safari (latest version & previous version)<br>Tablets on Android 4.1 or later: Chrome (latest & previous version)
|-
|}

[[Category: OX7]]
[[Category: AppSuite]]

AppSuite:OX System Requirements

2022-04-11T12:02:14Z

WolfgangRosenauer:

= OX App Suite Requirements - Open-Xchange supported components overview =

The following table provides an overview about the supported components of OX App Suite and further products. This overview makes no claim to be complete.

Information about Maintenance expiries of components, versions and browser support, can be found in the [[AppSuite:Versioning_and_Numbering#Maintenance_expires|Maintenance Expires Table]]

== Hardware Requirements ==

=== General Assumptions ===

Open-Xchange App Suite Server (middleware services) is designed to run on physical servers or virtual machines of the same flavor. Cloud environments might be used in terms of Infrastructure as a Service (IaaS), meaning that all components need to be deployed in a classical manner on virtual machines.

This means in particular, but not only:

* Infrastructure is supposed to be "quasi-static". Automatic replacement of broken nodes is fine as long as this is always an exceptional case. Scaling out or reducing number of nodes must always be a conscious task and closely monitored.
* The only supported "Database as a service" solution is AWS RDS for MariaDB as defined by belows compatibility table.

Especially we expect the virtual hardware to be not over-provisioned. Each VM must have dedicated resources with respect to CPU cores, RAM, IOPS, storage, network bandwidth, network latency, etc.

Network is expected to be flat, inside one datacenter, no multi-datacenter, no segments. No packet loss, low latency.

'''Disclaimer: All recommendations below are without guarantee and can differ for specific deployments. For mid- and large-scale setups a detailed deployment planning and sizing tests are mandatory and should be agreed on with OX Professional Services.'''

=== High Level Design / OS setup ===

Operate services separately (USM, Document/Image Converters) as described in [https://oxpedia.org/wiki/index.php?title=AppSuite:Running_a_cluster Cluster Setup].

Clocks between all nodes must be synchronized (e.g. via NTP).

Open file/max process limits need to be adjusted properly. Based on the used Linux distribution and init system configuration will differ, see Resource Limits for further explanation.

Platform Architecture: 64 bit versions (x84_64) of the supported [[#Software Requirements | Linux distributions]]

=== Node Sizing ===

==== OX App Suite Middleware ====

* Max. 8 GB heap per JVM + 4 GB system memory for other daemons and the OS (buffers, caches)
* 4 CPU cores (virtual, physical or hyperthreads) for plain HTTP connections. If TLS is terminated on application nodes this might need to be doubled.
* Disk space
** 8 GB for OS and software
** Some services like Document Converter need SWAP partitions (~1 * RAM)
** 2 * system memory of free disk space (i.e. 12 GB RAM => 24 GB free disk space) for file spooling, log files, heap and core dumps

=== Untested/Unsupported Deployments ===

* Changes to Garbage Collector settings
* Running in containerized environments (Docker, rkt)
* Elasticity/High velocity of nodes going up and down: Services are sometimes stateful and demand static configuration
* Cloud platform services (PaaS) that promise to replacements for certain supported technologies but have not been verified by OX for these regards
* Multi-site active-active

== Software Requirements ==

=== Linux Distributions ===

OX App Suite is available as Linux packages for the following distributions:

{|border="2" rules="all" align="left">
|'''Distribution'''
|'''Versions'''
|'''Remarks'''
|-
| 
| 
| 
|-
|Red Hat Enterprise Linux
|7
|
|-
|CentOS
|7
|Install from RHEL package repositories
|-
|Debian
|9 (Stretch), 10 (Buster)
|
|-
|Univention Corporate Server
|4.4, 5.0
|
|-
|Amazon Linux
|2
|Discontinued Support with end of life of OX App Suite v7.10.5
|-
|}

=== Java ===

OX App Suite Middleware requires OpenJDK headless JRE 8 or 9. Linux distributions might offer only packages for OpenJDK 11 JRE or higher, which are not suitable for OX App Suite. It is in those cases required to install Eclipse Temurin 8 JRE with HotSpot VM (successor of Adoptium). A comprehensive installation guide can be found at https://adoptium.net/de/installation/linux/. The correct JRE package is *temurin-8-jdk*.

=== Databases ===

OX App Suite uses MySQL/MariaDB with the InnoDB storage engine as its primary data store. The following vendors and products are supported.

{|border="2" rules="all" align="left">
|'''Vendor'''
|'''Product'''
|'''Versions'''
|-
| 
| 
| 
|-
|Oracle
|MySQL Community Edition, Standard Edition, Enterprise Edition
|v5.6.x, v5.7.x
|-
|MariaDB
|MariaDB Server, Galera Cluster
|v10.1.x, v10.2.x, v10.4.x, v10.5.x.
|-
|Amazon
|AWS RDS for MariaDB
|10.2.x<br>Discontinued Support with end of life of OX App Suite v7.10.5
|-
|}

==== Important Notes ====

* Open-Xchange does not plan to support '''MySQL 8 or higher'''. As MariaDB and MySQL are diverging and cannot be assumed drop-in replacements anymore, Open-Xchange will focus on MariaDB Server and MariaDB Galera Cluster. Future App Suite releases '''> 7.10.x''' might rely on features only available in '''MariaDB'''.
* Open-Xchange supports '''Percona XtraDB Cluster''' for existing customers with initial deployments done using '''App Suite 7.8.x or earlier'''. Those customers can continue to use Percona XtraDB Cluster throughout the 7.10.x release series. Like for MySQL, 7.10.x supports only versions 5.6 and 5.7. It is not planned to support Percona XtraDB Cluster beyond 7.10.x.

* For some Linux distributions the included MySQL/MariaDB packages are too old to be used with App Suite. It is mandatory then to install a supported version from '''upstream package sources'''. Possible sources are the official vendor repositories of MySQL or MariaDB as well as for example Red Hat Software Collections.
* Required '''MySQL/MariaDB configuration''' configuration differs between '''App Suite 7.8.4 and 7.10.x''' and also between the different database systems in terms of SQL modes. See [[My.cnf]] for details.
* For upgrades from App Suite <= 7.8.2 to >= 7.10.0 a comprehensive '''database upgrade guide''' exists: [[AppSuite:7_10_Database_Migration]]

== HTTP Reverse Proxy ==

An HTTP server with reverse proxy and load balancing capabilities is required in front of App Suite application servers. TLS termination, virtual hosts, path-based routing, sticky sessions and X-Forwarded headers are typical required features. OX strongly recommends [https://httpd.apache.org/ Apache httpd 2.x] for that. Configuration examples can be found in the quickinstall guides.

'''Important:''' For websocket support Apache httpd 2.4.x is needed, 2.2.x does not support the required ws_tunnel module. Websockets are mandatory for OX Documents starting with v7.10.3. Like with JRE and MySQL/MariaDB it might be necessary to use 3rd party packages to get the needed Linux packages. Especially for RHEL6 we recommend using Red Hat Software Collections.

== Webserver ==

[https://httpd.apache.org/ Apache httpd 2.x] is required as webserver to serve static App Suite UI content. Configuration examples can be found in the quickinstall guides.

== File Storage ==

=== Temporary Data ===

OX App Suite stores temporary files in the local file system, e.g. for spooling of uploaded data. Any file system supported by the installed JRE is suitable.

=== Persistent Data ===

Persistent data like OX Drive files, PIM attachments etc. and temporary attachment data need to be stored in a distributed file system as registered filestore that is available from all server nodes. For single-node setups a local file system mount point can be used, small to mid-scale setups can be powered by NFS. For large-scale setups object storages should be considered.

==== Object Storages ====

OX App Suite ships with different optional adapters to support object storages.

{|border="2" rules="all" align="left">
|'''Vendor'''
|'''Product'''
|'''API'''
|'''Remarks'''
|-
| 
| 
| 
| 
|-
|Amazon
|AWS S3
|S3 HTTP API
|See also [[AppSuite:S3_File_Store]]
|-
|CEPH
|RadosGW
|S3 HTTP API
|See also [[AppSuite:S3_File_Store]]
|-
|Scality
|Scality RING
|Sproxyd HTTP API
|See also [[AppSuite:Scality_File_Store]]
|-
|}

== Desktop Browser (Minimum display resolution: 1024 x 768)==

{|border="2" rules="all" align="left">
|'''Browser'''
|'''OX App Suite User Front-End'''
|-
| 
| 
|-
|Google Chrome (latest & previous version)
|v7.10.5, v7.10.6
|-
|Mozilla Firefox (latest & current ESR-Version)
|v7.10.5, v7.10.6
|-
|Apple Safari (latest & previous version; macOS only)
|v7.10.5, v7.10.6
|-
|Microsoft Edge (Chromium-based)
|v7.10.5, v7.10.6
|-
|Microsoft Internet Explorer 10/11
|v7.6.3
|-
|}

== Mobile Device Support==

{|border="2" rules="all" align="left">
|'''Mobile Device'''
|'''Supported Browser'''
|'''OX App Suite User Front-End'''
|'''Minimum Speed Requirements'''
|-
| 
| 
| 
| 
|-
|iPhone on iOS 14 / iOS 15 / iPad OS
|Safari
|v7.10.5, v7.10.6
|3G connections (512/256kBit/s, 350ms latency)
|-
|Smartphone on Android 4.1 or later
|Chrome (latest & previous version)
|v7.10.5, v7.10.6
|3G connections (512/256kBit/s, 350ms latency)
|}

== Tablet Support==

{|border="2" rules="all" align="left">
|'''Tablet'''
|'''Supported Browser'''
|'''OX App Suite User Front-End'''
|'''Minimum Speed Requirements'''
|-
| 
| 
| 
| 
|-
|Apple iPad (all devices) on iOS 14 / iOS 15 / iPad OS
|Safari
|v7.10.5, v7.10.6
|3G connections (512/256kBit/s, 350ms latency)
|-
|Tablets on Android 4.1 or later
|Chrome (latest & previous version)
|v7.10.5, v7.10.6
|3G connections (512/256kBit/s, 350ms latency)
|}

== Calendar/Contact synchronization Apple macOS ==

{|border="2" rules="all" align="left">
|'''Requirement'''
|Calendar synchronization with CalDAV
|Contacts synchronization with CardDAV
|-
| 
| 
| 
|-
|macOS 11.0 (Big Sur)
|[[File:check.gif]]
|[[File:check.gif]]
|-
|macOS 12.0 (Monterey)
|[[File:check.gif]]
|[[File:check.gif]]
|-
|}

== Calendar/Contact synchronization Apple iOS ==

{|border="2" rules="all" align="left">
|'''Requirement'''
|Calendar synchronization with CalDAV
|Contacts synchronization with CardDAV
|-
| 
| 
| 
|-
|Apple iOS 14 / iOS 15 / iPad OS
|[[File:check.gif]]
|[[File:check.gif]]
|-
|}

== Mobility Solution - Supported- Platforms, Features and Devices ==

{|border="2" rules="all" align="left">
|'''Feature/Technology/Device'''
|[http://oxpedia.org/wiki/index.php?title=OXtender_for_Business_Mobility '''OXtender for Business Mobility'''] (availalble for App Suite, OXHE, OXSE)
|-
| 
| 
|-
|Exchange Active Sync 2.5
|[[File:check.gif]]
|-
|Exchange Active Sync 12.1
|[[File:check.gif]]
|-
| 
| 
|-
|Access and creation of emails
|[[File:check.gif]]
|-
|Personal PIM folder
|[[File:check.gif]]
|-
|Public and Shared PIM folder
|[[File:cross.gif]]
|-
|Global address book
|[[File:check.gif]]
|-
|Push E-Mail
|[[File:check.gif]]
|-
| 
| 
|-
|Apple iOS 14 / iOS 15 / iPad OS
|[[File:check.gif]]
|-
|Android 8 (Oreo) or later with latest Gmail app.
|[[File:check.gif]]
|-
|}

== OX Drive Clients ==

{|border="2" rules="all" align="left">
|'''Requirement'''
|'''System / Platform'''
|-
| 
| 
|-
|OX Drive for Windows
|OX App Suite 7.10.5, OX App Suite 7.10.6<br>Latest versions of Windows 10 (no support of macOS clients with emulators and Windows RT)
|-
|OX Drive for Apple macOS
|OX App Suite 7.10.5, OX App Suite 7.10.6<br>macOS Big Sur 11, macOS Monterey 12, Intel- and Apple Silicon-based devices are both supported
|-
|OX Drive v2 for Apple iOS
|OX App Suite 7.10.5, OX App Suite 7.10.6<br>iOS / iPadOS 14 and above
|-
|OX Drive v3 for Apple iOS
|OX App Suite 7.10.6<br>iOS / iPadOS 14 and above
|-
|OX Drive for Android
|OX App Suite 7.10.5, OX App Suite 7.10.6<br>Smartphones and tablets running Android 7.0 (API level 24) and above.
|-
|}

== OX Sync App ==

{|border="2" rules="all" align="left">
|'''Requirement'''
|'''System / Platform / User Interface'''
|-
| 
| 
|-
|OX App Suite
|OX App Suite 7.10.5, OX App Suite 7.10.6
|-
|OX Sync App for Android
|Smartphone on Android 5.0 or later
|-
|}

== OX Guard ==

{|border="2" rules="all" align="left">
|'''Requirement'''
|'''System / Platform / User Interface'''
|-
| 
| 
|-
|OX App Suite
|OX Guard since v2.10.5: OX App Suite v7.10.5<br>OX Guard since v2.10.6: OX App Suite v7.10.6
|-
|Mobile Device and Tablet Support
|Apple iPhone on iOS 14 / iOS 15 / iPad OS: Safari (latest version & previous version)<br>Smartphone on Android 4.1 or later: Chrome (latest & previous version)<br>Apple iPad (all devices) on iOS 14 / iOS 15 / iPad OS: Safari Safari (latest version & previous version)<br>Tablets on Android 4.1 or later: Chrome (latest & previous version)
|-
|}

[[Category: OX7]]
[[Category: AppSuite]]

AppSuite:OX System Requirements

2022-04-11T12:01:42Z

WolfgangRosenauer:

= OX App Suite Requirements - Open-Xchange supported components overview =

The following table provides an overview about the supported components of OX App Suite and further products. This overview makes no claim to be complete.

Information about Maintenance expiries of components, versions and browser support, can be found in the [[AppSuite:Versioning_and_Numbering#Maintenance_expires|Maintenance Expires Table]]

== Hardware Requirements ==

=== General Assumptions ===

Open-Xchange App Suite Server (middleware services) is designed to run on physical servers or virtual machines of the same flavor. Cloud environments might be used in terms of Infrastructure as a Service (IaaS), meaning that all components need to be deployed in a classical manner on virtual machines.

This means in particular, but not only:

* Infrastructure is supposed to be "quasi-static". Automatic replacement of broken nodes is fine as long as this is always an exceptional case. Scaling out or reducing number of nodes must always be a conscious task and closely monitored.
* The only supported "Database as a service" solution is AWS RDS for MariaDB as defined by belows compatibility table.

Especially we expect the virtual hardware to be not over-provisioned. Each VM must have dedicated resources with respect to CPU cores, RAM, IOPS, storage, network bandwidth, network latency, etc.

Network is expected to be flat, inside one datacenter, no multi-datacenter, no segments. No packet loss, low latency.

'''Disclaimer: All recommendations below are without guarantee and can differ for specific deployments. For mid- and large-scale setups a detailed deployment planning and sizing tests are mandatory and should be agreed on with OX Professional Services.'''

=== High Level Design / OS setup ===

Operate services separately (USM, Document/Image Converters) as described in [https://oxpedia.org/wiki/index.php?title=AppSuite:Running_a_cluster Cluster Setup].

Clocks between all nodes must be synchronized (e.g. via NTP).

Open file/max process limits need to be adjusted properly. Based on the used Linux distribution and init system configuration will differ, see Resource Limits for further explanation.

Platform Architecture: 64 bit versions (x84_64) of the supported [[#Software Requirements | Linux distributions]]

=== Node Sizing ===

==== OX App Suite Middleware ====

* Max. 8 GB heap per JVM + 4 GB system memory for other daemons and the OS (buffers, caches)
* 4 CPU cores (virtual, physical or hyperthreads) for plain HTTP connections. If TLS is terminated on application nodes this might need to be doubled.
* Disk space
** 8 GB for OS and software
** Some services like Document Converter need SWAP partitions (~1 * RAM)
** 2 * system memory of free disk space (i.e. 12 GB RAM => 24 GB free disk space) for file spooling, log files, heap and core dumps

=== Untested/Unsupported Deployments ===

* Changes to Garbage Collector settings
* Running in containerized environments (Docker, rkt)
* Elasticity/High velocity of nodes going up and down: Services are sometimes stateful and demand static configuration
* Cloud platform services (PaaS) that promise to replacements for certain supported technologies but have not been verified by OX for these regards
* Multi-site active-active

== Software Requirements ==

=== Linux Distributions ===

OX App Suite is available as Linux packages for the following distributions:

{|border="2" rules="all" align="left">
|'''Distribution'''
|'''Versions'''
|'''Remarks'''
|-
| 
| 
| 
|-
|Red Hat Enterprise Linux
|7
|
|-
|CentOS
|7
|Install from RHEL package repositories
|-
|Debian
|9 (Stretch), 10 (Buster)
|
|-
|Univention Corporate Server
|4.4, 5.0
|
|-
|Amazon Linux
|2
|Discontinued Support with end of life of OX App Suite v7.10.5
|-
|}

=== Java ===

OX App Suite Middleware requires OpenJDK headless JRE 8 or 9. Linux distributions might offer only packages for OpenJDK 11 JRE, which is not suitable for OX App Suite. It is in those cases required to install Eclipse Temurin 8 JRE with HotSpot VM (successor of Adoptium). A comprehensive installation guide can be found at https://adoptium.net/de/installation/linux/. The correct JRE package is *temurin-8-jdk*.

=== Databases ===

OX App Suite uses MySQL/MariaDB with the InnoDB storage engine as its primary data store. The following vendors and products are supported.

{|border="2" rules="all" align="left">
|'''Vendor'''
|'''Product'''
|'''Versions'''
|-
| 
| 
| 
|-
|Oracle
|MySQL Community Edition, Standard Edition, Enterprise Edition
|v5.6.x, v5.7.x
|-
|MariaDB
|MariaDB Server, Galera Cluster
|v10.1.x, v10.2.x, v10.4.x, v10.5.x.
|-
|Amazon
|AWS RDS for MariaDB
|10.2.x<br>Discontinued Support with end of life of OX App Suite v7.10.5
|-
|}

==== Important Notes ====

* Open-Xchange does not plan to support '''MySQL 8 or higher'''. As MariaDB and MySQL are diverging and cannot be assumed drop-in replacements anymore, Open-Xchange will focus on MariaDB Server and MariaDB Galera Cluster. Future App Suite releases '''> 7.10.x''' might rely on features only available in '''MariaDB'''.
* Open-Xchange supports '''Percona XtraDB Cluster''' for existing customers with initial deployments done using '''App Suite 7.8.x or earlier'''. Those customers can continue to use Percona XtraDB Cluster throughout the 7.10.x release series. Like for MySQL, 7.10.x supports only versions 5.6 and 5.7. It is not planned to support Percona XtraDB Cluster beyond 7.10.x.

* For some Linux distributions the included MySQL/MariaDB packages are too old to be used with App Suite. It is mandatory then to install a supported version from '''upstream package sources'''. Possible sources are the official vendor repositories of MySQL or MariaDB as well as for example Red Hat Software Collections.
* Required '''MySQL/MariaDB configuration''' configuration differs between '''App Suite 7.8.4 and 7.10.x''' and also between the different database systems in terms of SQL modes. See [[My.cnf]] for details.
* For upgrades from App Suite <= 7.8.2 to >= 7.10.0 a comprehensive '''database upgrade guide''' exists: [[AppSuite:7_10_Database_Migration]]

== HTTP Reverse Proxy ==

An HTTP server with reverse proxy and load balancing capabilities is required in front of App Suite application servers. TLS termination, virtual hosts, path-based routing, sticky sessions and X-Forwarded headers are typical required features. OX strongly recommends [https://httpd.apache.org/ Apache httpd 2.x] for that. Configuration examples can be found in the quickinstall guides.

'''Important:''' For websocket support Apache httpd 2.4.x is needed, 2.2.x does not support the required ws_tunnel module. Websockets are mandatory for OX Documents starting with v7.10.3. Like with JRE and MySQL/MariaDB it might be necessary to use 3rd party packages to get the needed Linux packages. Especially for RHEL6 we recommend using Red Hat Software Collections.

== Webserver ==

[https://httpd.apache.org/ Apache httpd 2.x] is required as webserver to serve static App Suite UI content. Configuration examples can be found in the quickinstall guides.

== File Storage ==

=== Temporary Data ===

OX App Suite stores temporary files in the local file system, e.g. for spooling of uploaded data. Any file system supported by the installed JRE is suitable.

=== Persistent Data ===

Persistent data like OX Drive files, PIM attachments etc. and temporary attachment data need to be stored in a distributed file system as registered filestore that is available from all server nodes. For single-node setups a local file system mount point can be used, small to mid-scale setups can be powered by NFS. For large-scale setups object storages should be considered.

==== Object Storages ====

OX App Suite ships with different optional adapters to support object storages.

{|border="2" rules="all" align="left">
|'''Vendor'''
|'''Product'''
|'''API'''
|'''Remarks'''
|-
| 
| 
| 
| 
|-
|Amazon
|AWS S3
|S3 HTTP API
|See also [[AppSuite:S3_File_Store]]
|-
|CEPH
|RadosGW
|S3 HTTP API
|See also [[AppSuite:S3_File_Store]]
|-
|Scality
|Scality RING
|Sproxyd HTTP API
|See also [[AppSuite:Scality_File_Store]]
|-
|}

== Desktop Browser (Minimum display resolution: 1024 x 768)==

{|border="2" rules="all" align="left">
|'''Browser'''
|'''OX App Suite User Front-End'''
|-
| 
| 
|-
|Google Chrome (latest & previous version)
|v7.10.5, v7.10.6
|-
|Mozilla Firefox (latest & current ESR-Version)
|v7.10.5, v7.10.6
|-
|Apple Safari (latest & previous version; macOS only)
|v7.10.5, v7.10.6
|-
|Microsoft Edge (Chromium-based)
|v7.10.5, v7.10.6
|-
|Microsoft Internet Explorer 10/11
|v7.6.3
|-
|}

== Mobile Device Support==

{|border="2" rules="all" align="left">
|'''Mobile Device'''
|'''Supported Browser'''
|'''OX App Suite User Front-End'''
|'''Minimum Speed Requirements'''
|-
| 
| 
| 
| 
|-
|iPhone on iOS 14 / iOS 15 / iPad OS
|Safari
|v7.10.5, v7.10.6
|3G connections (512/256kBit/s, 350ms latency)
|-
|Smartphone on Android 4.1 or later
|Chrome (latest & previous version)
|v7.10.5, v7.10.6
|3G connections (512/256kBit/s, 350ms latency)
|}

== Tablet Support==

{|border="2" rules="all" align="left">
|'''Tablet'''
|'''Supported Browser'''
|'''OX App Suite User Front-End'''
|'''Minimum Speed Requirements'''
|-
| 
| 
| 
| 
|-
|Apple iPad (all devices) on iOS 14 / iOS 15 / iPad OS
|Safari
|v7.10.5, v7.10.6
|3G connections (512/256kBit/s, 350ms latency)
|-
|Tablets on Android 4.1 or later
|Chrome (latest & previous version)
|v7.10.5, v7.10.6
|3G connections (512/256kBit/s, 350ms latency)
|}

== Calendar/Contact synchronization Apple macOS ==

{|border="2" rules="all" align="left">
|'''Requirement'''
|Calendar synchronization with CalDAV
|Contacts synchronization with CardDAV
|-
| 
| 
| 
|-
|macOS 11.0 (Big Sur)
|[[File:check.gif]]
|[[File:check.gif]]
|-
|macOS 12.0 (Monterey)
|[[File:check.gif]]
|[[File:check.gif]]
|-
|}

== Calendar/Contact synchronization Apple iOS ==

{|border="2" rules="all" align="left">
|'''Requirement'''
|Calendar synchronization with CalDAV
|Contacts synchronization with CardDAV
|-
| 
| 
| 
|-
|Apple iOS 14 / iOS 15 / iPad OS
|[[File:check.gif]]
|[[File:check.gif]]
|-
|}

== Mobility Solution - Supported- Platforms, Features and Devices ==

{|border="2" rules="all" align="left">
|'''Feature/Technology/Device'''
|[http://oxpedia.org/wiki/index.php?title=OXtender_for_Business_Mobility '''OXtender for Business Mobility'''] (availalble for App Suite, OXHE, OXSE)
|-
| 
| 
|-
|Exchange Active Sync 2.5
|[[File:check.gif]]
|-
|Exchange Active Sync 12.1
|[[File:check.gif]]
|-
| 
| 
|-
|Access and creation of emails
|[[File:check.gif]]
|-
|Personal PIM folder
|[[File:check.gif]]
|-
|Public and Shared PIM folder
|[[File:cross.gif]]
|-
|Global address book
|[[File:check.gif]]
|-
|Push E-Mail
|[[File:check.gif]]
|-
| 
| 
|-
|Apple iOS 14 / iOS 15 / iPad OS
|[[File:check.gif]]
|-
|Android 8 (Oreo) or later with latest Gmail app.
|[[File:check.gif]]
|-
|}

== OX Drive Clients ==

{|border="2" rules="all" align="left">
|'''Requirement'''
|'''System / Platform'''
|-
| 
| 
|-
|OX Drive for Windows
|OX App Suite 7.10.5, OX App Suite 7.10.6<br>Latest versions of Windows 10 (no support of macOS clients with emulators and Windows RT)
|-
|OX Drive for Apple macOS
|OX App Suite 7.10.5, OX App Suite 7.10.6<br>macOS Big Sur 11, macOS Monterey 12, Intel- and Apple Silicon-based devices are both supported
|-
|OX Drive v2 for Apple iOS
|OX App Suite 7.10.5, OX App Suite 7.10.6<br>iOS / iPadOS 14 and above
|-
|OX Drive v3 for Apple iOS
|OX App Suite 7.10.6<br>iOS / iPadOS 14 and above
|-
|OX Drive for Android
|OX App Suite 7.10.5, OX App Suite 7.10.6<br>Smartphones and tablets running Android 7.0 (API level 24) and above.
|-
|}

== OX Sync App ==

{|border="2" rules="all" align="left">
|'''Requirement'''
|'''System / Platform / User Interface'''
|-
| 
| 
|-
|OX App Suite
|OX App Suite 7.10.5, OX App Suite 7.10.6
|-
|OX Sync App for Android
|Smartphone on Android 5.0 or later
|-
|}

== OX Guard ==

{|border="2" rules="all" align="left">
|'''Requirement'''
|'''System / Platform / User Interface'''
|-
| 
| 
|-
|OX App Suite
|OX Guard since v2.10.5: OX App Suite v7.10.5<br>OX Guard since v2.10.6: OX App Suite v7.10.6
|-
|Mobile Device and Tablet Support
|Apple iPhone on iOS 14 / iOS 15 / iPad OS: Safari (latest version & previous version)<br>Smartphone on Android 4.1 or later: Chrome (latest & previous version)<br>Apple iPad (all devices) on iOS 14 / iOS 15 / iPad OS: Safari Safari (latest version & previous version)<br>Tablets on Android 4.1 or later: Chrome (latest & previous version)
|-
|}

[[Category: OX7]]
[[Category: AppSuite]]

AppSuite:ClientIdentifiers

2022-02-11T10:51:15Z

WolfgangRosenauer:

= List of App Suite client identifiers =

The tables contain the existing client identifiers (user agents) which are also collected in the OX database as "last used" entries.

== Actively used ==

{|
|CALDAV
|CalDAV client access
|-
|CARDDAV
|CardDAV client access
|-
|open-xchange-appsuite
|OX App Suite web frontend
|-
|open-xchange-mobile-api-facade
|[[AppSuite:OX_Mail_App|OX Mail App]]
|-
|OpenXchange.Android.OXDrive
|OX Drive for Android
|-
|OpenXchange.HTTPClient.OXDrive
|OX Drive for Microsoft Windows
|-
|OXDrive
|OX Drive for Microsoft Windows (faulty recording)
|-
|OpenXchange.iosClient.OXDrive
|OX Drive for iOS (legacy)
|-
|iOS.Drive
|OX Drive for iOS (v3)
|-
|OSX.OXDrive
|OX Drive for MacOS
|-
|USM-EAS
|[[AppSuite:Connector_for_Business_Mobility_Installation_Guide|Connector for Business Mobility]]
|-
|WEBDAV_INFOSTORE
|WebDAV access to Drive
|}

== Obsolete ==

{|
|com.openexchange.ox.gui.dhtml
|Open-Xchange Server 6 web frontend
|-
|OpenXchange.HTTPClient.OXUploader
|[[AppSuite:OX_Outlook_Uploader|OX Uploader for Outlook]]
|-
|com.open-xchange.updater.olox1
|OX Connector for Outlook
|-
|com.open-xchange.updater.olox2
|OX Connector 2 for Outlook
|-
|open-xchange-mailapp
|Legacy OX Mail App (v1)
|-
|OpenXchange.HTTPClient.OXNotifier
|OX Notifier for Microsoft Windows
|-
|com.open-xchange.updater.OXNotifier
|
|-
|USM-JSON
|
|-
|OUTLOOK_UPDATER
|
|-
|com.openexchange.mobileapp
|
|-
|ox.mobileapp
|
|-
|DRIVE_UPDATER
|
|-
|WEBDAV_XML
|
|-
|OpenXchange.HTTPClient.OXAddIn
|
|-
|WEBDAV_VCARD
|
|}

AppSuite:OX System Requirements

2022-02-09T12:10:40Z

WolfgangRosenauer: /* Databases */

= OX App Suite Requirements - Open-Xchange supported components overview =

The following table provides an overview about the supported components of OX App Suite and further products. This overview makes no claim to be complete.

Information about Maintenance expiries of components, versions and browser support, can be found in the [[AppSuite:Versioning_and_Numbering#Maintenance_expires|Maintenance Expires Table]]

== Hardware Requirements ==

=== General Assumptions ===

Open-Xchange App Suite Server (middleware services) is designed to run on physical servers or virtual machines of the same flavor. Cloud environments might be used in terms of Infrastructure as a Service (IaaS), meaning that all components need to be deployed in a classical manner on virtual machines.

This means in particular, but not only:

* Infrastructure is supposed to be "quasi-static". Automatic replacement of broken nodes is fine as long as this is always an exceptional case. Scaling out or reducing number of nodes must always be a conscious task and closely monitored.
* The only supported "Database as a service" solution is AWS RDS for MariaDB as defined by belows compatibility table.

Especially we expect the virtual hardware to be not over-provisioned. Each VM must have dedicated resources with respect to CPU cores, RAM, IOPS, storage, network bandwidth, network latency, etc.

Network is expected to be flat, inside one datacenter, no multi-datacenter, no segments. No packet loss, low latency.

'''Disclaimer: All recommendations below are without guarantee and can differ for specific deployments. For mid- and large-scale setups a detailed deployment planning and sizing tests are mandatory and should be agreed on with OX Professional Services.'''

=== High Level Design / OS setup ===

Operate services separately (USM, Document/Image Converters) as described in [https://oxpedia.org/wiki/index.php?title=AppSuite:Running_a_cluster Cluster Setup].

Clocks between all nodes must be synchronized (e.g. via NTP).

Open file/max process limits need to be adjusted properly. Based on the used Linux distribution and init system configuration will differ, see Resource Limits for further explanation.

Platform Architecture: 64 bit versions (x84_64) of the supported [[#Software Requirements | Linux distributions]]

=== Node Sizing ===

==== OX App Suite Middleware ====

* Max. 8 GB heap per JVM + 4 GB system memory for other daemons and the OS (buffers, caches)
* 4 CPU cores (virtual, physical or hyperthreads) for plain HTTP connections. If TLS is terminated on application nodes this might need to be doubled.
* Disk space
** 8 GB for OS and software
** Some services like Document Converter need SWAP partitions (~1 * RAM)
** 2 * system memory of free disk space (i.e. 12 GB RAM => 24 GB free disk space) for file spooling, log files, heap and core dumps

=== Untested/Unsupported Deployments ===

* Changes to Garbage Collector settings
* Running in containerized environments (Docker, rkt)
* Elasticity/High velocity of nodes going up and down: Services are sometimes stateful and demand static configuration
* Cloud platform services (PaaS) that promise to replacements for certain supported technologies but have not been verified by OX for these regards
* Multi-site active-active

== Software Requirements ==

=== Linux Distributions ===

OX App Suite is available as Linux packages for the following distributions:

{|border="2" rules="all" align="left">
|'''Distribution'''
|'''Versions'''
|'''Remarks'''
|-
| 
| 
| 
|-
|Red Hat Enterprise Linux
|7
|
|-
|CentOS
|7
|Install from RHEL package repositories
|-
|Debian
|9 (Stretch), 10 (Buster)
|
|-
|Univention Corporate Server
|4.4, 5.0
|
|-
|Amazon Linux
|2
|Discontinued Support with end of life of OX App Suite v7.10.5
|-
|}

=== Java ===

OX App Suite Middleware requires OpenJDK headless JRE 8 or 9. Linux distributions might offer only packages for OpenJDK 11 JRE, which is not suitable for OX App Suite. It is in those cases required to install AdoptOpenJDK 8 JRE with HotSpot VM. A comprehensive installation guide can be found at https://adoptopenjdk.net/installation.html#linux-pkg. The correct JRE package is adoptopenjdk-8-hotspot-jre.

=== Databases ===

OX App Suite uses MySQL/MariaDB with the InnoDB storage engine as its primary data store. The following vendors and products are supported.

{|border="2" rules="all" align="left">
|'''Vendor'''
|'''Product'''
|'''Versions'''
|-
| 
| 
| 
|-
|Oracle
|MySQL Community Edition, Standard Edition, Enterprise Edition
|v5.6.x, v5.7.x
|-
|MariaDB
|MariaDB Server, Galera Cluster
|v10.1.x, v10.2.x, v10.4.x, v10.5.x.
|-
|Amazon
|AWS RDS for MariaDB
|10.2.x<br>Discontinued Support with end of life of OX App Suite v7.10.5
|-
|}

==== Important Notes ====

* Open-Xchange does not plan to support '''MySQL 8 or higher'''. As MariaDB and MySQL are diverging and cannot be assumed drop-in replacements anymore, Open-Xchange will focus on MariaDB Server and MariaDB Galera Cluster. Future App Suite releases '''> 7.10.x''' might rely on features only available in '''MariaDB'''.
* Open-Xchange supports '''Percona XtraDB Cluster''' for existing customers with initial deployments done using '''App Suite 7.8.x or earlier'''. Those customers can continue to use Percona XtraDB Cluster throughout the 7.10.x release series. Like for MySQL, 7.10.x supports only versions 5.6 and 5.7. It is not planned to support Percona XtraDB Cluster beyond 7.10.x.

* For some Linux distributions the included MySQL/MariaDB packages are too old to be used with App Suite. It is mandatory then to install a supported version from '''upstream package sources'''. Possible sources are the official vendor repositories of MySQL or MariaDB as well as for example Red Hat Software Collections.
* Required '''MySQL/MariaDB configuration''' configuration differs between '''App Suite 7.8.4 and 7.10.x''' and also between the different database systems in terms of SQL modes. See [[My.cnf]] for details.
* For upgrades from App Suite <= 7.8.2 to >= 7.10.0 a comprehensive '''database upgrade guide''' exists: [[AppSuite:7_10_Database_Migration]]

== HTTP Reverse Proxy ==

An HTTP server with reverse proxy and load balancing capabilities is required in front of App Suite application servers. TLS termination, virtual hosts, path-based routing, sticky sessions and X-Forwarded headers are typical required features. OX strongly recommends [https://httpd.apache.org/ Apache httpd 2.x] for that. Configuration examples can be found in the quickinstall guides.

'''Important:''' For websocket support Apache httpd 2.4.x is needed, 2.2.x does not support the required ws_tunnel module. Websockets are mandatory for OX Documents starting with v7.10.3. Like with JRE and MySQL/MariaDB it might be necessary to use 3rd party packages to get the needed Linux packages. Especially for RHEL6 we recommend using Red Hat Software Collections.

== Webserver ==

[https://httpd.apache.org/ Apache httpd 2.x] is required as webserver to serve static App Suite UI content. Configuration examples can be found in the quickinstall guides.

== File Storage ==

=== Temporary Data ===

OX App Suite stores temporary files in the local file system, e.g. for spooling of uploaded data. Any file system supported by the installed JRE is suitable.

=== Persistent Data ===

Persistent data like OX Drive files, PIM attachments etc. and temporary attachment data need to be stored in a distributed file system as registered filestore that is available from all server nodes. For single-node setups a local file system mount point can be used, small to mid-scale setups can be powered by NFS. For large-scale setups object storages should be considered.

==== Object Storages ====

OX App Suite ships with different optional adapters to support object storages.

{|border="2" rules="all" align="left">
|'''Vendor'''
|'''Product'''
|'''API'''
|'''Remarks'''
|-
| 
| 
| 
| 
|-
|Amazon
|AWS S3
|S3 HTTP API
|See also [[AppSuite:S3_File_Store]]
|-
|CEPH
|RadosGW
|S3 HTTP API
|See also [[AppSuite:S3_File_Store]]
|-
|Scality
|Scality RING
|Sproxyd HTTP API
|See also [[AppSuite:Scality_File_Store]]
|-
|}

== Desktop Browser (Minimum display resolution: 1024 x 768)==

{|border="2" rules="all" align="left">
|'''Browser'''
|'''OX App Suite User Front-End'''
|-
| 
| 
|-
|Google Chrome (latest & previous version)
|v7.10.5, v7.10.6
|-
|Mozilla Firefox (latest & current ESR-Version)
|v7.10.5, v7.10.6
|-
|Apple Safari (latest & previous version; macOS only)
|v7.10.5, v7.10.6
|-
|Microsoft Edge (Chromium-based)
|v7.10.5, v7.10.6
|-
|Microsoft Internet Explorer 10/11
|v7.6.3
|-
|}

== Mobile Device Support==

{|border="2" rules="all" align="left">
|'''Mobile Device'''
|'''Supported Browser'''
|'''OX App Suite User Front-End'''
|'''Minimum Speed Requirements'''
|-
| 
| 
| 
| 
|-
|iPhone on iOS 14 / iOS 15 / iPad OS
|Safari
|v7.10.5, v7.10.6
|3G connections (512/256kBit/s, 350ms latency)
|-
|Smartphone on Android 4.1 or later
|Chrome (latest & previous version)
|v7.10.5, v7.10.6
|3G connections (512/256kBit/s, 350ms latency)
|}

== Tablet Support==

{|border="2" rules="all" align="left">
|'''Tablet'''
|'''Supported Browser'''
|'''OX App Suite User Front-End'''
|'''Minimum Speed Requirements'''
|-
| 
| 
| 
| 
|-
|Apple iPad (all devices) on iOS 14 / iOS 15 / iPad OS
|Safari
|v7.10.5, v7.10.6
|3G connections (512/256kBit/s, 350ms latency)
|-
|Tablets on Android 4.1 or later
|Chrome (latest & previous version)
|v7.10.5, v7.10.6
|3G connections (512/256kBit/s, 350ms latency)
|}

== Calendar/Contact synchronization Apple macOS ==

{|border="2" rules="all" align="left">
|'''Requirement'''
|Calendar synchronization with CalDAV
|Contacts synchronization with CardDAV
|-
| 
| 
| 
|-
|macOS 11.0 (Big Sur)
|[[File:check.gif]]
|[[File:check.gif]]
|-
|macOS 12.0 (Monterey)
|[[File:check.gif]]
|[[File:check.gif]]
|-
|}

== Calendar/Contact synchronization Apple iOS ==

{|border="2" rules="all" align="left">
|'''Requirement'''
|Calendar synchronization with CalDAV
|Contacts synchronization with CardDAV
|-
| 
| 
| 
|-
|Apple iOS 14 / iOS 15 / iPad OS
|[[File:check.gif]]
|[[File:check.gif]]
|-
|}

== Mobility Solution - Supported- Platforms, Features and Devices ==

{|border="2" rules="all" align="left">
|'''Feature/Technology/Device'''
|[http://oxpedia.org/wiki/index.php?title=OXtender_for_Business_Mobility '''OXtender for Business Mobility'''] (availalble for App Suite, OXHE, OXSE)
|-
| 
| 
|-
|Exchange Active Sync 2.5
|[[File:check.gif]]
|-
|Exchange Active Sync 12.1
|[[File:check.gif]]
|-
| 
| 
|-
|Access and creation of emails
|[[File:check.gif]]
|-
|Personal PIM folder
|[[File:check.gif]]
|-
|Public and Shared PIM folder
|[[File:cross.gif]]
|-
|Global address book
|[[File:check.gif]]
|-
|Push E-Mail
|[[File:check.gif]]
|-
| 
| 
|-
|Apple iOS 14 / iOS 15 / iPad OS
|[[File:check.gif]]
|-
|Android 8 (Oreo) or later with latest Gmail app.
|[[File:check.gif]]
|-
|}

== OX Drive Clients ==

{|border="2" rules="all" align="left">
|'''Requirement'''
|'''System / Platform'''
|-
| 
| 
|-
|OX Drive for Windows
|OX App Suite 7.10.5, OX App Suite 7.10.6<br>Latest versions of Windows 10 (no support of macOS clients with emulators and Windows RT)
|-
|OX Drive for Apple macOS
|OX App Suite 7.10.5, OX App Suite 7.10.6<br>macOS Big Sur 11, macOS Monterey 12, Intel- and Apple Silicon-based devices are both supported
|-
|OX Drive v2 for Apple iOS
|OX App Suite 7.10.5, OX App Suite 7.10.6<br>iOS / iPadOS 14 and above
|-
|OX Drive v3 for Apple iOS
|OX App Suite 7.10.6<br>iOS / iPadOS 14 and above
|-
|OX Drive for Android
|OX App Suite 7.10.5, OX App Suite 7.10.6<br>Smartphones and tablets running Android 7.0 (API level 24) and above.
|-
|}

== OX Sync App ==

{|border="2" rules="all" align="left">
|'''Requirement'''
|'''System / Platform / User Interface'''
|-
| 
| 
|-
|OX App Suite
|OX App Suite 7.10.5, OX App Suite 7.10.6
|-
|OX Sync App for Android
|Smartphone on Android 5.0 or later
|-
|}

== OX Guard ==

{|border="2" rules="all" align="left">
|'''Requirement'''
|'''System / Platform / User Interface'''
|-
| 
| 
|-
|OX App Suite
|OX Guard since v2.10.5: OX App Suite v7.10.5<br>OX Guard since v2.10.6: OX App Suite v7.10.6
|-
|Mobile Device and Tablet Support
|Apple iPhone on iOS 14 / iOS 15 / iPad OS: Safari (latest version & previous version)<br>Smartphone on Android 4.1 or later: Chrome (latest & previous version)<br>Apple iPad (all devices) on iOS 14 / iOS 15 / iPad OS: Safari Safari (latest version & previous version)<br>Tablets on Android 4.1 or later: Chrome (latest & previous version)
|-
|}

[[Category: OX7]]
[[Category: AppSuite]]

AppSuite:ClientIdentifiers

2022-02-08T14:53:05Z

WolfgangRosenauer:

= List of App Suite client identifiers =

The tables contain the existing client identifiers (user agents) which are also collected in the OX database as "last used" entries.

== Actively used ==

{|
|CALDAV
|CalDAV client access
|-
|CARDDAV
|CardDAV client access
|-
|open-xchange-appsuite
|OX App Suite web frontend
|-
|open-xchange-mobile-api-facade
|[[AppSuite:OX_Mail_App|OX Mail App]]
|-
|OpenXchange.Android.OXDrive
|OX Drive for Android
|-
|OpenXchange.HTTPClient.OXDrive
|OX Drive for Microsoft Windows
|-
|OpenXchange.iosClient.OXDrive
|OX Drive for iOS (legacy)
|-
|iOS.Drive
|OX Drive for iOS (v3)
|-
|OSX.OXDrive
|OX Drive for MacOS
|-
|OXDrive
|
|-
|USM-EAS
|[[AppSuite:Connector_for_Business_Mobility_Installation_Guide|Connector for Business Mobility]]
|-
|WEBDAV_INFOSTORE
|WebDAV access to Drive
|}

== Obsolete ==

{|
|com.openexchange.ox.gui.dhtml
|Open-Xchange Server 6 web frontend
|-
|OpenXchange.HTTPClient.OXUploader
|[[AppSuite:OX_Outlook_Uploader|OX Uploader for Outlook]]
|-
|com.open-xchange.updater.olox1
|OX Connector for Outlook
|-
|com.open-xchange.updater.olox2
|OX Connector 2 for Outlook
|-
|open-xchange-mailapp
|Legacy OX Mail App (v1)
|-
|OpenXchange.HTTPClient.OXNotifier
|OX Notifier for Microsoft Windows
|-
|com.open-xchange.updater.OXNotifier
|
|-
|USM-JSON
|
|-
|OUTLOOK_UPDATER
|
|-
|com.openexchange.mobileapp
|
|-
|ox.mobileapp
|
|-
|DRIVE_UPDATER
|
|-
|WEBDAV_XML
|
|-
|OpenXchange.HTTPClient.OXAddIn
|
|-
|WEBDAV_VCARD
|
|}

AppSuite:ClientIdentifiers

2022-02-08T14:52:48Z

WolfgangRosenauer:

= List of App Suite client identifiers =

----
<pre style="color: red">This page is under construction!</pre>
----

The tables contain the existing client identifiers (user agents) which are also collected in the OX database as "last used" entries.

== Actively used ==

{|
|CALDAV
|CalDAV client access
|-
|CARDDAV
|CardDAV client access
|-
|open-xchange-appsuite
|OX App Suite web frontend
|-
|open-xchange-mobile-api-facade
|[[AppSuite:OX_Mail_App|OX Mail App]]
|-
|OpenXchange.Android.OXDrive
|OX Drive for Android
|-
|OpenXchange.HTTPClient.OXDrive
|OX Drive for Microsoft Windows
|-
|OpenXchange.iosClient.OXDrive
|OX Drive for iOS (legacy)
|-
|iOS.Drive
|OX Drive for iOS (v3)
|-
|OSX.OXDrive
|OX Drive for MacOS
|-
|OXDrive
|
|-
|USM-EAS
|[[AppSuite:Connector_for_Business_Mobility_Installation_Guide|Connector for Business Mobility]]
|-
|WEBDAV_INFOSTORE
|WebDAV access to Drive
|}

== Obsolete ==

{|
|com.openexchange.ox.gui.dhtml
|Open-Xchange Server 6 web frontend
|-
|OpenXchange.HTTPClient.OXUploader
|[[AppSuite:OX_Outlook_Uploader|OX Uploader for Outlook]]
|-
|com.open-xchange.updater.olox1
|OX Connector for Outlook
|-
|com.open-xchange.updater.olox2
|OX Connector 2 for Outlook
|-
|open-xchange-mailapp
|Legacy OX Mail App (v1)
|-
|OpenXchange.HTTPClient.OXNotifier
|OX Notifier for Microsoft Windows
|-
|com.open-xchange.updater.OXNotifier
|
|-
|USM-JSON
|
|-
|OUTLOOK_UPDATER
|
|-
|com.openexchange.mobileapp
|
|-
|ox.mobileapp
|
|-
|DRIVE_UPDATER
|
|-
|WEBDAV_XML
|
|-
|OpenXchange.HTTPClient.OXAddIn
|
|-
|WEBDAV_VCARD
|
|}

AppSuite:ClientIdentifiers

2022-02-08T14:52:16Z

WolfgangRosenauer:

= List of App Suite client identifiers =

----
<pre style="color: red">This page is under construction!</pre>
----

The tables contain the existing client identifiers (user agents) which are also collected in the OX database as "last used" entries.

== Actively used ==

{|
|CALDAV
|CalDAV client access
|-
|CARDDAV
|CardDAV client access
|-
|open-xchange-appsuite
|OX App Suite web frontend
|-
|open-xchange-mobile-api-facade
|[[AppSuite:OX_Mail_App|OX Mail App]]
|-
|OpenXchange.Android.OXDrive
|OX Drive for Android
|-
|OpenXchange.HTTPClient.OXDrive
|OX Drive for Microsoft Windows
|-
|OpenXchange.iosClient.OXDrive
|OX Drive for iOS (legacy)
|-
|iOS.Drive
|OX Drive for iOS (v3)
|-
|OSX.OXDrive
|OX Drive for MacOS
|-
|OXDrive
|
|-
|USM-EAS
|[[AppSuite:Connector_for_Business_Mobility_Installation_Guide|Connector for Business Mobility]]
|-
|WEBDAV_INFOSTORE
|WebDAV access to Drive
|-
|OpenXchange.HTTPClient.OXUploader
|[[AppSuite:OX_Outlook_Uploader|OX Uploader for Outlook]]
|}

== Obsolete ==

{|
|com.openexchange.ox.gui.dhtml
|Open-Xchange Server 6 web frontend
|-
|com.open-xchange.updater.olox1
|OX Connector for Outlook
|-
|com.open-xchange.updater.olox2
|OX Connector 2 for Outlook
|-
|open-xchange-mailapp
|Legacy OX Mail App (v1)
|-
|OpenXchange.HTTPClient.OXNotifier
|OX Notifier for Microsoft Windows
|-
|com.open-xchange.updater.OXNotifier
|
|-
|USM-JSON
|
|-
|OUTLOOK_UPDATER
|
|-
|com.openexchange.mobileapp
|
|-
|ox.mobileapp
|
|-
|DRIVE_UPDATER
|
|-
|WEBDAV_XML
|
|-
|OpenXchange.HTTPClient.OXAddIn
|
|-
|WEBDAV_VCARD
|
|}

AppSuite:ClientIdentifiers

2022-01-25T15:49:15Z

WolfgangRosenauer:

= List of App Suite client identifiers =

----
<pre style="color: red">This page is under construction!</pre>
----

The tables contain the existing client identifiers (user agents) which are also collected in the OX database as "last used" entries.

== Actively used ==

{|
|CALDAV
|CalDAV client access
|-
|CARDDAV
|CardDAV client access
|-
|open-xchange-appsuite
|OX App Suite web frontend
|-
|open-xchange-mobile-api-facade
|[[AppSuite:OX_Mail_App|OX Mail App]]
|-
|OpenXchange.Android.OXDrive
|OX Drive for Android
|-
|OpenXchange.HTTPClient.OXDrive
|OX Drive for Microsoft Windows
|-
|OpenXchange.iosClient.OXDrive
|OX Drive for iOS (legacy)
|-
|iOS.Drive
|OX Drive for iOS (v3)
|-
|OSX.OXDrive
|OX Drive for MacOS
|-
|OXDrive
|
|-
|USM-EAS
|[[AppSuite:Connector_for_Business_Mobility_Installation_Guide|Connector for Business Mobility]]
|-
|WEBDAV_INFOSTORE
|WebDAV access to Drive
|-
|WEBDAV_VCARD
|
|-
|OpenXchange.HTTPClient.OXUploader
|[[AppSuite:OX_Outlook_Uploader|OX Uploader for Outlook]]
|}

== Obsolete ==

{|
|com.openexchange.ox.gui.dhtml
|Open-Xchange Server 6 web frontend
|-
|com.open-xchange.updater.olox1
|OX Connector for Outlook
|-
|com.open-xchange.updater.olox2
|OX Connector 2 for Outlook
|-
|open-xchange-mailapp
|Legacy OX Mail App (v1)
|-
|OpenXchange.HTTPClient.OXNotifier
|OX Notifier for Microsoft Windows
|-
|com.open-xchange.updater.OXNotifier
|
|-
|USM-JSON
|
|-
|OUTLOOK_UPDATER
|
|-
|com.openexchange.mobileapp
|
|-
|ox.mobileapp
|
|-
|DRIVE_UPDATER
|
|-
|WEBDAV_XML
|
|-
|OpenXchange.HTTPClient.OXAddIn
|
|}

AppSuite:ClientIdentifiers

2022-01-25T15:48:02Z

WolfgangRosenauer:

= List of App Suite client identifiers =

----
<pre style="color: red">This page is under construction!</pre>
----

The tables contain the existing client identifiers (user agents) which are also collected in the OX database as "last used" entries.

== Actively used ==

{|
|CALDAV
|CalDAV client access
|-
|CARDDAV
|CardDAV client access
|-
|open-xchange-appsuite
|OX App Suite web frontend
|-
|open-xchange-mobile-api-facade
|[[AppSuite:OX_Mail_App|OX Mail App]]
|-
|OpenXchange.Android.OXDrive
|OX Drive for Android
|-
|OpenXchange.HTTPClient.OXDrive
|OX Drive for Microsoft Windows
|-
|OpenXchange.HTTPClient.OXUploader
|[[AppSuite:OX_Outlook_Uploader|OX Uploader for Outlook]]
|-
|OpenXchange.iosClient.OXDrive
|OX Drive for iOS (legacy)
|-
|iOS.Drive
|OX Drive for iOS (v3)
|-
|OSX.OXDrive
|OX Drive for MacOS
|-
|OXDrive
|
|-
|USM-EAS
|[[AppSuite:Connector_for_Business_Mobility_Installation_Guide|Connector for Business Mobility]]
|-
|WEBDAV_INFOSTORE
|WebDAV access to Drive
|-
|WEBDAV_VCARD
|
|}

== Obsolete ==

{|
|com.openexchange.ox.gui.dhtml
|Open-Xchange Server 6 web frontend
|-
|com.open-xchange.updater.olox1
|OX Connector for Outlook
|-
|com.open-xchange.updater.olox2
|OX Connector 2 for Outlook
|-
|open-xchange-mailapp
|Legacy OX Mail App (v1)
|-
|OpenXchange.HTTPClient.OXNotifier
|OX Notifier for Microsoft Windows
|-
|com.open-xchange.updater.OXNotifier
|
|-
|USM-JSON
|
|-
|OUTLOOK_UPDATER
|
|-
|com.openexchange.mobileapp
|
|-
|ox.mobileapp
|
|-
|DRIVE_UPDATER
|
|-
|WEBDAV_XML
|
|-
|OpenXchange.HTTPClient.OXAddIn
|
|}

AppSuite:ClientIdentifiers

2022-01-25T15:36:04Z

WolfgangRosenauer:

= List of App Suite client identifiers =

----
<pre style="color: red">This page is under construction!</pre>
----

The tables contain the existing client identifiers (user agents) which are also collected in the OX database as "last used" entries.

== Actively used ==

{|
|CALDAV
|CalDAV client access
|-
|CARDDAV
|CardDAV client access
|-
|open-xchange-appsuite
|OX App Suite web frontend
|-
|open-xchange-mobile-api-facade
|[[AppSuite:OX_Mail_App|OX Mail App]]
|-
|OpenXchange.Android.OXDrive
|OX Drive for Android
|-
|OpenXchange.HTTPClient.OXAddIn
|
|-
|OpenXchange.HTTPClient.OXDrive
|
|-
|OpenXchange.HTTPClient.OXUploader
|[[AppSuite:OX_Outlook_Uploader|OX Uploader for Outlook]]
|-
|OpenXchange.iosClient.OXDrive
|OX Drive for iOS
|-
|OSX.OXDrive
|OX Drive for MacOS
|-
|OXDrive
|
|-
|USM-EAS
|[[AppSuite:Connector_for_Business_Mobility_Installation_Guide|Connector for Business Mobility]]
|-
|WEBDAV_INFOSTORE
|WebDAV access to Drive
|-
|WEBDAV_VCARD
|
|}

== Obsolete ==

{|
|com.openexchange.ox.gui.dhtml
|Open-Xchange Server 6 web frontend
|-
|com.open-xchange.updater.olox1
|OX Connector for Outlook
|-
|com.open-xchange.updater.olox2
|OX Connector 2 for Outlook
|-
|open-xchange-mailapp
|Legacy OX Mail App (v1)
|-
|OpenXchange.HTTPClient.OXNotifier
|OX Notifier for Microsoft Windows
|-
|com.open-xchange.updater.OXNotifier
|
|-
|USM-JSON
|
|-
|OUTLOOK_UPDATER
|
|-
|com.openexchange.mobileapp
|
|-
|ox.mobileapp
|
|-
|DRIVE_UPDATER
|
|-
|WEBDAV_XML
|
|}

AppSuite:ClientIdentifiers

2022-01-25T13:46:08Z

WolfgangRosenauer:

= List of App Suite client identifiers =

----
<pre style="color: red">This page is under construction!</pre>
----

The tables contain the existing client identifiers (user agents) which are also collected in the OX database as "last used" entries.

== Actively used ==

{|
|CALDAV
|
|-
|CARDDAV
|
|-
|DRIVE_UPDATER
|
|-
|open-xchange-appsuite
|OX App Suite web frontend
|-
|open-xchange-mobile-api-facade
|[[AppSuite:OX_Mail_App|OX Mail App]]
|-
|OpenXchange.Android.OXDrive
|
|-
|OpenXchange.HTTPClient.OXAddIn
|
|-
|OpenXchange.HTTPClient.OXDrive
|
|-
|OpenXchange.HTTPClient.OXUploader
|[[AppSuite:OX_Outlook_Uploader|OX Uploader for Outlook]]
|-
|OpenXchange.iosClient.OXDrive
|
|-
|OSX.OXDrive
|
|-
|OXDrive
|
|-
|USM-EAS
|[[AppSuite:Connector_for_Business_Mobility_Installation_Guide|Connector for Business Mobility]]
|-
|WEBDAV_INFOSTORE
|
|-
|WEBDAV_VCARD
|
|-
|WEBDAV_XML
|
|}

== Obsolete ==

{|
|com.openexchange.ox.gui.dhtml
|Open-Xchange Server 6 web frontend
|-
|com.open-xchange.updater.olox1
|OX Connector for Outlook
|-
|com.open-xchange.updater.olox2
|OX Connector 2 for Outlook
|-
|open-xchange-mailapp
|Legacy OX Mail App (v1)
|-
|OpenXchange.HTTPClient.OXNotifier
|OX Notifier for Microsoft Windows
|-
|com.open-xchange.updater.OXNotifier
|
|-
|USM-JSON
|
|-
|OUTLOOK_UPDATER
|
|-
|com.openexchange.mobileapp
|
|-
|ox.mobileapp
|
|}

AppSuite:ClientIdentifiers

2022-01-25T08:31:11Z

WolfgangRosenauer:

= List of App Suite client identifiers =

----
<pre style="color: red">This page is under construction!</pre>
----

The tables contain the existing client identifiers (user agents) which are also collected in the OX database as "last used" entries.

== Actively used ==

{|
|CALDAV
|
|-
|CARDDAV
|
|-
|DRIVE_UPDATER
|
|-
|open-xchange-appsuite
|OX App Suite web frontend
|-
|open-xchange-mobile-api-facade
|[[AppSuite:OX_Mail_App|OX Mail App]]
|-
|OpenXchange.Android.OXDrive
|
|-
|OpenXchange.HTTPClient.OXAddIn
|
|-
|OpenXchange.HTTPClient.OXDrive
|
|-
|OpenXchange.HTTPClient.OXUploader
|[[AppSuite:OX_Outlook_Uploader|OX Uploader for Outlook]]
|-
|OpenXchange.iosClient.OXDrive
|
|-
|OSX.OXDrive
|
|-
|OXDrive
|
|-
|USM-EAS
|
|-
|WEBDAV_INFOSTORE
|
|-
|WEBDAV_VCARD
|
|-
|WEBDAV_XML
|
|}

== Obsolete ==

{|
|com.openexchange.ox.gui.dhtml
|Open-Xchange Server 6 web frontend
|-
|com.open-xchange.updater.olox1
|OX Connector for Outlook
|-
|com.open-xchange.updater.olox2
|OX Connector 2 for Outlook
|-
|open-xchange-mailapp
|Legacy OX Mail App (v1)
|-
|OpenXchange.HTTPClient.OXNotifier
|OX Notifier for Microsoft Windows
|-
|com.open-xchange.updater.OXNotifier
|
|-
|USM-JSON
|
|-
|OUTLOOK_UPDATER
|
|}

AppSuite:ClientIdentifiers

2022-01-25T08:30:01Z

WolfgangRosenauer:

= List of App Suite client identifiers =

----
<pre style="color: red">This page is under construction!</pre>
----

== Actively used ==

{|
|CALDAV
|
|-
|CARDDAV
|
|-
|DRIVE_UPDATER
|
|-
|open-xchange-appsuite
|OX App Suite web frontend
|-
|open-xchange-mobile-api-facade
|[[AppSuite:OX_Mail_App|OX Mail App]]
|-
|OpenXchange.Android.OXDrive
|
|-
|OpenXchange.HTTPClient.OXAddIn
|
|-
|OpenXchange.HTTPClient.OXDrive
|
|-
|OpenXchange.HTTPClient.OXUploader
|[[AppSuite:OX_Outlook_Uploader|OX Uploader for Outlook]]
|-
|OpenXchange.iosClient.OXDrive
|
|-
|OSX.OXDrive
|
|-
|OXDrive
|
|-
|USM-EAS
|
|-
|WEBDAV_INFOSTORE
|
|-
|WEBDAV_VCARD
|
|-
|WEBDAV_XML
|
|}

== Obsolete ==

{|
|com.openexchange.ox.gui.dhtml
|Open-Xchange Server 6 web frontend
|-
|com.open-xchange.updater.olox1
|OX Connector for Outlook
|-
|com.open-xchange.updater.olox2
|OX Connector 2 for Outlook
|-
|open-xchange-mailapp
|Legacy OX Mail App (v1)
|-
|OpenXchange.HTTPClient.OXNotifier
|OX Notifier for Microsoft Windows
|-
|com.open-xchange.updater.OXNotifier
|
|-
|USM-JSON
|
|-
|OUTLOOK_UPDATER
|
|}

AppSuite:ClientIdentifiers

2022-01-25T08:28:38Z

WolfgangRosenauer: Created page with "= List of App Suite client identifiers = ---- <pre style="color: red">This page is under construction!</pre> ---- == Actively used == {| |CALDAV | |- |CARDDAV | |- |DRIVE_U..."

= List of App Suite client identifiers =

----
<pre style="color: red">This page is under construction!</pre>
----

== Actively used ==

{|
|CALDAV
|
|-
|CARDDAV
|
|-
|DRIVE_UPDATER
|
|-
|open-xchange-appsuite
|OX App Suite web frontend
|-
|open-xchange-mobile-api-facade
|[[AppSuite:OX_Mail_App|OX Mail App]]
|-
|OpenXchange.Android.OXDrive
|
|-
|OpenXchange.HTTPClient.OXAddIn
|
|-
|OpenXchange.HTTPClient.OXDrive
|
|-
|OpenXchange.HTTPClient.OXUploader
|[[AppSuite:OX_Outlook_Uploader|OX Uploader for Outlook]]
|-
|OpenXchange.iosClient.OXDrive
|
|-
|OSX.OXDrive
|
|-
|OUTLOOK_UPDATER
|
|-
|OXDrive
|
|-
|USM-EAS
|
|-
|WEBDAV_INFOSTORE
|
|-
|WEBDAV_VCARD
|
|-
|WEBDAV_XML
|
|}

== Obsolete ==

{|
|com.openexchange.ox.gui.dhtml
|Open-Xchange Server 6 web frontend
|-
|com.open-xchange.updater.olox1
|OX Connector for Outlook
|-
|com.open-xchange.updater.olox2
|OX Connector 2 for Outlook
|-
|open-xchange-mailapp
|Legacy OX Mail App (v1)
|-
|OpenXchange.HTTPClient.OXNotifier
|OX Notifier for Microsoft Windows
|-
|com.open-xchange.updater.OXNotifier
|
|-
|USM-JSON
|
|}

AppSuite:S3 File Store

2021-06-09T08:03:46Z

WolfgangRosenauer: /* Overview */

__TOC__

= Overview =

Besides ordinary local- or NFS-filesystem-based filestores, OX may also be used with a cloud storage solution offering an S3 interface. The required functionality is added with the package ''open-xchange-filestore-s3''. The filestore integration was tested against the regular Amazon Simple Storage Service (S3), however, other object storage implementation offering an S3-compatible API should work, too. The list of officially supported S3 storages can be found on the [https://oxpedia.org/wiki/index.php?title=AppSuite:OX_System_Requirements#File_Storage system requirements page].

= Installation & Configuration =

This chapter shows which components need to be installed and where configuration is done.

{{InstallPlugin | pluginname=open-xchange-filestore-s3 | toplevel=products | sopath=appsuite/stable/backend | version=App Suite}}

== Configuration ==

S3 filestores can be configured in the configuration file ''filestore-s3.properties'' once they have been registered on the server with the ''registerfilestore'' command.

=== Register an S3 filestore ===

Similarly to local- or NFS-filesystem-based filestores, S3 filestore need to be registered using the commandline tool ''registerfilestore'' before they can be used. The ''scheme''-part of the filestore URI must be set to ''s3'' in this case. Besides the common ''s3://'' prefix of such filestore URIs, the remaining authority component of the URI specifies an identifier of the filestore that will be used to refer to this filestore registration in the configuration file. It's recommended to use the bucket name here, for example:

root@ox01:/opt/open-xchange/sbin# ./registerfilestore -A oxadminmaster -P secret -t s3://ox-filestore-s3 -s 1048576000 -x 5000
filestore 7433 registered

=== Configure the filestore ===

Additional configuration for each registered filestore is done in the configuration file ''filestore-s3.properties''. To map configuration properties to specific filestore registrations, the filestore identifier corresponding to the defined authority part of the filestore URI is used in the property names. Please refer to the inline documentation or the examples below for details.

Note: In most cases, you want to use the same configuration throughout the whole ox cluster, so you should make sure to use the same ''filestore-s3.properties'' configuration file on all nodes.

= Step-by-step guide to setup an AWS S3 storage =

The following walktrhorugh outlines all steps necessary to complete the setup of a S3 filestore running on the regular Amazon Simple Storage Service (S3).

== Prerequisites ==
* Installed ''open-xchange-filestore-s3'' package
* A valid account for Amazon S3
* AWS access key, e.g. ''AKIAIOSFODNN7EXAMPLE''
* AWS secret key, e.g. ''wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY''

== Create a bucket ==
* Login to the S3 Management Console at https://console.aws.amazon.com/s3/
* Click the ''Create Bucket'' button
* Select a bucket name of your choice, e.g. ''ox-filestore-s3''
* Select the region according to your needs, e.g. ''EU (Ireland)''
* Click ''Create''

== Register the filestore ==
* Open a terminal on a running backend server of your OX cluster
* Navigate to the directory where the commandline utilities are installed, usually at ''/opt/open-xchange/sbin''
* Run the ''registerfilestore'' tool using a storepath URL starting with the ''s3'' scheme (use ''s3://'' as prefix literally) followed by the filestore ID (the bucket name seems most appropriate here, however, you can still use a different name), e.g.:
./registerfilestore -A oxadminmaster -P secret -t s3://ox-filestore-s3 -s 1048576000 -x 5000''
(execute "./registerfilestore -h" for more information regarding possible commandline arguments)
* The internal ID of the new filestore is printed out

== Configure the filestore ==
* Open the configuration file ''filestore-s3.properties'' in your favourite editor
* Insert a new set of properties using the filestore ID assigned during registration of the filestore in the previous step, e.g. ''ox-filestore-s3'':
com.openexchange.filestore.s3.ox-filestore-s3.endpoint=
com.openexchange.filestore.s3.ox-filestore-s3.bucketName=
com.openexchange.filestore.s3.ox-filestore-s3.region=
com.openexchange.filestore.s3.ox-filestore-s3.pathStyleAccess=
com.openexchange.filestore.s3.ox-filestore-s3.accessKey=
com.openexchange.filestore.s3.ox-filestore-s3.secretKey=
com.openexchange.filestore.s3.ox-filestore-s3.encryption=
com.openexchange.filestore.s3.ox-filestore-s3.signerOverride=
com.openexchange.filestore.s3.ox-filestore-s3.chunkSize=
* Specify the endpoint to use depending on the chosen region (see http://docs.aws.amazon.com/general/latest/gr/rande.html#s3_region for a list of endpoints), e.g.:
com.openexchange.filestore.s3.ox-filestore-s3.endpoint=https://s3-eu-west-1.amazonaws.com
* Set the bucket name for the filestore, e.g.:
com.openexchange.filestore.s3.ox-filestore-s3.bucketName=ox-filestore-s3
* Define the location constraint according to the chosen region - valid values are listed in the comments of the properties file - e.g.:
com.openexchange.filestore.s3.ox-filestore-s3.region=eu-west-1
* Configure path style / virtual host access (recommended to set to ''false'' for Amazon S3, must be ''false'' when using the default endpoint ''s3.amazonaws.com'' and a different region than US), see http://docs.aws.amazon.com/AmazonS3/latest/dev/VirtualHosting.html for details):
com.openexchange.filestore.s3.ox-filestore-s3.pathStyleAccess=false
* Specify your API access and secret keys, e.g.:
com.openexchange.filestore.s3.ox-filestore-s3.accessKey=AKIAIOSFODNN7EXAMPLE
com.openexchange.filestore.s3.ox-filestore-s3.secretKey=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
* Configure encryption as needed (''none'' in this example):
com.openexchange.filestore.s3.ox-filestore-s3.encryption=none
* Specify the signing algorithm if applicable. Please mind that this setting needs to be adjusted to "AWSS3V4SignerType" when targeting the newer "v4-only" regions like Frankfurt or Beijing.
com.openexchange.filestore.s3.ox-filestore-s3.encryption=S3SignerType
* Optionally override the default minimum chunk size to use when doing multipart uploads.
com.openexchange.filestore.s3.ox-filestore-s3.chunkSize=5MB

== Create contexts using the filestore ==
* New contexts that should use the configured filestore can be created by suppliying the ID of the registered filestore in the ''createcontext'' commandline tool. Use the internal ID returned by the previously used ''registerfilestore'' command executed above, e.g., assuming the ID returned from the ''registerfilestore'' command was ''6'':
./createcontext -A oxadminmaster -P secret -u oxadmin -d "Context Admin" -g Admin -s User -p secret -e oxadmin@example.com -q 1000 -L example.com --access-combination-name=all -F 6

== Check the configuration ==
* Login to the App Suite webinterface with a user from a context using the S3 filestore
* Upload a new file in the ''Drive'' module and download it again to verify basic functionality
* Check the S3 management console to verify the creation of the new file; here, the file should show up under a virtual prefix based on the parent context

[[Category: AppSuite]] [[Category: Administration]] [[Category: Cluster]]

Caldav carddav Bundles

2021-03-10T16:49:10Z

WolfgangRosenauer: /* Alternative 2: Apache useragent detection */

This article is valid until the version 7.10.2 of the Open Xchange Server. For newer versions please visit https://documentation.open-xchange.com/latest/middleware/miscellaneous/caldav_carddav.html

= 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 Calendar and Address Book clients.

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 Mac OS X 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 your existing <code>VirtualHost</code> entry. This is an <b>example</b> where <code>MYSERVER.TLD</code> is the domain-name of the ox-server:

# NameVirtualHost directive no longer has any effect since Apache >=2.4
# uncomment only for Apache Versions <2.4
#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>

ProxyPass / balancer://oxserver-sync/servlet/dav/

</VirtualHost>

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

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} Reminders [OR]
RewriteCond %{HTTP_USER_AGENT} DataAccess [OR]
RewriteCond %{HTTP_USER_AGENT} DAVKit [OR]
RewriteCond %{HTTP_USER_AGENT} DAVx5 [OR]
RewriteCond %{HTTP_USER_AGENT} OpenSync [OR]
RewriteCond %{HTTP_USER_AGENT} "DAVdroid" [OR]
RewriteCond %{HTTP_USER_AGENT} Lightning [OR]
RewriteCond %{HTTP_USER_AGENT} Thunderbird [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\ Book [OR]
RewriteCond %{HTTP_USER_AGENT} CalendarStore [OR]
RewriteCond %{HTTP_USER_AGENT} CalendarAgent [OR]
RewriteCond %{HTTP_USER_AGENT} CalDAV%20Sync%20Adapter [OR]
RewriteCond %{HTTP_USER_AGENT} CalDavSynchronizer [OR]
RewriteCond %{HTTP_USER_AGENT} accountsd [OR]
RewriteCond %{HTTP_USER_AGENT} "eM Client" [OR]
RewriteCond %{HTTP_USER_AGENT} "OX Sync" [OR]
RewriteCond %{HTTP_USER_AGENT} CalDav [OR]
RewriteCond %{HTTP_USER_AGENT} CoreDAV [OR]
RewriteCond %{HTTP_USER_AGENT} remindd
RewriteCond %{HTTP_USER_AGENT} "!Open-Xchange Calendar Feed Client"
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.

'''Note:''' Depending on the specific configuration, such a global definition of the rewrite rules might not be appropriate. However, the rules may also be defined inside a <code>Directory</code> context. More details are available at http://httpd.apache.org/docs/current/mod/mod_rewrite.html#rewriterule.

== 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. The rewrite target must be the root of your DAV server.
The well-known aliases should be added for your DAV vhost and on the vhost serving the host matching the mail domain:

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

In the case of not serving the DAV service on the vhost root additionally some DNS TXT records are recommended:

_caldavs._tcp.MYSERVER.TLD. 10800 IN TXT path=/servlet/dav
_caldav._tcp.MYSERVER.TLD. 10800 IN TXT path=/servlet/dav
_carddavs._tcp.MYSERVER.TLD. 10800 IN TXT path=/servlet/dav
_carddav._tcp.MYSERVER.TLD. 10800 IN TXT path=/servlet/dav

== Installation on OX App Suite ==

=== Debian GNU/Linux 9.0 ===

Add the following entry to /etc/apt/sources.list.d/open-xchange.list if not already present:

deb https://software.open-xchange.com/products/appsuite/stable/backend/DebianStretch/ /

# if you have a valid maintenance subscription, please uncomment the
# following and add the ldb account data to the url so that the most recent
# packages get installed
# deb https://[CUSTOMERID:PASSWORD]@software.open-xchange.com/products/appsuite/stable/backend/updates/DebianStretch/ /

and run

$ apt-get update
$ apt-get install open-xchange-dav

=== Debian GNU/Linux 10.0 ===

Add the following entry to /etc/apt/sources.list.d/open-xchange.list if not already present:

deb https://software.open-xchange.com/products/appsuite/stable/backend/DebianBuster/ /

# if you have a valid maintenance subscription, please uncomment the
# following and add the ldb account data to the url so that the most recent
# packages get installed
# deb https://[CUSTOMERID:PASSWORD]@software.open-xchange.com/products/appsuite/stable/backend/updates/DebianBuster/ /

and run

$ apt-get update
$ apt-get install open-xchange-dav

=== SUSE Linux Enterprise Server 12 (valid until 7.10.3)===

Add the package repository using zypper if not already present:

$ zypper ar https://software.open-xchange.com/products/appsuite/7.10.3/backend/SLE_12 ox

If you have a valid maintenance subscription, please run the following command and add the ldb account data to the url so that the most recent packages get installed:

$ zypper ar https://[CUSTOMERID:PASSWORD]@software.open-xchange.com/products/appsuite/7.10.3/backend/updates/SLES11 ox-updates

and run

$ zypper ref
$ zypper in open-xchange-dav

=== RedHat Enterprise Linux 6 (valid until 7.10.3)===

Start a console and create a software repository file if not already present:

$ vim /etc/yum.repos.d/ox.repo

[ox]
name=Open-Xchange
baseurl=https://software.open-xchange.com/products/appsuite/7.10.3/backend/RHEL6/
gpgkey=https://software.open-xchange.com/oxbuildkey.pub
enabled=1
gpgcheck=1
metadata_expire=0m

# if you have a valid maintenance subscription, please uncomment the
# following and add the ldb account data to the url so that the most recent
# packages get installed
# [ox-updates]
# name=Open-Xchange Updates
# baseurl=https://[CUSTOMERID:PASSWORD]@software.open-xchange.com/products/appsuite/7.10.3/backend/updates/RHEL6/
# gpgkey=https://software.open-xchange.com/oxbuildkey.pub
# enabled=1
# gpgcheck=1
# metadata_expire=0m

and run

$ yum update
$ yum install open-xchange-dav

===RedHat Enterprise Linux 7 ===

Start a console and create a software repository file if not already present:

$ vim /etc/yum.repos.d/ox.repo

[ox]
name=Open-Xchange
baseurl=https://software.open-xchange.com/products/appsuite/stable/backend/RHEL7/
gpgkey=https://software.open-xchange.com/oxbuildkey.pub
enabled=1
gpgcheck=1
metadata_expire=0m

# if you have a valid maintenance subscription, please uncomment the
# following and add the ldb account data to the url so that the most recent
# packages get installed
# [ox-updates]
# name=Open-Xchange Updates
# baseurl=https://[CUSTOMERID:PASSWORD]@software.open-xchange.com/products/appsuite/stable/backend/updates/RHEL7/
# gpgkey=https://software.open-xchange.com/oxbuildkey.pub
# enabled=1
# gpgcheck=1
# metadata_expire=0m

and run

$ yum update
$ yum install open-xchange-dav

===CentOS 6 (valid until 7.10.3)===

Start a console and create a software repository file if not already present:

$ vim /etc/yum.repos.d/ox.repo

[ox]
name=Open-Xchange
baseurl=https://software.open-xchange.com/products/appsuite/7.10.3/backend/RHEL6/
gpgkey=https://software.open-xchange.com/oxbuildkey.pub
enabled=1
gpgcheck=1
metadata_expire=0m

# if you have a valid maintenance subscription, please uncomment the
# following and add the ldb account data to the url so that the most recent
# packages get installed
# [ox-updates]
# name=Open-Xchange Updates
# baseurl=https://[CUSTOMERID:PASSWORD]@software.open-xchange.com/products/appsuite/7.10.3/backend/updates/RHEL6/
# gpgkey=https://software.open-xchange.com/oxbuildkey.pub
# enabled=1
# gpgcheck=1
# metadata_expire=0m

and run

$ yum update
$ yum install open-xchange-dav

===CentOS 7===

Start a console and create a software repository file if not already present:

$ vim /etc/yum.repos.d/ox.repo

[ox]
name=Open-Xchange
baseurl=https://software.open-xchange.com/products/appsuite/stable/backend/RHEL7/
gpgkey=https://software.open-xchange.com/oxbuildkey.pub
enabled=1
gpgcheck=1
metadata_expire=0m

# if you have a valid maintenance subscription, please uncomment the
# following and add the ldb account data to the url so that the most recent
# packages get installed
# [ox-updates]
# name=Open-Xchange Updates
# baseurl=https://[CUSTOMERID:PASSWORD]@software.open-xchange.com/products/appsuite/stable/backend/updates/RHEL7/
# gpgkey=https://software.open-xchange.com/oxbuildkey.pub
# enabled=1
# gpgcheck=1
# metadata_expire=0m

and run

$ yum update
$ yum install open-xchange-dav

== CalDAV Configuration ==

The following configuration options are available in the configuration files <code>caldav.properties</code> and <code>caldav.yml</code>:

===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:

/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 <code>contextSets</code> 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/carddav.properties:
com.openexchange.carddav.enabled=false

/opt/open-xchange/etc/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]]

Caldav carddav Bundles

2021-03-10T16:34:02Z

WolfgangRosenauer: /* Alternative 2: Apache useragent detection */

This article is valid until the version 7.10.2 of the Open Xchange Server. For newer versions please visit https://documentation.open-xchange.com/latest/middleware/miscellaneous/caldav_carddav.html

= 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 Calendar and Address Book clients.

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 Mac OS X 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 your existing <code>VirtualHost</code> entry. This is an <b>example</b> where <code>MYSERVER.TLD</code> is the domain-name of the ox-server:

# NameVirtualHost directive no longer has any effect since Apache >=2.4
# uncomment only for Apache Versions <2.4
#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>

ProxyPass / balancer://oxserver-sync/servlet/dav/

</VirtualHost>

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

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} Reminders [OR]
RewriteCond %{HTTP_USER_AGENT} DataAccess [OR]
RewriteCond %{HTTP_USER_AGENT} DAVKit [OR]
RewriteCond %{HTTP_USER_AGENT} DAVx5 [OR]
RewriteCond %{HTTP_USER_AGENT} OpenSync [OR]
RewriteCond %{HTTP_USER_AGENT} "DAVdroid" [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\ Book [OR]
RewriteCond %{HTTP_USER_AGENT} CalendarStore [OR]
RewriteCond %{HTTP_USER_AGENT} CalendarAgent [OR]
RewriteCond %{HTTP_USER_AGENT} CalDAV%20Sync%20Adapter [OR]
RewriteCond %{HTTP_USER_AGENT} accountsd [OR]
RewriteCond %{HTTP_USER_AGENT} "eM Client" [OR]
RewriteCond %{HTTP_USER_AGENT} "OX Sync" [OR]
RewriteCond %{HTTP_USER_AGENT} CalDav [OR]
RewriteCond %{HTTP_USER_AGENT} CoreDAV [OR]
RewriteCond %{HTTP_USER_AGENT} remindd
RewriteCond %{HTTP_USER_AGENT} "!Open-Xchange Calendar Feed Client"
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.

'''Note:''' Depending on the specific configuration, such a global definition of the rewrite rules might not be appropriate. However, the rules may also be defined inside a <code>Directory</code> context. More details are available at http://httpd.apache.org/docs/current/mod/mod_rewrite.html#rewriterule.

== 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. The rewrite target must be the root of your DAV server.
The well-known aliases should be added for your DAV vhost and on the vhost serving the host matching the mail domain:

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

In the case of not serving the DAV service on the vhost root additionally some DNS TXT records are recommended:

_caldavs._tcp.MYSERVER.TLD. 10800 IN TXT path=/servlet/dav
_caldav._tcp.MYSERVER.TLD. 10800 IN TXT path=/servlet/dav
_carddavs._tcp.MYSERVER.TLD. 10800 IN TXT path=/servlet/dav
_carddav._tcp.MYSERVER.TLD. 10800 IN TXT path=/servlet/dav

== Installation on OX App Suite ==

=== Debian GNU/Linux 9.0 ===

Add the following entry to /etc/apt/sources.list.d/open-xchange.list if not already present:

deb https://software.open-xchange.com/products/appsuite/stable/backend/DebianStretch/ /

# if you have a valid maintenance subscription, please uncomment the
# following and add the ldb account data to the url so that the most recent
# packages get installed
# deb https://[CUSTOMERID:PASSWORD]@software.open-xchange.com/products/appsuite/stable/backend/updates/DebianStretch/ /

and run

$ apt-get update
$ apt-get install open-xchange-dav

=== Debian GNU/Linux 10.0 ===

Add the following entry to /etc/apt/sources.list.d/open-xchange.list if not already present:

deb https://software.open-xchange.com/products/appsuite/stable/backend/DebianBuster/ /

# if you have a valid maintenance subscription, please uncomment the
# following and add the ldb account data to the url so that the most recent
# packages get installed
# deb https://[CUSTOMERID:PASSWORD]@software.open-xchange.com/products/appsuite/stable/backend/updates/DebianBuster/ /

and run

$ apt-get update
$ apt-get install open-xchange-dav

=== SUSE Linux Enterprise Server 12 (valid until 7.10.3)===

Add the package repository using zypper if not already present:

$ zypper ar https://software.open-xchange.com/products/appsuite/7.10.3/backend/SLE_12 ox

If you have a valid maintenance subscription, please run the following command and add the ldb account data to the url so that the most recent packages get installed:

$ zypper ar https://[CUSTOMERID:PASSWORD]@software.open-xchange.com/products/appsuite/7.10.3/backend/updates/SLES11 ox-updates

and run

$ zypper ref
$ zypper in open-xchange-dav

=== RedHat Enterprise Linux 6 (valid until 7.10.3)===

Start a console and create a software repository file if not already present:

$ vim /etc/yum.repos.d/ox.repo

[ox]
name=Open-Xchange
baseurl=https://software.open-xchange.com/products/appsuite/7.10.3/backend/RHEL6/
gpgkey=https://software.open-xchange.com/oxbuildkey.pub
enabled=1
gpgcheck=1
metadata_expire=0m

# if you have a valid maintenance subscription, please uncomment the
# following and add the ldb account data to the url so that the most recent
# packages get installed
# [ox-updates]
# name=Open-Xchange Updates
# baseurl=https://[CUSTOMERID:PASSWORD]@software.open-xchange.com/products/appsuite/7.10.3/backend/updates/RHEL6/
# gpgkey=https://software.open-xchange.com/oxbuildkey.pub
# enabled=1
# gpgcheck=1
# metadata_expire=0m

and run

$ yum update
$ yum install open-xchange-dav

===RedHat Enterprise Linux 7 ===

Start a console and create a software repository file if not already present:

$ vim /etc/yum.repos.d/ox.repo

[ox]
name=Open-Xchange
baseurl=https://software.open-xchange.com/products/appsuite/stable/backend/RHEL7/
gpgkey=https://software.open-xchange.com/oxbuildkey.pub
enabled=1
gpgcheck=1
metadata_expire=0m

# if you have a valid maintenance subscription, please uncomment the
# following and add the ldb account data to the url so that the most recent
# packages get installed
# [ox-updates]
# name=Open-Xchange Updates
# baseurl=https://[CUSTOMERID:PASSWORD]@software.open-xchange.com/products/appsuite/stable/backend/updates/RHEL7/
# gpgkey=https://software.open-xchange.com/oxbuildkey.pub
# enabled=1
# gpgcheck=1
# metadata_expire=0m

and run

$ yum update
$ yum install open-xchange-dav

===CentOS 6 (valid until 7.10.3)===

Start a console and create a software repository file if not already present:

$ vim /etc/yum.repos.d/ox.repo

[ox]
name=Open-Xchange
baseurl=https://software.open-xchange.com/products/appsuite/7.10.3/backend/RHEL6/
gpgkey=https://software.open-xchange.com/oxbuildkey.pub
enabled=1
gpgcheck=1
metadata_expire=0m

# if you have a valid maintenance subscription, please uncomment the
# following and add the ldb account data to the url so that the most recent
# packages get installed
# [ox-updates]
# name=Open-Xchange Updates
# baseurl=https://[CUSTOMERID:PASSWORD]@software.open-xchange.com/products/appsuite/7.10.3/backend/updates/RHEL6/
# gpgkey=https://software.open-xchange.com/oxbuildkey.pub
# enabled=1
# gpgcheck=1
# metadata_expire=0m

and run

$ yum update
$ yum install open-xchange-dav

===CentOS 7===

Start a console and create a software repository file if not already present:

$ vim /etc/yum.repos.d/ox.repo

[ox]
name=Open-Xchange
baseurl=https://software.open-xchange.com/products/appsuite/stable/backend/RHEL7/
gpgkey=https://software.open-xchange.com/oxbuildkey.pub
enabled=1
gpgcheck=1
metadata_expire=0m

# if you have a valid maintenance subscription, please uncomment the
# following and add the ldb account data to the url so that the most recent
# packages get installed
# [ox-updates]
# name=Open-Xchange Updates
# baseurl=https://[CUSTOMERID:PASSWORD]@software.open-xchange.com/products/appsuite/stable/backend/updates/RHEL7/
# gpgkey=https://software.open-xchange.com/oxbuildkey.pub
# enabled=1
# gpgcheck=1
# metadata_expire=0m

and run

$ yum update
$ yum install open-xchange-dav

== CalDAV Configuration ==

The following configuration options are available in the configuration files <code>caldav.properties</code> and <code>caldav.yml</code>:

===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:

/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 <code>contextSets</code> 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/carddav.properties:
com.openexchange.carddav.enabled=false

/opt/open-xchange/etc/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:Mobile API Facade

2021-02-11T16:17:47Z

WolfgangRosenauer: /* Version Matrix */

= Mobile API Facade =

== General Information ==

The Mobile API Facade is a server component that brings the new native mobile mail apps together with the OX App Suite. We’ve built the façade based on the technology used and proven in the OX App Suite middleware. The facade is developed in Java, utilizing the OSGI Framework.

The Facade provides offline friendly HTTP interface by doing the work, the connections through the HTTP API, to the OX App Suite and providing only the data the offline capable clients need. In some cases multiple requests to the OX App Suite are combined into one for its clients.The facade also offers a method to tell the clients that information on the server haven’t changed since the last time the client asked for it. This reduces the amount of data to transmit to the clients under certain circumstances, especially important in mobile networks were bandwidth (and overall traffic) is limited. Thanks to facade some functionality can be shared among all clients and need only get implemented once. One example for this is the teaser text extraction, and HTML mail handling in general.The facade also provides a pluggable authentication system. In the default case, login request are just forwarded to the middleware. In more advanced use-cases, the login request is forwarded to IDM of the customer and an OX session is created from the access token from the IDM. For clients this is pretty straightforward.

== License information ==

=== Used 3rd party licenses ===

In addition to the 3rd party software [https://www.open-xchange.com/legal/licenses-ox-app-suite/ used by AppSuite], the Mobile API Facade uses to following libraries:

* [https://www.open-xchange.com/fileadmin/user_upload/images/portfolio/license/MIT_License_Generic.pdf Project Lombok (The MIT License]
* [https://www.open-xchange.com/fileadmin/user_upload/images/portfolio/license/MIT_License_Generic.pdf Semver4J (The MIT License)]

== Requirements ==

The Mobile API Facade has to be installed alongside an OX App Suite installation. It requires at least OX App Suite v7.8.4.

== Version Matrix ==
{|border="2" rules="all" align="left">
|-
|colspan=1|'''OX App Suite Core Version'''
|colspan=1|'''Mobile API Facade Version'''
|colspan=1|'''Version-Stream'''
|-
|v7.8.4
|v1.0.x
|stable-1.0
|-
|v7.10.1
|v1.4.x
|stable-1.4
|-
|v7.10.2
|v1.6.x
|stable-1.6
|-
|v7.10.3
|v1.8.x
|stable-1.8
|-
|v7.10.4
|v1.10.x
|stable-1.10
|-
|v7.10.5
|v1.12.x
|stable-1.12
|-
|}

== Mobile API Facade API ==

Further information about the Mobile API Facade API can be found at:
https://documentation.open-xchange.com/components/facade/1.0.0/

= OX Mail Server-side Installation and Configuration on OX App Suite v7.10.3 =

This chapter describes how the backend components of OX Mail are installed and configured on the server.

== Available packages ==

Mobile API Facade is available with the following backend packages:

* ''open-xchange-mobile-api-facade''

Installation on the server varies depending on the underlying distribution, details are available in the following chapters.

=== Redhat Enterprise Linux 6 or CentOS 6 ===

Add the following repositories to your Open-Xchange yum configuration:

{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/mobile-api-facade/stable-1.8|pc2n=rhelname|pc2v=RHEL6|mobile-api-facade}}

$ yum install open-xchange-mobile-api-facade

=== Redhat Enterprise Linux 7 or CentOS 7 ===

Add the following repositories to your Open-Xchange yum configuration:

{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/mobile-api-facade/stable-1.8|pc2n=rhelname|pc2v=RHEL7|mobile-api-facade}}

$ yum install open-xchange-mobile-api-facade

=== Debian GNU/Linux 9.0 ===

Add the following repositories to your Open-Xchange apt configuration:

{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/mobile-api-facade/stable-1.8|pc2n=debianname|pc2v=DebianStretch|mobile-api-facade}}

$ apt-get update
$ apt-get install open-xchange-mobile-api-facade

=== Debian GNU/Linux 10.0 ===

Add the following repositories to your Open-Xchange apt configuration:

{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/mobile-api-facade/stable-1.8|pc2n=debianname|pc2v=DebianBuster|mobile-api-facade}}

$ apt-get update
$ apt-get install open-xchange-mobile-api-facade

=== SUSE Linux Enterprise Server 12 ===

{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/mobile-api-facade/stable-1.8|pc2n=susename|pc2v=SLE_12|mobile-api-facade}}

$ zypper ref
$ zypper install open-xchange-mobile-api-facade

= OX Mail Server-side Installation and Configuration on OX App Suite 7.8.x and 7.10.x =

If you want to update an older version of OX Mobile API Facade to the latest maintenance release, add the following entry to <tt>/etc/apt/sources.list.d/open-xchange.list</tt>. Replace VERSION with the link for the stream of versions as listed above in the version matrix (e.g. stable-1.8) or a specific version you are using (e.g. 1.8.3).

This chapter describes how the backend components of OX Mail are installed and configured on the server.

== Available packages ==

Mobile API Facade is available with the following backend packages:

* ''open-xchange-mobile-api-facade''

Installation on the server varies depending on the underlying distribution, details are available in the following chapters.

=== Redhat Enterprise Linux 6 or CentOS 6 ===

Add the following repositories to your Open-Xchange yum configuration:

{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/mobile-api-facade/VERSION|pc2n=rhelname|pc2v=RHEL6|mobile-api-facade}}

$ yum install open-xchange-mobile-api-facade

=== Redhat Enterprise Linux 7 or CentOS 7 ===

Add the following repositories to your Open-Xchange yum configuration:

{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/mobile-api-facade/VERSION|pc2n=rhelname|pc2v=RHEL7|mobile-api-facade}}

$ yum install open-xchange-mobile-api-facade

=== Debian GNU/Linux 8.0 ===

Add the following repositories to your Open-Xchange apt configuration:

{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/mobile-api-facade/VERSION|pc2n=debianname|pc2v=DebianJessie|mobile-api-facade}}

$ apt-get update
$ apt-get install open-xchange-mobile-api-facade

=== Debian GNU/Linux 9.0 ===

Add the following repositories to your Open-Xchange apt configuration:

{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/mobile-api-facade/VERSION|pc2n=debianname|pc2v=DebianStretch|mobile-api-facade}}

$ apt-get update
$ apt-get install open-xchange-mobile-api-facade

=== Debian GNU/Linux 10.0 ===

Add the following repositories to your Open-Xchange apt configuration:

{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/mobile-api-facade/VERSION|pc2n=debianname|pc2v=DebianBuster|mobile-api-facade}}

$ apt-get update
$ apt-get install open-xchange-mobile-api-facade

=== SUSE Linux Enterprise Server 12 ===

{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/mobile-api-facade/VERSION|pc2n=susename|pc2v=SLE_12|mobile-api-facade}}

$ zypper ref
$ zypper install open-xchange-mobile-api-facade

= Configuration Mobile API Facade =

== Introduction ==

To be able to use the native mail apps the Mobile API Facade needs to be installed in front of the OX App Suite middleware. This document describes how to configure the Mobile API Facade.

The Mobile API Facade stores its configuration in the files <code>/opt/open-xchange/mobile-api-facade/etc/facade.properties</code> (the global configuration) and in <code>/opt/open-xchange/mobile-api-facade/etc/mobile-api-facade-config.yml</code> (hostname specific configuration). Both files support the same configuration properties as can be seen on https://documentation.open-xchange.com/components/mobile-api-facade/config/1.8/.

== Connection to the OX App Suite Middleware ==

After installation of the facade package ("open-xchange-mobile-api-facade") the property <code>com.openexchange.mobile.api.facade.MiddlewareBaseUrl</code> needs to get set to the correct URL. This property needs to be explicitly configured by the administrator. It has no default value. Its possible to connect the Mobile API Facade directly to a middleware process, but this is highly discouraged. The Mobile API Facade should always connect to a middleware process through a load balancer.

An example:

com.openexchange.mobile.api.facade.MiddlewareBaseUrl=https://appsuite.example.com/appsuite/api

After this configuration the open-xchange-mobile-api-facade needs to get restarted.

== Proxy configuration ==

<Proxy balancer://oxcluster_facade>
Order Allow,Deny
Allow from all
BalancerMember http://appsuite-middleware1.example.com:8007 timeout=100 smax=0 ttl=60 retry=60 loadfactor=50 keepalive=On route=FOX1
BalancerMember http://appsuite-middleware2.example.com:8007 timeout=100 smax=0 ttl=60 retry=60 loadfactor=50 keepalive=On route=FOX2

ProxySet stickysession=JSESSIONID|jsessionidscolonpathdelim=On
SetEnv proxy-initial-not-pooled
SetEnv proxy-sendchunked
</Proxy>

ProxyPass /services/api-facade balancer://oxcluster_facade/services/api-facade

== Traffic compression ==

The clients need to exchange a lot of data with the facade to accomplish the task of a mail client. This traffic can be compressed. Clients add the header "Accept-Encoding: gzip,deflate" by default. For this to work the Apache web server in front of the facade needs to handle this as the facade itself is not returning compressed response bodies.

For Apache HTTPD <code>{mod_deflate}</code> needs to be enabled and the following line needs to be added to your virtual host:

AddOutputFilterByType DEFLATE text/html text/plain text/javascript application/javascript text/css
text/xml application/xml text/x-js application/x-javascript application/json

== Starting/Stopping the Facade Service ==

The facade runs as its own service independent of the normal OX App Suite middleware. For this on Debian-based system it can be started with

service open-xchange-mobile-api-facade start

It can be stopped with

service open-xchange-mobile-api-facade stop

== Rereading configuration from disk ==

All configuration properties which are marked as reloadable can be configured without restarting the Mobile API Facade by using the <code>reloadconfiguration</code> utility. As the Mobile API Facade runs in its own process you need to tell <code>reloadconfiguration</code> to connect it instead of the Middleware. This can be done by:

reloadconfiguration -p 1100

== Ports ==

As the Mobile API Facade is its own process it also has its own JMX port and its own RMI port. The default JMX port is 9995 and the default RMI port is 1100. These ports needs to be explicitly specified to the command line tools using either JMX or RMI.

== Configuration of Mobile API Facade behavior ==

This can be configured in facade.properties and mobile-api-facade-config.yml.

=== Multiple host names ===

The Mobile API Facade supports multiple host names on one instance, that are configured differently. These can be configured in mobile-api-facade-config.yml. This file in YAML format. Beware that indentation is really important in YAML.

<pre>
[ host name ]:
[ properties, you want to configure ]

[ host name ]:
[ properties, you want to configure ]

...
</pre>

The allowed properties are the same as allowed in facade.properties. You can find a complete list at https://documentation.open-xchange.com/components/mobile-api-facade/config/1.8/.

=== Custom properties ===

It's possible to configure custom properties to be returned to clients. This is usefull to return special configurations to your clients. Custom properties are key/attribute values under the "customProperties" key.

Example:

<pre>
appsuite.example.com:
customProperties:
custom.specific.property: true
custom.specific.property.2: "value"
</pre>

=== Client specific configuration ===

By implementing the client specific feature the above configuration possibilities got extended. We now have to use YAML lists for each host name. This allows to add multiple different configurations to one host configuration. You can add a list of matchers in the "matches" key to a host configuration. The first "matches" entry for a given host name that matches to the given User-Agent header sent by the client will be used. Further evaluation is not done at runtime. Configuration properties need to be on the same indentation level as the "matches" key. These host configurations inherit a default configuration from the configuration in facade.properties. Otherwise they need to be complete. They don't inherit configuration properties from other places.

<pre>
[ host name ]:
- matches:
[ matchers, you want to match against ]
[ properties, you want to configure ]
- matches:
[ matchers, you want to match against ]
[ properties, you want to configure ]
...
</pre>

Example:

The iOS version supported in the beginning was iOS 9 and up. At some point in time due to technical reasons support for iOS 9 and 10 was dropped and the application supported iOS 11 and up. When you now want to update all installations on iOS 11 and up to the latest app version but leave old installations in intact you can use the force upgrade feature of the apps. Keep in mind that the matching process stops when the first match is found. If no match was found the default configuration is used.

<pre>
appsuite.example.com:
- matches:
platform: 'iOS'
osVersion: '11.0-'
brand: 'OpenXchange'
com.openexchange.mobile.api.facade.minimumClientVersion.ios: '11.2'
com.openexchange.mobile.api.facade.returnNonPrimaryAccounts: false
- matches:
platform: 'iOS'
osVersion: '-10.99'
brand: 'OpenXchange'
com.openexchange.mobile.api.facade.returnNonPrimaryAccounts: false
</pre>

=== Matchers ===

Several matchers are possible. All match against values in the User-Agent header.

- platform: This matcher allows it to match only for "Android" or "iOS"
- version: This matcher checks against the application version. This is not the marketing version displayed in the About screen of the application.
- osVersion: The version of the operating system on the client device
- device: This matches against the exact device model.
brand: This matches against the brand name of the app. By default this is "OpenXchange". Versions specifically branded for customers have a unique brand name.

=== Version matching ===

For the matchers 'version' and 'osVersion' we allow to match concrete versions or version ranges. When adding a matcher with a concrete version, just put the version number as string attribute after the matcher name.

<pre>
appsuite.example.com:
- matches:
platform: 'iOS'
osVersion: '11.0'
com.openexchange.mobile.api.facade.returnNonPrimaryAccounts: false
</pre>

When matching a range we are always matching inclusive. You can either use a closed range, a range with a given start value and an end value, or an open range with either a start value or an end value. Keep in mind that to match all versions lower then '11.0' you need use a probably non-existing version number like '10.99'.

<pre>
appsuite.example.com:
- matches:
platform: 'iOS'
osVersion: '11.0-'
com.openexchange.mobile.api.facade.returnNonPrimaryAccounts: true
- matches:
platform: 'iOS'
osVersion: '-10.99'
com.openexchange.mobile.api.facade.returnNonPrimaryAccounts: false
</pre>

== Debugging ==

In order to check whether installation went successful you may want to run

$ curl -v http://localhost:8007/services/api-facade/v1/version

That should return a JSON string like this:

<code>
{"version":"1.6.8","commitHash":"9e90d6072407b73c3e05b86ce724962af1a3de61","middlewareVersion":"7.10.2-Rev15"}
</code>

Mailclient autoconfiguration

2021-01-22T11:26:59Z

WolfgangRosenauer: /* Installation */

= Providing autoconfiguration for mail clients =

This article explains a solution for autoconfiguration for a set of mail clients which can be configured against a mail system automatically by just entering email address and password. There are three widely used approaches to do this via a self hosted lookup method, based on Microsoft's autodiscover, [https://developer.mozilla.org/en-US/docs/Mozilla/Thunderbird/Autoconfiguration Mozilla's autoconfig], and iOS/MacOS provisioning which are relevant to support detecting IMAP and SMTP server details for client configuration. Another option is solely based on DNS SRV discovery ([https://tools.ietf.org/html/rfc6186 RFC 6186]).

Since [[AppSuite:EM_Client_for_OX_App_Suite|eMClient for OX App Suite]] is using the Microsoft based solution this service is especially important to have a smooth user experience for customer environments offering it to their users.

autodiscover and autoconfig are based on XML schemas. Therefore for very simple deployments it might even be enough to serve some static XML files for both usecases. Please see the respective vendor standard documentation for more details.

In this article we show how to deploy a simple autoconfiguration service based on the open source solution [https://automx.org/en/ automx].

== Preparations ==

The autoconfiguration protocols use several ways to find the XML provided later by automx. In the following section there is listed in which order the protocols are looking for the XML. Depending where you would like to serve the XML files you can choose from those options.

The domain example.org as in those examples are the ones taken from the entered email address.

=== autoconfig ===

# http://autoconfig.example.org/mail/config-v1.1.xml
# http://example.org/.well-known/autoconfig/mail/config-v1.1.xml

=== autodiscover ===

# https://example.org/autodiscover/autodiscover.xml
# https://autodiscover.example.org/autodiscover/autodiscover.xml
# DNS SRV lookup for autodiscover.tcp.example.org

=== DNS SRV ===

A DNS SRV entry for autodiscover would look like this:

_autodiscover._tcp IN SRV 0 0 443 $HOSTNAME.example.org.

The following DNS SRV records can be used to provide configuration hints for mail clients supporting RFC 6186:

_submission._tcp SRV 0 1 587 mail.example.org.
_imap._tcp SRV 2 1 143 imap.example.org.
_imaps._tcp SRV 1 1 993 imap.example.org.
_pop3._tcp SRV 4 1 110 pop3.example.org.
_pop3s._tcp SRV 3 1 995 pop3.example.org.

== automx ==

=== Installation ===

If you would like to support eMClient for OX App Suite please make sure that you are using a version after 1.1.1 or an earlier patched version which supports the DAV and OX services.
Also please note that the current versions of automx2 do neither support DAV nor the OX service extensions for autodiscover. It currently only supports IMAP and SMTP services.

For manual installation please refer to the [https://automx.org/en/#download automx download instructions].

RPM packages for SUSE and RHEL flavours are provided by the [https://software.opensuse.org/package/automx Open Build Service]. Those packages are currently version 0.10.2 with the above patches applied and are working with Python 2.

=== Configuration ===

==== automx ====

Please find detailed documentation via '''man automx.conf''' and for more dynamic setups automx_script, automx_ldap and automx_sql.

/etc/automx.conf:

<nowiki>
[automx]
provider = example.org
domains = example.org, example.com
debug = no
logfile = /var/log/automx/automx.log

# Protect against DoS
memcache = 127.0.0.1:11211
memcache_ttl = 600
client_error_limit = 20
rate_limit_exception_networks = 127.0.0.0/8, ::1/128

# The DEFAULT section is always merged into each other section. Each section
# can overwrite settings done here.
[DEFAULT]
account_type = email
account_name = example Mail
account_name_short = example Mail

# If a domain is listed in the automx section, it may have its own section. If
# none is found here, the global section is used.
[global]
backend = static
action = settings

# EAS (mobilesync)
server_url = https://eas.example.org
server_name = example

# If you want to sign mobileconfig profiles, enable these options. Make sure
# that your webserver has proper privileges to read the key. The cert file
# must contain the server certificate and all intermediate certificates. You
# can simply concatenate these certificates.
#sign_mobileconfig = yes
#sign_cert = /path/to/cert
#sign_key = /path/to/key

smtp = yes
smtp_server = mail.example.org
smtp_port = 587
smtp_encryption = starttls
smtp_auth = plaintext
smtp_auth_identity = %s
smtp_refresh_ttl = 6
smtp_default = yes

imap = yes
imap_server = mail.example.org
imap_port = 993
imap_encryption = ssl
imap_auth = plaintext
imap_auth_identity = %s
imap_refresh_ttl = 6
pop = yes
pop_server = mail.example.org
pop_port = 995
pop_encryption = ssl
pop_auth = plaintext
pop_auth_identity = %s
pop_refresh_ttl = 6

carddav = yes
carddav_server = https://dav.example.org/
carddav_auth_identity = %s

caldav = yes
caldav_server = https://dav.example.org/
caldav_auth_identity = %s

ox = yes
ox_server = https://ox.example.org/
ox_auth_identity = %s

follow = imap_starttls

[imap_starttls]
backend = static_append

imap = yes
imap_server = mail.example.org
imap_port = 143
imap_encryption = starttls
imap_auth = plaintext
imap_auth_identity = %s
imap_refresh_ttl = 6
</nowiki>

==== Apache ====

e.g. /etc/{apache2,httpd}/conf.d/automx.conf:

<nowiki>
<IfModule mod_wsgi.c>
WSGIChunkedRequest On

WSGIScriptAliasMatch \
(?i)^/.+/(autodiscover|config-v1.1).xml \
/usr/lib/automx/automx_wsgi.py

WSGIScriptAlias \
/mobileconfig \
/usr/lib/automx/automx_wsgi.py

<Directory "/usr/lib/automx">
Require all granted
</Directory>
</IfModule>
</nowiki>

In case the iOS/MacOS web provisioning should be provided there should also be a /etc/{apache2,httpd}/conf.d/automx-web.conf:

<nowiki>
Alias /automx "/usr/share/automx/"

<Directory "/usr/share/automx">
Options Indexes MultiViews
Require all granted
</Directory>
</nowiki>

eMClient for OX App Suite has a special requirement to make the autoconfiguration experience nice and straightforward. To make it ask directly for a password instead of later in the setup process (where it requires a restart of the application to be fully functional) it is required to protect the autodiscover.xml via basic auth. In our scenario there is nothing to protect really so in this example we allow any credentials for access but still ask for some.

For this add the following section to /etc/{apache2,httpd}/conf.d/automx.conf:

<nowiki>
<Location "/autodiscover/autodiscover.xml">
AuthType Basic
AuthName "Restricted"
AuthBasicProvider anon
Anonymous_NoUserID off
Anonymous_MustGiveEmail off
Anonymous_VerifyEmail off
Anonymous_LogEmail off
Anonymous *
Require valid-user
</Location>
</nowiki>

== Related links ==

[[Caldav_carddav_Bundles#Autodiscovery|DAV autodiscovery]]

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

Mailclient autoconfiguration

2021-01-22T11:26:37Z

WolfgangRosenauer: /* automx */

= Providing autoconfiguration for mail clients =

This article explains a solution for autoconfiguration for a set of mail clients which can be configured against a mail system automatically by just entering email address and password. There are three widely used approaches to do this via a self hosted lookup method, based on Microsoft's autodiscover, [https://developer.mozilla.org/en-US/docs/Mozilla/Thunderbird/Autoconfiguration Mozilla's autoconfig], and iOS/MacOS provisioning which are relevant to support detecting IMAP and SMTP server details for client configuration. Another option is solely based on DNS SRV discovery ([https://tools.ietf.org/html/rfc6186 RFC 6186]).

Since [[AppSuite:EM_Client_for_OX_App_Suite|eMClient for OX App Suite]] is using the Microsoft based solution this service is especially important to have a smooth user experience for customer environments offering it to their users.

autodiscover and autoconfig are based on XML schemas. Therefore for very simple deployments it might even be enough to serve some static XML files for both usecases. Please see the respective vendor standard documentation for more details.

In this article we show how to deploy a simple autoconfiguration service based on the open source solution [https://automx.org/en/ automx].

== Preparations ==

The autoconfiguration protocols use several ways to find the XML provided later by automx. In the following section there is listed in which order the protocols are looking for the XML. Depending where you would like to serve the XML files you can choose from those options.

The domain example.org as in those examples are the ones taken from the entered email address.

=== autoconfig ===

# http://autoconfig.example.org/mail/config-v1.1.xml
# http://example.org/.well-known/autoconfig/mail/config-v1.1.xml

=== autodiscover ===

# https://example.org/autodiscover/autodiscover.xml
# https://autodiscover.example.org/autodiscover/autodiscover.xml
# DNS SRV lookup for autodiscover.tcp.example.org

=== DNS SRV ===

A DNS SRV entry for autodiscover would look like this:

_autodiscover._tcp IN SRV 0 0 443 $HOSTNAME.example.org.

The following DNS SRV records can be used to provide configuration hints for mail clients supporting RFC 6186:

_submission._tcp SRV 0 1 587 mail.example.org.
_imap._tcp SRV 2 1 143 imap.example.org.
_imaps._tcp SRV 1 1 993 imap.example.org.
_pop3._tcp SRV 4 1 110 pop3.example.org.
_pop3s._tcp SRV 3 1 995 pop3.example.org.

== automx ==

=== Installation ===

If you would like to support eMClient for OX App Suite please make sure that you are using a version after 1.1.1 or an earlier patched version which supports the DAV and OX services. automx2 does not have any support for anything but mail protocols yet and is not sufficient.
Also please note that the current versions of automx2 do neither support DAV nor the OX service extensions for autodiscover. It currently only supports IMAP and SMTP services.

For manual installation please refer to the [https://automx.org/en/#download automx download instructions].

RPM packages for SUSE and RHEL flavours are provided by the [https://software.opensuse.org/package/automx Open Build Service]. Those packages are currently version 0.10.2 with the above patches applied and are working with Python 2.

=== Configuration ===

==== automx ====

Please find detailed documentation via '''man automx.conf''' and for more dynamic setups automx_script, automx_ldap and automx_sql.

/etc/automx.conf:

<nowiki>
[automx]
provider = example.org
domains = example.org, example.com
debug = no
logfile = /var/log/automx/automx.log

# Protect against DoS
memcache = 127.0.0.1:11211
memcache_ttl = 600
client_error_limit = 20
rate_limit_exception_networks = 127.0.0.0/8, ::1/128

# The DEFAULT section is always merged into each other section. Each section
# can overwrite settings done here.
[DEFAULT]
account_type = email
account_name = example Mail
account_name_short = example Mail

# If a domain is listed in the automx section, it may have its own section. If
# none is found here, the global section is used.
[global]
backend = static
action = settings

# EAS (mobilesync)
server_url = https://eas.example.org
server_name = example

# If you want to sign mobileconfig profiles, enable these options. Make sure
# that your webserver has proper privileges to read the key. The cert file
# must contain the server certificate and all intermediate certificates. You
# can simply concatenate these certificates.
#sign_mobileconfig = yes
#sign_cert = /path/to/cert
#sign_key = /path/to/key

smtp = yes
smtp_server = mail.example.org
smtp_port = 587
smtp_encryption = starttls
smtp_auth = plaintext
smtp_auth_identity = %s
smtp_refresh_ttl = 6
smtp_default = yes

imap = yes
imap_server = mail.example.org
imap_port = 993
imap_encryption = ssl
imap_auth = plaintext
imap_auth_identity = %s
imap_refresh_ttl = 6
pop = yes
pop_server = mail.example.org
pop_port = 995
pop_encryption = ssl
pop_auth = plaintext
pop_auth_identity = %s
pop_refresh_ttl = 6

carddav = yes
carddav_server = https://dav.example.org/
carddav_auth_identity = %s

caldav = yes
caldav_server = https://dav.example.org/
caldav_auth_identity = %s

ox = yes
ox_server = https://ox.example.org/
ox_auth_identity = %s

follow = imap_starttls

[imap_starttls]
backend = static_append

imap = yes
imap_server = mail.example.org
imap_port = 143
imap_encryption = starttls
imap_auth = plaintext
imap_auth_identity = %s
imap_refresh_ttl = 6
</nowiki>

==== Apache ====

e.g. /etc/{apache2,httpd}/conf.d/automx.conf:

<nowiki>
<IfModule mod_wsgi.c>
WSGIChunkedRequest On

WSGIScriptAliasMatch \
(?i)^/.+/(autodiscover|config-v1.1).xml \
/usr/lib/automx/automx_wsgi.py

WSGIScriptAlias \
/mobileconfig \
/usr/lib/automx/automx_wsgi.py

<Directory "/usr/lib/automx">
Require all granted
</Directory>
</IfModule>
</nowiki>

In case the iOS/MacOS web provisioning should be provided there should also be a /etc/{apache2,httpd}/conf.d/automx-web.conf:

<nowiki>
Alias /automx "/usr/share/automx/"

<Directory "/usr/share/automx">
Options Indexes MultiViews
Require all granted
</Directory>
</nowiki>

eMClient for OX App Suite has a special requirement to make the autoconfiguration experience nice and straightforward. To make it ask directly for a password instead of later in the setup process (where it requires a restart of the application to be fully functional) it is required to protect the autodiscover.xml via basic auth. In our scenario there is nothing to protect really so in this example we allow any credentials for access but still ask for some.

For this add the following section to /etc/{apache2,httpd}/conf.d/automx.conf:

<nowiki>
<Location "/autodiscover/autodiscover.xml">
AuthType Basic
AuthName "Restricted"
AuthBasicProvider anon
Anonymous_NoUserID off
Anonymous_MustGiveEmail off
Anonymous_VerifyEmail off
Anonymous_LogEmail off
Anonymous *
Require valid-user
</Location>
</nowiki>

== Related links ==

[[Caldav_carddav_Bundles#Autodiscovery|DAV autodiscovery]]

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

AppSuite:OX Guard

2021-01-12T21:46:05Z

WolfgangRosenauer: /* Apache */

= OX Guard (Version 2.10) =

For previous versions of OX Guard, please click here
* [[AppSuite:OX_Guard_2-0 | Installation and information of OX Guard 2.0 - 2.2]]
* [[Appsuite:OX_Guard_2_8 | Installation and information of OX Guard 2.4 - 2.8]]

If upgrading from 2.6 or 2.8, please see
* [[Appsuite:OX_Guard_Upgrade_2_10|Upgrading to 2.10]]

== Overview ==

OX Guard is a fully integrated security add-on to OX App Suite that provides end users with a flexible email and file encryption solution. OX Guard is a highly scalable, multi server, feature rich solution that is so simple-to-use that end users will actually use it. With a single click a user can take control of their security and send secure emails and share encrypted files. This can be done from any device to both OX App Suite and non-OX App Suite users.

OX Guard uses standard PGP encryption for the encryption of email and files. PGP has been around for a long time, yet has not really caught on with the masses. This is generally blamed on the confusion and complications of managing the keys, understanding trust, PGP format types, and lack of trusted central key repositories. Guard simplifies all of this, making PGP encryption as easy as a one click process, with no keys to keep track of, yet the options of advanced PGP management for those that know how.

This article will guide you through the installation of Guard and describes the basic configuration and software requirements. As it is intended as a quick walk-through it assumes an existing installation of the operating system including a single server App Suite setup as well as average system administration skills. This guide will also show you how to setup a basic installation with none of the typically used distributed environment settings. The objective of this guide is:

* To setup a single server installation
* To setup a single Guard instance on an existing Open-Xchange installation, no cluster
* To use the database service on the existing Open-Xchange installation for Guard, no replication
* To provide a basic configuration setup, no mail server configuration

=== Key Features ===

* Simple security at the touch of a button
* Provides user based security - Separate from provider
* Supplementary security to Provider based security - Layered
* Powerful features yet simple to use and understand
* Security - Inside and outside of the OX environment
* Email and Drive integration
* Uses proven PGP security

=== Availability ===

If an OX App Suite customer would like to evaluate OX Guard integration, the first step is to contact OX Sales. OX Sales will then work on the request and send prices and license/API (for the hosted infrastructure) key details to the customer.

=== Requirements ===

Please review [https://oxpedia.org/wiki/index.php?title=AppSuite:OX_System_Requirements#OX_Guard OX Guard Requirements] for a full list of requirements.

Since OX Guard is a Microservice it can either be added to an existing Open-Xchange installation or it can be deployed on a dedicated environment. The version of Guard installed is dependent on the Appsuite version installed. Please refer to the version matrix below.

==== Prerequisites ====

* Open-Xchange REST API
* Grizzly HTTP connector (open-xchange-grizzly)
* A supported Java Virtual Machine (Java 8)
* An Open-Xchange App Suite installation (see version Matrix)
* Please Note: To get access to the latest minor features and bug fixes, you need to have a valid license. The article [https://oxpedia.org/wiki/index.php?title=AppSuite:UpdatingOXPackages Updating OX-Packages] explains how that can be done.

==== Version Matrix ====
{|
! style="text-align:left;"| Core Version
! Guard Version
|-
|7.8.1
|2.4.0 or 2.4.2
|-
|7.8.2
|2.4.2
|-
|7.8.3
|2.6.0
|-
|7.8.4
|2.8.0
|-
|7.10.0
|2.10.0
|-
|7.10.1
|2.10.1
|-
|7.10.2
|2.10.2
|-
|7.10.3
|2.10.3
|-
|7.10.4
|2.10.4
|}

=== Important Notes ===

==== Customisation ====

OX Guard version supports branding / theming using the configuration cascade, defining a templateID for a user or context. Check the [https://oxpedia.org/wiki/index.php?title=AppSuite:GuardCustomization OX Guard Customisation] article for more details.

==== Mail Resolver ====

READ THIS VERY CAREFULLY; BEFORE PROCEEDING WITH GUARD INSTALLATION!

The Guard installation must be able to determine if an email recipient is a local OX user or if it should be a guest account. The default MailResolver uses the context domain name to do this. On many installations, domains may extend across multiple context and multiple database shards. In these cases, the default MailResolver won't work. In addition, if a custom authentication package is used, the Mail Resolver will likely not work.

Once Guard is installed, please be sure to test the mail resolver using:

<source lang="bash">/opt/open-xchange/sbin/guard test email@domain</source>
to see if the mail Resolver works.

If the test does not work, you will likely need a custom Mail Resolver. Please see [https://oxpedia.org/wiki/index.php?title=AppSuite:GuardMailResolver Mail Resolver] page

This resolver software ''depends heavily on your local deployment''.

== Download and Installation ==

=== General ===

The installation of the <code>open-xchange-guard-backend-plugin</code> package which is required for Guard and the main <code>open-xchange-guard</code> package in version 2.4.0 or higher will eventually execute database update tasks if installed and activated. Please take this into account.

There are several components to the Guard service. They can be all installed on the same server as the OX middleware or on a separate server.

The components required for the OX middleware are: <code>open-xchange-rest</code>, <code>open-xchange-guard-backend-plugin</code> and <code>open-xchange-guard-ui</code>.

The components required for the OX frontend are: <code>open-xchange-guard-ui-static</code> and optionally <code>open-xchange-guard-help-en-us</code> (or preferred language for help files).

The components required for the Guard server <code>open-xchange-guard</code> and either <code>open-xchange-guard-file-storage</code> or <code>open-xchange-guard-s3-storage</code> depending on what storage you want to use. The examples below make use of the <code>open-xchange-guard-file-storage</code>. Adjust the commands accordingly to fit your needs. In addition <code>open-xchange</code> and <code>open-xchange-core</code> are required to run OX Guard.

=== Debian Linux 9.0 (Stretch) ===

If not already done, add the following repositories to your Open-Xchange apt configuration:

deb https://software.open-xchange.com/products/guard/stable/guard/DebianStretch /
deb https://software.open-xchange.com/products/appsuite/stable/backend/DebianStretch /

and then run for a single node installation:

$ apt-get update
$ apt-get install open-xchange-rest open-xchange-guard open-xchange-guard-file-storage open-xchange-guard-ui open-xchange-guard-ui-static open-xchange-guard-backend-plugin

or the following for a distributed installation:

$ apt-get update
$ apt-get install open-xchange-guard open-xchange-guard-file-storage
The packages <code>open-xchange-guard-ui</code> <code>open-xchange-rest</code> and <code>open-xchange-guard-backend-plugin</code> missing in the distributed installation have to be installed on the node running the middleware. The package <code>open-xchange-guard-ui-static</code> must be installed in the frontend (apache node).

=== Debian Linux 10.0 (Buster) *Version 2.10.3+ only* ===

If not already done, add the following repositories to your Open-Xchange apt configuration:

deb https://software.open-xchange.com/products/guard/stable/guard/DebianBuster /
deb https://software.open-xchange.com/products/appsuite/stable/backend/DebianBuster /

and then run for a single node installation:

$ apt-get update
$ apt-get install open-xchange-rest open-xchange-guard open-xchange-guard-file-storage open-xchange-guard-ui open-xchange-guard-ui-static open-xchange-guard-backend-plugin

or the following for a distributed installation:

$ apt-get update
$ apt-get install open-xchange-guard open-xchange-guard-file-storage
The packages <code>open-xchange-guard-ui</code> <code>open-xchange-rest</code> and <code>open-xchange-guard-backend-plugin</code> missing in the distributed installation have to be installed on the node running the middleware. The package <code>open-xchange-guard-ui-static</code> must be installed in the frontend (apache node).

=== RedHat Enterprise Linux 6 or CentOS 6 (valid until v2.10.3) ===

If not already done, add the following repositories to your Open-Xchange yum configuration:

[open-xchange-guard-stable-guard]
name=Open-Xchange-guard-stable-guard
baseurl=https://software.open-xchange.com/products/guard/2.10.3/guard/RHEL6/
gpgkey=https://software.open-xchange.com/oxbuildkey.pub
enabled=1
gpgcheck=1
metadata_expire=0m

[ox-backend]
name=Open-Xchange-backend
baseurl=https://software.open-xchange.com/products/appsuite/7.10.3/backend/RHEL6/
gpgkey=https://software.open-xchange.com/oxbuildkey.pub
enabled=1
gpgcheck=1
metadata_expire=0m

and then run for a single node installation:

$ yum update
$ yum install open-xchange-rest open-xchange-guard open-xchange-guard-file-storage open-xchange-guard-ui open-xchange-guard-ui-static open-xchange-guard-backend-plugin
or the following for a distributed installation:

$ yum update
$ yum install open-xchange-guard open-xchange-guard-file-storage
The packages <code>open-xchange-guard-ui</code> <code>open-xchange-rest</code> and <code>open-xchange-guard-backend-plugin</code> missing in the distributed installation have to be installed on the node running the middleware. The package <code>open-xchange-guard-ui-static</code> must be installed in the frontend (apache node).

=== Redhat Enterprise Linux 7 or CentOS 7 ===

If not already done, add the following repositories to your Open-Xchange yum configuration:

[open-xchange-guard-stable-guard]
name=Open-Xchange-guard-stable-guard
baseurl=https://software.open-xchange.com/products/guard/stable/guard/RHEL7/
gpgkey=https://software.open-xchange.com/oxbuildkey.pub
enabled=1
gpgcheck=1
metadata_expire=0m

[ox-backend]
name=Open-Xchange-backend
baseurl=https://software.open-xchange.com/products/appsuite/stable/backend/RHEL7/
gpgkey=https://software.open-xchange.com/oxbuildkey.pub
enabled=1
gpgcheck=1
metadata_expire=0m

and then run for a single node installation:

$ yum update
$ yum install open-xchange-rest open-xchange-guard open-xchange-guard-file-storage open-xchange-guard-ui open-xchange-guard-ui-static open-xchange-guard-backend-plugin
or the following for a distributed installation:

$ yum update
$ yum install open-xchange-guard open-xchange-guard-file-storage

The packages <code>open-xchange-guard-ui</code> <code>open-xchange-rest</code> and <code>open-xchange-guard-backend-plugin</code> missing in the distributed installation have to be installed on the node running the middleware. The package <code>open-xchange-guard-ui-static</code> must be installed in the frontend (apache node).

=== SUSE Linux Enterprise Server 12 (valid until 2.10.3) ===

Add the package repository using zypper if not already present:

$ zypper ar https://software.open-xchange.com/products/guard/2.10.3/guard/SLE_12 guard-stable-guard
$ zypper ar https://software.open-xchange.com/products/appsuite/7.10.3/backend/SLE_12 ox-backend

and then run for a single node installation:

$ zypper ref
$ zypper in open-xchange-rest open-xchange-guard open-xchange-guard-file-storage open-xchange-guard-ui open-xchange-guard-ui-static

or the following for a distributed installation:

$ zypper ref
$ zypper in open-xchange-guard open-xchange-guard-file-storage

The packages <code>open-xchange-guard-ui</code> <code>open-xchange-rest</code> and <code>open-xchange-guard-backend-plugin</code> missing in the distributed installation have to be installed on the node running the middleware. The package <code>open-xchange-guard-ui-static</code> must be installed in the frontend (apache node).

=== Univention Corporate Server ===

If you have purchased the OX App Suite for UCS, the OX Guard is part of the offering. OX Guard is available in the Univention App Center. Please check the UMC module App Center for the installation of the OX Guard at your already available environment.

Please note: By default, OX Guard generates the link to the secure content for external recipients on the basis of the local fully qualified domain name (FQDN). If the local FQDN is not reachable from the Internet, it has to be specified manually. This can be done by setting a UCR variable, e.g. via the UMC module "Univention Configuration Registry". The variable has to contain the external FQDN of the OX Guard system:

<source lang="bash">oxguard/cfg/guard.properties/com.openexchange.guard.externalEmailURL=HOSTNAME.DOMAINNAME</source>

== Update OX Guard ==

This section contains information about updating a 2.10.0 version (e.g. for patch fixes). Upgrading from prior versions is discussed in different articles.

=== Debian Linux 9.0 (Stretch) ===

If not already done, add the following repositories to your Open-Xchange apt configuration:

deb <https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/guard/stable/guard/updates/DebianStretch />
deb <https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/appsuite/stable/backend/DebianStretch /</source>>

Then run:

$ apt-get update
$ apt-get dist-upgrade</source>

If you want to see, what apt-get is going to do without actually doing it, you can run:

$ apt-get dist-upgrade -s</source>

=== Redhat Enterprise Linux 6 or CentOS 6 (valid until 2.10.3) ===

If not already done, add the following repositories to your Open-Xchange yum configuration:

[open-xchange-guard-stable-guard-updates]
name=Open-Xchange-guard-stable-guard-updates
baseurl=https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/guard/2.10.3/guard/updates/RHEL6/
gpgkey=https://software.open-xchange.com/oxbuildkey.pub
enabled=1
gpgcheck=1
metadata_expire=0m

[ox-backend]
name=Open-Xchange-backend
baseurl=https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/appsuite/7.10.3/backend/updates/RHEL6/
gpgkey=https://software.open-xchange.com/oxbuildkey.pub
enabled=1
gpgcheck=1
metadata_expire=0m</source>

and then run:

$ yum update
$ yum upgrade</source>

=== Redhat Enterprise Linux 7 or CentOS 7 ===

If not already done, add the following repositories to your Open-Xchange yum configuration:

[open-xchange-guard-stable-guard-updates]
name=Open-Xchange-guard-stable-guard-updates
baseurl=https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/guard/stable/guard/updates/RHEL7/
gpgkey=https://software.open-xchange.com/oxbuildkey.pub
enabled=1
gpgcheck=1
metadata_expire=0m

[ox-backend]
name=Open-Xchange-backend
baseurl=https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/appsuite/stable/backend/updates/RHEL7/
gpgkey=https://software.open-xchange.com/oxbuildkey.pub
enabled=1
gpgcheck=1
metadata_expire=0m</source>

and then run:

$ yum update
$ yum upgrade</source>

=== SUSE Linux Enterprise Server 12 (valid until 2.10.3) ===

Add the package repository using <code>zypper</code> if not already present:

$ zypper ar https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/guard/2.10.3/guard/updates/SLE_12 guard-stable-guard-updates
$ zypper ar https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/appsuite/7.10.3/backend/updates/SLE_12 ox-backend</source>

and then run:

$ zypper dup -r guard-stable-guard-backend-updates
$ zypper dup -r guard-stable-guard-ui-updates</source>

You might need to run:

$ zypper ref</source>

to update the repository metadata before running <code>zypper</code> up.

=== Univention Corporate Server ===

If you have purchased the OX App Suite for UCS, the OX Guard is part of the offering. OX Guard is available in the Univention App Center. Please check the UMC module App Center for the update of the OX Guard.

== Configuration ==

The following gives an overview of the most important settings to enable Guard for users on the Open-Xchange installation. Some of those settings have to be modified in order to establish the database and REST API access from the Guard service. All settings relating to the Guard backend component are located in the configuration file <code>guard-core.properties</code> located in <code>/opt/open-xchange/etc</code>. The default configuration should be sufficient for a basic "up-and-running" setup (with the exception of defining the database username and password). Please refer to the inline documentation of the configuration file for more advanced options. Additional information can be found in the [https://oxpedia.org/wiki/index.php?title=AppSuite:OX_Guard_Configuration_2_10 Guard Configuration] article.

=== Basic Configuration ===

<source lang="bash">$ vim /opt/open-xchange/etc/guard-core.properties</source>
Guard database for storing Guard user information, main lookup tables:

<source lang="bash">com.openexchange.guard.oxguardDatabaseHostname=localhost</source>
Guard database that stores keys for guest users. May be the same as above. New guest shards will be created on this database as needed. If not supplied, will use the <code>oxguardDatabaseHostname</code>:

<source lang="bash">com.openexchange.guard.oxguardShardDatabase=localhost</source>
Username and Password for the databases above:

<source lang="bash">com.openexchange.guard.databaseUsername=openexchange
com.openexchange.guard.databasePassword=db_password</source>
Open-Xchange REST API host:

<source lang="bash">com.openexchange.guard.restApiHostname=localhost</source>
Open-Xchange REST API username and password (need to be defined in the OX backend in the "Configure services" below):

<source lang="bash">com.openexchange.guard.restApiUsername=apiusername
com.openexchange.guard.restApiPassword=apipassword</source>
External URL for this Open-Xchange installation. This setting will be used to generate the link to the secure content for external recipients:

<source lang="bash">com.openexchange.guard.externalEmailURL=URL_TO_OX</source>
=== Middleware Configuration on OX Guard node ===

If you are installing OX Guard on a node that until yet did not host an Open-Xchange middleware you have to additionally configure some parts of the following properties files:

* <code>configdb.properties</code>: information about the existing configuration database.
* <code>server.properties</code>: information about the connections have to be set.
* <code>system.properties</code>: at least <code>SERVER_NAME</code> should be set.

=== Sevices Configuration ===

==== Apache ====

Configure the <code>mod_proxy_http</code> module by adding the Guard API.

Debian GNU/Linux 9.0 and 10.0
<source lang="bash">$ vim /etc/apache2/sites-enabled/000-default.conf</source>

Redhat Enterprise Linux 6/7 or CentOS 6/7
<source lang="bash">$ vim /etc/httpd/conf.d/ox.conf</source>

Add the following section into VirtualHost definition:

<Directory /var/www/html/guard>
Options -Indexes
</Directory>

Debian GNU/Linux 9.0 and 10.0
<source lang="bash">$ vim /etc/apache2/conf-enabled/proxy_http.conf</source>

Redhat Enterprise Linux 6/7 or CentOS 6/7
<source lang="bash">$ vim /etc/httpd/conf.d/proxy_http.conf</source>

<Proxy balancer://oxguard>
Order deny,allow
Allow from all

BalancerMember http://localhost:8009/ timeout=1800 smax=0 ttl=60 retry=60 loadfactor=100 route=OX1
ProxySet stickysession=JSESSIONID|jsessionid scolonpathdelim=ON
SetEnv proxy-initial-not-pooled
SetEnv proxy-sendchunked
</Proxy>

ProxyPass /appsuite/api/oxguard balancer://oxguard/oxguard
ProxyPass /pks balancer://oxguard/pgp
ProxyPass /.well-known/openpgpkey/hu balancer://oxguard/hu

'''Please Note''': The Guard API settings must be inserted '''''before''''' the existing <code>ProxyPass /appsuite/api</code> parameter.

'''Also Note''': If you already have a Proxy balancer for the OX backend with the same URL (say http://localhost:8080) then you don't need the second BalancerMember entry, and you can just have the ProxyPass address that balancer instead.

After the configuration is done, restart the Apache webserver

<source lang="bash">$ apachectl restart</source>

=== Open-Xchange Middleware Configuration ===

Edit the <code>guard-api.properties</code> configuration file for the OX backend where the guard-backend-plugin was installed. Please remove comments in front of the following settings to the configuration file <code>guard-api.properties</code> on the Open-Xchange backend servers:

<source lang="bash">$ vim /opt/open-xchange/etc/guard-api.properties</source>
<source lang="bash"># OX Guard general permission, required to activate Guard in the AppSuite UI.
com.openexchange.capability.guard=true

# Default theme template id for all users that have no custom template id configured.
com.openexchange.guard.templateID=0</source>
Configure the API username and password that you assigned to Guard in the <code>server.properties</code> file:

<source lang="bash">$ vim /opt/open-xchange/etc/server.properties</source>
<source lang="bash"># Specify the user name used for HTTP basic auth by internal REST servlet
com.openexchange.rest.services.basic-auth.login=apiusername

# Specify the password used for HTTP basic auth by internal REST servlet
com.openexchange.rest.services.basic-auth.password=apipassword</source>
Finally, the OX backend needs to know where the Guard server is located. This is used to notify the Guard server of changes in users, and to send emails marked for signature. The URL for the Guard server should include the URL suffix <code>/guardadmin</code>. In the event of a cluster setup, any Guard server can be referenced here, as it is not session specific, though ideally would have a HTTP load balancer/failover URL:

<source lang="bash">$ vim /opt/open-xchange/etc/guard-api.properties</source>
<source lang="bash"># Specifies the URI to the OX Guard end-point; e.g. http://guard.host.invalid:8081/guardadmin
# Default is empty
com.openexchange.guard.endpoint=http://guardserver:8009/guardadmin</source>
Restart the OX backend

<source lang="bash">$ /etc/init.d/open-xchange restart</source>
==== SELinux ====

Running SELinux prohibits your local Open-Xchange backend service to connect to localhost:8009, which is where the Guard backend service listens to. In order to allow localhost connections to 8009 execute the following:

<source lang="bash">$ setsebool -P httpd_can_network_connect 1</source>
=== Generating the <code>oxguardpass</code> ===

Once the Guard configuration (database and backend configuration) and the service configuration has been applied, the Guard administration script needs to be executed in order to create the master password file in <code>/opt/open-xchange/etc/oxguardpass</code>. The initiation only needs to be done '''once''' for a multi server setup, for details please see the sections '''Optional''' and/or '''Clustering'''.

'''Please Note''': If you run a cluster of OX / Guard nodes, only execute this command on '''ONE''' node. Not on all nodes! See [https://oxpedia.org/wiki/index.php?title=AppSuite:GuardCluster OX Guard Clustering] for details.

<source lang="bash">$ /opt/open-xchange/sbin/guard --init</source>
'''Please Note''': It is important to understand that the master password file located at <code>/opt/open-xchange/etc/oxguardpass</code> is required to reset user passwords; without them the administrator will not be able to reset user passwords anymore in the future. The file contains the passwords used to encrypt the master database key, as well as passwords used to encrypt protected data in the users table. It must be the same on all Guard servers.

=== Test Setup ===

Not required, but it is a good idea to test the Guard setup before enabling for any users. The test function will verify that Guard has a good connection to the OX backend, and that it can resolve email addresses to users.

To test, use an email address that exists on the OX backend (john@example.com for this example)

<source lang="bash">/opt/open-xchange/sbin/guard --test john@example.com</source>
Guard should return information from the OX backend regarding the user associated with "john@example.com". Problems resolving information for the user should be resolved before using Guard. Check Rest API passwords and settings if errors returned.

=== Enabling Guard for Users ===

Guard provides three capabilities for users in the environment as well as a basic "core" level:

* Guard: <code>com.openexchange.capability.guard</code>
* Guard Mail: <code>com.openexchange.capability.guard-mail</code>
* Guard Drive: <code>com.openexchange.capability.guard-drive</code>
* Guard Docs: <code>com.openexchange.capability.guard-docs</code>

The "core" Guard enabled a basic read functionality for Guard encrypted emails. We recommend enabling this for all users, as this allows all recipients to read Guard emails sent to them. Great opportunity for upsell. Recipients with only Guard enabled can then do a secure reply to the sender, but they can't start a new email or add recipients.

'''Guard Mail''', '''Guard Drive''' and '''Guard Docs''' are additional options for users. "Guard Mail" allows users the full functionality of Guard emails. "Guard Drive" allows for encryption and decryption of Drive files and "Guard Docs" allows direct integration of Guard into Documents.

Each of those three Guard components is enabled for all users that have the according capability configured. Please note that users need to have the Drive permission set to use Guard Drive. So the users that have Guard Drive enabled must be a subset of those users with OX Drive permission. Since v7.6.0 we enforce this via the default configuration. Those capabilities can be activated for specific user by using the Open-Xchange provisioning scripts:

==== Guard Mail: ====

<source lang="bash">$ /opt/open-xchange/sbin/changeuser -c 1 -A oxadmin -P admin_password -u testuser --config/com.openexchange.capability.guard-mail=true</source>
==== Guard Drive: ====

<source lang="bash">$ /opt/open-xchange/sbin/changeuser -c 1 -A oxadmin -P admin_password -u testuser --config/com.openexchange.capability.guard-drive=true</source>
'''Please Note''': Guard Drive requires Guard Mail to be configured for the user as well. In addition, these capabilities may be configured globally by editing the <code>guard-api.properties</code> file on the OX backend.

=== External Guest recipients ===
Starting in Guard 2.10.0, when an encrypted email is sent to a user that does not have Guard, a guest account is created for them in appsuite. The recipient uses the Guest account to read the encrypted email. These guest users MUST have guard capabilities. To do this, guard capability must be added to guest accounts.
<code>/opt/open-xchange/etc/share.properties</code>
<source lang="bash">com.openexchange.share.guestCapabilityMode=static
com.openexchange.share.staticGuestCapabilities=guard</source>
In a distributed system, the Guest accounts should not be considered transient. Guard servers must be able to verify the guest account exists in the session storage services.
<source lang="bash">com.openexchange.share.transientSessions=false</source>

=== Guest Storage ===
When an encrypted email is sent to an external Guest, a copy of the fully encrypted email is stored on the server. This is used to create an inbox of encrypted emails for the guest. By entering in a password, the emails can be decrypted and displayed.

How these files are stored depend on which package, open-xchange-guard-file-storage or open-xchange-guard-s3-storage, was installed.

The file retention policy is configured in the guard-core.properties file.

=== Recipient key detection ===

==== Local ====

Guard needs to determine if an email recipients email address is an internal or external (non-ox) user.

To detect if the recipient is an account on the same OX Guard system there is a mechanism needed to map a recipient mail address to the correct local OX context. The default implementation delivered in the product achieves that by looking up the mail domain (@example.com) within the list of context mappings. That is at least not possible in case of ISPs where different users/contexts use the same mail domain. In case your OX system does not use mail domains in context mappings it is required to deploy an OX OSGi bundle implementing the <code>com.openexchange.mailmapping.MailResolver</code> class or by interfacing Guard with your mail resolver system. Please see [https://oxpedia.org/wiki/index.php?title=AppSuite:GuardMailResolver OX Guard Mail Resolver] for details.

==== External ====

Starting with Guard 2.0, Guard will use public PGP Key servers if configured to find PGP Public keys. In addition, Guard will also look up SRV records for PGP Key servers for a recipients domain. This follows the standards [http://tools.ietf.org/html/draft-shaw-openpgp-hkp-00#page-9 OpenPGP Draft].

External PGP servers to use can be configured in the guard.properties file on the Guard servers.

<source lang="bash">com.openexchange.guard.publicPGPDirectory = hkp://keys.gnupg.net:11371, hkp://pgp.mit.edu:11371</source>

If you would like this Guard installation discoverable as HKP service by other Guard servers, then create an SRV record for each domain ("example.com" in this illustration):

<source lang="bash">_hkp._tcp.example.com. 28800 IN SRV 10 1 80 appsuite.example.com.</source>

'''Please Note''' PGP Public key servers by default append the path /pks when the record is obtained from an SRV record. The proxy (also included in Apache config above) routes anything under /pks to the OX Guard PGP server.
<source lang="bash">ProxyPass /pks balancer://oxguard/pgp</source>

Guard keys are also discoverable using the webkey service as specified here: https://tools.ietf.org/html/draft-koch-openpgp-webkey-service-02
This is enabled if you include the
<source lang="bash">ProxyPass /.well-known/openpgpkey/hu balancer://oxguard/hu</source>
in the proxy_http.conf as above.
Please note that the well-known request is targeted at the domain part of the mail address. Therefore clients will request for a mail address name@example.com the URI https://example.com/.well-known/openpgpkey/hu/...

That means that there is the very likely need that some sort of proxying or rewriting from the webserver providing the domain needs to happen. For example for proxying using Apache 2.4 it would roughly look like this:

<source lang="bash">
SSLProxyEngine on
<LocationMatch /.well-known/openpgpkey/>
ProxyPass https://ox.example.com/.well-known/openpgpkey/
</LocationMatch>
</source>

=== Clustering ===

You can run multiple OX Guard servers in your environment to ensure high availability or enhance scalability. OX Guard integrates seamlessly into the existing Open-Xchange infrastructure by using the existing interface standards and is therefor transparent to the environment. A couple of things have to be prepared in order to loosely couple OX Guard servers with Open-Xchange servers in a cluster.

==== MySQL ====

The MySQL servers need to be configured in order to allow access to the configdb of Open-Xchange. To do so you need to set the following configuration in the MySQL <code>my.cnf</code>:

<source lang="bash">bind = 0.0.0.0</source>
This allows the Guard backend to bind to the MySQL host which is configured in the <code>guard-core.properties</code> file with <code>com.openexchange.guard.configdbHostname</code>. After the bind for the MySQL instance is configured and the OX Guard backend would be able to connect to the configured host, you have to grant access for the OX Guard service on the MySQL instance to manage the databases. Do so by connecting to the MySQL server via the MySQL client. Authenticate if necessary and execute the following, please note that you have to modify the hostname / IP address of the client who should be able to connect to this database, it should include all possible OX Guard servers:

<source lang="sql">GRANT ALL PRIVILEGES ON *.* TO 'openexchange'@'oxguard.example.com' IDENTIFIED BY ‘secret’;</source>

==== Apache ====

OX Guard uses the Open-Xchange REST API to store and fetch data from the Open-Xchange databases. The REST API is a servlet running in the Grizzly container. By default it is not exposed as a servlet through Apache and is only accessibly via port 8009. In order to use Apache's load balancing via <code>mod_proxy</code> we need to add a servlet called "preliminary" to <code>proxy_http.conf</code>, example based on a clustered <code>mod_proxy</code>configuration:

<Location /preliminary>
Order Deny,Allow
Deny from all
# Only allow access from Guard 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.
</Location>

ProxyPass /preliminary balancer://oxcluster/preliminary

Make sure that the balancer is properly configured in the <code>mod_proxy</code> configuration. Examples on how to do so can be found in our clustering configuration for Open-Xchange AppSuite. Like explained in the example above, please make sure that this location is only available in your internal network, there is no need to expose <code>/preliminary</code> to the public, it is only used by Guard servers to connect to the OX backend. If you have a load balancer in front of the Apache cluster you should consider blocking access to <code>/preliminary</code> from WAN to restrict access to the servlet to internal network services only.

Now add the OX Guard <code>BalancerMembers</code> to the oxguard balancer configuration (also in <code>proxy_http.conf</code>) to address all your OX Guard nodes in the cluster in this balancer configuration. The configuration has to be applied to all Apache nodes within the cluster.

If the Apache server is a dedicated server <code>/</code> instance you also have to install the OX Guard UI-Static package on all Apache nodes in the cluster in order to provide static files like images or CSS to the OX Guard client. Example for Debian (the OX Guard repository has to be configured in the package management prior):

<source lang="bash">$ apt-get install open-xchange-guard-ui-static</source>

==== Open-Xchange ====

Disable the Open-Xchange IPCheck for session verification. This is required because OX Guard will use the users session cookie to connect to the Open-Xchange REST API, but as a different IP address than the OX Guard server has been used during authentication the request would fail if you don't disable the IPCheck:

<source lang="bash">$ vim /opt/open-xchange/etc/server.properties</source>
and set:

<source lang="bash">com.openexchange.IPCheck=false</source>
The OX Guard UI package has to be installed on all Open-Xchange backend nodes as well, example for Debian (the OX Guard repository has to be configured in the package management prior):

<source lang="bash">$ apt-get install open-xchange-guard-ui</source>
Restart the Open-Xchange service afterwards.

==== OX Guard ====

For details in clustering Guard servers, please see [https://oxpedia.org/wiki/index.php?title=AppSuite:GuardCluster OX Guard Clustering]. It is '''critical''' that all Guard servers have the same <code>oxguardpass</code> file. Please see the clustering link for details. Do not run <code>/opt/open-xchange/sbin/guard --init</code> on more than one server.

After all the services like MySQL, Apache and Open-Xchange have been configured you need to update the OX Guard backend configuration to point to the correct API endpoints. Set the REST API endpoint to an Apache server by setting the following value in <code>/opt/open-xchange/etc/guard-core.properties</code>:

<source lang="bash">com.openexchange.guard.restApiHostname=apache.example.com</source>
Per default Guard will try to connect to port 8009 to this host, but as we configured the REST API to be proxies thorugh the servlet <code>/preliminary</code> on every Apache we now also need to change the target port for the REST API. You can do so by adding the following line into <code>/opt/open-xchange/etc/guard-core.properties</code>:

<source lang="bash">com.openexchange.guard.oxBackendPort=80</source>
Please also change all settings in regards to MySQL like <code>com.openexchange.guard.configdbHostname</code>, <code>com.openexchange.guard.oxguardDatabaseHostname</code>, <code>com.openexchange.guard.databaseUsername</code> or <code>om.openexchange.guard.databasePassword</code>.

Afterwards restart the OX Guard service and check the log file if the OX Guard backend is able to connect to the configured REST API.

=== Multi Node ===

If you have multiple OX and Guard installations, please see the following documentation [https://oxpedia.org/wiki/index.php?title=AppSuite:OX_Guard_Modular OX Guard Modular Setup].

=== Mail Filter Integration (2.10.4+) ===

To add additional mail filter tests (verify PGP signature, or encrypt incoming), please see
[[AppSuite:OX_Guard_MailFilter | MailFilter Integration]]

== Support API ==

The OX Guard Support API enables administrative access to various functions for maintaining OX Guard from a client in a role as a support employee. A client has to do a BASIC AUTH authentication in order to access the API. Username and password can be configured in the guard-core.properties file using the following settings:

# Specify the username and password for accessing the Support API of Guard
com.openexchange.guard.supportApiUsername=
com.openexchange.guard.supportApiPassword=

In contrast to the rest of the OX Guard requests, the OX Guard support API requests are accessible using: /guardsupport. This distinction allows more flexible configuration since the support API should not always be accessible from everywhere.

'''Warning''': Exposing the support API to the internet could be huge security risk. Only add to Apache if you know what you are doing.

=== Reset password ===

<code>POST /guardsupport/?action=reset_password</code>

Performs a password reset and sends a new random generated password to a specified email address by the user or a default address if the user did not specify an email address. (''Since Guard 2.0'')

Parameters:

* <code>email</code> – The email address of the user to reset the password for
* <code>default</code> (optional) – The email address to send the new password to, if the user did not specify a secondary email address

Response:
PRIMARY if the reset was sent to the primary email address. SECONDARY if the reset email was sent to the secondary email address that the user specified

=== Expose key ===

<code>POST /guardsupport/?action=expose_key</code>

Marks a deleted user key temporary as “exposed” and creates a unique URL for downloading the exposed key. Automatic resetting of exposed keys to "not exposed" is scheduled once a day and resets all exposed keys which have been exposed before X hours, where X can be configured using com.openexchange.guard.exposedKeyDurationInHours in the guard.properties files. (''Since Guard 2.0'')

Parameters:

* <code>email</code> – The email address of the user to expose the deleted keys for
* <code>cid</code> – The context id

Response: A URL pointing to the downloadable exposed keys.

=== Delete user ===

<code>POST /guardsupport/?action=delete_user</code>

Deletes all keys related to a certain user. The keys are backed up and can be exposed using the “expose_key” call. (''Since Guard 2.0'')

Parameters:

* <code>user_id</code> – The user's id
* <code>cid</code> - The context id

=== Upgrade User (Release 2.10 and later) ===

<code>POST /guardsupport/?action=upgrade_guest</code>

Upgrades a Guest account. This action copies all of the keys from the Guest account to a full OX account, assuming that user has Guard capabilities.

Parameters:

* <code>email</code> - The email address of the Guest user
* <code>user_id</code> – The user's new id
* <code>cid</code> - The user's new context id

== Customisation ==

Guard's templates are customisable at the user and context level. Please see [https://oxpedia.org/wiki/index.php?title=AppSuite:GuardCustomization Customisation] for details.

== Entropy ==

Guard requires entropy (randomness) to generate the private/public keys that are used. Depending on the server and it's environment, this may become a problem. Please see [https://oxpedia.org/wiki/index.php?title=AppSuite:GuardEntropy Entropy] for a possible solution.

AppSuite:Available Translations

2020-11-18T14:51:23Z

WolfgangRosenauer:

= Open-Xchange Server Translations for OX App Suite =

=== Available Language Translations ===

{| border="1" cellpadding="3" cellspacing="0"
!align="left" |Language
!align="left" |Code
!align="left" |Status
!align="left" |Documentation
!align="left" |Contributor
|-
| [[Image:Flag_us.png]] US English
| en_US
| Supported
| Online Help/Manual
| Open-Xchange
|-
| [[Image:Flag_gb.png]] British English
| en_GB
| Supported
| Online Help/Manual
| Open-Xchange
|-
| [[Image:Flag_de.png]] German
| de_DE
| Supported
| Online Help/Manual
| Open-Xchange
|-
| [[Image:Flag_fr.png]] French
| fr_FR
| Supported
| Online Help/Manual
| Open-Xchange
|-
| [[Image:Flag_cn.png]] Canadian French
| fr_CA
| Supported
|
| Open-Xchange
|-
| [[Image:Flag_es.png]] Spanish
| es_ES
| Supported
| Online Help/Manual
| Open-Xchange
|-
| [[Image:Flag_mx.png]] Mexican Spanish
| es_MX
| Supported
| Online Help/Manual
| Open-Xchange
|-
| [[Image:Flag_nl.png]] Dutch
| nl_NL
| Supported
| Online Help/Manual
| Open-Xchange
|-
| [[Image:Flag_pl.png]] Polish
| pl_PL
| Supported
| Online Help/Manual
| Open-Xchange
|-
| [[Image:japanese.jpeg]] Japanese
| ja_JP
| Supported
| Online Help/Manual
| Open-Xchange
|-
| [[Image:Flag_it.png]] Italian
| it_IT
| Supported
| Online Help/Manual
| Open-Xchange
|-
| [[Image:china.jpg]] Simplified Chinese
| zh_CN
| Supported
| Online Help/Manual
| Open-Xchange
|-
| [[Image:china.jpg]] Traditional Chinese
| zh_TW
| Supported
| Online Help/Manual
| Open-Xchange
|-
| [[Image:ungarn.jpg]] Hungarian
| hu_HU
| Supported
|
| Open-Xchange
|-
| [[Image:Slovakia.jpg]] Slovak
| sk_SK
| Supported
|
| Open-Xchange
|-
| [[Image:Czech.jpg]] Czech
| cs_CZ
| Supported
|
| Open-Xchange
|-
| [[Image:latvia.jpg]] Latvian
| lv_LV
| Supported
|
| Open-Xchange
|-
|[[Image:Flag_romania.png]] Romanian
| ro_RO
| Supported
|
| Open-Xchange
|-
| [[Image:brazil.png|17px]] Brazilian Portuguese
| pt_BR
| Supported
|
| Open-Xchange
|-
| [[File:Flag_se.png|17px]] Swedish
| sv_SE
| Supported
|
| Open-Xchange
|-
| [[File:Flag_dk.png|17px]] Danish
| da_DK
| Supported
|
| Open-Xchange
|-
| [[File:Russian.png|17px]] Russian
| ru_RU
| Supported
|
| Open-Xchange
|-
| [[File:flag_fin.png|17px]] Finnish
| fi_FI
| Supported
|
| Open-Xchange
|-
| [[File:flag_Tur.png|17px]] Turkish
| tr_TR
| Supported
| Online Help/Manual
| Open-Xchange
|}

'''Any other languages which may be provided by installation packages are not supported and might even have a bad UI/UX impact when installed. Please use at your own risk!'''

[[Category: OX7]]
[[Category: AppSuite]]

AppSuite:OX Guard

2020-11-04T22:52:23Z

WolfgangRosenauer: /* Enabling Guard for Users */

= OX Guard (Version 2.10) =

For previous versions of OX Guard, please click here
* [[AppSuite:OX_Guard_2-0 | Installation and information of OX Guard 2.0 - 2.2]]
* [[Appsuite:OX_Guard_2_8 | Installation and information of OX Guard 2.4 - 2.8]]

If upgrading from 2.6 or 2.8, please see
* [[Appsuite:OX_Guard_Upgrade_2_10|Upgrading to 2.10]]

== Overview ==

OX Guard is a fully integrated security add-on to OX App Suite that provides end users with a flexible email and file encryption solution. OX Guard is a highly scalable, multi server, feature rich solution that is so simple-to-use that end users will actually use it. With a single click a user can take control of their security and send secure emails and share encrypted files. This can be done from any device to both OX App Suite and non-OX App Suite users.

OX Guard uses standard PGP encryption for the encryption of email and files. PGP has been around for a long time, yet has not really caught on with the masses. This is generally blamed on the confusion and complications of managing the keys, understanding trust, PGP format types, and lack of trusted central key repositories. Guard simplifies all of this, making PGP encryption as easy as a one click process, with no keys to keep track of, yet the options of advanced PGP management for those that know how.

This article will guide you through the installation of Guard and describes the basic configuration and software requirements. As it is intended as a quick walk-through it assumes an existing installation of the operating system including a single server App Suite setup as well as average system administration skills. This guide will also show you how to setup a basic installation with none of the typically used distributed environment settings. The objective of this guide is:

* To setup a single server installation
* To setup a single Guard instance on an existing Open-Xchange installation, no cluster
* To use the database service on the existing Open-Xchange installation for Guard, no replication
* To provide a basic configuration setup, no mail server configuration

=== Key Features ===

* Simple security at the touch of a button
* Provides user based security - Separate from provider
* Supplementary security to Provider based security - Layered
* Powerful features yet simple to use and understand
* Security - Inside and outside of the OX environment
* Email and Drive integration
* Uses proven PGP security

=== Availability ===

If an OX App Suite customer would like to evaluate OX Guard integration, the first step is to contact OX Sales. OX Sales will then work on the request and send prices and license/API (for the hosted infrastructure) key details to the customer.

=== Requirements ===

Please review [https://oxpedia.org/wiki/index.php?title=AppSuite:OX_System_Requirements#OX_Guard OX Guard Requirements] for a full list of requirements.

Since OX Guard is a Microservice it can either be added to an existing Open-Xchange installation or it can be deployed on a dedicated environment. The version of Guard installed is dependent on the Appsuite version installed. Please refer to the version matrix below.

==== Prerequisites ====

* Open-Xchange REST API
* Grizzly HTTP connector (open-xchange-grizzly)
* A supported Java Virtual Machine (Java 8)
* An Open-Xchange App Suite installation (see version Matrix)
* Please Note: To get access to the latest minor features and bug fixes, you need to have a valid license. The article [https://oxpedia.org/wiki/index.php?title=AppSuite:UpdatingOXPackages Updating OX-Packages] explains how that can be done.

==== Version Matrix ====
{|
! style="text-align:left;"| Core Version
! Guard Version
|-
|7.8.1
|2.4.0 or 2.4.2
|-
|7.8.2
|2.4.2
|-
|7.8.3
|2.6.0
|-
|7.8.4
|2.8.0
|-
|7.10.0
|2.10.0
|-
|7.10.1
|2.10.1
|-
|7.10.2
|2.10.2
|-
|7.10.3
|2.10.3
|-
|7.10.4
|2.10.4
|}

=== Important Notes ===

==== Customisation ====

OX Guard version supports branding / theming using the configuration cascade, defining a templateID for a user or context. Check the [https://oxpedia.org/wiki/index.php?title=AppSuite:GuardCustomization OX Guard Customisation] article for more details.

==== Mail Resolver ====

READ THIS VERY CAREFULLY; BEFORE PROCEEDING WITH GUARD INSTALLATION!

The Guard installation must be able to determine if an email recipient is a local OX user or if it should be a guest account. The default MailResolver uses the context domain name to do this. On many installations, domains may extend across multiple context and multiple database shards. In these cases, the default MailResolver won't work. In addition, if a custom authentication package is used, the Mail Resolver will likely not work.

Once Guard is installed, please be sure to test the mail resolver using:

<source lang="bash">/opt/open-xchange/sbin/guard test email@domain</source>
to see if the mail Resolver works.

If the test does not work, you will likely need a custom Mail Resolver. Please see [https://oxpedia.org/wiki/index.php?title=AppSuite:GuardMailResolver Mail Resolver] page

This resolver software ''depends heavily on your local deployment''.

== Download and Installation ==

=== General ===

The installation of the <code>open-xchange-guard-backend-plugin</code> package which is required for Guard and the main <code>open-xchange-guard</code> package in version 2.4.0 or higher will eventually execute database update tasks if installed and activated. Please take this into account.

There are several components to the Guard service. They can be all installed on the same server as the OX middleware or on a separate server.

The components required for the OX middleware are: <code>open-xchange-rest</code>, <code>open-xchange-guard-backend-plugin</code> and <code>open-xchange-guard-ui</code>.

The components required for the OX frontend are: <code>open-xchange-guard-ui-static</code> and optionally <code>open-xchange-guard-help-en-us</code> (or preferred language for help files).

The components required for the Guard server <code>open-xchange-guard</code> and either <code>open-xchange-guard-file-storage</code> or <code>open-xchange-guard-s3-storage</code> depending on what storage you want to use. The examples below make use of the <code>open-xchange-guard-file-storage</code>. Adjust the commands accordingly to fit your needs. In addition <code>open-xchange</code> and <code>open-xchange-core</code> are required to run OX Guard.

=== Debian Linux 9.0 (Stretch) ===

If not already done, add the following repositories to your Open-Xchange apt configuration:

deb https://software.open-xchange.com/products/guard/stable/guard/DebianStretch /
deb https://software.open-xchange.com/products/appsuite/stable/backend/DebianStretch /

and then run for a single node installation:

$ apt-get update
$ apt-get install open-xchange-rest open-xchange-guard open-xchange-guard-file-storage open-xchange-guard-ui open-xchange-guard-ui-static open-xchange-guard-backend-plugin

or the following for a distributed installation:

$ apt-get update
$ apt-get install open-xchange-guard open-xchange-guard-file-storage
The packages <code>open-xchange-guard-ui</code> <code>open-xchange-rest</code> and <code>open-xchange-guard-backend-plugin</code> missing in the distributed installation have to be installed on the node running the middleware. The package <code>open-xchange-guard-ui-static</code> must be installed in the frontend (apache node).

=== Debian Linux 10.0 (Buster) *Version 2.10.3+ only* ===

If not already done, add the following repositories to your Open-Xchange apt configuration:

deb https://software.open-xchange.com/products/guard/stable/guard/DebianBuster /
deb https://software.open-xchange.com/products/appsuite/stable/backend/DebianBuster /

and then run for a single node installation:

$ apt-get update
$ apt-get install open-xchange-rest open-xchange-guard open-xchange-guard-file-storage open-xchange-guard-ui open-xchange-guard-ui-static open-xchange-guard-backend-plugin

or the following for a distributed installation:

$ apt-get update
$ apt-get install open-xchange-guard open-xchange-guard-file-storage
The packages <code>open-xchange-guard-ui</code> <code>open-xchange-rest</code> and <code>open-xchange-guard-backend-plugin</code> missing in the distributed installation have to be installed on the node running the middleware. The package <code>open-xchange-guard-ui-static</code> must be installed in the frontend (apache node).

=== RedHat Enterprise Linux 6 or CentOS 6 (valid until v2.10.3) ===

If not already done, add the following repositories to your Open-Xchange yum configuration:

[open-xchange-guard-stable-guard]
name=Open-Xchange-guard-stable-guard
baseurl=https://software.open-xchange.com/products/guard/2.10.3/guard/RHEL6/
gpgkey=https://software.open-xchange.com/oxbuildkey.pub
enabled=1
gpgcheck=1
metadata_expire=0m

[ox-backend]
name=Open-Xchange-backend
baseurl=https://software.open-xchange.com/products/appsuite/7.10.3/backend/RHEL6/
gpgkey=https://software.open-xchange.com/oxbuildkey.pub
enabled=1
gpgcheck=1
metadata_expire=0m

and then run for a single node installation:

$ yum update
$ yum install open-xchange-rest open-xchange-guard open-xchange-guard-file-storage open-xchange-guard-ui open-xchange-guard-ui-static open-xchange-guard-backend-plugin
or the following for a distributed installation:

$ yum update
$ yum install open-xchange-guard open-xchange-guard-file-storage
The packages <code>open-xchange-guard-ui</code> <code>open-xchange-rest</code> and <code>open-xchange-guard-backend-plugin</code> missing in the distributed installation have to be installed on the node running the middleware. The package <code>open-xchange-guard-ui-static</code> must be installed in the frontend (apache node).

=== Redhat Enterprise Linux 7 or CentOS 7 ===

If not already done, add the following repositories to your Open-Xchange yum configuration:

[open-xchange-guard-stable-guard]
name=Open-Xchange-guard-stable-guard
baseurl=https://software.open-xchange.com/products/guard/stable/guard/RHEL7/
gpgkey=https://software.open-xchange.com/oxbuildkey.pub
enabled=1
gpgcheck=1
metadata_expire=0m

[ox-backend]
name=Open-Xchange-backend
baseurl=https://software.open-xchange.com/products/appsuite/stable/backend/RHEL7/
gpgkey=https://software.open-xchange.com/oxbuildkey.pub
enabled=1
gpgcheck=1
metadata_expire=0m

and then run for a single node installation:

$ yum update
$ yum install open-xchange-rest open-xchange-guard open-xchange-guard-file-storage open-xchange-guard-ui open-xchange-guard-ui-static open-xchange-guard-backend-plugin
or the following for a distributed installation:

$ yum update
$ yum install open-xchange-guard open-xchange-guard-file-storage

The packages <code>open-xchange-guard-ui</code> <code>open-xchange-rest</code> and <code>open-xchange-guard-backend-plugin</code> missing in the distributed installation have to be installed on the node running the middleware. The package <code>open-xchange-guard-ui-static</code> must be installed in the frontend (apache node).

=== SUSE Linux Enterprise Server 12 (valid until 2.10.3) ===

Add the package repository using zypper if not already present:

$ zypper ar https://software.open-xchange.com/products/guard/2.10.3/guard/SLE_12 guard-stable-guard
$ zypper ar https://software.open-xchange.com/products/appsuite/7.10.3/backend/SLE_12 ox-backend

and then run for a single node installation:

$ zypper ref
$ zypper in open-xchange-rest open-xchange-guard open-xchange-guard-file-storage open-xchange-guard-ui open-xchange-guard-ui-static

or the following for a distributed installation:

$ zypper ref
$ zypper in open-xchange-guard open-xchange-guard-file-storage

The packages <code>open-xchange-guard-ui</code> <code>open-xchange-rest</code> and <code>open-xchange-guard-backend-plugin</code> missing in the distributed installation have to be installed on the node running the middleware. The package <code>open-xchange-guard-ui-static</code> must be installed in the frontend (apache node).

=== Univention Corporate Server ===

If you have purchased the OX App Suite for UCS, the OX Guard is part of the offering. OX Guard is available in the Univention App Center. Please check the UMC module App Center for the installation of the OX Guard at your already available environment.

Please note: By default, OX Guard generates the link to the secure content for external recipients on the basis of the local fully qualified domain name (FQDN). If the local FQDN is not reachable from the Internet, it has to be specified manually. This can be done by setting a UCR variable, e.g. via the UMC module "Univention Configuration Registry". The variable has to contain the external FQDN of the OX Guard system:

<source lang="bash">oxguard/cfg/guard.properties/com.openexchange.guard.externalEmailURL=HOSTNAME.DOMAINNAME</source>

== Update OX Guard ==

This section contains information about updating a 2.10.0 version (e.g. for patch fixes). Upgrading from prior versions is discussed in different articles.

=== Debian Linux 9.0 (Stretch) ===

If not already done, add the following repositories to your Open-Xchange apt configuration:

deb <https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/guard/stable/guard/updates/DebianStretch />
deb <https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/appsuite/stable/backend/DebianStretch /</source>>

Then run:

$ apt-get update
$ apt-get dist-upgrade</source>

If you want to see, what apt-get is going to do without actually doing it, you can run:

$ apt-get dist-upgrade -s</source>

=== Redhat Enterprise Linux 6 or CentOS 6 (valid until 2.10.3) ===

If not already done, add the following repositories to your Open-Xchange yum configuration:

[open-xchange-guard-stable-guard-updates]
name=Open-Xchange-guard-stable-guard-updates
baseurl=https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/guard/2.10.3/guard/updates/RHEL6/
gpgkey=https://software.open-xchange.com/oxbuildkey.pub
enabled=1
gpgcheck=1
metadata_expire=0m

[ox-backend]
name=Open-Xchange-backend
baseurl=https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/appsuite/7.10.3/backend/updates/RHEL6/
gpgkey=https://software.open-xchange.com/oxbuildkey.pub
enabled=1
gpgcheck=1
metadata_expire=0m</source>

and then run:

$ yum update
$ yum upgrade</source>

=== Redhat Enterprise Linux 7 or CentOS 7 ===

If not already done, add the following repositories to your Open-Xchange yum configuration:

[open-xchange-guard-stable-guard-updates]
name=Open-Xchange-guard-stable-guard-updates
baseurl=https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/guard/stable/guard/updates/RHEL7/
gpgkey=https://software.open-xchange.com/oxbuildkey.pub
enabled=1
gpgcheck=1
metadata_expire=0m

[ox-backend]
name=Open-Xchange-backend
baseurl=https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/appsuite/stable/backend/updates/RHEL7/
gpgkey=https://software.open-xchange.com/oxbuildkey.pub
enabled=1
gpgcheck=1
metadata_expire=0m</source>

and then run:

$ yum update
$ yum upgrade</source>

=== SUSE Linux Enterprise Server 12 (valid until 2.10.3) ===

Add the package repository using <code>zypper</code> if not already present:

$ zypper ar https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/guard/2.10.3/guard/updates/SLE_12 guard-stable-guard-updates
$ zypper ar https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/appsuite/7.10.3/backend/updates/SLE_12 ox-backend</source>

and then run:

$ zypper dup -r guard-stable-guard-backend-updates
$ zypper dup -r guard-stable-guard-ui-updates</source>

You might need to run:

$ zypper ref</source>

to update the repository metadata before running <code>zypper</code> up.

=== Univention Corporate Server ===

If you have purchased the OX App Suite for UCS, the OX Guard is part of the offering. OX Guard is available in the Univention App Center. Please check the UMC module App Center for the update of the OX Guard.

== Configuration ==

The following gives an overview of the most important settings to enable Guard for users on the Open-Xchange installation. Some of those settings have to be modified in order to establish the database and REST API access from the Guard service. All settings relating to the Guard backend component are located in the configuration file <code>guard-core.properties</code> located in <code>/opt/open-xchange/etc</code>. The default configuration should be sufficient for a basic "up-and-running" setup (with the exception of defining the database username and password). Please refer to the inline documentation of the configuration file for more advanced options. Additional information can be found in the [https://oxpedia.org/wiki/index.php?title=AppSuite:OX_Guard_Configuration_2_10 Guard Configuration] article.

=== Basic Configuration ===

<source lang="bash">$ vim /opt/open-xchange/etc/guard-core.properties</source>
Guard database for storing Guard user information, main lookup tables:

<source lang="bash">com.openexchange.guard.oxguardDatabaseHostname=localhost</source>
Guard database that stores keys for guest users. May be the same as above. New guest shards will be created on this database as needed. If not supplied, will use the <code>oxguardDatabaseHostname</code>:

<source lang="bash">com.openexchange.guard.oxguardShardDatabase=localhost</source>
Username and Password for the databases above:

<source lang="bash">com.openexchange.guard.databaseUsername=openexchange
com.openexchange.guard.databasePassword=db_password</source>
Open-Xchange REST API host:

<source lang="bash">com.openexchange.guard.restApiHostname=localhost</source>
Open-Xchange REST API username and password (need to be defined in the OX backend in the "Configure services" below):

<source lang="bash">com.openexchange.guard.restApiUsername=apiusername
com.openexchange.guard.restApiPassword=apipassword</source>
External URL for this Open-Xchange installation. This setting will be used to generate the link to the secure content for external recipients:

<source lang="bash">com.openexchange.guard.externalEmailURL=URL_TO_OX</source>
=== Middleware Configuration on OX Guard node ===

If you are installing OX Guard on a node that until yet did not host an Open-Xchange middleware you have to additionally configure some parts of the following properties files:

* <code>configdb.properties</code>: information about the existing configuration database.
* <code>server.properties</code>: information about the connections have to be set.
* <code>system.properties</code>: at least <code>SERVER_NAME</code> should be set.

=== Sevices Configuration ===

==== Apache ====

Configure the <code>mod_proxy_http</code> module by adding the Guard API.

===== Redhat Enterprise Linux 6 or CentOS 6 =====

<source lang="bash">$ vim /etc/httpd/conf.d/proxy_http.conf</source>

===== Debian GNU/Linux 9.0 =====

<source lang="bash">$ vim /etc/apache2/conf-enabled/proxy_http.conf</source>

<Proxy balancer://oxguard>
Order deny,allow
Allow from all

BalancerMember http://localhost:8009/ timeout=1800 smax=0 ttl=60 retry=60 loadfactor=100 route=OX1
ProxySet stickysession=JSESSIONID|jsessionid scolonpathdelim=ON
SetEnv proxy-initial-not-pooled
SetEnv proxy-sendchunked
</Proxy>

ProxyPass /appsuite/api/oxguard balancer://oxguard/oxguard
ProxyPass /pks balancer://oxguard/pgp
ProxyPass /.well-known/openpgpkey/hu balancer://oxguard/hu

'''Please Note''': The Guard API settings must be inserted '''''before''''' the existing <code>ProxyPass /appsuite/api</code> parameter.

'''Also Note''': If you already have a Proxy balancer for the OX backend with the same URL (say http://localhost:8080) then you don't need the second BalancerMember entry, and you can just have the ProxyPass address that balancer instead.

After the configuration is done, restart the Apache webserver

<source lang="bash">$ apachectl restart</source>

=== Open-Xchange Middleware Configuration ===

Edit the <code>guard-api.properties</code> configuration file for the OX backend where the guard-backend-plugin was installed. Please remove comments in front of the following settings to the configuration file <code>guard-api.properties</code> on the Open-Xchange backend servers:

<source lang="bash">$ vim /opt/open-xchange/etc/guard-api.properties</source>
<source lang="bash"># OX Guard general permission, required to activate Guard in the AppSuite UI.
com.openexchange.capability.guard=true

# Default theme template id for all users that have no custom template id configured.
com.openexchange.guard.templateID=0</source>
Configure the API username and password that you assigned to Guard in the <code>server.properties</code> file:

<source lang="bash">$ vim /opt/open-xchange/etc/server.properties</source>
<source lang="bash"># Specify the user name used for HTTP basic auth by internal REST servlet
com.openexchange.rest.services.basic-auth.login=apiusername

# Specify the password used for HTTP basic auth by internal REST servlet
com.openexchange.rest.services.basic-auth.password=apipassword</source>
Finally, the OX backend needs to know where the Guard server is located. This is used to notify the Guard server of changes in users, and to send emails marked for signature. The URL for the Guard server should include the URL suffix <code>/guardadmin</code>. In the event of a cluster setup, any Guard server can be referenced here, as it is not session specific, though ideally would have a HTTP load balancer/failover URL:

<source lang="bash">$ vim /opt/open-xchange/etc/guard-api.properties</source>
<source lang="bash"># Specifies the URI to the OX Guard end-point; e.g. http://guard.host.invalid:8081/guardadmin
# Default is empty
com.openexchange.guard.endpoint=http://guardserver:8009/guardadmin</source>
Restart the OX backend

<source lang="bash">$ /etc/init.d/open-xchange restart</source>
==== SELinux ====

Running SELinux prohibits your local Open-Xchange backend service to connect to localhost:8009, which is where the Guard backend service listens to. In order to allow localhost connections to 8009 execute the following:

<source lang="bash">$ setsebool -P httpd_can_network_connect 1</source>
=== Generating the <code>oxguardpass</code> ===

Once the Guard configuration (database and backend configuration) and the service configuration has been applied, the Guard administration script needs to be executed in order to create the master password file in <code>/opt/open-xchange/etc/oxguardpass</code>. The initiation only needs to be done '''once''' for a multi server setup, for details please see the sections '''Optional''' and/or '''Clustering'''.

'''Please Note''': If you run a cluster of OX / Guard nodes, only execute this command on '''ONE''' node. Not on all nodes! See [https://oxpedia.org/wiki/index.php?title=AppSuite:GuardCluster OX Guard Clustering] for details.

<source lang="bash">$ /opt/open-xchange/sbin/guard --init</source>
'''Please Note''': It is important to understand that the master password file located at <code>/opt/open-xchange/etc/oxguardpass</code> is required to reset user passwords; without them the administrator will not be able to reset user passwords anymore in the future. The file contains the passwords used to encrypt the master database key, as well as passwords used to encrypt protected data in the users table. It must be the same on all Guard servers.

=== Test Setup ===

Not required, but it is a good idea to test the Guard setup before enabling for any users. The test function will verify that Guard has a good connection to the OX backend, and that it can resolve email addresses to users.

To test, use an email address that exists on the OX backend (john@example.com for this example)

<source lang="bash">/opt/open-xchange/sbin/guard --test john@example.com</source>
Guard should return information from the OX backend regarding the user associated with "john@example.com". Problems resolving information for the user should be resolved before using Guard. Check Rest API passwords and settings if errors returned.

=== Enabling Guard for Users ===

Guard provides three capabilities for users in the environment as well as a basic "core" level:

* Guard: <code>com.openexchange.capability.guard</code>
* Guard Mail: <code>com.openexchange.capability.guard-mail</code>
* Guard Drive: <code>com.openexchange.capability.guard-drive</code>
* Guard Docs: <code>com.openexchange.capability.guard-docs</code>

The "core" Guard enabled a basic read functionality for Guard encrypted emails. We recommend enabling this for all users, as this allows all recipients to read Guard emails sent to them. Great opportunity for upsell. Recipients with only Guard enabled can then do a secure reply to the sender, but they can't start a new email or add recipients.

'''Guard Mail''', '''Guard Drive''' and '''Guard Docs''' are additional options for users. "Guard Mail" allows users the full functionality of Guard emails. "Guard Drive" allows for encryption and decryption of Drive files and "Guard Docs" allows direct integration of Guard into Documents.

Each of those three Guard components is enabled for all users that have the according capability configured. Please note that users need to have the Drive permission set to use Guard Drive. So the users that have Guard Drive enabled must be a subset of those users with OX Drive permission. Since v7.6.0 we enforce this via the default configuration. Those capabilities can be activated for specific user by using the Open-Xchange provisioning scripts:

==== Guard Mail: ====

<source lang="bash">$ /opt/open-xchange/sbin/changeuser -c 1 -A oxadmin -P admin_password -u testuser --config/com.openexchange.capability.guard-mail=true</source>
==== Guard Drive: ====

<source lang="bash">$ /opt/open-xchange/sbin/changeuser -c 1 -A oxadmin -P admin_password -u testuser --config/com.openexchange.capability.guard-drive=true</source>
'''Please Note''': Guard Drive requires Guard Mail to be configured for the user as well. In addition, these capabilities may be configured globally by editing the <code>guard-api.properties</code> file on the OX backend.

=== External Guest recipients ===
Starting in Guard 2.10.0, when an encrypted email is sent to a user that does not have Guard, a guest account is created for them in appsuite. The recipient uses the Guest account to read the encrypted email. These guest users MUST have guard capabilities. To do this, guard capability must be added to guest accounts.
<code>/opt/open-xchange/etc/share.properties</code>
<source lang="bash">com.openexchange.share.guestCapabilityMode=static
com.openexchange.share.staticGuestCapabilities=guard</source>
In a distributed system, the Guest accounts should not be considered transient. Guard servers must be able to verify the guest account exists in the session storage services.
<source lang="bash">com.openexchange.share.transientSessions=false</source>

=== Guest Storage ===
When an encrypted email is sent to an external Guest, a copy of the fully encrypted email is stored on the server. This is used to create an inbox of encrypted emails for the guest. By entering in a password, the emails can be decrypted and displayed.

How these files are stored depend on which package, open-xchange-guard-file-storage or open-xchange-guard-s3-storage, was installed.

The file retention policy is configured in the guard-core.properties file.

=== Recipient key detection ===

==== Local ====

Guard needs to determine if an email recipients email address is an internal or external (non-ox) user.

To detect if the recipient is an account on the same OX Guard system there is a mechanism needed to map a recipient mail address to the correct local OX context. The default implementation delivered in the product achieves that by looking up the mail domain (@example.com) within the list of context mappings. That is at least not possible in case of ISPs where different users/contexts use the same mail domain. In case your OX system does not use mail domains in context mappings it is required to deploy an OX OSGi bundle implementing the <code>com.openexchange.mailmapping.MailResolver</code> class or by interfacing Guard with your mail resolver system. Please see [https://oxpedia.org/wiki/index.php?title=AppSuite:GuardMailResolver OX Guard Mail Resolver] for details.

==== External ====

Starting with Guard 2.0, Guard will use public PGP Key servers if configured to find PGP Public keys. In addition, Guard will also look up SRV records for PGP Key servers for a recipients domain. This follows the standards [http://tools.ietf.org/html/draft-shaw-openpgp-hkp-00#page-9 OpenPGP Draft].

External PGP servers to use can be configured in the guard.properties file on the Guard servers.

<source lang="bash">com.openexchange.guard.publicPGPDirectory = hkp://keys.gnupg.net:11371, hkp://pgp.mit.edu:11371</source>

If you would like this Guard installation discoverable as HKP service by other Guard servers, then create an SRV record for each domain ("example.com" in this illustration):

<source lang="bash">_hkp._tcp.example.com. 28800 IN SRV 10 1 80 appsuite.example.com.</source>

'''Please Note''' PGP Public key servers by default append the path /pks when the record is obtained from an SRV record. The proxy (also included in Apache config above) routes anything under /pks to the OX Guard PGP server.
<source lang="bash">ProxyPass /pks balancer://oxguard/pgp</source>

Guard keys are also discoverable using the webkey service as specified here: https://tools.ietf.org/html/draft-koch-openpgp-webkey-service-02
This is enabled if you include the
<source lang="bash">ProxyPass /.well-known/openpgpkey/hu balancer://oxguard/hu</source>
in the proxy_http.conf as above.
Please note that the well-known request is targeted at the domain part of the mail address. Therefore clients will request for a mail address name@example.com the URI https://example.com/.well-known/openpgpkey/hu/...

That means that there is the very likely need that some sort of proxying or rewriting from the webserver providing the domain needs to happen. For example for proxying using Apache 2.4 it would roughly look like this:

<source lang="bash">
SSLProxyEngine on
<LocationMatch /.well-known/openpgpkey/>
ProxyPass https://ox.example.com/.well-known/openpgpkey/
</LocationMatch>
</source>

=== Clustering ===

You can run multiple OX Guard servers in your environment to ensure high availability or enhance scalability. OX Guard integrates seamlessly into the existing Open-Xchange infrastructure by using the existing interface standards and is therefor transparent to the environment. A couple of things have to be prepared in order to loosely couple OX Guard servers with Open-Xchange servers in a cluster.

==== MySQL ====

The MySQL servers need to be configured in order to allow access to the configdb of Open-Xchange. To do so you need to set the following configuration in the MySQL <code>my.cnf</code>:

<source lang="bash">bind = 0.0.0.0</source>
This allows the Guard backend to bind to the MySQL host which is configured in the <code>guard-core.properties</code> file with <code>com.openexchange.guard.configdbHostname</code>. After the bind for the MySQL instance is configured and the OX Guard backend would be able to connect to the configured host, you have to grant access for the OX Guard service on the MySQL instance to manage the databases. Do so by connecting to the MySQL server via the MySQL client. Authenticate if necessary and execute the following, please note that you have to modify the hostname / IP address of the client who should be able to connect to this database, it should include all possible OX Guard servers:

<source lang="sql">GRANT ALL PRIVILEGES ON *.* TO 'openexchange'@'oxguard.example.com' IDENTIFIED BY ‘secret’;</source>

==== Apache ====

OX Guard uses the Open-Xchange REST API to store and fetch data from the Open-Xchange databases. The REST API is a servlet running in the Grizzly container. By default it is not exposed as a servlet through Apache and is only accessibly via port 8009. In order to use Apache's load balancing via <code>mod_proxy</code> we need to add a servlet called "preliminary" to <code>proxy_http.conf</code>, example based on a clustered <code>mod_proxy</code>configuration:

<Location /preliminary>
Order Deny,Allow
Deny from all
# Only allow access from Guard 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.
</Location>

ProxyPass /preliminary balancer://oxcluster/preliminary

Make sure that the balancer is properly configured in the <code>mod_proxy</code> configuration. Examples on how to do so can be found in our clustering configuration for Open-Xchange AppSuite. Like explained in the example above, please make sure that this location is only available in your internal network, there is no need to expose <code>/preliminary</code> to the public, it is only used by Guard servers to connect to the OX backend. If you have a load balancer in front of the Apache cluster you should consider blocking access to <code>/preliminary</code> from WAN to restrict access to the servlet to internal network services only.

Now add the OX Guard <code>BalancerMembers</code> to the oxguard balancer configuration (also in <code>proxy_http.conf</code>) to address all your OX Guard nodes in the cluster in this balancer configuration. The configuration has to be applied to all Apache nodes within the cluster.

If the Apache server is a dedicated server <code>/</code> instance you also have to install the OX Guard UI-Static package on all Apache nodes in the cluster in order to provide static files like images or CSS to the OX Guard client. Example for Debian (the OX Guard repository has to be configured in the package management prior):

<source lang="bash">$ apt-get install open-xchange-guard-ui-static</source>

==== Open-Xchange ====

Disable the Open-Xchange IPCheck for session verification. This is required because OX Guard will use the users session cookie to connect to the Open-Xchange REST API, but as a different IP address than the OX Guard server has been used during authentication the request would fail if you don't disable the IPCheck:

<source lang="bash">$ vim /opt/open-xchange/etc/server.properties</source>
and set:

<source lang="bash">com.openexchange.IPCheck=false</source>
The OX Guard UI package has to be installed on all Open-Xchange backend nodes as well, example for Debian (the OX Guard repository has to be configured in the package management prior):

<source lang="bash">$ apt-get install open-xchange-guard-ui</source>
Restart the Open-Xchange service afterwards.

==== OX Guard ====

For details in clustering Guard servers, please see [https://oxpedia.org/wiki/index.php?title=AppSuite:GuardCluster OX Guard Clustering]. It is '''critical''' that all Guard servers have the same <code>oxguardpass</code> file. Please see the clustering link for details. Do not run <code>/opt/open-xchange/sbin/guard --init</code> on more than one server.

After all the services like MySQL, Apache and Open-Xchange have been configured you need to update the OX Guard backend configuration to point to the correct API endpoints. Set the REST API endpoint to an Apache server by setting the following value in <code>/opt/open-xchange/etc/guard-core.properties</code>:

<source lang="bash">com.openexchange.guard.restApiHostname=apache.example.com</source>
Per default Guard will try to connect to port 8009 to this host, but as we configured the REST API to be proxies thorugh the servlet <code>/preliminary</code> on every Apache we now also need to change the target port for the REST API. You can do so by adding the following line into <code>/opt/open-xchange/etc/guard-core.properties</code>:

<source lang="bash">com.openexchange.guard.oxBackendPort=80</source>
Please also change all settings in regards to MySQL like <code>com.openexchange.guard.configdbHostname</code>, <code>com.openexchange.guard.oxguardDatabaseHostname</code>, <code>com.openexchange.guard.databaseUsername</code> or <code>om.openexchange.guard.databasePassword</code>.

Afterwards restart the OX Guard service and check the log file if the OX Guard backend is able to connect to the configured REST API.

=== Multi Node ===

If you have multiple OX and Guard installations, please see the following documentation [https://oxpedia.org/wiki/index.php?title=AppSuite:OX_Guard_Modular OX Guard Modular Setup].

=== Mail Filter Integration (2.10.4+) ===

To add additional mail filter tests (verify PGP signature, or encrypt incoming), please see
[[AppSuite:OX_Guard_MailFilter | MailFilter Integration]]

== Support API ==

The OX Guard Support API enables administrative access to various functions for maintaining OX Guard from a client in a role as a support employee. A client has to do a BASIC AUTH authentication in order to access the API. Username and password can be configured in the guard-core.properties file using the following settings:

# Specify the username and password for accessing the Support API of Guard
com.openexchange.guard.supportApiUsername=
com.openexchange.guard.supportApiPassword=

In contrast to the rest of the OX Guard requests, the OX Guard support API requests are accessible using: /guardsupport. This distinction allows more flexible configuration since the support API should not always be accessible from everywhere.

'''Warning''': Exposing the support API to the internet could be huge security risk. Only add to Apache if you know what you are doing.

=== Reset password ===

<code>POST /guardsupport/?action=reset_password</code>

Performs a password reset and sends a new random generated password to a specified email address by the user or a default address if the user did not specify an email address. (''Since Guard 2.0'')

Parameters:

* <code>email</code> – The email address of the user to reset the password for
* <code>default</code> (optional) – The email address to send the new password to, if the user did not specify a secondary email address

Response:
PRIMARY if the reset was sent to the primary email address. SECONDARY if the reset email was sent to the secondary email address that the user specified

=== Expose key ===

<code>POST /guardsupport/?action=expose_key</code>

Marks a deleted user key temporary as “exposed” and creates a unique URL for downloading the exposed key. Automatic resetting of exposed keys to "not exposed" is scheduled once a day and resets all exposed keys which have been exposed before X hours, where X can be configured using com.openexchange.guard.exposedKeyDurationInHours in the guard.properties files. (''Since Guard 2.0'')

Parameters:

* <code>email</code> – The email address of the user to expose the deleted keys for
* <code>cid</code> – The context id

Response: A URL pointing to the downloadable exposed keys.

=== Delete user ===

<code>POST /guardsupport/?action=delete_user</code>

Deletes all keys related to a certain user. The keys are backed up and can be exposed using the “expose_key” call. (''Since Guard 2.0'')

Parameters:

* <code>user_id</code> – The user's id
* <code>cid</code> - The context id

=== Upgrade User (Release 2.10 and later) ===

<code>POST /guardsupport/?action=upgrade_guest</code>

Upgrades a Guest account. This action copies all of the keys from the Guest account to a full OX account, assuming that user has Guard capabilities.

Parameters:

* <code>email</code> - The email address of the Guest user
* <code>user_id</code> – The user's new id
* <code>cid</code> - The user's new context id

== Customisation ==

Guard's templates are customisable at the user and context level. Please see [https://oxpedia.org/wiki/index.php?title=AppSuite:GuardCustomization Customisation] for details.

== Entropy ==

Guard requires entropy (randomness) to generate the private/public keys that are used. Depending on the server and it's environment, this may become a problem. Please see [https://oxpedia.org/wiki/index.php?title=AppSuite:GuardEntropy Entropy] for a possible solution.

AppSuite:OX Guard

2020-10-10T07:05:38Z

WolfgangRosenauer: /* External */

= OX Guard (Version 2.10) =

For previous versions of OX Guard, please click here
* [[AppSuite:OX_Guard_2-0 | Installation and information of OX Guard 2.0 - 2.2]]
* [[Appsuite:OX_Guard_2_8 | Installation and information of OX Guard 2.4 - 2.8]]

If upgrading from 2.6 or 2.8, please see
* [[Appsuite:OX_Guard_Upgrade_2_10|Upgrading to 2.10]]

== Overview ==

OX Guard is a fully integrated security add-on to OX App Suite that provides end users with a flexible email and file encryption solution. OX Guard is a highly scalable, multi server, feature rich solution that is so simple-to-use that end users will actually use it. With a single click a user can take control of their security and send secure emails and share encrypted files. This can be done from any device to both OX App Suite and non-OX App Suite users.

OX Guard uses standard PGP encryption for the encryption of email and files. PGP has been around for a long time, yet has not really caught on with the masses. This is generally blamed on the confusion and complications of managing the keys, understanding trust, PGP format types, and lack of trusted central key repositories. Guard simplifies all of this, making PGP encryption as easy as a one click process, with no keys to keep track of, yet the options of advanced PGP management for those that know how.

This article will guide you through the installation of Guard and describes the basic configuration and software requirements. As it is intended as a quick walk-through it assumes an existing installation of the operating system including a single server App Suite setup as well as average system administration skills. This guide will also show you how to setup a basic installation with none of the typically used distributed environment settings. The objective of this guide is:

* To setup a single server installation
* To setup a single Guard instance on an existing Open-Xchange installation, no cluster
* To use the database service on the existing Open-Xchange installation for Guard, no replication
* To provide a basic configuration setup, no mail server configuration

=== Key Features ===

* Simple security at the touch of a button
* Provides user based security - Separate from provider
* Supplementary security to Provider based security - Layered
* Powerful features yet simple to use and understand
* Security - Inside and outside of the OX environment
* Email and Drive integration
* Uses proven PGP security

=== Availability ===

If an OX App Suite customer would like to evaluate OX Guard integration, the first step is to contact OX Sales. OX Sales will then work on the request and send prices and license/API (for the hosted infrastructure) key details to the customer.

=== Requirements ===

Please review [https://oxpedia.org/wiki/index.php?title=AppSuite:OX_System_Requirements#OX_Guard OX Guard Requirements] for a full list of requirements.

Since OX Guard is a Microservice it can either be added to an existing Open-Xchange installation or it can be deployed on a dedicated environment. The version of Guard installed is dependent on the Appsuite version installed. Please refer to the version matrix below.

==== Prerequisites ====

* Open-Xchange REST API
* Grizzly HTTP connector (open-xchange-grizzly)
* A supported Java Virtual Machine (Java 8)
* An Open-Xchange App Suite installation (see version Matrix)
* Please Note: To get access to the latest minor features and bug fixes, you need to have a valid license. The article [https://oxpedia.org/wiki/index.php?title=AppSuite:UpdatingOXPackages Updating OX-Packages] explains how that can be done.

==== Version Matrix ====
{|
! style="text-align:left;"| Core Version
! Guard Version
|-
|7.8.1
|2.4.0 or 2.4.2
|-
|7.8.2
|2.4.2
|-
|7.8.3
|2.6.0
|-
|7.8.4
|2.8.0
|-
|7.10.0
|2.10.0
|-
|7.10.1
|2.10.1
|-
|7.10.2
|2.10.2
|-
|7.10.3
|2.10.3
|-
|7.10.4
|2.10.4
|}

=== Important Notes ===

==== Customisation ====

OX Guard version supports branding / theming using the configuration cascade, defining a templateID for a user or context. Check the [https://oxpedia.org/wiki/index.php?title=AppSuite:GuardCustomization OX Guard Customisation] article for more details.

==== Mail Resolver ====

READ THIS VERY CAREFULLY; BEFORE PROCEEDING WITH GUARD INSTALLATION!

The Guard installation must be able to determine if an email recipient is a local OX user or if it should be a guest account. The default MailResolver uses the context domain name to do this. On many installations, domains may extend across multiple context and multiple database shards. In these cases, the default MailResolver won't work. In addition, if a custom authentication package is used, the Mail Resolver will likely not work.

Once Guard is installed, please be sure to test the mail resolver using:

<source lang="bash">/opt/open-xchange/sbin/guard test email@domain</source>
to see if the mail Resolver works.

If the test does not work, you will likely need a custom Mail Resolver. Please see [https://oxpedia.org/wiki/index.php?title=AppSuite:GuardMailResolver Mail Resolver] page

This resolver software ''depends heavily on your local deployment''.

== Download and Installation ==

=== General ===

The installation of the <code>open-xchange-guard-backend-plugin</code> package which is required for Guard and the main <code>open-xchange-guard</code> package in version 2.4.0 or higher will eventually execute database update tasks if installed and activated. Please take this into account.

There are several components to the Guard service. They can be all installed on the same server as the OX middleware or on a separate server.

The components required for the OX middleware are: <code>open-xchange-rest</code>, <code>open-xchange-guard-backend-plugin</code> and <code>open-xchange-guard-ui</code>.

The components required for the OX frontend are: <code>open-xchange-guard-ui-static</code> and optionally <code>open-xchange-guard-help-en-us</code> (or preferred language for help files).

The components required for the Guard server <code>open-xchange-guard</code> and either <code>open-xchange-guard-file-storage</code> or <code>open-xchange-guard-s3-storage</code> depending on what storage you want to use. The examples below make use of the <code>open-xchange-guard-file-storage</code>. Adjust the commands accordingly to fit your needs. In addition <code>open-xchange</code> and <code>open-xchange-core</code> are required to run OX Guard.

=== Debian Linux 9.0 (Stretch) ===

If not already done, add the following repositories to your Open-Xchange apt configuration:

deb https://software.open-xchange.com/products/guard/stable/guard/DebianStretch /
deb https://software.open-xchange.com/products/appsuite/stable/backend/DebianStretch /

and then run for a single node installation:

$ apt-get update
$ apt-get install open-xchange-rest open-xchange-guard open-xchange-guard-file-storage open-xchange-guard-ui open-xchange-guard-ui-static open-xchange-guard-backend-plugin

or the following for a distributed installation:

$ apt-get update
$ apt-get install open-xchange-guard open-xchange-guard-file-storage
The packages <code>open-xchange-guard-ui</code> <code>open-xchange-rest</code> and <code>open-xchange-guard-backend-plugin</code> missing in the distributed installation have to be installed on the node running the middleware. The package <code>open-xchange-guard-ui-static</code> must be installed in the frontend (apache node).

=== Debian Linux 10.0 (Buster) *Version 2.10.3+ only* ===

If not already done, add the following repositories to your Open-Xchange apt configuration:

deb https://software.open-xchange.com/products/guard/stable/guard/DebianBuster /
deb https://software.open-xchange.com/products/appsuite/stable/backend/DebianBuster /

and then run for a single node installation:

$ apt-get update
$ apt-get install open-xchange-rest open-xchange-guard open-xchange-guard-file-storage open-xchange-guard-ui open-xchange-guard-ui-static open-xchange-guard-backend-plugin

or the following for a distributed installation:

$ apt-get update
$ apt-get install open-xchange-guard open-xchange-guard-file-storage
The packages <code>open-xchange-guard-ui</code> <code>open-xchange-rest</code> and <code>open-xchange-guard-backend-plugin</code> missing in the distributed installation have to be installed on the node running the middleware. The package <code>open-xchange-guard-ui-static</code> must be installed in the frontend (apache node).

=== RedHat Enterprise Linux 6 or CentOS 6 (valid until v2.10.3) ===

If not already done, add the following repositories to your Open-Xchange yum configuration:

[open-xchange-guard-stable-guard]
name=Open-Xchange-guard-stable-guard
baseurl=https://software.open-xchange.com/products/guard/2.10.3/guard/RHEL6/
gpgkey=https://software.open-xchange.com/oxbuildkey.pub
enabled=1
gpgcheck=1
metadata_expire=0m

[ox-backend]
name=Open-Xchange-backend
baseurl=https://software.open-xchange.com/products/appsuite/7.10.3/backend/RHEL6/
gpgkey=https://software.open-xchange.com/oxbuildkey.pub
enabled=1
gpgcheck=1
metadata_expire=0m

and then run for a single node installation:

$ yum update
$ yum install open-xchange-rest open-xchange-guard open-xchange-guard-file-storage open-xchange-guard-ui open-xchange-guard-ui-static open-xchange-guard-backend-plugin
or the following for a distributed installation:

$ yum update
$ yum install open-xchange-guard open-xchange-guard-file-storage
The packages <code>open-xchange-guard-ui</code> <code>open-xchange-rest</code> and <code>open-xchange-guard-backend-plugin</code> missing in the distributed installation have to be installed on the node running the middleware. The package <code>open-xchange-guard-ui-static</code> must be installed in the frontend (apache node).

=== Redhat Enterprise Linux 7 or CentOS 7 ===

If not already done, add the following repositories to your Open-Xchange yum configuration:

[open-xchange-guard-stable-guard]
name=Open-Xchange-guard-stable-guard
baseurl=https://software.open-xchange.com/products/guard/stable/guard/RHEL7/
gpgkey=https://software.open-xchange.com/oxbuildkey.pub
enabled=1
gpgcheck=1
metadata_expire=0m

[ox-backend]
name=Open-Xchange-backend
baseurl=https://software.open-xchange.com/products/appsuite/stable/backend/RHEL7/
gpgkey=https://software.open-xchange.com/oxbuildkey.pub
enabled=1
gpgcheck=1
metadata_expire=0m

and then run for a single node installation:

$ yum update
$ yum install open-xchange-rest open-xchange-guard open-xchange-guard-file-storage open-xchange-guard-ui open-xchange-guard-ui-static open-xchange-guard-backend-plugin
or the following for a distributed installation:

$ yum update
$ yum install open-xchange-guard open-xchange-guard-file-storage

The packages <code>open-xchange-guard-ui</code> <code>open-xchange-rest</code> and <code>open-xchange-guard-backend-plugin</code> missing in the distributed installation have to be installed on the node running the middleware. The package <code>open-xchange-guard-ui-static</code> must be installed in the frontend (apache node).

=== SUSE Linux Enterprise Server 12 (valid until 2.10.3) ===

Add the package repository using zypper if not already present:

$ zypper ar https://software.open-xchange.com/products/guard/2.10.3/guard/SLE_12 guard-stable-guard
$ zypper ar https://software.open-xchange.com/products/appsuite/7.10.3/backend/SLE_12 ox-backend

and then run for a single node installation:

$ zypper ref
$ zypper in open-xchange-rest open-xchange-guard open-xchange-guard-file-storage open-xchange-guard-ui open-xchange-guard-ui-static

or the following for a distributed installation:

$ zypper ref
$ zypper in open-xchange-guard open-xchange-guard-file-storage

The packages <code>open-xchange-guard-ui</code> <code>open-xchange-rest</code> and <code>open-xchange-guard-backend-plugin</code> missing in the distributed installation have to be installed on the node running the middleware. The package <code>open-xchange-guard-ui-static</code> must be installed in the frontend (apache node).

=== Univention Corporate Server ===

If you have purchased the OX App Suite for UCS, the OX Guard is part of the offering. OX Guard is available in the Univention App Center. Please check the UMC module App Center for the installation of the OX Guard at your already available environment.

Please note: By default, OX Guard generates the link to the secure content for external recipients on the basis of the local fully qualified domain name (FQDN). If the local FQDN is not reachable from the Internet, it has to be specified manually. This can be done by setting a UCR variable, e.g. via the UMC module "Univention Configuration Registry". The variable has to contain the external FQDN of the OX Guard system:

<source lang="bash">oxguard/cfg/guard.properties/com.openexchange.guard.externalEmailURL=HOSTNAME.DOMAINNAME</source>

== Update OX Guard ==

This section contains information about updating a 2.10.0 version (e.g. for patch fixes). Upgrading from prior versions is discussed in different articles.

=== Debian Linux 9.0 (Stretch) ===

If not already done, add the following repositories to your Open-Xchange apt configuration:

deb <https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/guard/stable/guard/updates/DebianStretch />
deb <https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/appsuite/stable/backend/DebianStretch /</source>>

Then run:

$ apt-get update
$ apt-get dist-upgrade</source>

If you want to see, what apt-get is going to do without actually doing it, you can run:

$ apt-get dist-upgrade -s</source>

=== Redhat Enterprise Linux 6 or CentOS 6 (valid until 2.10.3) ===

If not already done, add the following repositories to your Open-Xchange yum configuration:

[open-xchange-guard-stable-guard-updates]
name=Open-Xchange-guard-stable-guard-updates
baseurl=https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/guard/2.10.3/guard/updates/RHEL6/
gpgkey=https://software.open-xchange.com/oxbuildkey.pub
enabled=1
gpgcheck=1
metadata_expire=0m

[ox-backend]
name=Open-Xchange-backend
baseurl=https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/appsuite/7.10.3/backend/updates/RHEL6/
gpgkey=https://software.open-xchange.com/oxbuildkey.pub
enabled=1
gpgcheck=1
metadata_expire=0m</source>

and then run:

$ yum update
$ yum upgrade</source>

=== Redhat Enterprise Linux 7 or CentOS 7 ===

If not already done, add the following repositories to your Open-Xchange yum configuration:

[open-xchange-guard-stable-guard-updates]
name=Open-Xchange-guard-stable-guard-updates
baseurl=https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/guard/stable/guard/updates/RHEL7/
gpgkey=https://software.open-xchange.com/oxbuildkey.pub
enabled=1
gpgcheck=1
metadata_expire=0m

[ox-backend]
name=Open-Xchange-backend
baseurl=https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/appsuite/stable/backend/updates/RHEL7/
gpgkey=https://software.open-xchange.com/oxbuildkey.pub
enabled=1
gpgcheck=1
metadata_expire=0m</source>

and then run:

$ yum update
$ yum upgrade</source>

=== SUSE Linux Enterprise Server 12 (valid until 2.10.3) ===

Add the package repository using <code>zypper</code> if not already present:

$ zypper ar https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/guard/2.10.3/guard/updates/SLE_12 guard-stable-guard-updates
$ zypper ar https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/appsuite/7.10.3/backend/updates/SLE_12 ox-backend</source>

and then run:

$ zypper dup -r guard-stable-guard-backend-updates
$ zypper dup -r guard-stable-guard-ui-updates</source>

You might need to run:

$ zypper ref</source>

to update the repository metadata before running <code>zypper</code> up.

=== Univention Corporate Server ===

If you have purchased the OX App Suite for UCS, the OX Guard is part of the offering. OX Guard is available in the Univention App Center. Please check the UMC module App Center for the update of the OX Guard.

== Configuration ==

The following gives an overview of the most important settings to enable Guard for users on the Open-Xchange installation. Some of those settings have to be modified in order to establish the database and REST API access from the Guard service. All settings relating to the Guard backend component are located in the configuration file <code>guard-core.properties</code> located in <code>/opt/open-xchange/etc</code>. The default configuration should be sufficient for a basic "up-and-running" setup (with the exception of defining the database username and password). Please refer to the inline documentation of the configuration file for more advanced options. Additional information can be found in the [https://oxpedia.org/wiki/index.php?title=AppSuite:OX_Guard_Configuration_2_10 Guard Configuration] article.

=== Basic Configuration ===

<source lang="bash">$ vim /opt/open-xchange/etc/guard-core.properties</source>
Guard database for storing Guard user information, main lookup tables:

<source lang="bash">com.openexchange.guard.oxguardDatabaseHostname=localhost</source>
Guard database that stores keys for guest users. May be the same as above. New guest shards will be created on this database as needed. If not supplied, will use the <code>oxguardDatabaseHostname</code>:

<source lang="bash">com.openexchange.guard.oxguardShardDatabase=localhost</source>
Username and Password for the databases above:

<source lang="bash">com.openexchange.guard.databaseUsername=openexchange
com.openexchange.guard.databasePassword=db_password</source>
Open-Xchange REST API host:

<source lang="bash">com.openexchange.guard.restApiHostname=localhost</source>
Open-Xchange REST API username and password (need to be defined in the OX backend in the "Configure services" below):

<source lang="bash">com.openexchange.guard.restApiUsername=apiusername
com.openexchange.guard.restApiPassword=apipassword</source>
External URL for this Open-Xchange installation. This setting will be used to generate the link to the secure content for external recipients:

<source lang="bash">com.openexchange.guard.externalEmailURL=URL_TO_OX</source>
=== Middleware Configuration on OX Guard node ===

If you are installing OX Guard on a node that until yet did not host an Open-Xchange middleware you have to additionally configure some parts of the following properties files:

* <code>configdb.properties</code>: information about the existing configuration database.
* <code>server.properties</code>: information about the connections have to be set.
* <code>system.properties</code>: at least <code>SERVER_NAME</code> should be set.

=== Sevices Configuration ===

==== Apache ====

Configure the <code>mod_proxy_http</code> module by adding the Guard API.

===== Redhat Enterprise Linux 6 or CentOS 6 =====

<source lang="bash">$ vim /etc/httpd/conf.d/proxy_http.conf</source>

===== Debian GNU/Linux 9.0 =====

<source lang="bash">$ vim /etc/apache2/conf-enabled/proxy_http.conf</source>

<Proxy balancer://oxguard>
Order deny,allow
Allow from all

BalancerMember http://localhost:8009/ timeout=1800 smax=0 ttl=60 retry=60 loadfactor=100 route=OX1
ProxySet stickysession=JSESSIONID|jsessionid scolonpathdelim=ON
SetEnv proxy-initial-not-pooled
SetEnv proxy-sendchunked
</Proxy>

ProxyPass /appsuite/api/oxguard balancer://oxguard/oxguard
ProxyPass /pks balancer://oxguard/pgp
ProxyPass /.well-known/openpgpkey/hu balancer://oxguard/hu

'''Please Note''': The Guard API settings must be inserted '''''before''''' the existing <code>ProxyPass /appsuite/api</code> parameter.

'''Also Note''': If you already have a Proxy balancer for the OX backend with the same URL (say http://localhost:8080) then you don't need the second BalancerMember entry, and you can just have the ProxyPass address that balancer instead.

After the configuration is done, restart the Apache webserver

<source lang="bash">$ apachectl restart</source>

=== Open-Xchange Middleware Configuration ===

Edit the <code>guard-api.properties</code> configuration file for the OX backend where the guard-backend-plugin was installed. Please remove comments in front of the following settings to the configuration file <code>guard-api.properties</code> on the Open-Xchange backend servers:

<source lang="bash">$ vim /opt/open-xchange/etc/guard-api.properties</source>
<source lang="bash"># OX Guard general permission, required to activate Guard in the AppSuite UI.
com.openexchange.capability.guard=true

# Default theme template id for all users that have no custom template id configured.
com.openexchange.guard.templateID=0</source>
Configure the API username and password that you assigned to Guard in the <code>server.properties</code> file:

<source lang="bash">$ vim /opt/open-xchange/etc/server.properties</source>
<source lang="bash"># Specify the user name used for HTTP basic auth by internal REST servlet
com.openexchange.rest.services.basic-auth.login=apiusername

# Specify the password used for HTTP basic auth by internal REST servlet
com.openexchange.rest.services.basic-auth.password=apipassword</source>
Finally, the OX backend needs to know where the Guard server is located. This is used to notify the Guard server of changes in users, and to send emails marked for signature. The URL for the Guard server should include the URL suffix <code>/guardadmin</code>. In the event of a cluster setup, any Guard server can be referenced here, as it is not session specific, though ideally would have a HTTP load balancer/failover URL:

<source lang="bash">$ vim /opt/open-xchange/etc/guard-api.properties</source>
<source lang="bash"># Specifies the URI to the OX Guard end-point; e.g. http://guard.host.invalid:8081/guardadmin
# Default is empty
com.openexchange.guard.endpoint=http://guardserver:8009/guardadmin</source>
Restart the OX backend

<source lang="bash">$ /etc/init.d/open-xchange restart</source>
==== SELinux ====

Running SELinux prohibits your local Open-Xchange backend service to connect to localhost:8009, which is where the Guard backend service listens to. In order to allow localhost connections to 8009 execute the following:

<source lang="bash">$ setsebool -P httpd_can_network_connect 1</source>
=== Generating the <code>oxguardpass</code> ===

Once the Guard configuration (database and backend configuration) and the service configuration has been applied, the Guard administration script needs to be executed in order to create the master password file in <code>/opt/open-xchange/etc/oxguardpass</code>. The initiation only needs to be done '''once''' for a multi server setup, for details please see the sections '''Optional''' and/or '''Clustering'''.

'''Please Note''': If you run a cluster of OX / Guard nodes, only execute this command on '''ONE''' node. Not on all nodes! See [https://oxpedia.org/wiki/index.php?title=AppSuite:GuardCluster OX Guard Clustering] for details.

<source lang="bash">$ /opt/open-xchange/sbin/guard --init</source>
'''Please Note''': It is important to understand that the master password file located at <code>/opt/open-xchange/etc/oxguardpass</code> is required to reset user passwords; without them the administrator will not be able to reset user passwords anymore in the future. The file contains the passwords used to encrypt the master database key, as well as passwords used to encrypt protected data in the users table. It must be the same on all Guard servers.

=== Test Setup ===

Not required, but it is a good idea to test the Guard setup before enabling for any users. The test function will verify that Guard has a good connection to the OX backend, and that it can resolve email addresses to users.

To test, use an email address that exists on the OX backend (john@example.com for this example)

<source lang="bash">/opt/open-xchange/sbin/guard --test john@example.com</source>
Guard should return information from the OX backend regarding the user associated with "john@example.com". Problems resolving information for the user should be resolved before using Guard. Check Rest API passwords and settings if errors returned.

=== Enabling Guard for Users ===

Guard provides two capabilities for users in the environment as well as a basic "core" level:

* Guard: <code>com.openexchange.capability.guard</code>
* Guard Mail: <code>com.openexchange.capability.guard-mail</code>
* Guard Drive: <code>com.openexchange.capability.guard-drive</code>

The "core" Guard enabled a basic read functionality for Guard encrypted emails. We recommend enabling this for all users, as this allows all recipients to read Guard emails sent to them. Great opportunity for upsell. Recipients with only Guard enabled can then do a secure reply to the sender, but they can't start a new email or add recipients.

'''Guard Mail''' and '''Guard Drive''' are additional options for users. "Guard Mail" allows users the full functionality of Guard emails. "Guard Drive" allows for encryption and decryption of drive files.

Each of those two Guard components is enabled for all users that have the according capability configured. Please note that users need to have the Drive permission set to use Guard Drive. So the users that have Guard Drive enabled must be a subset of those users with OX Drive permission. Since v7.6.0 we enforce this via the default configuration. Those capabilities can be activated for specific user by using the Open-Xchange provisioning scripts:

==== Guard Mail: ====

<source lang="bash">$ /opt/open-xchange/sbin/changeuser -c 1 -A oxadmin -P admin_password -u testuser --config/com.openexchange.capability.guard-mail=true</source>
==== Guard Drive: ====

<source lang="bash">$ /opt/open-xchange/sbin/changeuser -c 1 -A oxadmin -P admin_password -u testuser --config/com.openexchange.capability.guard-drive=true</source>
'''Please Note''': Guard Drive requires Guard Mail to be configured for the user as well. In addition, these capabilities may be configured globally by editing the <code>guard-api.properties</code> file on the OX backend.

=== External Guest recipients ===
Starting in Guard 2.10.0, when an encrypted email is sent to a user that does not have Guard, a guest account is created for them in appsuite. The recipient uses the Guest account to read the encrypted email. These guest users MUST have guard capabilities. To do this, guard capability must be added to guest accounts.
<code>/opt/open-xchange/etc/share.properties</code>
<source lang="bash">com.openexchange.share.guestCapabilityMode=static
com.openexchange.share.staticGuestCapabilities=guard</source>
In a distributed system, the Guest accounts should not be considered transient. Guard servers must be able to verify the guest account exists in the session storage services.
<source lang="bash">com.openexchange.share.transientSessions=false</source>

=== Guest Storage ===
When an encrypted email is sent to an external Guest, a copy of the fully encrypted email is stored on the server. This is used to create an inbox of encrypted emails for the guest. By entering in a password, the emails can be decrypted and displayed.

How these files are stored depend on which package, open-xchange-guard-file-storage or open-xchange-guard-s3-storage, was installed.

The file retention policy is configured in the guard-core.properties file.

=== Recipient key detection ===

==== Local ====

Guard needs to determine if an email recipients email address is an internal or external (non-ox) user.

To detect if the recipient is an account on the same OX Guard system there is a mechanism needed to map a recipient mail address to the correct local OX context. The default implementation delivered in the product achieves that by looking up the mail domain (@example.com) within the list of context mappings. That is at least not possible in case of ISPs where different users/contexts use the same mail domain. In case your OX system does not use mail domains in context mappings it is required to deploy an OX OSGi bundle implementing the <code>com.openexchange.mailmapping.MailResolver</code> class or by interfacing Guard with your mail resolver system. Please see [https://oxpedia.org/wiki/index.php?title=AppSuite:GuardMailResolver OX Guard Mail Resolver] for details.

==== External ====

Starting with Guard 2.0, Guard will use public PGP Key servers if configured to find PGP Public keys. In addition, Guard will also look up SRV records for PGP Key servers for a recipients domain. This follows the standards [http://tools.ietf.org/html/draft-shaw-openpgp-hkp-00#page-9 OpenPGP Draft].

External PGP servers to use can be configured in the guard.properties file on the Guard servers.

<source lang="bash">com.openexchange.guard.publicPGPDirectory = hkp://keys.gnupg.net:11371, hkp://pgp.mit.edu:11371</source>

If you would like this Guard installation discoverable as HKP service by other Guard servers, then create an SRV record for each domain ("example.com" in this illustration):

<source lang="bash">_hkp._tcp.example.com. 28800 IN SRV 10 1 80 appsuite.example.com.</source>

'''Please Note''' PGP Public key servers by default append the path /pks when the record is obtained from an SRV record. The proxy (also included in Apache config above) routes anything under /pks to the OX Guard PGP server.
<source lang="bash">ProxyPass /pks balancer://oxguard/pgp</source>

Guard keys are also discoverable using the webkey service as specified here: https://tools.ietf.org/html/draft-koch-openpgp-webkey-service-02
This is enabled if you include the
<source lang="bash">ProxyPass /.well-known/openpgpkey/hu balancer://oxguard/hu</source>
in the proxy_http.conf as above.
Please note that the well-known request is targeted at the domain part of the mail address. Therefore clients will request for a mail address name@example.com the URI https://example.com/.well-known/openpgpkey/hu/...

That means that there is the very likely need that some sort of proxying or rewriting from the webserver providing the domain needs to happen. For example for proxying using Apache 2.4 it would roughly look like this:

<source lang="bash">
SSLProxyEngine on
<LocationMatch /.well-known/openpgpkey/>
ProxyPass https://ox.example.com/.well-known/openpgpkey/
</LocationMatch>
</source>

=== Clustering ===

You can run multiple OX Guard servers in your environment to ensure high availability or enhance scalability. OX Guard integrates seamlessly into the existing Open-Xchange infrastructure by using the existing interface standards and is therefor transparent to the environment. A couple of things have to be prepared in order to loosely couple OX Guard servers with Open-Xchange servers in a cluster.

==== MySQL ====

The MySQL servers need to be configured in order to allow access to the configdb of Open-Xchange. To do so you need to set the following configuration in the MySQL <code>my.cnf</code>:

<source lang="bash">bind = 0.0.0.0</source>
This allows the Guard backend to bind to the MySQL host which is configured in the <code>guard-core.properties</code> file with <code>com.openexchange.guard.configdbHostname</code>. After the bind for the MySQL instance is configured and the OX Guard backend would be able to connect to the configured host, you have to grant access for the OX Guard service on the MySQL instance to manage the databases. Do so by connecting to the MySQL server via the MySQL client. Authenticate if necessary and execute the following, please note that you have to modify the hostname / IP address of the client who should be able to connect to this database, it should include all possible OX Guard servers:

<source lang="sql">GRANT ALL PRIVILEGES ON *.* TO 'openexchange'@'oxguard.example.com' IDENTIFIED BY ‘secret’;</source>

==== Apache ====

OX Guard uses the Open-Xchange REST API to store and fetch data from the Open-Xchange databases. The REST API is a servlet running in the Grizzly container. By default it is not exposed as a servlet through Apache and is only accessibly via port 8009. In order to use Apache's load balancing via <code>mod_proxy</code> we need to add a servlet called "preliminary" to <code>proxy_http.conf</code>, example based on a clustered <code>mod_proxy</code>configuration:

<Location /preliminary>
Order Deny,Allow
Deny from all
# Only allow access from Guard 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.
</Location>

ProxyPass /preliminary balancer://oxcluster/preliminary

Make sure that the balancer is properly configured in the <code>mod_proxy</code> configuration. Examples on how to do so can be found in our clustering configuration for Open-Xchange AppSuite. Like explained in the example above, please make sure that this location is only available in your internal network, there is no need to expose <code>/preliminary</code> to the public, it is only used by Guard servers to connect to the OX backend. If you have a load balancer in front of the Apache cluster you should consider blocking access to <code>/preliminary</code> from WAN to restrict access to the servlet to internal network services only.

Now add the OX Guard <code>BalancerMembers</code> to the oxguard balancer configuration (also in <code>proxy_http.conf</code>) to address all your OX Guard nodes in the cluster in this balancer configuration. The configuration has to be applied to all Apache nodes within the cluster.

If the Apache server is a dedicated server <code>/</code> instance you also have to install the OX Guard UI-Static package on all Apache nodes in the cluster in order to provide static files like images or CSS to the OX Guard client. Example for Debian (the OX Guard repository has to be configured in the package management prior):

<source lang="bash">$ apt-get install open-xchange-guard-ui-static</source>

==== Open-Xchange ====

Disable the Open-Xchange IPCheck for session verification. This is required because OX Guard will use the users session cookie to connect to the Open-Xchange REST API, but as a different IP address than the OX Guard server has been used during authentication the request would fail if you don't disable the IPCheck:

<source lang="bash">$ vim /opt/open-xchange/etc/server.properties</source>
and set:

<source lang="bash">com.openexchange.IPCheck=false</source>
The OX Guard UI package has to be installed on all Open-Xchange backend nodes as well, example for Debian (the OX Guard repository has to be configured in the package management prior):

<source lang="bash">$ apt-get install open-xchange-guard-ui</source>
Restart the Open-Xchange service afterwards.

==== OX Guard ====

For details in clustering Guard servers, please see [https://oxpedia.org/wiki/index.php?title=AppSuite:GuardCluster OX Guard Clustering]. It is '''critical''' that all Guard servers have the same <code>oxguardpass</code> file. Please see the clustering link for details. Do not run <code>/opt/open-xchange/sbin/guard --init</code> on more than one server.

After all the services like MySQL, Apache and Open-Xchange have been configured you need to update the OX Guard backend configuration to point to the correct API endpoints. Set the REST API endpoint to an Apache server by setting the following value in <code>/opt/open-xchange/etc/guard-core.properties</code>:

<source lang="bash">com.openexchange.guard.restApiHostname=apache.example.com</source>
Per default Guard will try to connect to port 8009 to this host, but as we configured the REST API to be proxies thorugh the servlet <code>/preliminary</code> on every Apache we now also need to change the target port for the REST API. You can do so by adding the following line into <code>/opt/open-xchange/etc/guard-core.properties</code>:

<source lang="bash">com.openexchange.guard.oxBackendPort=80</source>
Please also change all settings in regards to MySQL like <code>com.openexchange.guard.configdbHostname</code>, <code>com.openexchange.guard.oxguardDatabaseHostname</code>, <code>com.openexchange.guard.databaseUsername</code> or <code>om.openexchange.guard.databasePassword</code>.

Afterwards restart the OX Guard service and check the log file if the OX Guard backend is able to connect to the configured REST API.

=== Multi Node ===

If you have multiple OX and Guard installations, please see the following documentation [https://oxpedia.org/wiki/index.php?title=AppSuite:OX_Guard_Modular OX Guard Modular Setup].

=== Mail Filter Integration (2.10.4+) ===

To add additional mail filter tests (verify PGP signature, or encrypt incoming), please see
[[AppSuite:OX_Guard_MailFilter | MailFilter Integration]]

== Support API ==

The OX Guard Support API enables administrative access to various functions for maintaining OX Guard from a client in a role as a support employee. A client has to do a BASIC AUTH authentication in order to access the API. Username and password can be configured in the guard-core.properties file using the following settings:

# Specify the username and password for accessing the Support API of Guard
com.openexchange.guard.supportApiUsername=
com.openexchange.guard.supportApiPassword=

In contrast to the rest of the OX Guard requests, the OX Guard support API requests are accessible using: /guardsupport. This distinction allows more flexible configuration since the support API should not always be accessible from everywhere.

'''Warning''': Exposing the support API to the internet could be huge security risk. Only add to Apache if you know what you are doing.

=== Reset password ===

<code>POST /guardsupport/?action=reset_password</code>

Performs a password reset and sends a new random generated password to a specified email address by the user or a default address if the user did not specify an email address. (''Since Guard 2.0'')

Parameters:

* <code>email</code> – The email address of the user to reset the password for
* <code>default</code> (optional) – The email address to send the new password to, if the user did not specify a secondary email address

Response:
PRIMARY if the reset was sent to the primary email address. SECONDARY if the reset email was sent to the secondary email address that the user specified

=== Expose key ===

<code>POST /guardsupport/?action=expose_key</code>

Marks a deleted user key temporary as “exposed” and creates a unique URL for downloading the exposed key. Automatic resetting of exposed keys to "not exposed" is scheduled once a day and resets all exposed keys which have been exposed before X hours, where X can be configured using com.openexchange.guard.exposedKeyDurationInHours in the guard.properties files. (''Since Guard 2.0'')

Parameters:

* <code>email</code> – The email address of the user to expose the deleted keys for
* <code>cid</code> – The context id

Response: A URL pointing to the downloadable exposed keys.

=== Delete user ===

<code>POST /guardsupport/?action=delete_user</code>

Deletes all keys related to a certain user. The keys are backed up and can be exposed using the “expose_key” call. (''Since Guard 2.0'')

Parameters:

* <code>user_id</code> – The user's id
* <code>cid</code> - The context id

=== Upgrade User (Release 2.10 and later) ===

<code>POST /guardsupport/?action=upgrade_guest</code>

Upgrades a Guest account. This action copies all of the keys from the Guest account to a full OX account, assuming that user has Guard capabilities.

Parameters:

* <code>email</code> - The email address of the Guest user
* <code>user_id</code> – The user's new id
* <code>cid</code> - The user's new context id

== Customisation ==

Guard's templates are customisable at the user and context level. Please see [https://oxpedia.org/wiki/index.php?title=AppSuite:GuardCustomization Customisation] for details.

== Entropy ==

Guard requires entropy (randomness) to generate the private/public keys that are used. Depending on the server and it's environment, this may become a problem. Please see [https://oxpedia.org/wiki/index.php?title=AppSuite:GuardEntropy Entropy] for a possible solution.

AppSuite:OX Guard

2020-10-10T07:00:25Z

WolfgangRosenauer: /* External Guest recipients: */

= OX Guard (Version 2.10) =

For previous versions of OX Guard, please click here
* [[AppSuite:OX_Guard_2-0 | Installation and information of OX Guard 2.0 - 2.2]]
* [[Appsuite:OX_Guard_2_8 | Installation and information of OX Guard 2.4 - 2.8]]

If upgrading from 2.6 or 2.8, please see
* [[Appsuite:OX_Guard_Upgrade_2_10|Upgrading to 2.10]]

== Overview ==

OX Guard is a fully integrated security add-on to OX App Suite that provides end users with a flexible email and file encryption solution. OX Guard is a highly scalable, multi server, feature rich solution that is so simple-to-use that end users will actually use it. With a single click a user can take control of their security and send secure emails and share encrypted files. This can be done from any device to both OX App Suite and non-OX App Suite users.

OX Guard uses standard PGP encryption for the encryption of email and files. PGP has been around for a long time, yet has not really caught on with the masses. This is generally blamed on the confusion and complications of managing the keys, understanding trust, PGP format types, and lack of trusted central key repositories. Guard simplifies all of this, making PGP encryption as easy as a one click process, with no keys to keep track of, yet the options of advanced PGP management for those that know how.

This article will guide you through the installation of Guard and describes the basic configuration and software requirements. As it is intended as a quick walk-through it assumes an existing installation of the operating system including a single server App Suite setup as well as average system administration skills. This guide will also show you how to setup a basic installation with none of the typically used distributed environment settings. The objective of this guide is:

* To setup a single server installation
* To setup a single Guard instance on an existing Open-Xchange installation, no cluster
* To use the database service on the existing Open-Xchange installation for Guard, no replication
* To provide a basic configuration setup, no mail server configuration

=== Key Features ===

* Simple security at the touch of a button
* Provides user based security - Separate from provider
* Supplementary security to Provider based security - Layered
* Powerful features yet simple to use and understand
* Security - Inside and outside of the OX environment
* Email and Drive integration
* Uses proven PGP security

=== Availability ===

If an OX App Suite customer would like to evaluate OX Guard integration, the first step is to contact OX Sales. OX Sales will then work on the request and send prices and license/API (for the hosted infrastructure) key details to the customer.

=== Requirements ===

Please review [https://oxpedia.org/wiki/index.php?title=AppSuite:OX_System_Requirements#OX_Guard OX Guard Requirements] for a full list of requirements.

Since OX Guard is a Microservice it can either be added to an existing Open-Xchange installation or it can be deployed on a dedicated environment. The version of Guard installed is dependent on the Appsuite version installed. Please refer to the version matrix below.

==== Prerequisites ====

* Open-Xchange REST API
* Grizzly HTTP connector (open-xchange-grizzly)
* A supported Java Virtual Machine (Java 8)
* An Open-Xchange App Suite installation (see version Matrix)
* Please Note: To get access to the latest minor features and bug fixes, you need to have a valid license. The article [https://oxpedia.org/wiki/index.php?title=AppSuite:UpdatingOXPackages Updating OX-Packages] explains how that can be done.

==== Version Matrix ====
{|
! style="text-align:left;"| Core Version
! Guard Version
|-
|7.8.1
|2.4.0 or 2.4.2
|-
|7.8.2
|2.4.2
|-
|7.8.3
|2.6.0
|-
|7.8.4
|2.8.0
|-
|7.10.0
|2.10.0
|-
|7.10.1
|2.10.1
|-
|7.10.2
|2.10.2
|-
|7.10.3
|2.10.3
|-
|7.10.4
|2.10.4
|}

=== Important Notes ===

==== Customisation ====

OX Guard version supports branding / theming using the configuration cascade, defining a templateID for a user or context. Check the [https://oxpedia.org/wiki/index.php?title=AppSuite:GuardCustomization OX Guard Customisation] article for more details.

==== Mail Resolver ====

READ THIS VERY CAREFULLY; BEFORE PROCEEDING WITH GUARD INSTALLATION!

The Guard installation must be able to determine if an email recipient is a local OX user or if it should be a guest account. The default MailResolver uses the context domain name to do this. On many installations, domains may extend across multiple context and multiple database shards. In these cases, the default MailResolver won't work. In addition, if a custom authentication package is used, the Mail Resolver will likely not work.

Once Guard is installed, please be sure to test the mail resolver using:

<source lang="bash">/opt/open-xchange/sbin/guard test email@domain</source>
to see if the mail Resolver works.

If the test does not work, you will likely need a custom Mail Resolver. Please see [https://oxpedia.org/wiki/index.php?title=AppSuite:GuardMailResolver Mail Resolver] page

This resolver software ''depends heavily on your local deployment''.

== Download and Installation ==

=== General ===

The installation of the <code>open-xchange-guard-backend-plugin</code> package which is required for Guard and the main <code>open-xchange-guard</code> package in version 2.4.0 or higher will eventually execute database update tasks if installed and activated. Please take this into account.

There are several components to the Guard service. They can be all installed on the same server as the OX middleware or on a separate server.

The components required for the OX middleware are: <code>open-xchange-rest</code>, <code>open-xchange-guard-backend-plugin</code> and <code>open-xchange-guard-ui</code>.

The components required for the OX frontend are: <code>open-xchange-guard-ui-static</code> and optionally <code>open-xchange-guard-help-en-us</code> (or preferred language for help files).

The components required for the Guard server <code>open-xchange-guard</code> and either <code>open-xchange-guard-file-storage</code> or <code>open-xchange-guard-s3-storage</code> depending on what storage you want to use. The examples below make use of the <code>open-xchange-guard-file-storage</code>. Adjust the commands accordingly to fit your needs. In addition <code>open-xchange</code> and <code>open-xchange-core</code> are required to run OX Guard.

=== Debian Linux 9.0 (Stretch) ===

If not already done, add the following repositories to your Open-Xchange apt configuration:

deb https://software.open-xchange.com/products/guard/stable/guard/DebianStretch /
deb https://software.open-xchange.com/products/appsuite/stable/backend/DebianStretch /

and then run for a single node installation:

$ apt-get update
$ apt-get install open-xchange-rest open-xchange-guard open-xchange-guard-file-storage open-xchange-guard-ui open-xchange-guard-ui-static open-xchange-guard-backend-plugin

or the following for a distributed installation:

$ apt-get update
$ apt-get install open-xchange-guard open-xchange-guard-file-storage
The packages <code>open-xchange-guard-ui</code> <code>open-xchange-rest</code> and <code>open-xchange-guard-backend-plugin</code> missing in the distributed installation have to be installed on the node running the middleware. The package <code>open-xchange-guard-ui-static</code> must be installed in the frontend (apache node).

=== Debian Linux 10.0 (Buster) *Version 2.10.3+ only* ===

If not already done, add the following repositories to your Open-Xchange apt configuration:

deb https://software.open-xchange.com/products/guard/stable/guard/DebianBuster /
deb https://software.open-xchange.com/products/appsuite/stable/backend/DebianBuster /

and then run for a single node installation:

$ apt-get update
$ apt-get install open-xchange-rest open-xchange-guard open-xchange-guard-file-storage open-xchange-guard-ui open-xchange-guard-ui-static open-xchange-guard-backend-plugin

or the following for a distributed installation:

$ apt-get update
$ apt-get install open-xchange-guard open-xchange-guard-file-storage
The packages <code>open-xchange-guard-ui</code> <code>open-xchange-rest</code> and <code>open-xchange-guard-backend-plugin</code> missing in the distributed installation have to be installed on the node running the middleware. The package <code>open-xchange-guard-ui-static</code> must be installed in the frontend (apache node).

=== RedHat Enterprise Linux 6 or CentOS 6 (valid until v2.10.3) ===

If not already done, add the following repositories to your Open-Xchange yum configuration:

[open-xchange-guard-stable-guard]
name=Open-Xchange-guard-stable-guard
baseurl=https://software.open-xchange.com/products/guard/2.10.3/guard/RHEL6/
gpgkey=https://software.open-xchange.com/oxbuildkey.pub
enabled=1
gpgcheck=1
metadata_expire=0m

[ox-backend]
name=Open-Xchange-backend
baseurl=https://software.open-xchange.com/products/appsuite/7.10.3/backend/RHEL6/
gpgkey=https://software.open-xchange.com/oxbuildkey.pub
enabled=1
gpgcheck=1
metadata_expire=0m

and then run for a single node installation:

$ yum update
$ yum install open-xchange-rest open-xchange-guard open-xchange-guard-file-storage open-xchange-guard-ui open-xchange-guard-ui-static open-xchange-guard-backend-plugin
or the following for a distributed installation:

$ yum update
$ yum install open-xchange-guard open-xchange-guard-file-storage
The packages <code>open-xchange-guard-ui</code> <code>open-xchange-rest</code> and <code>open-xchange-guard-backend-plugin</code> missing in the distributed installation have to be installed on the node running the middleware. The package <code>open-xchange-guard-ui-static</code> must be installed in the frontend (apache node).

=== Redhat Enterprise Linux 7 or CentOS 7 ===

If not already done, add the following repositories to your Open-Xchange yum configuration:

[open-xchange-guard-stable-guard]
name=Open-Xchange-guard-stable-guard
baseurl=https://software.open-xchange.com/products/guard/stable/guard/RHEL7/
gpgkey=https://software.open-xchange.com/oxbuildkey.pub
enabled=1
gpgcheck=1
metadata_expire=0m

[ox-backend]
name=Open-Xchange-backend
baseurl=https://software.open-xchange.com/products/appsuite/stable/backend/RHEL7/
gpgkey=https://software.open-xchange.com/oxbuildkey.pub
enabled=1
gpgcheck=1
metadata_expire=0m

and then run for a single node installation:

$ yum update
$ yum install open-xchange-rest open-xchange-guard open-xchange-guard-file-storage open-xchange-guard-ui open-xchange-guard-ui-static open-xchange-guard-backend-plugin
or the following for a distributed installation:

$ yum update
$ yum install open-xchange-guard open-xchange-guard-file-storage

The packages <code>open-xchange-guard-ui</code> <code>open-xchange-rest</code> and <code>open-xchange-guard-backend-plugin</code> missing in the distributed installation have to be installed on the node running the middleware. The package <code>open-xchange-guard-ui-static</code> must be installed in the frontend (apache node).

=== SUSE Linux Enterprise Server 12 (valid until 2.10.3) ===

Add the package repository using zypper if not already present:

$ zypper ar https://software.open-xchange.com/products/guard/2.10.3/guard/SLE_12 guard-stable-guard
$ zypper ar https://software.open-xchange.com/products/appsuite/7.10.3/backend/SLE_12 ox-backend

and then run for a single node installation:

$ zypper ref
$ zypper in open-xchange-rest open-xchange-guard open-xchange-guard-file-storage open-xchange-guard-ui open-xchange-guard-ui-static

or the following for a distributed installation:

$ zypper ref
$ zypper in open-xchange-guard open-xchange-guard-file-storage

The packages <code>open-xchange-guard-ui</code> <code>open-xchange-rest</code> and <code>open-xchange-guard-backend-plugin</code> missing in the distributed installation have to be installed on the node running the middleware. The package <code>open-xchange-guard-ui-static</code> must be installed in the frontend (apache node).

=== Univention Corporate Server ===

If you have purchased the OX App Suite for UCS, the OX Guard is part of the offering. OX Guard is available in the Univention App Center. Please check the UMC module App Center for the installation of the OX Guard at your already available environment.

Please note: By default, OX Guard generates the link to the secure content for external recipients on the basis of the local fully qualified domain name (FQDN). If the local FQDN is not reachable from the Internet, it has to be specified manually. This can be done by setting a UCR variable, e.g. via the UMC module "Univention Configuration Registry". The variable has to contain the external FQDN of the OX Guard system:

<source lang="bash">oxguard/cfg/guard.properties/com.openexchange.guard.externalEmailURL=HOSTNAME.DOMAINNAME</source>

== Update OX Guard ==

This section contains information about updating a 2.10.0 version (e.g. for patch fixes). Upgrading from prior versions is discussed in different articles.

=== Debian Linux 9.0 (Stretch) ===

If not already done, add the following repositories to your Open-Xchange apt configuration:

deb <https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/guard/stable/guard/updates/DebianStretch />
deb <https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/appsuite/stable/backend/DebianStretch /</source>>

Then run:

$ apt-get update
$ apt-get dist-upgrade</source>

If you want to see, what apt-get is going to do without actually doing it, you can run:

$ apt-get dist-upgrade -s</source>

=== Redhat Enterprise Linux 6 or CentOS 6 (valid until 2.10.3) ===

If not already done, add the following repositories to your Open-Xchange yum configuration:

[open-xchange-guard-stable-guard-updates]
name=Open-Xchange-guard-stable-guard-updates
baseurl=https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/guard/2.10.3/guard/updates/RHEL6/
gpgkey=https://software.open-xchange.com/oxbuildkey.pub
enabled=1
gpgcheck=1
metadata_expire=0m

[ox-backend]
name=Open-Xchange-backend
baseurl=https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/appsuite/7.10.3/backend/updates/RHEL6/
gpgkey=https://software.open-xchange.com/oxbuildkey.pub
enabled=1
gpgcheck=1
metadata_expire=0m</source>

and then run:

$ yum update
$ yum upgrade</source>

=== Redhat Enterprise Linux 7 or CentOS 7 ===

If not already done, add the following repositories to your Open-Xchange yum configuration:

[open-xchange-guard-stable-guard-updates]
name=Open-Xchange-guard-stable-guard-updates
baseurl=https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/guard/stable/guard/updates/RHEL7/
gpgkey=https://software.open-xchange.com/oxbuildkey.pub
enabled=1
gpgcheck=1
metadata_expire=0m

[ox-backend]
name=Open-Xchange-backend
baseurl=https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/appsuite/stable/backend/updates/RHEL7/
gpgkey=https://software.open-xchange.com/oxbuildkey.pub
enabled=1
gpgcheck=1
metadata_expire=0m</source>

and then run:

$ yum update
$ yum upgrade</source>

=== SUSE Linux Enterprise Server 12 (valid until 2.10.3) ===

Add the package repository using <code>zypper</code> if not already present:

$ zypper ar https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/guard/2.10.3/guard/updates/SLE_12 guard-stable-guard-updates
$ zypper ar https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/appsuite/7.10.3/backend/updates/SLE_12 ox-backend</source>

and then run:

$ zypper dup -r guard-stable-guard-backend-updates
$ zypper dup -r guard-stable-guard-ui-updates</source>

You might need to run:

$ zypper ref</source>

to update the repository metadata before running <code>zypper</code> up.

=== Univention Corporate Server ===

If you have purchased the OX App Suite for UCS, the OX Guard is part of the offering. OX Guard is available in the Univention App Center. Please check the UMC module App Center for the update of the OX Guard.

== Configuration ==

The following gives an overview of the most important settings to enable Guard for users on the Open-Xchange installation. Some of those settings have to be modified in order to establish the database and REST API access from the Guard service. All settings relating to the Guard backend component are located in the configuration file <code>guard-core.properties</code> located in <code>/opt/open-xchange/etc</code>. The default configuration should be sufficient for a basic "up-and-running" setup (with the exception of defining the database username and password). Please refer to the inline documentation of the configuration file for more advanced options. Additional information can be found in the [https://oxpedia.org/wiki/index.php?title=AppSuite:OX_Guard_Configuration_2_10 Guard Configuration] article.

=== Basic Configuration ===

<source lang="bash">$ vim /opt/open-xchange/etc/guard-core.properties</source>
Guard database for storing Guard user information, main lookup tables:

<source lang="bash">com.openexchange.guard.oxguardDatabaseHostname=localhost</source>
Guard database that stores keys for guest users. May be the same as above. New guest shards will be created on this database as needed. If not supplied, will use the <code>oxguardDatabaseHostname</code>:

<source lang="bash">com.openexchange.guard.oxguardShardDatabase=localhost</source>
Username and Password for the databases above:

<source lang="bash">com.openexchange.guard.databaseUsername=openexchange
com.openexchange.guard.databasePassword=db_password</source>
Open-Xchange REST API host:

<source lang="bash">com.openexchange.guard.restApiHostname=localhost</source>
Open-Xchange REST API username and password (need to be defined in the OX backend in the "Configure services" below):

<source lang="bash">com.openexchange.guard.restApiUsername=apiusername
com.openexchange.guard.restApiPassword=apipassword</source>
External URL for this Open-Xchange installation. This setting will be used to generate the link to the secure content for external recipients:

<source lang="bash">com.openexchange.guard.externalEmailURL=URL_TO_OX</source>
=== Middleware Configuration on OX Guard node ===

If you are installing OX Guard on a node that until yet did not host an Open-Xchange middleware you have to additionally configure some parts of the following properties files:

* <code>configdb.properties</code>: information about the existing configuration database.
* <code>server.properties</code>: information about the connections have to be set.
* <code>system.properties</code>: at least <code>SERVER_NAME</code> should be set.

=== Sevices Configuration ===

==== Apache ====

Configure the <code>mod_proxy_http</code> module by adding the Guard API.

===== Redhat Enterprise Linux 6 or CentOS 6 =====

<source lang="bash">$ vim /etc/httpd/conf.d/proxy_http.conf</source>

===== Debian GNU/Linux 9.0 =====

<source lang="bash">$ vim /etc/apache2/conf-enabled/proxy_http.conf</source>

<Proxy balancer://oxguard>
Order deny,allow
Allow from all

BalancerMember http://localhost:8009/ timeout=1800 smax=0 ttl=60 retry=60 loadfactor=100 route=OX1
ProxySet stickysession=JSESSIONID|jsessionid scolonpathdelim=ON
SetEnv proxy-initial-not-pooled
SetEnv proxy-sendchunked
</Proxy>

ProxyPass /appsuite/api/oxguard balancer://oxguard/oxguard
ProxyPass /pks balancer://oxguard/pgp
ProxyPass /.well-known/openpgpkey/hu balancer://oxguard/hu

'''Please Note''': The Guard API settings must be inserted '''''before''''' the existing <code>ProxyPass /appsuite/api</code> parameter.

'''Also Note''': If you already have a Proxy balancer for the OX backend with the same URL (say http://localhost:8080) then you don't need the second BalancerMember entry, and you can just have the ProxyPass address that balancer instead.

After the configuration is done, restart the Apache webserver

<source lang="bash">$ apachectl restart</source>

=== Open-Xchange Middleware Configuration ===

Edit the <code>guard-api.properties</code> configuration file for the OX backend where the guard-backend-plugin was installed. Please remove comments in front of the following settings to the configuration file <code>guard-api.properties</code> on the Open-Xchange backend servers:

<source lang="bash">$ vim /opt/open-xchange/etc/guard-api.properties</source>
<source lang="bash"># OX Guard general permission, required to activate Guard in the AppSuite UI.
com.openexchange.capability.guard=true

# Default theme template id for all users that have no custom template id configured.
com.openexchange.guard.templateID=0</source>
Configure the API username and password that you assigned to Guard in the <code>server.properties</code> file:

<source lang="bash">$ vim /opt/open-xchange/etc/server.properties</source>
<source lang="bash"># Specify the user name used for HTTP basic auth by internal REST servlet
com.openexchange.rest.services.basic-auth.login=apiusername

# Specify the password used for HTTP basic auth by internal REST servlet
com.openexchange.rest.services.basic-auth.password=apipassword</source>
Finally, the OX backend needs to know where the Guard server is located. This is used to notify the Guard server of changes in users, and to send emails marked for signature. The URL for the Guard server should include the URL suffix <code>/guardadmin</code>. In the event of a cluster setup, any Guard server can be referenced here, as it is not session specific, though ideally would have a HTTP load balancer/failover URL:

<source lang="bash">$ vim /opt/open-xchange/etc/guard-api.properties</source>
<source lang="bash"># Specifies the URI to the OX Guard end-point; e.g. http://guard.host.invalid:8081/guardadmin
# Default is empty
com.openexchange.guard.endpoint=http://guardserver:8009/guardadmin</source>
Restart the OX backend

<source lang="bash">$ /etc/init.d/open-xchange restart</source>
==== SELinux ====

Running SELinux prohibits your local Open-Xchange backend service to connect to localhost:8009, which is where the Guard backend service listens to. In order to allow localhost connections to 8009 execute the following:

<source lang="bash">$ setsebool -P httpd_can_network_connect 1</source>
=== Generating the <code>oxguardpass</code> ===

Once the Guard configuration (database and backend configuration) and the service configuration has been applied, the Guard administration script needs to be executed in order to create the master password file in <code>/opt/open-xchange/etc/oxguardpass</code>. The initiation only needs to be done '''once''' for a multi server setup, for details please see the sections '''Optional''' and/or '''Clustering'''.

'''Please Note''': If you run a cluster of OX / Guard nodes, only execute this command on '''ONE''' node. Not on all nodes! See [https://oxpedia.org/wiki/index.php?title=AppSuite:GuardCluster OX Guard Clustering] for details.

<source lang="bash">$ /opt/open-xchange/sbin/guard --init</source>
'''Please Note''': It is important to understand that the master password file located at <code>/opt/open-xchange/etc/oxguardpass</code> is required to reset user passwords; without them the administrator will not be able to reset user passwords anymore in the future. The file contains the passwords used to encrypt the master database key, as well as passwords used to encrypt protected data in the users table. It must be the same on all Guard servers.

=== Test Setup ===

Not required, but it is a good idea to test the Guard setup before enabling for any users. The test function will verify that Guard has a good connection to the OX backend, and that it can resolve email addresses to users.

To test, use an email address that exists on the OX backend (john@example.com for this example)

<source lang="bash">/opt/open-xchange/sbin/guard --test john@example.com</source>
Guard should return information from the OX backend regarding the user associated with "john@example.com". Problems resolving information for the user should be resolved before using Guard. Check Rest API passwords and settings if errors returned.

=== Enabling Guard for Users ===

Guard provides two capabilities for users in the environment as well as a basic "core" level:

* Guard: <code>com.openexchange.capability.guard</code>
* Guard Mail: <code>com.openexchange.capability.guard-mail</code>
* Guard Drive: <code>com.openexchange.capability.guard-drive</code>

The "core" Guard enabled a basic read functionality for Guard encrypted emails. We recommend enabling this for all users, as this allows all recipients to read Guard emails sent to them. Great opportunity for upsell. Recipients with only Guard enabled can then do a secure reply to the sender, but they can't start a new email or add recipients.

'''Guard Mail''' and '''Guard Drive''' are additional options for users. "Guard Mail" allows users the full functionality of Guard emails. "Guard Drive" allows for encryption and decryption of drive files.

Each of those two Guard components is enabled for all users that have the according capability configured. Please note that users need to have the Drive permission set to use Guard Drive. So the users that have Guard Drive enabled must be a subset of those users with OX Drive permission. Since v7.6.0 we enforce this via the default configuration. Those capabilities can be activated for specific user by using the Open-Xchange provisioning scripts:

==== Guard Mail: ====

<source lang="bash">$ /opt/open-xchange/sbin/changeuser -c 1 -A oxadmin -P admin_password -u testuser --config/com.openexchange.capability.guard-mail=true</source>
==== Guard Drive: ====

<source lang="bash">$ /opt/open-xchange/sbin/changeuser -c 1 -A oxadmin -P admin_password -u testuser --config/com.openexchange.capability.guard-drive=true</source>
'''Please Note''': Guard Drive requires Guard Mail to be configured for the user as well. In addition, these capabilities may be configured globally by editing the <code>guard-api.properties</code> file on the OX backend.

=== External Guest recipients ===
Starting in Guard 2.10.0, when an encrypted email is sent to a user that does not have Guard, a guest account is created for them in appsuite. The recipient uses the Guest account to read the encrypted email. These guest users MUST have guard capabilities. To do this, guard capability must be added to guest accounts.
<code>/opt/open-xchange/etc/share.properties</code>
<source lang="bash">com.openexchange.share.guestCapabilityMode=static
com.openexchange.share.staticGuestCapabilities=guard</source>
In a distributed system, the Guest accounts should not be considered transient. Guard servers must be able to verify the guest account exists in the session storage services.
<source lang="bash">com.openexchange.share.transientSessions=false</source>

=== Guest Storage ===
When an encrypted email is sent to an external Guest, a copy of the fully encrypted email is stored on the server. This is used to create an inbox of encrypted emails for the guest. By entering in a password, the emails can be decrypted and displayed.

How these files are stored depend on which package, open-xchange-guard-file-storage or open-xchange-guard-s3-storage, was installed.

The file retention policy is configured in the guard-core.properties file.

=== Recipient key detection ===

==== Local ====

Guard needs to determine if an email recipients email address is an internal or external (non-ox) user.

To detect if the recipient is an account on the same OX Guard system there is a mechanism needed to map a recipient mail address to the correct local OX context. The default implementation delivered in the product achieves that by looking up the mail domain (@example.com) within the list of context mappings. That is at least not possible in case of ISPs where different users/contexts use the same mail domain. In case your OX system does not use mail domains in context mappings it is required to deploy an OX OSGi bundle implementing the <code>com.openexchange.mailmapping.MailResolver</code> class or by interfacing Guard with your mail resolver system. Please see [https://oxpedia.org/wiki/index.php?title=AppSuite:GuardMailResolver OX Guard Mail Resolver] for details.

==== External ====

Starting with Guard 2.0, Guard will use public PGP Key servers if configured to find PGP Public keys. In addition, Guard will also look up SRV records for PGP Key servers for a recipients domain. This follows the standards [http://tools.ietf.org/html/draft-shaw-openpgp-hkp-00#page-9 OpenPGP Draft].

External PGP servers to use can be configured in the guard.properties file on the Guard servers.

<source lang="bash">com.openexchange.guard.publicPGPDirectory = hkp://keys.gnupg.net:11371, hkp://pgp.mit.edu:11371</source>
If you would like this Guard installation discoverable by other Guard servers, then create an SRV record for each domain ("example.com" in this illustration):

<source lang="bash">_hkp._tcp.example.com. 28800 IN SRV 10 1 80 appsuite.example.com.</source>

'''Please Note''' PGP Public key servers by default append use the URL server/pks when the record is obtained from an SRV record. The proxy above routes anything with the Apache domain/pks to the OX Guard PGP server.

Guard keys are also discoverable using the webkey service as specified here: https://tools.ietf.org/html/draft-koch-openpgp-webkey-service-02
This is enabled if you include the
<source lang="bash">ProxyPass /.well-known/openpgpkey/hu balancer://oxguard/hu</source>
in the proxy_http.conf as above.
Please note that the well-known request is targeted on the domain part of the mail adress. Therefore clients will request for a mail address name@example.com the URI https://example.com/.well-known/openpgpkey/hu/...

That means that there is the likely need that some sort of proxying or rewriting from the webserver providing the domain needs to happen. For example for proxying using Apache 2.4 it would roughly look like this:

<source lang="bash">
SSLProxyEngine on
<LocationMatch /.well-known/openpgpkey/>
ProxyPass https://ox.example.com/.well-known/openpgpkey/
</LocationMatch>
</source>

=== Clustering ===

You can run multiple OX Guard servers in your environment to ensure high availability or enhance scalability. OX Guard integrates seamlessly into the existing Open-Xchange infrastructure by using the existing interface standards and is therefor transparent to the environment. A couple of things have to be prepared in order to loosely couple OX Guard servers with Open-Xchange servers in a cluster.

==== MySQL ====

The MySQL servers need to be configured in order to allow access to the configdb of Open-Xchange. To do so you need to set the following configuration in the MySQL <code>my.cnf</code>:

<source lang="bash">bind = 0.0.0.0</source>
This allows the Guard backend to bind to the MySQL host which is configured in the <code>guard-core.properties</code> file with <code>com.openexchange.guard.configdbHostname</code>. After the bind for the MySQL instance is configured and the OX Guard backend would be able to connect to the configured host, you have to grant access for the OX Guard service on the MySQL instance to manage the databases. Do so by connecting to the MySQL server via the MySQL client. Authenticate if necessary and execute the following, please note that you have to modify the hostname / IP address of the client who should be able to connect to this database, it should include all possible OX Guard servers:

<source lang="sql">GRANT ALL PRIVILEGES ON *.* TO 'openexchange'@'oxguard.example.com' IDENTIFIED BY ‘secret’;</source>

==== Apache ====

OX Guard uses the Open-Xchange REST API to store and fetch data from the Open-Xchange databases. The REST API is a servlet running in the Grizzly container. By default it is not exposed as a servlet through Apache and is only accessibly via port 8009. In order to use Apache's load balancing via <code>mod_proxy</code> we need to add a servlet called "preliminary" to <code>proxy_http.conf</code>, example based on a clustered <code>mod_proxy</code>configuration:

<Location /preliminary>
Order Deny,Allow
Deny from all
# Only allow access from Guard 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.
</Location>

ProxyPass /preliminary balancer://oxcluster/preliminary

Make sure that the balancer is properly configured in the <code>mod_proxy</code> configuration. Examples on how to do so can be found in our clustering configuration for Open-Xchange AppSuite. Like explained in the example above, please make sure that this location is only available in your internal network, there is no need to expose <code>/preliminary</code> to the public, it is only used by Guard servers to connect to the OX backend. If you have a load balancer in front of the Apache cluster you should consider blocking access to <code>/preliminary</code> from WAN to restrict access to the servlet to internal network services only.

Now add the OX Guard <code>BalancerMembers</code> to the oxguard balancer configuration (also in <code>proxy_http.conf</code>) to address all your OX Guard nodes in the cluster in this balancer configuration. The configuration has to be applied to all Apache nodes within the cluster.

If the Apache server is a dedicated server <code>/</code> instance you also have to install the OX Guard UI-Static package on all Apache nodes in the cluster in order to provide static files like images or CSS to the OX Guard client. Example for Debian (the OX Guard repository has to be configured in the package management prior):

<source lang="bash">$ apt-get install open-xchange-guard-ui-static</source>

==== Open-Xchange ====

Disable the Open-Xchange IPCheck for session verification. This is required because OX Guard will use the users session cookie to connect to the Open-Xchange REST API, but as a different IP address than the OX Guard server has been used during authentication the request would fail if you don't disable the IPCheck:

<source lang="bash">$ vim /opt/open-xchange/etc/server.properties</source>
and set:

<source lang="bash">com.openexchange.IPCheck=false</source>
The OX Guard UI package has to be installed on all Open-Xchange backend nodes as well, example for Debian (the OX Guard repository has to be configured in the package management prior):

<source lang="bash">$ apt-get install open-xchange-guard-ui</source>
Restart the Open-Xchange service afterwards.

==== OX Guard ====

For details in clustering Guard servers, please see [https://oxpedia.org/wiki/index.php?title=AppSuite:GuardCluster OX Guard Clustering]. It is '''critical''' that all Guard servers have the same <code>oxguardpass</code> file. Please see the clustering link for details. Do not run <code>/opt/open-xchange/sbin/guard --init</code> on more than one server.

After all the services like MySQL, Apache and Open-Xchange have been configured you need to update the OX Guard backend configuration to point to the correct API endpoints. Set the REST API endpoint to an Apache server by setting the following value in <code>/opt/open-xchange/etc/guard-core.properties</code>:

<source lang="bash">com.openexchange.guard.restApiHostname=apache.example.com</source>
Per default Guard will try to connect to port 8009 to this host, but as we configured the REST API to be proxies thorugh the servlet <code>/preliminary</code> on every Apache we now also need to change the target port for the REST API. You can do so by adding the following line into <code>/opt/open-xchange/etc/guard-core.properties</code>:

<source lang="bash">com.openexchange.guard.oxBackendPort=80</source>
Please also change all settings in regards to MySQL like <code>com.openexchange.guard.configdbHostname</code>, <code>com.openexchange.guard.oxguardDatabaseHostname</code>, <code>com.openexchange.guard.databaseUsername</code> or <code>om.openexchange.guard.databasePassword</code>.

Afterwards restart the OX Guard service and check the log file if the OX Guard backend is able to connect to the configured REST API.

=== Multi Node ===

If you have multiple OX and Guard installations, please see the following documentation [https://oxpedia.org/wiki/index.php?title=AppSuite:OX_Guard_Modular OX Guard Modular Setup].

=== Mail Filter Integration (2.10.4+) ===

To add additional mail filter tests (verify PGP signature, or encrypt incoming), please see
[[AppSuite:OX_Guard_MailFilter | MailFilter Integration]]

== Support API ==

The OX Guard Support API enables administrative access to various functions for maintaining OX Guard from a client in a role as a support employee. A client has to do a BASIC AUTH authentication in order to access the API. Username and password can be configured in the guard-core.properties file using the following settings:

# Specify the username and password for accessing the Support API of Guard
com.openexchange.guard.supportApiUsername=
com.openexchange.guard.supportApiPassword=

In contrast to the rest of the OX Guard requests, the OX Guard support API requests are accessible using: /guardsupport. This distinction allows more flexible configuration since the support API should not always be accessible from everywhere.

'''Warning''': Exposing the support API to the internet could be huge security risk. Only add to Apache if you know what you are doing.

=== Reset password ===

<code>POST /guardsupport/?action=reset_password</code>

Performs a password reset and sends a new random generated password to a specified email address by the user or a default address if the user did not specify an email address. (''Since Guard 2.0'')

Parameters:

* <code>email</code> – The email address of the user to reset the password for
* <code>default</code> (optional) – The email address to send the new password to, if the user did not specify a secondary email address

Response:
PRIMARY if the reset was sent to the primary email address. SECONDARY if the reset email was sent to the secondary email address that the user specified

=== Expose key ===

<code>POST /guardsupport/?action=expose_key</code>

Marks a deleted user key temporary as “exposed” and creates a unique URL for downloading the exposed key. Automatic resetting of exposed keys to "not exposed" is scheduled once a day and resets all exposed keys which have been exposed before X hours, where X can be configured using com.openexchange.guard.exposedKeyDurationInHours in the guard.properties files. (''Since Guard 2.0'')

Parameters:

* <code>email</code> – The email address of the user to expose the deleted keys for
* <code>cid</code> – The context id

Response: A URL pointing to the downloadable exposed keys.

=== Delete user ===

<code>POST /guardsupport/?action=delete_user</code>

Deletes all keys related to a certain user. The keys are backed up and can be exposed using the “expose_key” call. (''Since Guard 2.0'')

Parameters:

* <code>user_id</code> – The user's id
* <code>cid</code> - The context id

=== Upgrade User (Release 2.10 and later) ===

<code>POST /guardsupport/?action=upgrade_guest</code>

Upgrades a Guest account. This action copies all of the keys from the Guest account to a full OX account, assuming that user has Guard capabilities.

Parameters:

* <code>email</code> - The email address of the Guest user
* <code>user_id</code> – The user's new id
* <code>cid</code> - The user's new context id

== Customisation ==

Guard's templates are customisable at the user and context level. Please see [https://oxpedia.org/wiki/index.php?title=AppSuite:GuardCustomization Customisation] for details.

== Entropy ==

Guard requires entropy (randomness) to generate the private/public keys that are used. Depending on the server and it's environment, this may become a problem. Please see [https://oxpedia.org/wiki/index.php?title=AppSuite:GuardEntropy Entropy] for a possible solution.

AppSuite:OX Guard

2020-09-23T07:17:36Z

WolfgangRosenauer:

= OX Guard (Version 2.10) =

For previous versions of OX Guard, please click here
* [[AppSuite:OX_Guard_2-0 | Installation and information of OX Guard 2.0 - 2.2]]
* [[Appsuite:OX_Guard_2_8 | Installation and information of OX Guard 2.4 - 2.8]]

If upgrading from 2.6 or 2.8, please see
* [[Appsuite:OX_Guard_Upgrade_2_10|Upgrading to 2.10]]

== Overview ==

OX Guard is a fully integrated security add-on to OX App Suite that provides end users with a flexible email and file encryption solution. OX Guard is a highly scalable, multi server, feature rich solution that is so simple-to-use that end users will actually use it. With a single click a user can take control of their security and send secure emails and share encrypted files. This can be done from any device to both OX App Suite and non-OX App Suite users.

OX Guard uses standard PGP encryption for the encryption of email and files. PGP has been around for a long time, yet has not really caught on with the masses. This is generally blamed on the confusion and complications of managing the keys, understanding trust, PGP format types, and lack of trusted central key repositories. Guard simplifies all of this, making PGP encryption as easy as a one click process, with no keys to keep track of, yet the options of advanced PGP management for those that know how.

This article will guide you through the installation of Guard and describes the basic configuration and software requirements. As it is intended as a quick walk-through it assumes an existing installation of the operating system including a single server App Suite setup as well as average system administration skills. This guide will also show you how to setup a basic installation with none of the typically used distributed environment settings. The objective of this guide is:

* To setup a single server installation
* To setup a single Guard instance on an existing Open-Xchange installation, no cluster
* To use the database service on the existing Open-Xchange installation for Guard, no replication
* To provide a basic configuration setup, no mail server configuration

=== Key Features ===

* Simple security at the touch of a button
* Provides user based security - Separate from provider
* Supplementary security to Provider based security - Layered
* Powerful features yet simple to use and understand
* Security - Inside and outside of the OX environment
* Email and Drive integration
* Uses proven PGP security

=== Availability ===

If an OX App Suite customer would like to evaluate OX Guard integration, the first step is to contact OX Sales. OX Sales will then work on the request and send prices and license/API (for the hosted infrastructure) key details to the customer.

=== Requirements ===

Please review [https://oxpedia.org/wiki/index.php?title=AppSuite:OX_System_Requirements#OX_Guard OX Guard Requirements] for a full list of requirements.

Since OX Guard is a Microservice it can either be added to an existing Open-Xchange installation or it can be deployed on a dedicated environment. The version of Guard installed is dependent on the Appsuite version installed. Please refer to the version matrix below.

==== Prerequisites ====

* Open-Xchange REST API
* Grizzly HTTP connector (open-xchange-grizzly)
* A supported Java Virtual Machine (Java 8)
* An Open-Xchange App Suite installation (see version Matrix)
* Please Note: To get access to the latest minor features and bug fixes, you need to have a valid license. The article [https://oxpedia.org/wiki/index.php?title=AppSuite:UpdatingOXPackages Updating OX-Packages] explains how that can be done.

==== Version Matrix ====
{|
! style="text-align:left;"| Core Version
! Guard Version
|-
|7.8.1
|2.4.0 or 2.4.2
|-
|7.8.2
|2.4.2
|-
|7.8.3
|2.6.0
|-
|7.8.4
|2.8.0
|-
|7.10.0
|2.10.0
|-
|7.10.1
|2.10.1
|-
|7.10.2
|2.10.2
|-
|7.10.3
|2.10.3
|-
|7.10.4
|2.10.4
|}

=== Important Notes ===

==== Customisation ====

OX Guard version supports branding / theming using the configuration cascade, defining a templateID for a user or context. Check the [https://oxpedia.org/wiki/index.php?title=AppSuite:GuardCustomization OX Guard Customisation] article for more details.

==== Mail Resolver ====

READ THIS VERY CAREFULLY; BEFORE PROCEEDING WITH GUARD INSTALLATION!

The Guard installation must be able to determine if an email recipient is a local OX user or if it should be a guest account. The default MailResolver uses the context domain name to do this. On many installations, domains may extend across multiple context and multiple database shards. In these cases, the default MailResolver won't work. In addition, if a custom authentication package is used, the Mail Resolver will likely not work.

Once Guard is installed, please be sure to test the mail resolver using:

<source lang="bash">/opt/open-xchange/sbin/guard test email@domain</source>
to see if the mail Resolver works.

If the test does not work, you will likely need a custom Mail Resolver. Please see [https://oxpedia.org/wiki/index.php?title=AppSuite:GuardMailResolver Mail Resolver] page

This resolver software ''depends heavily on your local deployment''.

== Download and Installation ==

=== General ===

The installation of the <code>open-xchange-guard-backend-plugin</code> package which is required for Guard and the main <code>open-xchange-guard</code> package in version 2.4.0 or higher will eventually execute database update tasks if installed and activated. Please take this into account.

There are several components to the Guard service. They can be all installed on the same server as the OX middleware or on a separate server.

The components required for the OX middleware are: <code>open-xchange-rest</code>, <code>open-xchange-guard-backend-plugin</code> and <code>open-xchange-guard-ui</code>.

The components required for the OX frontend are: <code>open-xchange-guard-ui-static</code> and optionally <code>open-xchange-guard-help-en-us</code> (or preferred language for help files).

The components required for the Guard server <code>open-xchange-guard</code> and either <code>open-xchange-guard-file-storage</code> or <code>open-xchange-guard-s3-storage</code> depending on what storage you want to use. The examples below make use of the <code>open-xchange-guard-file-storage</code>. Adjust the commands accordingly to fit your needs. In addition <code>open-xchange</code> and <code>open-xchange-core</code> are required to run OX Guard.

=== Debian Linux 9.0 (Stretch) ===

If not already done, add the following repositories to your Open-Xchange apt configuration:

deb https://software.open-xchange.com/products/guard/stable/guard/DebianStretch /
deb https://software.open-xchange.com/products/appsuite/stable/backend/DebianStretch /

and then run for a single node installation:

$ apt-get update
$ apt-get install open-xchange-rest open-xchange-guard open-xchange-guard-file-storage open-xchange-guard-ui open-xchange-guard-ui-static open-xchange-guard-backend-plugin

or the following for a distributed installation:

$ apt-get update
$ apt-get install open-xchange-guard open-xchange-guard-file-storage
The packages <code>open-xchange-guard-ui</code> <code>open-xchange-rest</code> and <code>open-xchange-guard-backend-plugin</code> missing in the distributed installation have to be installed on the node running the middleware. The package <code>open-xchange-guard-ui-static</code> must be installed in the frontend (apache node).

=== Debian Linux 10.0 (Buster) *Version 2.10.3+ only* ===

If not already done, add the following repositories to your Open-Xchange apt configuration:

deb https://software.open-xchange.com/products/guard/stable/guard/DebianBuster /
deb https://software.open-xchange.com/products/appsuite/stable/backend/DebianBuster /

and then run for a single node installation:

$ apt-get update
$ apt-get install open-xchange-rest open-xchange-guard open-xchange-guard-file-storage open-xchange-guard-ui open-xchange-guard-ui-static open-xchange-guard-backend-plugin

or the following for a distributed installation:

$ apt-get update
$ apt-get install open-xchange-guard open-xchange-guard-file-storage
The packages <code>open-xchange-guard-ui</code> <code>open-xchange-rest</code> and <code>open-xchange-guard-backend-plugin</code> missing in the distributed installation have to be installed on the node running the middleware. The package <code>open-xchange-guard-ui-static</code> must be installed in the frontend (apache node).

=== RedHat Enterprise Linux 6 or CentOS 6 (valid until v2.10.3) ===

If not already done, add the following repositories to your Open-Xchange yum configuration:

[open-xchange-guard-stable-guard]
name=Open-Xchange-guard-stable-guard
baseurl=https://software.open-xchange.com/products/guard/2.10.3/guard/RHEL6/
gpgkey=https://software.open-xchange.com/oxbuildkey.pub
enabled=1
gpgcheck=1
metadata_expire=0m

[ox-backend]
name=Open-Xchange-backend
baseurl=https://software.open-xchange.com/products/appsuite/7.10.3/backend/RHEL6/
gpgkey=https://software.open-xchange.com/oxbuildkey.pub
enabled=1
gpgcheck=1
metadata_expire=0m

and then run for a single node installation:

$ yum update
$ yum install open-xchange-rest open-xchange-guard open-xchange-guard-file-storage open-xchange-guard-ui open-xchange-guard-ui-static open-xchange-guard-backend-plugin
or the following for a distributed installation:

$ yum update
$ yum install open-xchange-guard open-xchange-guard-file-storage
The packages <code>open-xchange-guard-ui</code> <code>open-xchange-rest</code> and <code>open-xchange-guard-backend-plugin</code> missing in the distributed installation have to be installed on the node running the middleware. The package <code>open-xchange-guard-ui-static</code> must be installed in the frontend (apache node).

=== Redhat Enterprise Linux 7 or CentOS 7 ===

If not already done, add the following repositories to your Open-Xchange yum configuration:

[open-xchange-guard-stable-guard]
name=Open-Xchange-guard-stable-guard
baseurl=https://software.open-xchange.com/products/guard/stable/guard/RHEL7/
gpgkey=https://software.open-xchange.com/oxbuildkey.pub
enabled=1
gpgcheck=1
metadata_expire=0m

[ox-backend]
name=Open-Xchange-backend
baseurl=https://software.open-xchange.com/products/appsuite/stable/backend/RHEL7/
gpgkey=https://software.open-xchange.com/oxbuildkey.pub
enabled=1
gpgcheck=1
metadata_expire=0m

and then run for a single node installation:

$ yum update
$ yum install open-xchange-rest open-xchange-guard open-xchange-guard-file-storage open-xchange-guard-ui open-xchange-guard-ui-static open-xchange-guard-backend-plugin
or the following for a distributed installation:

$ yum update
$ yum install open-xchange-guard open-xchange-guard-file-storage

The packages <code>open-xchange-guard-ui</code> <code>open-xchange-rest</code> and <code>open-xchange-guard-backend-plugin</code> missing in the distributed installation have to be installed on the node running the middleware. The package <code>open-xchange-guard-ui-static</code> must be installed in the frontend (apache node).

=== SUSE Linux Enterprise Server 12 (valid until 2.10.3) ===

Add the package repository using zypper if not already present:

$ zypper ar https://software.open-xchange.com/products/guard/2.10.3/guard/SLE_12 guard-stable-guard
$ zypper ar https://software.open-xchange.com/products/appsuite/7.10.3/backend/SLE_12 ox-backend

and then run for a single node installation:

$ zypper ref
$ zypper in open-xchange-rest open-xchange-guard open-xchange-guard-file-storage open-xchange-guard-ui open-xchange-guard-ui-static

or the following for a distributed installation:

$ zypper ref
$ zypper in open-xchange-guard open-xchange-guard-file-storage

The packages <code>open-xchange-guard-ui</code> <code>open-xchange-rest</code> and <code>open-xchange-guard-backend-plugin</code> missing in the distributed installation have to be installed on the node running the middleware. The package <code>open-xchange-guard-ui-static</code> must be installed in the frontend (apache node).

=== Univention Corporate Server ===

If you have purchased the OX App Suite for UCS, the OX Guard is part of the offering. OX Guard is available in the Univention App Center. Please check the UMC module App Center for the installation of the OX Guard at your already available environment.

Please note: By default, OX Guard generates the link to the secure content for external recipients on the basis of the local fully qualified domain name (FQDN). If the local FQDN is not reachable from the Internet, it has to be specified manually. This can be done by setting a UCR variable, e.g. via the UMC module "Univention Configuration Registry". The variable has to contain the external FQDN of the OX Guard system:

<source lang="bash">oxguard/cfg/guard.properties/com.openexchange.guard.externalEmailURL=HOSTNAME.DOMAINNAME</source>

== Update OX Guard ==

This section contains information about updating a 2.10.0 version (e.g. for patch fixes). Upgrading from prior versions is discussed in different articles.

=== Debian Linux 9.0 (Stretch) ===

If not already done, add the following repositories to your Open-Xchange apt configuration:

deb <https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/guard/stable/guard/updates/DebianStretch />
deb <https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/appsuite/stable/backend/DebianStretch /</source>>

Then run:

$ apt-get update
$ apt-get dist-upgrade</source>

If you want to see, what apt-get is going to do without actually doing it, you can run:

$ apt-get dist-upgrade -s</source>

=== Redhat Enterprise Linux 6 or CentOS 6 (valid until 2.10.3) ===

If not already done, add the following repositories to your Open-Xchange yum configuration:

[open-xchange-guard-stable-guard-updates]
name=Open-Xchange-guard-stable-guard-updates
baseurl=https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/guard/2.10.3/guard/updates/RHEL6/
gpgkey=https://software.open-xchange.com/oxbuildkey.pub
enabled=1
gpgcheck=1
metadata_expire=0m

[ox-backend]
name=Open-Xchange-backend
baseurl=https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/appsuite/7.10.3/backend/updates/RHEL6/
gpgkey=https://software.open-xchange.com/oxbuildkey.pub
enabled=1
gpgcheck=1
metadata_expire=0m</source>

and then run:

$ yum update
$ yum upgrade</source>

=== Redhat Enterprise Linux 7 or CentOS 7 ===

If not already done, add the following repositories to your Open-Xchange yum configuration:

[open-xchange-guard-stable-guard-updates]
name=Open-Xchange-guard-stable-guard-updates
baseurl=https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/guard/stable/guard/updates/RHEL7/
gpgkey=https://software.open-xchange.com/oxbuildkey.pub
enabled=1
gpgcheck=1
metadata_expire=0m

[ox-backend]
name=Open-Xchange-backend
baseurl=https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/appsuite/stable/backend/updates/RHEL7/
gpgkey=https://software.open-xchange.com/oxbuildkey.pub
enabled=1
gpgcheck=1
metadata_expire=0m</source>

and then run:

$ yum update
$ yum upgrade</source>

=== SUSE Linux Enterprise Server 12 (valid until 2.10.3) ===

Add the package repository using <code>zypper</code> if not already present:

$ zypper ar https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/guard/2.10.3/guard/updates/SLE_12 guard-stable-guard-updates
$ zypper ar https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/appsuite/7.10.3/backend/updates/SLE_12 ox-backend</source>

and then run:

$ zypper dup -r guard-stable-guard-backend-updates
$ zypper dup -r guard-stable-guard-ui-updates</source>

You might need to run:

$ zypper ref</source>

to update the repository metadata before running <code>zypper</code> up.

=== Univention Corporate Server ===

If you have purchased the OX App Suite for UCS, the OX Guard is part of the offering. OX Guard is available in the Univention App Center. Please check the UMC module App Center for the update of the OX Guard.

== Configuration ==

The following gives an overview of the most important settings to enable Guard for users on the Open-Xchange installation. Some of those settings have to be modified in order to establish the database and REST API access from the Guard service. All settings relating to the Guard backend component are located in the configuration file <code>guard-core.properties</code> located in <code>/opt/open-xchange/etc</code>. The default configuration should be sufficient for a basic "up-and-running" setup (with the exception of defining the database username and password). Please refer to the inline documentation of the configuration file for more advanced options. Additional information can be found in the [https://oxpedia.org/wiki/index.php?title=AppSuite:OX_Guard_Configuration_2_10 Guard Configuration] article.

=== Basic Configuration ===

<source lang="bash">$ vim /opt/open-xchange/etc/guard-core.properties</source>
Guard database for storing Guard user information, main lookup tables:

<source lang="bash">com.openexchange.guard.oxguardDatabaseHostname=localhost</source>
Guard database that stores keys for guest users. May be the same as above. New guest shards will be created on this database as needed. If not supplied, will use the <code>oxguardDatabaseHostname</code>:

<source lang="bash">com.openexchange.guard.oxguardShardDatabase=localhost</source>
Username and Password for the databases above:

<source lang="bash">com.openexchange.guard.databaseUsername=openexchange
com.openexchange.guard.databasePassword=db_password</source>
Open-Xchange REST API host:

<source lang="bash">com.openexchange.guard.restApiHostname=localhost</source>
Open-Xchange REST API username and password (need to be defined in the OX backend in the "Configure services" below):

<source lang="bash">com.openexchange.guard.restApiUsername=apiusername
com.openexchange.guard.restApiPassword=apipassword</source>
External URL for this Open-Xchange installation. This setting will be used to generate the link to the secure content for external recipients:

<source lang="bash">com.openexchange.guard.externalEmailURL=URL_TO_OX</source>
=== Middleware Configuration on OX Guard node ===

If you are installing OX Guard on a node that until yet did not host an Open-Xchange middleware you have to additionally configure some parts of the following properties files:

* <code>configdb.properties</code>: information about the existing configuration database.
* <code>server.properties</code>: information about the connections have to be set.
* <code>system.properties</code>: at least <code>SERVER_NAME</code> should be set.

=== Sevices Configuration ===

==== Apache ====

Configure the <code>mod_proxy_http</code> module by adding the Guard API.

===== Redhat Enterprise Linux 6 or CentOS 6 =====

<source lang="bash">$ vim /etc/httpd/conf.d/proxy_http.conf</source>

===== Debian GNU/Linux 9.0 =====

<source lang="bash">$ vim /etc/apache2/conf-enabled/proxy_http.conf</source>

<Proxy balancer://oxguard>
Order deny,allow
Allow from all

BalancerMember http://localhost:8009/ timeout=1800 smax=0 ttl=60 retry=60 loadfactor=100 route=OX1
ProxySet stickysession=JSESSIONID|jsessionid scolonpathdelim=ON
SetEnv proxy-initial-not-pooled
SetEnv proxy-sendchunked
</Proxy>

ProxyPass /appsuite/api/oxguard balancer://oxguard/oxguard
ProxyPass /pks balancer://oxguard/pgp
ProxyPass /.well-known/openpgpkey/hu balancer://oxguard/hu

'''Please Note''': The Guard API settings must be inserted '''''before''''' the existing <code>ProxyPass /appsuite/api</code> parameter.

'''Also Note''': If you already have a Proxy balancer for the OX backend with the same URL (say http://localhost:8080) then you don't need the second BalancerMember entry, and you can just have the ProxyPass address that balancer instead.

After the configuration is done, restart the Apache webserver

<source lang="bash">$ apachectl restart</source>

=== Open-Xchange Middleware Configuration ===

Edit the <code>guard-api.properties</code> configuration file for the OX backend where the guard-backend-plugin was installed. Please remove comments in front of the following settings to the configuration file <code>guard-api.properties</code> on the Open-Xchange backend servers:

<source lang="bash">$ vim /opt/open-xchange/etc/guard-api.properties</source>
<source lang="bash"># OX Guard general permission, required to activate Guard in the AppSuite UI.
com.openexchange.capability.guard=true

# Default theme template id for all users that have no custom template id configured.
com.openexchange.guard.templateID=0</source>
Configure the API username and password that you assigned to Guard in the <code>server.properties</code> file:

<source lang="bash">$ vim /opt/open-xchange/etc/server.properties</source>
<source lang="bash"># Specify the user name used for HTTP basic auth by internal REST servlet
com.openexchange.rest.services.basic-auth.login=apiusername

# Specify the password used for HTTP basic auth by internal REST servlet
com.openexchange.rest.services.basic-auth.password=apipassword</source>
Finally, the OX backend needs to know where the Guard server is located. This is used to notify the Guard server of changes in users, and to send emails marked for signature. The URL for the Guard server should include the URL suffix <code>/guardadmin</code>. In the event of a cluster setup, any Guard server can be referenced here, as it is not session specific, though ideally would have a HTTP load balancer/failover URL:

<source lang="bash">$ vim /opt/open-xchange/etc/guard-api.properties</source>
<source lang="bash"># Specifies the URI to the OX Guard end-point; e.g. http://guard.host.invalid:8081/guardadmin
# Default is empty
com.openexchange.guard.endpoint=http://guardserver:8009/guardadmin</source>
Restart the OX backend

<source lang="bash">$ /etc/init.d/open-xchange restart</source>
==== SELinux ====

Running SELinux prohibits your local Open-Xchange backend service to connect to localhost:8009, which is where the Guard backend service listens to. In order to allow localhost connections to 8009 execute the following:

<source lang="bash">$ setsebool -P httpd_can_network_connect 1</source>
=== Generating the <code>oxguardpass</code> ===

Once the Guard configuration (database and backend configuration) and the service configuration has been applied, the Guard administration script needs to be executed in order to create the master password file in <code>/opt/open-xchange/etc/oxguardpass</code>. The initiation only needs to be done '''once''' for a multi server setup, for details please see the sections '''Optional''' and/or '''Clustering'''.

'''Please Note''': If you run a cluster of OX / Guard nodes, only execute this command on '''ONE''' node. Not on all nodes! See [https://oxpedia.org/wiki/index.php?title=AppSuite:GuardCluster OX Guard Clustering] for details.

<source lang="bash">$ /opt/open-xchange/sbin/guard --init</source>
'''Please Note''': It is important to understand that the master password file located at <code>/opt/open-xchange/etc/oxguardpass</code> is required to reset user passwords; without them the administrator will not be able to reset user passwords anymore in the future. The file contains the passwords used to encrypt the master database key, as well as passwords used to encrypt protected data in the users table. It must be the same on all Guard servers.

=== Test Setup ===

Not required, but it is a good idea to test the Guard setup before enabling for any users. The test function will verify that Guard has a good connection to the OX backend, and that it can resolve email addresses to users.

To test, use an email address that exists on the OX backend (john@example.com for this example)

<source lang="bash">/opt/open-xchange/sbin/guard --test john@example.com</source>
Guard should return information from the OX backend regarding the user associated with "john@example.com". Problems resolving information for the user should be resolved before using Guard. Check Rest API passwords and settings if errors returned.

=== Enabling Guard for Users ===

Guard provides two capabilities for users in the environment as well as a basic "core" level:

* Guard: <code>com.openexchange.capability.guard</code>
* Guard Mail: <code>com.openexchange.capability.guard-mail</code>
* Guard Drive: <code>com.openexchange.capability.guard-drive</code>

The "core" Guard enabled a basic read functionality for Guard encrypted emails. We recommend enabling this for all users, as this allows all recipients to read Guard emails sent to them. Great opportunity for upsell. Recipients with only Guard enabled can then do a secure reply to the sender, but they can't start a new email or add recipients.

'''Guard Mail''' and '''Guard Drive''' are additional options for users. "Guard Mail" allows users the full functionality of Guard emails. "Guard Drive" allows for encryption and decryption of drive files.

Each of those two Guard components is enabled for all users that have the according capability configured. Please note that users need to have the Drive permission set to use Guard Drive. So the users that have Guard Drive enabled must be a subset of those users with OX Drive permission. Since v7.6.0 we enforce this via the default configuration. Those capabilities can be activated for specific user by using the Open-Xchange provisioning scripts:

==== Guard Mail: ====

<source lang="bash">$ /opt/open-xchange/sbin/changeuser -c 1 -A oxadmin -P admin_password -u testuser --config/com.openexchange.capability.guard-mail=true</source>
==== Guard Drive: ====

<source lang="bash">$ /opt/open-xchange/sbin/changeuser -c 1 -A oxadmin -P admin_password -u testuser --config/com.openexchange.capability.guard-drive=true</source>
'''Please Note''': Guard Drive requires Guard Mail to be configured for the user as well. In addition, these capabilities may be configured globally by editing the <code>guard-api.properties</code> file on the OX backend.

=== External Guest recipients: ===
Starting in Guard 2.10.0, when an encrypted email is sent to a user that does not have Guard, a guest account is created for them in appsuite. The recipient uses the Guest account to read the encrypted email. These guest users MUST have guard capabilities. To do this, guard capability must be added to guest accounts.
<code>/opt/open-xchange/etc/share.properties</code>
<source lang="bash">com.openexchange.share.guestCapabilityMode=static
com.openexchange.share.staticGuestCapabilities=guard</source>
In a distributed system, the Guest accounts should not be considered transient. Guard servers must be able to verify the guest account exists in the session storage services.
<source lang="bash">com.openexchange.share.transientSessions=false</source>

=== Guest Storage ===
When an encrypted email is sent to an external Guest, a copy of the fully encrypted email is stored on the server. This is used to create an inbox of encrypted emails for the guest. By entering in a password, the emails can be decrypted and displayed.

How these files are stored depend on which package, open-xchange-guard-file-storage or open-xchange-guard-s3-storage, was installed.

The file retention policy is configured in the guard-core.properties file.

=== Recipient key detection ===

==== Local ====

Guard needs to determine if an email recipients email address is an internal or external (non-ox) user.

To detect if the recipient is an account on the same OX Guard system there is a mechanism needed to map a recipient mail address to the correct local OX context. The default implementation delivered in the product achieves that by looking up the mail domain (@example.com) within the list of context mappings. That is at least not possible in case of ISPs where different users/contexts use the same mail domain. In case your OX system does not use mail domains in context mappings it is required to deploy an OX OSGi bundle implementing the <code>com.openexchange.mailmapping.MailResolver</code> class or by interfacing Guard with your mail resolver system. Please see [https://oxpedia.org/wiki/index.php?title=AppSuite:GuardMailResolver OX Guard Mail Resolver] for details.

==== External ====

Starting with Guard 2.0, Guard will use public PGP Key servers if configured to find PGP Public keys. In addition, Guard will also look up SRV records for PGP Key servers for a recipients domain. This follows the standards [http://tools.ietf.org/html/draft-shaw-openpgp-hkp-00#page-9 OpenPGP Draft].

External PGP servers to use can be configured in the guard.properties file on the Guard servers.

<source lang="bash">com.openexchange.guard.publicPGPDirectory = hkp://keys.gnupg.net:11371, hkp://pgp.mit.edu:11371</source>
If you would like this Guard installation discoverable by other Guard servers, then create an SRV record for each domain ("example.com" in this illustration):

<source lang="bash">_hkp._tcp.example.com. 28800 IN SRV 10 1 80 appsuite.example.com.</source>

'''Please Note''' PGP Public key servers by default append use the URL server/pks when the record is obtained from an SRV record. The proxy above routes anything with the Apache domain/pks to the OX Guard PGP server.

Guard keys are also discoverable using the webkey service as specified here: https://tools.ietf.org/html/draft-koch-openpgp-webkey-service-02
This is enabled if you include the
<source lang="bash">ProxyPass /.well-known/openpgpkey/hu balancer://oxguard/hu</source>
in the proxy_http.conf as above.
Please note that the well-known request is targeted on the domain part of the mail adress. Therefore clients will request for a mail address name@example.com the URI https://example.com/.well-known/openpgpkey/hu/...

That means that there is the likely need that some sort of proxying or rewriting from the webserver providing the domain needs to happen. For example for proxying using Apache 2.4 it would roughly look like this:

<source lang="bash">
SSLProxyEngine on
<LocationMatch /.well-known/openpgpkey/>
ProxyPass https://ox.example.com/.well-known/openpgpkey/
</LocationMatch>
</source>

=== Clustering ===

You can run multiple OX Guard servers in your environment to ensure high availability or enhance scalability. OX Guard integrates seamlessly into the existing Open-Xchange infrastructure by using the existing interface standards and is therefor transparent to the environment. A couple of things have to be prepared in order to loosely couple OX Guard servers with Open-Xchange servers in a cluster.

==== MySQL ====

The MySQL servers need to be configured in order to allow access to the configdb of Open-Xchange. To do so you need to set the following configuration in the MySQL <code>my.cnf</code>:

<source lang="bash">bind = 0.0.0.0</source>
This allows the Guard backend to bind to the MySQL host which is configured in the <code>guard-core.properties</code> file with <code>com.openexchange.guard.configdbHostname</code>. After the bind for the MySQL instance is configured and the OX Guard backend would be able to connect to the configured host, you have to grant access for the OX Guard service on the MySQL instance to manage the databases. Do so by connecting to the MySQL server via the MySQL client. Authenticate if necessary and execute the following, please note that you have to modify the hostname / IP address of the client who should be able to connect to this database, it should include all possible OX Guard servers:

<source lang="sql">GRANT ALL PRIVILEGES ON *.* TO 'openexchange'@'oxguard.example.com' IDENTIFIED BY ‘secret’;</source>

==== Apache ====

OX Guard uses the Open-Xchange REST API to store and fetch data from the Open-Xchange databases. The REST API is a servlet running in the Grizzly container. By default it is not exposed as a servlet through Apache and is only accessibly via port 8009. In order to use Apache's load balancing via <code>mod_proxy</code> we need to add a servlet called "preliminary" to <code>proxy_http.conf</code>, example based on a clustered <code>mod_proxy</code>configuration:

<Location /preliminary>
Order Deny,Allow
Deny from all
# Only allow access from Guard 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.
</Location>

ProxyPass /preliminary balancer://oxcluster/preliminary

Make sure that the balancer is properly configured in the <code>mod_proxy</code> configuration. Examples on how to do so can be found in our clustering configuration for Open-Xchange AppSuite. Like explained in the example above, please make sure that this location is only available in your internal network, there is no need to expose <code>/preliminary</code> to the public, it is only used by Guard servers to connect to the OX backend. If you have a load balancer in front of the Apache cluster you should consider blocking access to <code>/preliminary</code> from WAN to restrict access to the servlet to internal network services only.

Now add the OX Guard <code>BalancerMembers</code> to the oxguard balancer configuration (also in <code>proxy_http.conf</code>) to address all your OX Guard nodes in the cluster in this balancer configuration. The configuration has to be applied to all Apache nodes within the cluster.

If the Apache server is a dedicated server <code>/</code> instance you also have to install the OX Guard UI-Static package on all Apache nodes in the cluster in order to provide static files like images or CSS to the OX Guard client. Example for Debian (the OX Guard repository has to be configured in the package management prior):

<source lang="bash">$ apt-get install open-xchange-guard-ui-static</source>

==== Open-Xchange ====

Disable the Open-Xchange IPCheck for session verification. This is required because OX Guard will use the users session cookie to connect to the Open-Xchange REST API, but as a different IP address than the OX Guard server has been used during authentication the request would fail if you don't disable the IPCheck:

<source lang="bash">$ vim /opt/open-xchange/etc/server.properties</source>
and set:

<source lang="bash">com.openexchange.IPCheck=false</source>
The OX Guard UI package has to be installed on all Open-Xchange backend nodes as well, example for Debian (the OX Guard repository has to be configured in the package management prior):

<source lang="bash">$ apt-get install open-xchange-guard-ui</source>
Restart the Open-Xchange service afterwards.

==== OX Guard ====

For details in clustering Guard servers, please see [https://oxpedia.org/wiki/index.php?title=AppSuite:GuardCluster OX Guard Clustering]. It is '''critical''' that all Guard servers have the same <code>oxguardpass</code> file. Please see the clustering link for details. Do not run <code>/opt/open-xchange/sbin/guard --init</code> on more than one server.

After all the services like MySQL, Apache and Open-Xchange have been configured you need to update the OX Guard backend configuration to point to the correct API endpoints. Set the REST API endpoint to an Apache server by setting the following value in <code>/opt/open-xchange/etc/guard-core.properties</code>:

<source lang="bash">com.openexchange.guard.restApiHostname=apache.example.com</source>
Per default Guard will try to connect to port 8009 to this host, but as we configured the REST API to be proxies thorugh the servlet <code>/preliminary</code> on every Apache we now also need to change the target port for the REST API. You can do so by adding the following line into <code>/opt/open-xchange/etc/guard-core.properties</code>:

<source lang="bash">com.openexchange.guard.oxBackendPort=80</source>
Please also change all settings in regards to MySQL like <code>com.openexchange.guard.configdbHostname</code>, <code>com.openexchange.guard.oxguardDatabaseHostname</code>, <code>com.openexchange.guard.databaseUsername</code> or <code>om.openexchange.guard.databasePassword</code>.

Afterwards restart the OX Guard service and check the log file if the OX Guard backend is able to connect to the configured REST API.

=== Multi Node ===

If you have multiple OX and Guard installations, please see the following documentation [https://oxpedia.org/wiki/index.php?title=AppSuite:OX_Guard_Modular OX Guard Modular Setup].

=== Mail Filter Integration (2.10.4+) ===

To add additional mail filter tests (verify PGP signature, or encrypt incoming), please see
[[AppSuite:OX_Guard_MailFilter | MailFilter Integration]]

== Support API ==

The OX Guard Support API enables administrative access to various functions for maintaining OX Guard from a client in a role as a support employee. A client has to do a BASIC AUTH authentication in order to access the API. Username and password can be configured in the guard-core.properties file using the following settings:

# Specify the username and password for accessing the Support API of Guard
com.openexchange.guard.supportApiUsername=
com.openexchange.guard.supportApiPassword=

In contrast to the rest of the OX Guard requests, the OX Guard support API requests are accessible using: /guardsupport. This distinction allows more flexible configuration since the support API should not always be accessible from everywhere.

'''Warning''': Exposing the support API to the internet could be huge security risk. Only add to Apache if you know what you are doing.

=== Reset password ===

<code>POST /guardsupport/?action=reset_password</code>

Performs a password reset and sends a new random generated password to a specified email address by the user or a default address if the user did not specify an email address. (''Since Guard 2.0'')

Parameters:

* <code>email</code> – The email address of the user to reset the password for
* <code>default</code> (optional) – The email address to send the new password to, if the user did not specify a secondary email address

Response:
PRIMARY if the reset was sent to the primary email address. SECONDARY if the reset email was sent to the secondary email address that the user specified

=== Expose key ===

<code>POST /guardsupport/?action=expose_key</code>

Marks a deleted user key temporary as “exposed” and creates a unique URL for downloading the exposed key. Automatic resetting of exposed keys to "not exposed" is scheduled once a day and resets all exposed keys which have been exposed before X hours, where X can be configured using com.openexchange.guard.exposedKeyDurationInHours in the guard.properties files. (''Since Guard 2.0'')

Parameters:

* <code>email</code> – The email address of the user to expose the deleted keys for
* <code>cid</code> – The context id

Response: A URL pointing to the downloadable exposed keys.

=== Delete user ===

<code>POST /guardsupport/?action=delete_user</code>

Deletes all keys related to a certain user. The keys are backed up and can be exposed using the “expose_key” call. (''Since Guard 2.0'')

Parameters:

* <code>user_id</code> – The user's id
* <code>cid</code> - The context id

=== Upgrade User (Release 2.10 and later) ===

<code>POST /guardsupport/?action=upgrade_guest</code>

Upgrades a Guest account. This action copies all of the keys from the Guest account to a full OX account, assuming that user has Guard capabilities.

Parameters:

* <code>email</code> - The email address of the Guest user
* <code>user_id</code> – The user's new id
* <code>cid</code> - The user's new context id

== Customisation ==

Guard's templates are customisable at the user and context level. Please see [https://oxpedia.org/wiki/index.php?title=AppSuite:GuardCustomization Customisation] for details.

== Entropy ==

Guard requires entropy (randomness) to generate the private/public keys that are used. Depending on the server and it's environment, this may become a problem. Please see [https://oxpedia.org/wiki/index.php?title=AppSuite:GuardEntropy Entropy] for a possible solution.

AppSuite:OX Guard

2020-09-15T09:47:02Z

WolfgangRosenauer: /* External */

= OX Guard (Version 2.10) =

For previous versions of OX Guard, please click here
* [[AppSuite:OX_Guard_2-0 | Installation and information of OX Guard 2.0 - 2.2]]
* [[Appsuite:OX_Guard_2_8 | Installation and information of OX Guard 2.4 - 2.8]]

If upgrading from 2.6 or 2.8, please see
* [[Appsuite:OX_Guard_Upgrade_2_10|Upgrading to 2.10]]

== Overview ==

OX Guard is a fully integrated security add-on to OX App Suite that provides end users with a flexible email and file encryption solution. OX Guard is a highly scalable, multi server, feature rich solution that is so simple-to-use that end users will actually use it. With a single click a user can take control of their security and send secure emails and share encrypted files. This can be done from any device to both OX App Suite and non-OX App Suite users.

OX Guard uses standard PGP encryption for the encryption of email and files. PGP has been around for a long time, yet has not really caught on with the masses. This is generally blamed on the confusion and complications of managing the keys, understanding trust, PGP format types, and lack of trusted central key repositories. Guard simplifies all of this, making PGP encryption as easy as a one click process, with no keys to keep track of, yet the options of advanced PGP management for those that know how.

This article will guide you through the installation of Guard and describes the basic configuration and software requirements. As it is intended as a quick walk-through it assumes an existing installation of the operating system including a single server App Suite setup as well as average system administration skills. This guide will also show you how to setup a basic installation with none of the typically used distributed environment settings. The objective of this guide is:

* To setup a single server installation
* To setup a single Guard instance on an existing Open-Xchange installation, no cluster
* To use the database service on the existing Open-Xchange installation for Guard, no replication
* To provide a basic configuration setup, no mail server configuration

=== Key Features ===

* Simple security at the touch of a button
* Provides user based security - Separate from provider
* Supplementary security to Provider based security - Layered
* Powerful features yet simple to use and understand
* Security - Inside and outside of the OX environment
* Email and Drive integration
* Uses proven PGP security

=== Availability ===

If an OX App Suite customer would like to evaluate OX Guard integration, the first step is to contact OX Sales. OX Sales will then work on the request and send prices and license/API (for the hosted infrastructure) key details to the customer.

=== Requirements ===

Please review [https://oxpedia.org/wiki/index.php?title=AppSuite:OX_System_Requirements#OX_Guard OX Guard Requirements] for a full list of requirements.

Since OX Guard is a Microservice it can either be added to an existing Open-Xchange installation or it can be deployed on a dedicated environment. The version of Guard installed is dependent on the Appsuite version installed. Please refer to the version matrix below.

==== Prerequisites ====

* Open-Xchange REST API
* Grizzly HTTP connector (open-xchange-grizzly)
* A supported Java Virtual Machine (Java 8)
* An Open-Xchange App Suite installation (see version Matrix)
* Please Note: To get access to the latest minor features and bug fixes, you need to have a valid license. The article [https://oxpedia.org/wiki/index.php?title=AppSuite:UpdatingOXPackages Updating OX-Packages] explains how that can be done.

==== Version Matrix ====
{|
! style="text-align:left;"| Core Version
! Guard Version
|-
|7.8.1
|2.4.0 or 2.4.2
|-
|7.8.2
|2.4.2
|-
|7.8.3
|2.6.0
|-
|7.8.4
|2.8.0
|-
|7.10.0
|2.10.0
|-
|7.10.1
|2.10.1
|-
|7.10.2
|2.10.2
|-
|7.10.3
|2.10.3
|}

=== Important Notes ===

==== Customisation ====

OX Guard version supports branding / theming using the configuration cascade, defining a templateID for a user or context. Check the [https://oxpedia.org/wiki/index.php?title=AppSuite:GuardCustomization OX Guard Customisation] article for more details.

==== Mail Resolver ====

READ THIS VERY CAREFULLY; BEFORE PROCEEDING WITH GUARD INSTALLATION!

The Guard installation must be able to determine if an email recipient is a local OX user or if it should be a guest account. The default MailResolver uses the context domain name to do this. On many installations, domains may extend across multiple context and multiple database shards. In these cases, the default MailResolver won't work. In addition, if a custom authentication package is used, the Mail Resolver will likely not work.

Once Guard is installed, please be sure to test the mail resolver using:

<source lang="bash">/opt/open-xchange/sbin/guard test email@domain</source>
to see if the mail Resolver works.

If the test does not work, you will likely need a custom Mail Resolver. Please see [https://oxpedia.org/wiki/index.php?title=AppSuite:GuardMailResolver Mail Resolver] page

This resolver software ''depends heavily on your local deployment''.

== Download and Installation ==

=== General ===

The installation of the <code>open-xchange-guard-backend-plugin</code> package which is required for Guard and the main <code>open-xchange-guard</code> package in version 2.4.0 or higher will eventually execute database update tasks if installed and activated. Please take this into account.

There are several components to the Guard service. They can be all installed on the same server as the OX middleware or on a separate server.

The components required for the OX middleware are: <code>open-xchange-rest</code>, <code>open-xchange-guard-backend-plugin</code> and <code>open-xchange-guard-ui</code>.

The components required for the OX frontend are: <code>open-xchange-guard-ui-static</code> and optionally <code>open-xchange-guard-help-en-us</code> (or preferred language for help files).

The components required for the Guard server <code>open-xchange-guard</code> and either <code>open-xchange-guard-file-storage</code> or <code>open-xchange-guard-s3-storage</code> depending on what storage you want to use. The examples below make use of the <code>open-xchange-guard-file-storage</code>. Adjust the commands accordingly to fit your needs. In addition <code>open-xchange</code> and <code>open-xchange-core</code> are required to run OX Guard.

=== Debian Linux 9.0 (Stretch) ===

If not already done, add the following repositories to your Open-Xchange apt configuration:

deb https://software.open-xchange.com/products/guard/stable/guard/DebianStretch /
deb https://software.open-xchange.com/products/appsuite/stable/backend/DebianStretch /

and then run for a single node installation:

$ apt-get update
$ apt-get install open-xchange-rest open-xchange-guard open-xchange-guard-file-storage open-xchange-guard-ui open-xchange-guard-ui-static open-xchange-guard-backend-plugin

or the following for a distributed installation:

$ apt-get update
$ apt-get install open-xchange-guard open-xchange-guard-file-storage
The packages <code>open-xchange-guard-ui</code> <code>open-xchange-rest</code> and <code>open-xchange-guard-backend-plugin</code> missing in the distributed installation have to be installed on the node running the middleware. The package <code>open-xchange-guard-ui-static</code> must be installed in the frontend (apache node).

=== Debian Linux 10.0 (Buster) *Version 2.10.3+ only* ===

If not already done, add the following repositories to your Open-Xchange apt configuration:

deb https://software.open-xchange.com/products/guard/stable/guard/DebianBuster /
deb https://software.open-xchange.com/products/appsuite/stable/backend/DebianBuster /

and then run for a single node installation:

$ apt-get update
$ apt-get install open-xchange-rest open-xchange-guard open-xchange-guard-file-storage open-xchange-guard-ui open-xchange-guard-ui-static open-xchange-guard-backend-plugin

or the following for a distributed installation:

$ apt-get update
$ apt-get install open-xchange-guard open-xchange-guard-file-storage
The packages <code>open-xchange-guard-ui</code> <code>open-xchange-rest</code> and <code>open-xchange-guard-backend-plugin</code> missing in the distributed installation have to be installed on the node running the middleware. The package <code>open-xchange-guard-ui-static</code> must be installed in the frontend (apache node).

=== RedHat Enterprise Linux 6 or CentOS 6 (valid until v2.10.3) ===

If not already done, add the following repositories to your Open-Xchange yum configuration:

[open-xchange-guard-stable-guard]
name=Open-Xchange-guard-stable-guard
baseurl=https://software.open-xchange.com/products/guard/2.10.3/guard/RHEL6/
gpgkey=https://software.open-xchange.com/oxbuildkey.pub
enabled=1
gpgcheck=1
metadata_expire=0m

[ox-backend]
name=Open-Xchange-backend
baseurl=https://software.open-xchange.com/products/appsuite/7.10.3/backend/RHEL6/
gpgkey=https://software.open-xchange.com/oxbuildkey.pub
enabled=1
gpgcheck=1
metadata_expire=0m

and then run for a single node installation:

$ yum update
$ yum install open-xchange-rest open-xchange-guard open-xchange-guard-file-storage open-xchange-guard-ui open-xchange-guard-ui-static open-xchange-guard-backend-plugin
or the following for a distributed installation:

$ yum update
$ yum install open-xchange-guard open-xchange-guard-file-storage
The packages <code>open-xchange-guard-ui</code> <code>open-xchange-rest</code> and <code>open-xchange-guard-backend-plugin</code> missing in the distributed installation have to be installed on the node running the middleware. The package <code>open-xchange-guard-ui-static</code> must be installed in the frontend (apache node).

=== Redhat Enterprise Linux 7 or CentOS 7 ===

If not already done, add the following repositories to your Open-Xchange yum configuration:

[open-xchange-guard-stable-guard]
name=Open-Xchange-guard-stable-guard
baseurl=https://software.open-xchange.com/products/guard/stable/guard/RHEL7/
gpgkey=https://software.open-xchange.com/oxbuildkey.pub
enabled=1
gpgcheck=1
metadata_expire=0m

[ox-backend]
name=Open-Xchange-backend
baseurl=https://software.open-xchange.com/products/appsuite/stable/backend/RHEL7/
gpgkey=https://software.open-xchange.com/oxbuildkey.pub
enabled=1
gpgcheck=1
metadata_expire=0m

and then run for a single node installation:

$ yum update
$ yum install open-xchange-rest open-xchange-guard open-xchange-guard-file-storage open-xchange-guard-ui open-xchange-guard-ui-static open-xchange-guard-backend-plugin
or the following for a distributed installation:

$ yum update
$ yum install open-xchange-guard open-xchange-guard-file-storage

The packages <code>open-xchange-guard-ui</code> <code>open-xchange-rest</code> and <code>open-xchange-guard-backend-plugin</code> missing in the distributed installation have to be installed on the node running the middleware. The package <code>open-xchange-guard-ui-static</code> must be installed in the frontend (apache node).

=== SUSE Linux Enterprise Server 12 (valid until 2.10.3) ===

Add the package repository using zypper if not already present:

$ zypper ar https://software.open-xchange.com/products/guard/2.10.3/guard/SLE_12 guard-stable-guard
$ zypper ar https://software.open-xchange.com/products/appsuite/7.10.3/backend/SLE_12 ox-backend

and then run for a single node installation:

$ zypper ref
$ zypper in open-xchange-rest open-xchange-guard open-xchange-guard-file-storage open-xchange-guard-ui open-xchange-guard-ui-static

or the following for a distributed installation:

$ zypper ref
$ zypper in open-xchange-guard open-xchange-guard-file-storage

The packages <code>open-xchange-guard-ui</code> <code>open-xchange-rest</code> and <code>open-xchange-guard-backend-plugin</code> missing in the distributed installation have to be installed on the node running the middleware. The package <code>open-xchange-guard-ui-static</code> must be installed in the frontend (apache node).

=== Univention Corporate Server ===

If you have purchased the OX App Suite for UCS, the OX Guard is part of the offering. OX Guard is available in the Univention App Center. Please check the UMC module App Center for the installation of the OX Guard at your already available environment.

Please note: By default, OX Guard generates the link to the secure content for external recipients on the basis of the local fully qualified domain name (FQDN). If the local FQDN is not reachable from the Internet, it has to be specified manually. This can be done by setting a UCR variable, e.g. via the UMC module "Univention Configuration Registry". The variable has to contain the external FQDN of the OX Guard system:

<source lang="bash">oxguard/cfg/guard.properties/com.openexchange.guard.externalEmailURL=HOSTNAME.DOMAINNAME</source>

== Update OX Guard ==

This section contains information about updating a 2.10.0 version (e.g. for patch fixes). Upgrading from prior versions is discussed in different articles.

=== Debian Linux 9.0 (Stretch) ===

If not already done, add the following repositories to your Open-Xchange apt configuration:

deb <https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/guard/stable/guard/updates/DebianStretch />
deb <https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/appsuite/stable/backend/DebianStretch /</source>>

Then run:

$ apt-get update
$ apt-get dist-upgrade</source>

If you want to see, what apt-get is going to do without actually doing it, you can run:

$ apt-get dist-upgrade -s</source>

=== Redhat Enterprise Linux 6 or CentOS 6 (valid until 2.10.3) ===

If not already done, add the following repositories to your Open-Xchange yum configuration:

[open-xchange-guard-stable-guard-updates]
name=Open-Xchange-guard-stable-guard-updates
baseurl=https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/guard/2.10.3/guard/updates/RHEL6/
gpgkey=https://software.open-xchange.com/oxbuildkey.pub
enabled=1
gpgcheck=1
metadata_expire=0m

[ox-backend]
name=Open-Xchange-backend
baseurl=https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/appsuite/7.10.3/backend/updates/RHEL6/
gpgkey=https://software.open-xchange.com/oxbuildkey.pub
enabled=1
gpgcheck=1
metadata_expire=0m</source>

and then run:

$ yum update
$ yum upgrade</source>

=== Redhat Enterprise Linux 7 or CentOS 7 ===

If not already done, add the following repositories to your Open-Xchange yum configuration:

[open-xchange-guard-stable-guard-updates]
name=Open-Xchange-guard-stable-guard-updates
baseurl=https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/guard/stable/guard/updates/RHEL7/
gpgkey=https://software.open-xchange.com/oxbuildkey.pub
enabled=1
gpgcheck=1
metadata_expire=0m

[ox-backend]
name=Open-Xchange-backend
baseurl=https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/appsuite/stable/backend/updates/RHEL7/
gpgkey=https://software.open-xchange.com/oxbuildkey.pub
enabled=1
gpgcheck=1
metadata_expire=0m</source>

and then run:

$ yum update
$ yum upgrade</source>

=== SUSE Linux Enterprise Server 12 (valid until 2.10.3) ===

Add the package repository using <code>zypper</code> if not already present:

$ zypper ar https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/guard/2.10.3/guard/updates/SLE_12 guard-stable-guard-updates
$ zypper ar https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/appsuite/7.10.3/backend/updates/SLE_12 ox-backend</source>

and then run:

$ zypper dup -r guard-stable-guard-backend-updates
$ zypper dup -r guard-stable-guard-ui-updates</source>

You might need to run:

$ zypper ref</source>

to update the repository metadata before running <code>zypper</code> up.

=== Univention Corporate Server ===

If you have purchased the OX App Suite for UCS, the OX Guard is part of the offering. OX Guard is available in the Univention App Center. Please check the UMC module App Center for the update of the OX Guard.

== Configuration ==

The following gives an overview of the most important settings to enable Guard for users on the Open-Xchange installation. Some of those settings have to be modified in order to establish the database and REST API access from the Guard service. All settings relating to the Guard backend component are located in the configuration file <code>guard-core.properties</code> located in <code>/opt/open-xchange/etc</code>. The default configuration should be sufficient for a basic "up-and-running" setup (with the exception of defining the database username and password). Please refer to the inline documentation of the configuration file for more advanced options. Additional information can be found in the [https://oxpedia.org/wiki/index.php?title=AppSuite:OX_Guard_Configuration_2_10 Guard Configuration] article.

=== Basic Configuration ===

<source lang="bash">$ vim /opt/open-xchange/etc/guard-core.properties</source>
Guard database for storing Guard user information, main lookup tables:

<source lang="bash">com.openexchange.guard.oxguardDatabaseHostname=localhost</source>
Guard database that stores keys for guest users. May be the same as above. New guest shards will be created on this database as needed. If not supplied, will use the <code>oxguardDatabaseHostname</code>:

<source lang="bash">com.openexchange.guard.oxguardShardDatabase=localhost</source>
Username and Password for the databases above:

<source lang="bash">com.openexchange.guard.databaseUsername=openexchange
com.openexchange.guard.databasePassword=db_password</source>
Open-Xchange REST API host:

<source lang="bash">com.openexchange.guard.restApiHostname=localhost</source>
Open-Xchange REST API username and password (need to be defined in the OX backend in the "Configure services" below):

<source lang="bash">com.openexchange.guard.restApiUsername=apiusername
com.openexchange.guard.restApiPassword=apipassword</source>
External URL for this Open-Xchange installation. This setting will be used to generate the link to the secure content for external recipients:

<source lang="bash">com.openexchange.guard.externalEmailURL=URL_TO_OX</source>
=== Middleware Configuration on OX Guard node ===

If you are installing OX Guard on a node that until yet did not host an Open-Xchange middleware you have to additionally configure some parts of the following properties files:

* <code>configdb.properties</code>: information about the existing configuration database.
* <code>server.properties</code>: information about the connections have to be set.
* <code>system.properties</code>: at least <code>SERVER_NAME</code> should be set.

=== Sevices Configuration ===

==== Apache ====

Configure the <code>mod_proxy_http</code> module by adding the Guard API.

===== Redhat Enterprise Linux 6 or CentOS 6 =====

<source lang="bash">$ vim /etc/httpd/conf.d/proxy_http.conf</source>

===== Debian GNU/Linux 9.0 =====

<source lang="bash">$ vim /etc/apache2/conf-enabled/proxy_http.conf</source>

<Proxy balancer://oxguard>
Order deny,allow
Allow from all

BalancerMember http://localhost:8009/ timeout=1800 smax=0 ttl=60 retry=60 loadfactor=100 route=OX1
ProxySet stickysession=JSESSIONID|jsessionid scolonpathdelim=ON
SetEnv proxy-initial-not-pooled
SetEnv proxy-sendchunked
</Proxy>

ProxyPass /appsuite/api/oxguard balancer://oxguard/oxguard
ProxyPass /pks balancer://oxguard/pgp
ProxyPass /.well-known/openpgpkey/hu balancer://oxguard/hu

'''Please Note''': The Guard API settings must be inserted '''''before''''' the existing <code>ProxyPass /appsuite/api</code> parameter.

'''Also Note''': If you already have a Proxy balancer for the OX backend with the same URL (say http://localhost:8080) then you don't need the second BalancerMember entry, and you can just have the ProxyPass address that balancer instead.

After the configuration is done, restart the Apache webserver

<source lang="bash">$ apachectl restart</source>

=== Open-Xchange Middleware Configuration ===

Edit the <code>guard-api.properties</code> configuration file for the OX backend where the guard-backend-plugin was installed. Please remove comments in front of the following settings to the configuration file <code>guard-api.properties</code> on the Open-Xchange backend servers:

<source lang="bash">$ vim /opt/open-xchange/etc/guard-api.properties</source>
<source lang="bash"># OX Guard general permission, required to activate Guard in the AppSuite UI.
com.openexchange.capability.guard=true

# Default theme template id for all users that have no custom template id configured.
com.openexchange.guard.templateID=0</source>
Configure the API username and password that you assigned to Guard in the <code>server.properties</code> file:

<source lang="bash">$ vim /opt/open-xchange/etc/server.properties</source>
<source lang="bash"># Specify the user name used for HTTP basic auth by internal REST servlet
com.openexchange.rest.services.basic-auth.login=apiusername

# Specify the password used for HTTP basic auth by internal REST servlet
com.openexchange.rest.services.basic-auth.password=apipassword</source>
Finally, the OX backend needs to know where the Guard server is located. This is used to notify the Guard server of changes in users, and to send emails marked for signature. The URL for the Guard server should include the URL suffix <code>/guardadmin</code>. In the event of a cluster setup, any Guard server can be referenced here, as it is not session specific, though ideally would have a HTTP load balancer/failover URL:

<source lang="bash">$ vim /opt/open-xchange/etc/guard-api.properties</source>
<source lang="bash"># Specifies the URI to the OX Guard end-point; e.g. http://guard.host.invalid:8081/guardadmin
# Default is empty
com.openexchange.guard.endpoint=http://guardserver:8009/guardadmin</source>
Restart the OX backend

<source lang="bash">$ /etc/init.d/open-xchange restart</source>
==== SELinux ====

Running SELinux prohibits your local Open-Xchange backend service to connect to localhost:8009, which is where the Guard backend service listens to. In order to allow localhost connections to 8009 execute the following:

<source lang="bash">$ setsebool -P httpd_can_network_connect 1</source>
=== Generating the <code>oxguardpass</code> ===

Once the Guard configuration (database and backend configuration) and the service configuration has been applied, the Guard administration script needs to be executed in order to create the master password file in <code>/opt/open-xchange/etc/oxguardpass</code>. The initiation only needs to be done '''once''' for a multi server setup, for details please see the sections '''Optional''' and/or '''Clustering'''.

'''Please Note''': If you run a cluster of OX / Guard nodes, only execute this command on '''ONE''' node. Not on all nodes! See [https://oxpedia.org/wiki/index.php?title=AppSuite:GuardCluster OX Guard Clustering] for details.

<source lang="bash">$ /opt/open-xchange/sbin/guard --init</source>
'''Please Note''': It is important to understand that the master password file located at <code>/opt/open-xchange/etc/oxguardpass</code> is required to reset user passwords; without them the administrator will not be able to reset user passwords anymore in the future. The file contains the passwords used to encrypt the master database key, as well as passwords used to encrypt protected data in the users table. It must be the same on all Guard servers.

=== Test Setup ===

Not required, but it is a good idea to test the Guard setup before enabling for any users. The test function will verify that Guard has a good connection to the OX backend, and that it can resolve email addresses to users.

To test, use an email address that exists on the OX backend (john@example.com for this example)

<source lang="bash">/opt/open-xchange/sbin/guard --test john@example.com</source>
Guard should return information from the OX backend regarding the user associated with "john@example.com". Problems resolving information for the user should be resolved before using Guard. Check Rest API passwords and settings if errors returned.

=== Enabling Guard for Users ===

Guard provides two capabilities for users in the environment as well as a basic "core" level:

* Guard: <code>com.openexchange.capability.guard</code>
* Guard Mail: <code>com.openexchange.capability.guard-mail</code>
* Guard Drive: <code>com.openexchange.capability.guard-drive</code>

The "core" Guard enabled a basic read functionality for Guard encrypted emails. We recommend enabling this for all users, as this allows all recipients to read Guard emails sent to them. Great opportunity for upsell. Recipients with only Guard enabled can then do a secure reply to the sender, but they can't start a new email or add recipients.

'''Guard Mail''' and '''Guard Drive''' are additional options for users. "Guard Mail" allows users the full functionality of Guard emails. "Guard Drive" allows for encryption and decryption of drive files.

Each of those two Guard components is enabled for all users that have the according capability configured. Please note that users need to have the Drive permission set to use Guard Drive. So the users that have Guard Drive enabled must be a subset of those users with OX Drive permission. Since v7.6.0 we enforce this via the default configuration. Those capabilities can be activated for specific user by using the Open-Xchange provisioning scripts:

==== Guard Mail: ====

<source lang="bash">$ /opt/open-xchange/sbin/changeuser -c 1 -A oxadmin -P admin_password -u testuser --config/com.openexchange.capability.guard-mail=true</source>
==== Guard Drive: ====

<source lang="bash">$ /opt/open-xchange/sbin/changeuser -c 1 -A oxadmin -P admin_password -u testuser --config/com.openexchange.capability.guard-drive=true</source>
'''Please Note''': Guard Drive requires Guard Mail to be configured for the user as well. In addition, these capabilities may be configured globally by editing the <code>guard-api.properties</code> file on the OX backend.

=== External Guest recipients: ===
Starting in Guard 2.10.0, when an encrypted email is sent to a user that does not have Guard, a guest account is created for them in appsuite. The recipient uses the Guest account to read the encrypted email. These guest users MUST have guard capabilities. To do this, guard capability must be added to guest accounts.
<code>/opt/open-xchange/etc/share.properties</code>
<source lang="bash">com.openexchange.share.guestCapabilityMode=static
com.openexchange.share.staticGuestCapabilities=guard</source>
In a distributed system, the Guest accounts should not be considered transient. Guard servers must be able to verify the guest account exists in the session storage services.
<source lang="bash">com.openexchange.share.transientSessions=false</source>

=== Guest Storage ===
When an encrypted email is sent to an external Guest, a copy of the fully encrypted email is stored on the server. This is used to create an inbox of encrypted emails for the guest. By entering in a password, the emails can be decrypted and displayed.

How these files are stored depend on which package, open-xchange-guard-file-storage or open-xchange-guard-s3-storage, was installed.

The file retention policy is configured in the guard-core.properties file.

=== Recipient key detection ===

==== Local ====

Guard needs to determine if an email recipients email address is an internal or external (non-ox) user.

To detect if the recipient is an account on the same OX Guard system there is a mechanism needed to map a recipient mail address to the correct local OX context. The default implementation delivered in the product achieves that by looking up the mail domain (@example.com) within the list of context mappings. That is at least not possible in case of ISPs where different users/contexts use the same mail domain. In case your OX system does not use mail domains in context mappings it is required to deploy an OX OSGi bundle implementing the <code>com.openexchange.mailmapping.MailResolver</code> class or by interfacing Guard with your mail resolver system. Please see [https://oxpedia.org/wiki/index.php?title=AppSuite:GuardMailResolver OX Guard Mail Resolver] for details.

==== External ====

Starting with Guard 2.0, Guard will use public PGP Key servers if configured to find PGP Public keys. In addition, Guard will also look up SRV records for PGP Key servers for a recipients domain. This follows the standards [http://tools.ietf.org/html/draft-shaw-openpgp-hkp-00#page-9 OpenPGP Draft].

External PGP servers to use can be configured in the guard.properties file on the Guard servers.

<source lang="bash">com.openexchange.guard.publicPGPDirectory = hkp://keys.gnupg.net:11371, hkp://pgp.mit.edu:11371</source>
If you would like this Guard installation discoverable by other Guard servers, then create an SRV record for each domain ("example.com" in this illustration):

<source lang="bash">_hkp._tcp.example.com. 28800 IN SRV 10 1 80 appsuite.example.com.</source>

'''Please Note''' PGP Public key servers by default append use the URL server/pks when the record is obtained from an SRV record. The proxy above routes anything with the Apache domain/pks to the OX Guard PGP server.

Guard keys are also discoverable using the webkey service as specified here: https://tools.ietf.org/html/draft-koch-openpgp-webkey-service-02
This is enabled if you include the
<source lang="bash">ProxyPass /.well-known/openpgpkey/hu balancer://oxguard/hu</source>
in the proxy_http.conf as above.
Please note that the well-known request is targeted on the domain part of the mail adress. Therefore clients will request for a mail address name@example.com the URI https://example.com/.well-known/openpgpkey/hu/...

That means that there is the likely need that some sort of proxying or rewriting from the webserver providing the domain needs to happen. For example for proxying using Apache 2.4 it would roughly look like this:

<source lang="bash">
SSLProxyEngine on
<LocationMatch /.well-known/openpgpkey/>
ProxyPass https://ox.example.com/.well-known/openpgpkey/
</LocationMatch>
</source>

=== Clustering ===

You can run multiple OX Guard servers in your environment to ensure high availability or enhance scalability. OX Guard integrates seamlessly into the existing Open-Xchange infrastructure by using the existing interface standards and is therefor transparent to the environment. A couple of things have to be prepared in order to loosely couple OX Guard servers with Open-Xchange servers in a cluster.

==== MySQL ====

The MySQL servers need to be configured in order to allow access to the configdb of Open-Xchange. To do so you need to set the following configuration in the MySQL <code>my.cnf</code>:

<source lang="bash">bind = 0.0.0.0</source>
This allows the Guard backend to bind to the MySQL host which is configured in the <code>guard-core.properties</code> file with <code>com.openexchange.guard.configdbHostname</code>. After the bind for the MySQL instance is configured and the OX Guard backend would be able to connect to the configured host, you have to grant access for the OX Guard service on the MySQL instance to manage the databases. Do so by connecting to the MySQL server via the MySQL client. Authenticate if necessary and execute the following, please note that you have to modify the hostname / IP address of the client who should be able to connect to this database, it should include all possible OX Guard servers:

<source lang="sql">GRANT ALL PRIVILEGES ON *.* TO 'openexchange'@'oxguard.example.com' IDENTIFIED BY ‘secret’;</source>

==== Apache ====

OX Guard uses the Open-Xchange REST API to store and fetch data from the Open-Xchange databases. The REST API is a servlet running in the Grizzly container. By default it is not exposed as a servlet through Apache and is only accessibly via port 8009. In order to use Apache's load balancing via <code>mod_proxy</code> we need to add a servlet called "preliminary" to <code>proxy_http.conf</code>, example based on a clustered <code>mod_proxy</code>configuration:

<Location /preliminary>
Order Deny,Allow
Deny from all
# Only allow access from Guard 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.
</Location>

ProxyPass /preliminary balancer://oxcluster/preliminary

Make sure that the balancer is properly configured in the <code>mod_proxy</code> configuration. Examples on how to do so can be found in our clustering configuration for Open-Xchange AppSuite. Like explained in the example above, please make sure that this location is only available in your internal network, there is no need to expose <code>/preliminary</code> to the public, it is only used by Guard servers to connect to the OX backend. If you have a load balancer in front of the Apache cluster you should consider blocking access to <code>/preliminary</code> from WAN to restrict access to the servlet to internal network services only.

Now add the OX Guard <code>BalancerMembers</code> to the oxguard balancer configuration (also in <code>proxy_http.conf</code>) to address all your OX Guard nodes in the cluster in this balancer configuration. The configuration has to be applied to all Apache nodes within the cluster.

If the Apache server is a dedicated server <code>/</code> instance you also have to install the OX Guard UI-Static package on all Apache nodes in the cluster in order to provide static files like images or CSS to the OX Guard client. Example for Debian (the OX Guard repository has to be configured in the package management prior):

<source lang="bash">$ apt-get install open-xchange-guard-ui-static</source>

==== Open-Xchange ====

Disable the Open-Xchange IPCheck for session verification. This is required because OX Guard will use the users session cookie to connect to the Open-Xchange REST API, but as a different IP address than the OX Guard server has been used during authentication the request would fail if you don't disable the IPCheck:

<source lang="bash">$ vim /opt/open-xchange/etc/server.properties</source>
and set:

<source lang="bash">com.openexchange.IPCheck=false</source>
The OX Guard UI package has to be installed on all Open-Xchange backend nodes as well, example for Debian (the OX Guard repository has to be configured in the package management prior):

<source lang="bash">$ apt-get install open-xchange-guard-ui</source>
Restart the Open-Xchange service afterwards.

==== OX Guard ====

For details in clustering Guard servers, please see [https://oxpedia.org/wiki/index.php?title=AppSuite:GuardCluster OX Guard Clustering]. It is '''critical''' that all Guard servers have the same <code>oxguardpass</code> file. Please see the clustering link for details. Do not run <code>/opt/open-xchange/sbin/guard --init</code> on more than one server.

After all the services like MySQL, Apache and Open-Xchange have been configured you need to update the OX Guard backend configuration to point to the correct API endpoints. Set the REST API endpoint to an Apache server by setting the following value in <code>/opt/open-xchange/etc/guard-core.properties</code>:

<source lang="bash">com.openexchange.guard.restApiHostname=apache.example.com</source>
Per default Guard will try to connect to port 8009 to this host, but as we configured the REST API to be proxies thorugh the servlet <code>/preliminary</code> on every Apache we now also need to change the target port for the REST API. You can do so by adding the following line into <code>/opt/open-xchange/etc/guard-core.properties</code>:

<source lang="bash">com.openexchange.guard.oxBackendPort=80</source>
Please also change all settings in regards to MySQL like <code>com.openexchange.guard.configdbHostname</code>, <code>com.openexchange.guard.oxguardDatabaseHostname</code>, <code>com.openexchange.guard.databaseUsername</code> or <code>om.openexchange.guard.databasePassword</code>.

Afterwards restart the OX Guard service and check the log file if the OX Guard backend is able to connect to the configured REST API.

=== Multi Node ===

If you have multiple OX and Guard installations, please see the following documentation [https://oxpedia.org/wiki/index.php?title=AppSuite:OX_Guard_Modular OX Guard Modular Setup].

=== Mail Filter Integration (2.10.4+) ===

To add additional mail filter tests (verify PGP signature, or encrypt incoming), please see
[[AppSuite:OX_Guard_MailFilter | MailFilter Integration]]

== Support API ==

The OX Guard Support API enables administrative access to various functions for maintaining OX Guard from a client in a role as a support employee. A client has to do a BASIC AUTH authentication in order to access the API. Username and password can be configured in the guard-core.properties file using the following settings:

# Specify the username and password for accessing the Support API of Guard
com.openexchange.guard.supportApiUsername=
com.openexchange.guard.supportApiPassword=

In contrast to the rest of the OX Guard requests, the OX Guard support API requests are accessible using: /guardsupport. This distinction allows more flexible configuration since the support API should not always be accessible from everywhere.

'''Warning''': Exposing the support API to the internet could be huge security risk. Only add to Apache if you know what you are doing.

=== Reset password ===

<code>POST /guardsupport/?action=reset_password</code>

Performs a password reset and sends a new random generated password to a specified email address by the user or a default address if the user did not specify an email address. (''Since Guard 2.0'')

Parameters:

* <code>email</code> – The email address of the user to reset the password for
* <code>default</code> (optional) – The email address to send the new password to, if the user did not specify a secondary email address

Response:
PRIMARY if the reset was sent to the primary email address. SECONDARY if the reset email was sent to the secondary email address that the user specified

=== Expose key ===

<code>POST /guardsupport/?action=expose_key</code>

Marks a deleted user key temporary as “exposed” and creates a unique URL for downloading the exposed key. Automatic resetting of exposed keys to "not exposed" is scheduled once a day and resets all exposed keys which have been exposed before X hours, where X can be configured using com.openexchange.guard.exposedKeyDurationInHours in the guard.properties files. (''Since Guard 2.0'')

Parameters:

* <code>email</code> – The email address of the user to expose the deleted keys for
* <code>cid</code> – The context id

Response: A URL pointing to the downloadable exposed keys.

=== Delete user ===

<code>POST /guardsupport/?action=delete_user</code>

Deletes all keys related to a certain user. The keys are backed up and can be exposed using the “expose_key” call. (''Since Guard 2.0'')

Parameters:

* <code>user_id</code> – The user's id
* <code>cid</code> - The context id

=== Upgrade User (Release 2.10 and later) ===

<code>POST /guardsupport/?action=upgrade_guest</code>

Upgrades a Guest account. This action copies all of the keys from the Guest account to a full OX account, assuming that user has Guard capabilities.

Parameters:

* <code>email</code> - The email address of the Guest user
* <code>user_id</code> – The user's new id
* <code>cid</code> - The user's new context id

== Customisation ==

Guard's templates are customisable at the user and context level. Please see [https://oxpedia.org/wiki/index.php?title=AppSuite:GuardCustomization Customisation] for details.

== Entropy ==

Guard requires entropy (randomness) to generate the private/public keys that are used. Depending on the server and it's environment, this may become a problem. Please see [https://oxpedia.org/wiki/index.php?title=AppSuite:GuardEntropy Entropy] for a possible solution.

AppSuite:OX Guard

2020-09-12T08:15:38Z

WolfgangRosenauer: /* External */

= OX Guard (Version 2.10) =

For previous versions of OX Guard, please click here
* [[AppSuite:OX_Guard_2-0 | Installation and information of OX Guard 2.0 - 2.2]]
* [[Appsuite:OX_Guard_2_8 | Installation and information of OX Guard 2.4 - 2.8]]

If upgrading from 2.6 or 2.8, please see
* [[Appsuite:OX_Guard_Upgrade_2_10|Upgrading to 2.10]]

== Overview ==

OX Guard is a fully integrated security add-on to OX App Suite that provides end users with a flexible email and file encryption solution. OX Guard is a highly scalable, multi server, feature rich solution that is so simple-to-use that end users will actually use it. With a single click a user can take control of their security and send secure emails and share encrypted files. This can be done from any device to both OX App Suite and non-OX App Suite users.

OX Guard uses standard PGP encryption for the encryption of email and files. PGP has been around for a long time, yet has not really caught on with the masses. This is generally blamed on the confusion and complications of managing the keys, understanding trust, PGP format types, and lack of trusted central key repositories. Guard simplifies all of this, making PGP encryption as easy as a one click process, with no keys to keep track of, yet the options of advanced PGP management for those that know how.

This article will guide you through the installation of Guard and describes the basic configuration and software requirements. As it is intended as a quick walk-through it assumes an existing installation of the operating system including a single server App Suite setup as well as average system administration skills. This guide will also show you how to setup a basic installation with none of the typically used distributed environment settings. The objective of this guide is:

* To setup a single server installation
* To setup a single Guard instance on an existing Open-Xchange installation, no cluster
* To use the database service on the existing Open-Xchange installation for Guard, no replication
* To provide a basic configuration setup, no mail server configuration

=== Key Features ===

* Simple security at the touch of a button
* Provides user based security - Separate from provider
* Supplementary security to Provider based security - Layered
* Powerful features yet simple to use and understand
* Security - Inside and outside of the OX environment
* Email and Drive integration
* Uses proven PGP security

=== Availability ===

If an OX App Suite customer would like to evaluate OX Guard integration, the first step is to contact OX Sales. OX Sales will then work on the request and send prices and license/API (for the hosted infrastructure) key details to the customer.

=== Requirements ===

Please review [https://oxpedia.org/wiki/index.php?title=AppSuite:OX_System_Requirements#OX_Guard OX Guard Requirements] for a full list of requirements.

Since OX Guard is a Microservice it can either be added to an existing Open-Xchange installation or it can be deployed on a dedicated environment. The version of Guard installed is dependent on the Appsuite version installed. Please refer to the version matrix below.

==== Prerequisites ====

* Open-Xchange REST API
* Grizzly HTTP connector (open-xchange-grizzly)
* A supported Java Virtual Machine (Java 8)
* An Open-Xchange App Suite installation (see version Matrix)
* Please Note: To get access to the latest minor features and bug fixes, you need to have a valid license. The article [https://oxpedia.org/wiki/index.php?title=AppSuite:UpdatingOXPackages Updating OX-Packages] explains how that can be done.

==== Version Matrix ====
{|
! style="text-align:left;"| Core Version
! Guard Version
|-
|7.8.1
|2.4.0 or 2.4.2
|-
|7.8.2
|2.4.2
|-
|7.8.3
|2.6.0
|-
|7.8.4
|2.8.0
|-
|7.10.0
|2.10.0
|-
|7.10.1
|2.10.1
|-
|7.10.2
|2.10.2
|-
|7.10.3
|2.10.3
|}

=== Important Notes ===

==== Customisation ====

OX Guard version supports branding / theming using the configuration cascade, defining a templateID for a user or context. Check the [https://oxpedia.org/wiki/index.php?title=AppSuite:GuardCustomization OX Guard Customisation] article for more details.

==== Mail Resolver ====

READ THIS VERY CAREFULLY; BEFORE PROCEEDING WITH GUARD INSTALLATION!

The Guard installation must be able to determine if an email recipient is a local OX user or if it should be a guest account. The default MailResolver uses the context domain name to do this. On many installations, domains may extend across multiple context and multiple database shards. In these cases, the default MailResolver won't work. In addition, if a custom authentication package is used, the Mail Resolver will likely not work.

Once Guard is installed, please be sure to test the mail resolver using:

<source lang="bash">/opt/open-xchange/sbin/guard test email@domain</source>
to see if the mail Resolver works.

If the test does not work, you will likely need a custom Mail Resolver. Please see [https://oxpedia.org/wiki/index.php?title=AppSuite:GuardMailResolver Mail Resolver] page

This resolver software ''depends heavily on your local deployment''.

== Download and Installation ==

=== General ===

The installation of the <code>open-xchange-guard-backend-plugin</code> package which is required for Guard and the main <code>open-xchange-guard</code> package in version 2.4.0 or higher will eventually execute database update tasks if installed and activated. Please take this into account.

There are several components to the Guard service. They can be all installed on the same server as the OX middleware or on a separate server.

The components required for the OX middleware are: <code>open-xchange-rest</code>, <code>open-xchange-guard-backend-plugin</code> and <code>open-xchange-guard-ui</code>.

The components required for the OX frontend are: <code>open-xchange-guard-ui-static</code> and optionally <code>open-xchange-guard-help-en-us</code> (or preferred language for help files).

The components required for the Guard server <code>open-xchange-guard</code> and either <code>open-xchange-guard-file-storage</code> or <code>open-xchange-guard-s3-storage</code> depending on what storage you want to use. The examples below make use of the <code>open-xchange-guard-file-storage</code>. Adjust the commands accordingly to fit your needs. In addition <code>open-xchange</code> and <code>open-xchange-core</code> are required to run OX Guard.

=== Debian Linux 9.0 (Stretch) ===

If not already done, add the following repositories to your Open-Xchange apt configuration:

deb https://software.open-xchange.com/products/guard/stable/guard/DebianStretch /
deb https://software.open-xchange.com/products/appsuite/stable/backend/DebianStretch /

and then run for a single node installation:

$ apt-get update
$ apt-get install open-xchange-rest open-xchange-guard open-xchange-guard-file-storage open-xchange-guard-ui open-xchange-guard-ui-static open-xchange-guard-backend-plugin

or the following for a distributed installation:

$ apt-get update
$ apt-get install open-xchange-guard open-xchange-guard-file-storage
The packages <code>open-xchange-guard-ui</code> <code>open-xchange-rest</code> and <code>open-xchange-guard-backend-plugin</code> missing in the distributed installation have to be installed on the node running the middleware. The package <code>open-xchange-guard-ui-static</code> must be installed in the frontend (apache node).

=== Debian Linux 10.0 (Buster) *Version 2.10.3+ only* ===

If not already done, add the following repositories to your Open-Xchange apt configuration:

deb https://software.open-xchange.com/products/guard/stable/guard/DebianBuster /
deb https://software.open-xchange.com/products/appsuite/stable/backend/DebianBuster /

and then run for a single node installation:

$ apt-get update
$ apt-get install open-xchange-rest open-xchange-guard open-xchange-guard-file-storage open-xchange-guard-ui open-xchange-guard-ui-static open-xchange-guard-backend-plugin

or the following for a distributed installation:

$ apt-get update
$ apt-get install open-xchange-guard open-xchange-guard-file-storage
The packages <code>open-xchange-guard-ui</code> <code>open-xchange-rest</code> and <code>open-xchange-guard-backend-plugin</code> missing in the distributed installation have to be installed on the node running the middleware. The package <code>open-xchange-guard-ui-static</code> must be installed in the frontend (apache node).

=== RedHat Enterprise Linux 6 or CentOS 6 (valid until v2.10.3) ===

If not already done, add the following repositories to your Open-Xchange yum configuration:

[open-xchange-guard-stable-guard]
name=Open-Xchange-guard-stable-guard
baseurl=https://software.open-xchange.com/products/guard/2.10.3/guard/RHEL6/
gpgkey=https://software.open-xchange.com/oxbuildkey.pub
enabled=1
gpgcheck=1
metadata_expire=0m

[ox-backend]
name=Open-Xchange-backend
baseurl=https://software.open-xchange.com/products/appsuite/7.10.3/backend/RHEL6/
gpgkey=https://software.open-xchange.com/oxbuildkey.pub
enabled=1
gpgcheck=1
metadata_expire=0m

and then run for a single node installation:

$ yum update
$ yum install open-xchange-rest open-xchange-guard open-xchange-guard-file-storage open-xchange-guard-ui open-xchange-guard-ui-static open-xchange-guard-backend-plugin
or the following for a distributed installation:

$ yum update
$ yum install open-xchange-guard open-xchange-guard-file-storage
The packages <code>open-xchange-guard-ui</code> <code>open-xchange-rest</code> and <code>open-xchange-guard-backend-plugin</code> missing in the distributed installation have to be installed on the node running the middleware. The package <code>open-xchange-guard-ui-static</code> must be installed in the frontend (apache node).

=== Redhat Enterprise Linux 7 or CentOS 7 ===

If not already done, add the following repositories to your Open-Xchange yum configuration:

[open-xchange-guard-stable-guard]
name=Open-Xchange-guard-stable-guard
baseurl=https://software.open-xchange.com/products/guard/stable/guard/RHEL7/
gpgkey=https://software.open-xchange.com/oxbuildkey.pub
enabled=1
gpgcheck=1
metadata_expire=0m

[ox-backend]
name=Open-Xchange-backend
baseurl=https://software.open-xchange.com/products/appsuite/stable/backend/RHEL7/
gpgkey=https://software.open-xchange.com/oxbuildkey.pub
enabled=1
gpgcheck=1
metadata_expire=0m

and then run for a single node installation:

$ yum update
$ yum install open-xchange-rest open-xchange-guard open-xchange-guard-file-storage open-xchange-guard-ui open-xchange-guard-ui-static open-xchange-guard-backend-plugin
or the following for a distributed installation:

$ yum update
$ yum install open-xchange-guard open-xchange-guard-file-storage

The packages <code>open-xchange-guard-ui</code> <code>open-xchange-rest</code> and <code>open-xchange-guard-backend-plugin</code> missing in the distributed installation have to be installed on the node running the middleware. The package <code>open-xchange-guard-ui-static</code> must be installed in the frontend (apache node).

=== SUSE Linux Enterprise Server 12 (valid until 2.10.3) ===

Add the package repository using zypper if not already present:

$ zypper ar https://software.open-xchange.com/products/guard/2.10.3/guard/SLE_12 guard-stable-guard
$ zypper ar https://software.open-xchange.com/products/appsuite/7.10.3/backend/SLE_12 ox-backend

and then run for a single node installation:

$ zypper ref
$ zypper in open-xchange-rest open-xchange-guard open-xchange-guard-file-storage open-xchange-guard-ui open-xchange-guard-ui-static

or the following for a distributed installation:

$ zypper ref
$ zypper in open-xchange-guard open-xchange-guard-file-storage

The packages <code>open-xchange-guard-ui</code> <code>open-xchange-rest</code> and <code>open-xchange-guard-backend-plugin</code> missing in the distributed installation have to be installed on the node running the middleware. The package <code>open-xchange-guard-ui-static</code> must be installed in the frontend (apache node).

=== Univention Corporate Server ===

If you have purchased the OX App Suite for UCS, the OX Guard is part of the offering. OX Guard is available in the Univention App Center. Please check the UMC module App Center for the installation of the OX Guard at your already available environment.

Please note: By default, OX Guard generates the link to the secure content for external recipients on the basis of the local fully qualified domain name (FQDN). If the local FQDN is not reachable from the Internet, it has to be specified manually. This can be done by setting a UCR variable, e.g. via the UMC module "Univention Configuration Registry". The variable has to contain the external FQDN of the OX Guard system:

<source lang="bash">oxguard/cfg/guard.properties/com.openexchange.guard.externalEmailURL=HOSTNAME.DOMAINNAME</source>

== Update OX Guard ==

This section contains information about updating a 2.10.0 version (e.g. for patch fixes). Upgrading from prior versions is discussed in different articles.

=== Debian Linux 9.0 (Stretch) ===

If not already done, add the following repositories to your Open-Xchange apt configuration:

deb <https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/guard/stable/guard/updates/DebianStretch />
deb <https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/appsuite/stable/backend/DebianStretch /</source>>

Then run:

$ apt-get update
$ apt-get dist-upgrade</source>

If you want to see, what apt-get is going to do without actually doing it, you can run:

$ apt-get dist-upgrade -s</source>

=== Redhat Enterprise Linux 6 or CentOS 6 (valid until 2.10.3) ===

If not already done, add the following repositories to your Open-Xchange yum configuration:

[open-xchange-guard-stable-guard-updates]
name=Open-Xchange-guard-stable-guard-updates
baseurl=https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/guard/2.10.3/guard/updates/RHEL6/
gpgkey=https://software.open-xchange.com/oxbuildkey.pub
enabled=1
gpgcheck=1
metadata_expire=0m

[ox-backend]
name=Open-Xchange-backend
baseurl=https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/appsuite/7.10.3/backend/updates/RHEL6/
gpgkey=https://software.open-xchange.com/oxbuildkey.pub
enabled=1
gpgcheck=1
metadata_expire=0m</source>

and then run:

$ yum update
$ yum upgrade</source>

=== Redhat Enterprise Linux 7 or CentOS 7 ===

If not already done, add the following repositories to your Open-Xchange yum configuration:

[open-xchange-guard-stable-guard-updates]
name=Open-Xchange-guard-stable-guard-updates
baseurl=https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/guard/stable/guard/updates/RHEL7/
gpgkey=https://software.open-xchange.com/oxbuildkey.pub
enabled=1
gpgcheck=1
metadata_expire=0m

[ox-backend]
name=Open-Xchange-backend
baseurl=https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/appsuite/stable/backend/updates/RHEL7/
gpgkey=https://software.open-xchange.com/oxbuildkey.pub
enabled=1
gpgcheck=1
metadata_expire=0m</source>

and then run:

$ yum update
$ yum upgrade</source>

=== SUSE Linux Enterprise Server 12 (valid until 2.10.3) ===

Add the package repository using <code>zypper</code> if not already present:

$ zypper ar https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/guard/2.10.3/guard/updates/SLE_12 guard-stable-guard-updates
$ zypper ar https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/appsuite/7.10.3/backend/updates/SLE_12 ox-backend</source>

and then run:

$ zypper dup -r guard-stable-guard-backend-updates
$ zypper dup -r guard-stable-guard-ui-updates</source>

You might need to run:

$ zypper ref</source>

to update the repository metadata before running <code>zypper</code> up.

=== Univention Corporate Server ===

If you have purchased the OX App Suite for UCS, the OX Guard is part of the offering. OX Guard is available in the Univention App Center. Please check the UMC module App Center for the update of the OX Guard.

== Configuration ==

The following gives an overview of the most important settings to enable Guard for users on the Open-Xchange installation. Some of those settings have to be modified in order to establish the database and REST API access from the Guard service. All settings relating to the Guard backend component are located in the configuration file <code>guard-core.properties</code> located in <code>/opt/open-xchange/etc</code>. The default configuration should be sufficient for a basic "up-and-running" setup (with the exception of defining the database username and password). Please refer to the inline documentation of the configuration file for more advanced options. Additional information can be found in the [https://oxpedia.org/wiki/index.php?title=AppSuite:OX_Guard_Configuration_2_10 Guard Configuration] article.

=== Basic Configuration ===

<source lang="bash">$ vim /opt/open-xchange/etc/guard-core.properties</source>
Guard database for storing Guard user information, main lookup tables:

<source lang="bash">com.openexchange.guard.oxguardDatabaseHostname=localhost</source>
Guard database that stores keys for guest users. May be the same as above. New guest shards will be created on this database as needed. If not supplied, will use the <code>oxguardDatabaseHostname</code>:

<source lang="bash">com.openexchange.guard.oxguardShardDatabase=localhost</source>
Username and Password for the databases above:

<source lang="bash">com.openexchange.guard.databaseUsername=openexchange
com.openexchange.guard.databasePassword=db_password</source>
Open-Xchange REST API host:

<source lang="bash">com.openexchange.guard.restApiHostname=localhost</source>
Open-Xchange REST API username and password (need to be defined in the OX backend in the "Configure services" below):

<source lang="bash">com.openexchange.guard.restApiUsername=apiusername
com.openexchange.guard.restApiPassword=apipassword</source>
External URL for this Open-Xchange installation. This setting will be used to generate the link to the secure content for external recipients:

<source lang="bash">com.openexchange.guard.externalEmailURL=URL_TO_OX</source>
=== Middleware Configuration on OX Guard node ===

If you are installing OX Guard on a node that until yet did not host an Open-Xchange middleware you have to additionally configure some parts of the following properties files:

* <code>configdb.properties</code>: information about the existing configuration database.
* <code>server.properties</code>: information about the connections have to be set.
* <code>system.properties</code>: at least <code>SERVER_NAME</code> should be set.

=== Sevices Configuration ===

==== Apache ====

Configure the <code>mod_proxy_http</code> module by adding the Guard API.

===== Redhat Enterprise Linux 6 or CentOS 6 =====

<source lang="bash">$ vim /etc/httpd/conf.d/proxy_http.conf</source>

===== Debian GNU/Linux 9.0 =====

<source lang="bash">$ vim /etc/apache2/conf-enabled/proxy_http.conf</source>

<Proxy balancer://oxguard>
Order deny,allow
Allow from all

BalancerMember http://localhost:8009/ timeout=1800 smax=0 ttl=60 retry=60 loadfactor=100 route=OX1
ProxySet stickysession=JSESSIONID|jsessionid scolonpathdelim=ON
SetEnv proxy-initial-not-pooled
SetEnv proxy-sendchunked
</Proxy>

ProxyPass /appsuite/api/oxguard balancer://oxguard/oxguard
ProxyPass /pks balancer://oxguard/pgp
ProxyPass /.well-known/openpgpkey/hu balancer://oxguard/hu

'''Please Note''': The Guard API settings must be inserted '''''before''''' the existing <code>ProxyPass /appsuite/api</code> parameter.

'''Also Note''': If you already have a Proxy balancer for the OX backend with the same URL (say http://localhost:8080) then you don't need the second BalancerMember entry, and you can just have the ProxyPass address that balancer instead.

After the configuration is done, restart the Apache webserver

<source lang="bash">$ apachectl restart</source>

=== Open-Xchange Middleware Configuration ===

Edit the <code>guard-api.properties</code> configuration file for the OX backend where the guard-backend-plugin was installed. Please remove comments in front of the following settings to the configuration file <code>guard-api.properties</code> on the Open-Xchange backend servers:

<source lang="bash">$ vim /opt/open-xchange/etc/guard-api.properties</source>
<source lang="bash"># OX Guard general permission, required to activate Guard in the AppSuite UI.
com.openexchange.capability.guard=true

# Default theme template id for all users that have no custom template id configured.
com.openexchange.guard.templateID=0</source>
Configure the API username and password that you assigned to Guard in the <code>server.properties</code> file:

<source lang="bash">$ vim /opt/open-xchange/etc/server.properties</source>
<source lang="bash"># Specify the user name used for HTTP basic auth by internal REST servlet
com.openexchange.rest.services.basic-auth.login=apiusername

# Specify the password used for HTTP basic auth by internal REST servlet
com.openexchange.rest.services.basic-auth.password=apipassword</source>
Finally, the OX backend needs to know where the Guard server is located. This is used to notify the Guard server of changes in users, and to send emails marked for signature. The URL for the Guard server should include the URL suffix <code>/guardadmin</code>. In the event of a cluster setup, any Guard server can be referenced here, as it is not session specific, though ideally would have a HTTP load balancer/failover URL:

<source lang="bash">$ vim /opt/open-xchange/etc/guard-api.properties</source>
<source lang="bash"># Specifies the URI to the OX Guard end-point; e.g. http://guard.host.invalid:8081/guardadmin
# Default is empty
com.openexchange.guard.endpoint=http://guardserver:8009/guardadmin</source>
Restart the OX backend

<source lang="bash">$ /etc/init.d/open-xchange restart</source>
==== SELinux ====

Running SELinux prohibits your local Open-Xchange backend service to connect to localhost:8009, which is where the Guard backend service listens to. In order to allow localhost connections to 8009 execute the following:

<source lang="bash">$ setsebool -P httpd_can_network_connect 1</source>
=== Generating the <code>oxguardpass</code> ===

Once the Guard configuration (database and backend configuration) and the service configuration has been applied, the Guard administration script needs to be executed in order to create the master password file in <code>/opt/open-xchange/etc/oxguardpass</code>. The initiation only needs to be done '''once''' for a multi server setup, for details please see the sections '''Optional''' and/or '''Clustering'''.

'''Please Note''': If you run a cluster of OX / Guard nodes, only execute this command on '''ONE''' node. Not on all nodes! See [https://oxpedia.org/wiki/index.php?title=AppSuite:GuardCluster OX Guard Clustering] for details.

<source lang="bash">$ /opt/open-xchange/sbin/guard --init</source>
'''Please Note''': It is important to understand that the master password file located at <code>/opt/open-xchange/etc/oxguardpass</code> is required to reset user passwords; without them the administrator will not be able to reset user passwords anymore in the future. The file contains the passwords used to encrypt the master database key, as well as passwords used to encrypt protected data in the users table. It must be the same on all Guard servers.

=== Test Setup ===

Not required, but it is a good idea to test the Guard setup before enabling for any users. The test function will verify that Guard has a good connection to the OX backend, and that it can resolve email addresses to users.

To test, use an email address that exists on the OX backend (john@example.com for this example)

<source lang="bash">/opt/open-xchange/sbin/guard --test john@example.com</source>
Guard should return information from the OX backend regarding the user associated with "john@example.com". Problems resolving information for the user should be resolved before using Guard. Check Rest API passwords and settings if errors returned.

=== Enabling Guard for Users ===

Guard provides two capabilities for users in the environment as well as a basic "core" level:

* Guard: <code>com.openexchange.capability.guard</code>
* Guard Mail: <code>com.openexchange.capability.guard-mail</code>
* Guard Drive: <code>com.openexchange.capability.guard-drive</code>

The "core" Guard enabled a basic read functionality for Guard encrypted emails. We recommend enabling this for all users, as this allows all recipients to read Guard emails sent to them. Great opportunity for upsell. Recipients with only Guard enabled can then do a secure reply to the sender, but they can't start a new email or add recipients.

'''Guard Mail''' and '''Guard Drive''' are additional options for users. "Guard Mail" allows users the full functionality of Guard emails. "Guard Drive" allows for encryption and decryption of drive files.

Each of those two Guard components is enabled for all users that have the according capability configured. Please note that users need to have the Drive permission set to use Guard Drive. So the users that have Guard Drive enabled must be a subset of those users with OX Drive permission. Since v7.6.0 we enforce this via the default configuration. Those capabilities can be activated for specific user by using the Open-Xchange provisioning scripts:

==== Guard Mail: ====

<source lang="bash">$ /opt/open-xchange/sbin/changeuser -c 1 -A oxadmin -P admin_password -u testuser --config/com.openexchange.capability.guard-mail=true</source>
==== Guard Drive: ====

<source lang="bash">$ /opt/open-xchange/sbin/changeuser -c 1 -A oxadmin -P admin_password -u testuser --config/com.openexchange.capability.guard-drive=true</source>
'''Please Note''': Guard Drive requires Guard Mail to be configured for the user as well. In addition, these capabilities may be configured globally by editing the <code>guard-api.properties</code> file on the OX backend.

=== External Guest recipients: ===
Starting in Guard 2.10.0, when an encrypted email is sent to a user that does not have Guard, a guest account is created for them in appsuite. The recipient uses the Guest account to read the encrypted email. These guest users MUST have guard capabilities. To do this, guard capability must be added to guest accounts.
<code>/opt/open-xchange/etc/share.properties</code>
<source lang="bash">com.openexchange.share.guestCapabilityMode=static
com.openexchange.share.staticGuestCapabilities=guard</source>
In a distributed system, the Guest accounts should not be considered transient. Guard servers must be able to verify the guest account exists in the session storage services.
<source lang="bash">com.openexchange.share.transientSessions=false</source>

=== Guest Storage ===
When an encrypted email is sent to an external Guest, a copy of the fully encrypted email is stored on the server. This is used to create an inbox of encrypted emails for the guest. By entering in a password, the emails can be decrypted and displayed.

How these files are stored depend on which package, open-xchange-guard-file-storage or open-xchange-guard-s3-storage, was installed.

The file retention policy is configured in the guard-core.properties file.

=== Recipient key detection ===

==== Local ====

Guard needs to determine if an email recipients email address is an internal or external (non-ox) user.

To detect if the recipient is an account on the same OX Guard system there is a mechanism needed to map a recipient mail address to the correct local OX context. The default implementation delivered in the product achieves that by looking up the mail domain (@example.com) within the list of context mappings. That is at least not possible in case of ISPs where different users/contexts use the same mail domain. In case your OX system does not use mail domains in context mappings it is required to deploy an OX OSGi bundle implementing the <code>com.openexchange.mailmapping.MailResolver</code> class or by interfacing Guard with your mail resolver system. Please see [https://oxpedia.org/wiki/index.php?title=AppSuite:GuardMailResolver OX Guard Mail Resolver] for details.

==== External ====

Starting with Guard 2.0, Guard will use public PGP Key servers if configured to find PGP Public keys. In addition, Guard will also look up SRV records for PGP Key servers for a recipients domain. This follows the standards [http://tools.ietf.org/html/draft-shaw-openpgp-hkp-00#page-9 OpenPGP Draft].

External PGP servers to use can be configured in the guard.properties file on the Guard servers.

<source lang="bash">com.openexchange.guard.publicPGPDirectory = hkp://keys.gnupg.net:11371, hkp://pgp.mit.edu:11371</source>
If you would like this Guard installation discoverable by other Guard servers, then create an SRV record for each domain ("example.com" in this illustration):

<source lang="bash">_hkp._tcp.example.com. 28800 IN SRV 10 1 80 appsuite.example.com.</source>

'''Please Note''' PGP Public key servers by default append use the URL server/pks when the record is obtained from an SRV record. The proxy above routes anything with the Apache domain/pks to the OX Guard PGP server.

Guard keys are also discoverable using the webkey service as specified here: https://tools.ietf.org/html/draft-koch-openpgp-webkey-service-02
This is enabled if you include the
<source lang="bash">ProxyPass /.well-known/openpgpkey/hu balancer://oxguard/hu</source>
in the proxy_http.conf as above.
Please note that the well-known request is targeted on the domain part of the mail adress. Therefore clients will request for a mail address name@example.com the URI https://example.com/.well-known/openpgpkey/hu/...

=== Clustering ===

You can run multiple OX Guard servers in your environment to ensure high availability or enhance scalability. OX Guard integrates seamlessly into the existing Open-Xchange infrastructure by using the existing interface standards and is therefor transparent to the environment. A couple of things have to be prepared in order to loosely couple OX Guard servers with Open-Xchange servers in a cluster.

==== MySQL ====

The MySQL servers need to be configured in order to allow access to the configdb of Open-Xchange. To do so you need to set the following configuration in the MySQL <code>my.cnf</code>:

<source lang="bash">bind = 0.0.0.0</source>
This allows the Guard backend to bind to the MySQL host which is configured in the <code>guard-core.properties</code> file with <code>com.openexchange.guard.configdbHostname</code>. After the bind for the MySQL instance is configured and the OX Guard backend would be able to connect to the configured host, you have to grant access for the OX Guard service on the MySQL instance to manage the databases. Do so by connecting to the MySQL server via the MySQL client. Authenticate if necessary and execute the following, please note that you have to modify the hostname / IP address of the client who should be able to connect to this database, it should include all possible OX Guard servers:

<source lang="sql">GRANT ALL PRIVILEGES ON *.* TO 'openexchange'@'oxguard.example.com' IDENTIFIED BY ‘secret’;</source>

==== Apache ====

OX Guard uses the Open-Xchange REST API to store and fetch data from the Open-Xchange databases. The REST API is a servlet running in the Grizzly container. By default it is not exposed as a servlet through Apache and is only accessibly via port 8009. In order to use Apache's load balancing via <code>mod_proxy</code> we need to add a servlet called "preliminary" to <code>proxy_http.conf</code>, example based on a clustered <code>mod_proxy</code>configuration:

<Location /preliminary>
Order Deny,Allow
Deny from all
# Only allow access from Guard 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.
</Location>

ProxyPass /preliminary balancer://oxcluster/preliminary

Make sure that the balancer is properly configured in the <code>mod_proxy</code> configuration. Examples on how to do so can be found in our clustering configuration for Open-Xchange AppSuite. Like explained in the example above, please make sure that this location is only available in your internal network, there is no need to expose <code>/preliminary</code> to the public, it is only used by Guard servers to connect to the OX backend. If you have a load balancer in front of the Apache cluster you should consider blocking access to <code>/preliminary</code> from WAN to restrict access to the servlet to internal network services only.

Now add the OX Guard <code>BalancerMembers</code> to the oxguard balancer configuration (also in <code>proxy_http.conf</code>) to address all your OX Guard nodes in the cluster in this balancer configuration. The configuration has to be applied to all Apache nodes within the cluster.

If the Apache server is a dedicated server <code>/</code> instance you also have to install the OX Guard UI-Static package on all Apache nodes in the cluster in order to provide static files like images or CSS to the OX Guard client. Example for Debian (the OX Guard repository has to be configured in the package management prior):

<source lang="bash">$ apt-get install open-xchange-guard-ui-static</source>

==== Open-Xchange ====

Disable the Open-Xchange IPCheck for session verification. This is required because OX Guard will use the users session cookie to connect to the Open-Xchange REST API, but as a different IP address than the OX Guard server has been used during authentication the request would fail if you don't disable the IPCheck:

<source lang="bash">$ vim /opt/open-xchange/etc/server.properties</source>
and set:

<source lang="bash">com.openexchange.IPCheck=false</source>
The OX Guard UI package has to be installed on all Open-Xchange backend nodes as well, example for Debian (the OX Guard repository has to be configured in the package management prior):

<source lang="bash">$ apt-get install open-xchange-guard-ui</source>
Restart the Open-Xchange service afterwards.

==== OX Guard ====

For details in clustering Guard servers, please see [https://oxpedia.org/wiki/index.php?title=AppSuite:GuardCluster OX Guard Clustering]. It is '''critical''' that all Guard servers have the same <code>oxguardpass</code> file. Please see the clustering link for details. Do not run <code>/opt/open-xchange/sbin/guard --init</code> on more than one server.

After all the services like MySQL, Apache and Open-Xchange have been configured you need to update the OX Guard backend configuration to point to the correct API endpoints. Set the REST API endpoint to an Apache server by setting the following value in <code>/opt/open-xchange/etc/guard-core.properties</code>:

<source lang="bash">com.openexchange.guard.restApiHostname=apache.example.com</source>
Per default Guard will try to connect to port 8009 to this host, but as we configured the REST API to be proxies thorugh the servlet <code>/preliminary</code> on every Apache we now also need to change the target port for the REST API. You can do so by adding the following line into <code>/opt/open-xchange/etc/guard-core.properties</code>:

<source lang="bash">com.openexchange.guard.oxBackendPort=80</source>
Please also change all settings in regards to MySQL like <code>com.openexchange.guard.configdbHostname</code>, <code>com.openexchange.guard.oxguardDatabaseHostname</code>, <code>com.openexchange.guard.databaseUsername</code> or <code>om.openexchange.guard.databasePassword</code>.

Afterwards restart the OX Guard service and check the log file if the OX Guard backend is able to connect to the configured REST API.

=== Multi Node ===

If you have multiple OX and Guard installations, please see the following documentation [https://oxpedia.org/wiki/index.php?title=AppSuite:OX_Guard_Modular OX Guard Modular Setup].

=== Mail Filter Integration (2.10.4+) ===

To add additional mail filter tests (verify PGP signature, or encrypt incoming), please see
[[AppSuite:OX_Guard_MailFilter | MailFilter Integration]]

== Support API ==

The OX Guard Support API enables administrative access to various functions for maintaining OX Guard from a client in a role as a support employee. A client has to do a BASIC AUTH authentication in order to access the API. Username and password can be configured in the guard-core.properties file using the following settings:

# Specify the username and password for accessing the Support API of Guard
com.openexchange.guard.supportApiUsername=
com.openexchange.guard.supportApiPassword=

In contrast to the rest of the OX Guard requests, the OX Guard support API requests are accessible using: /guardsupport. This distinction allows more flexible configuration since the support API should not always be accessible from everywhere.

'''Warning''': Exposing the support API to the internet could be huge security risk. Only add to Apache if you know what you are doing.

=== Reset password ===

<code>POST /guardsupport/?action=reset_password</code>

Performs a password reset and sends a new random generated password to a specified email address by the user or a default address if the user did not specify an email address. (''Since Guard 2.0'')

Parameters:

* <code>email</code> – The email address of the user to reset the password for
* <code>default</code> (optional) – The email address to send the new password to, if the user did not specify a secondary email address

Response:
PRIMARY if the reset was sent to the primary email address. SECONDARY if the reset email was sent to the secondary email address that the user specified

=== Expose key ===

<code>POST /guardsupport/?action=expose_key</code>

Marks a deleted user key temporary as “exposed” and creates a unique URL for downloading the exposed key. Automatic resetting of exposed keys to "not exposed" is scheduled once a day and resets all exposed keys which have been exposed before X hours, where X can be configured using com.openexchange.guard.exposedKeyDurationInHours in the guard.properties files. (''Since Guard 2.0'')

Parameters:

* <code>email</code> – The email address of the user to expose the deleted keys for
* <code>cid</code> – The context id

Response: A URL pointing to the downloadable exposed keys.

=== Delete user ===

<code>POST /guardsupport/?action=delete_user</code>

Deletes all keys related to a certain user. The keys are backed up and can be exposed using the “expose_key” call. (''Since Guard 2.0'')

Parameters:

* <code>user_id</code> – The user's id
* <code>cid</code> - The context id

=== Upgrade User (Release 2.10 and later) ===

<code>POST /guardsupport/?action=upgrade_guest</code>

Upgrades a Guest account. This action copies all of the keys from the Guest account to a full OX account, assuming that user has Guard capabilities.

Parameters:

* <code>email</code> - The email address of the Guest user
* <code>user_id</code> – The user's new id
* <code>cid</code> - The user's new context id

== Customisation ==

Guard's templates are customisable at the user and context level. Please see [https://oxpedia.org/wiki/index.php?title=AppSuite:GuardCustomization Customisation] for details.

== Entropy ==

Guard requires entropy (randomness) to generate the private/public keys that are used. Depending on the server and it's environment, this may become a problem. Please see [https://oxpedia.org/wiki/index.php?title=AppSuite:GuardEntropy Entropy] for a possible solution.

AppSuite:OX Guard MailFilter

2020-08-05T21:56:37Z

WolfgangRosenauer:

= OX Guard MailFilter Integration =

It is possible to add the Sieve test “PGP Signature” as well as the action “encrypt incoming” to the mailfilter functionality of Appsuite. This utilizes the sieve Extprograms plugin to call Guard through an api to either verify signatures or return the email encrypted.

== Overview ==

The user creates either the filter test “PGP Signature” or action “Encrypt email”. This creates a sieve rule that calls an external script with the user's ID and Context. Only pre-configured scripts can be called, there isn’t any ability for someone to create their own external scripts to be called.

Incoming emails then go through the Sieve filter, which then calls the external script with the user's ID and Context as parameters.

The external script calls the Guard server through an api call. Response is returned to the script. Either marked as signed, or the encrypted content of the email is returned.

== Setup: ==

Dovecot sieve extension ExtPrograms must be enabled. This adds three different capabilities to sieve vnd.dovecot.pipe, vnd.dovecot.filter, and vnd.dovecot.exectue (pipe is not required for these scripts), but they are disabled by default. “Filter” and “execute” must be enabled for users, and then the directories containing the scripts must be configured.

Example configuration:

=== 90-sieve.conf ===

<pre>plugin {
sieve = file:~/sieve;active=~/.dovecot.sieve
sieve_default = /var/lib/dovecot/sieve/default.sieve
sieve_plugins = sieve_extprograms
sieve_extensions = +vnd.dovecot.filter +vnd.dovecot.execute
# The directory contains the scripts that are available for the filter and execute
# commands.
sieve_filter_bin_dir = /usr/lib/dovecot/sieve-filter
sieve_execute_bin_dir = /usr/lib/dovecot/sieve-execute
}</pre>
Of course, the sieve protocol must be enabled and managesieve must be already working.

=== Scripts ===

There are currently two scripts, one to test the email signatures, another to encrypt the email. Add/create scripts in the following location (assuming the above configuration). Replace the username/password rest:secret with the REST username and password configured with Guard.

/usr/lib/dovecot/sieve-filter/guard.sh

<pre>#!/bin/bash
GUARD="${GUARD_SERVER:-localhost:8009}"

## Send the stdin to guard using curl, store result

encrypted=$(curl -s -X POST -F file=@- "http://${GUARD}/oxguard/pgpmail?action=encrypt_mime&user=${1}&context=${2}&respondWithJSON=true" --user rest:secret )

## Check for errors and basic sanity check

if [[ $encrypted == \{\"error* ]] ;
then
logger "Guard sieve encrypter error: $encrypted"
## Error, exit
exit 1
fi

## Return the encrypted text. Preserve /r

echo -e "$encrypted"</pre>
/usr/lib/dovecot/sieve-execute/guard-sig.sh

<pre>#!/bin/bash
GUARD="${GUARD_SERVER:-localhost:8009}"

## Send the stdin to guard using curl, store result

verified=$(curl -s -X POST -F file=@- "http://${GUARD}/oxguard/pgpmail?action=verify&user=${1}&context=${2}&simple=true&respondWithJSON=true" --user rest:secret )
logger $verified

## Check if returns true

if [[ $verified == "{\"data\":true}" ]] ;
then
exit 0
fi
if [[ $verified == \{\"error* ]] ;
then
logger "Guard sieve signature error: $verified"
fi
exit 1</pre>
There is no requirement that these scripts are in different directories. Dovecot requires that scripts are not world writable. In addition, as these scripts contain the rest username/password, recommend changing the owner to vmail and restricting permissions to 700

== Middleware Packages ==

On the middleware nodes the <code>open-xchange-guard-backend-mailfilter</code> package needs to be installed. This should be on the same nodes as the <code>open-xchange-guard-backend-plugin</code> package is installed.

=== Debian ===
<pre>
apt-get install open-xchange-guard-backend-mailfilter
</pre>

=== Redhat ===
<pre>
yum install open-xchange-guard-backend-mailfilter
</pre>

== Configuration ==

The guard mailfilter functionality must be enabled on the middleware. Recommend adding the configuration to guard-api.properties on the middleware servers:

com.openexchange.mail.filter.guard.sieveEnabled=true

The script names may be configured differently, but default to the following:

com.openexchange.mail.filter.guard.guardEncryptScript=guard.sh

com.openexchange.mail.filter.guard..guardSignatureScript=guard-sig.sh

== MailFilter User Interface ==

Assuming the user has guard-mail and mailfilter capabilities, they will now be able to add the configured test and actions for Guard.

AppSuite:Multifactor

2020-05-11T14:10:53Z

WolfgangRosenauer:

= Multifactor Authentication (since 7.10.2) =

This documentation has been moved.

For 7.10.2

https://documentation.open-xchange.com/7.10.2/middleware/security_and_encryption/multifactor_authentication.html

For 7.10.3

https://documentation.open-xchange.com/7.10.3/middleware/security_and_encryption/multifactor_authentication.html

AppSuite:Multifactor

2020-05-11T14:03:21Z

WolfgangRosenauer:

= Multifactor Authentication (since 7.10.2) =

Appsuite version 7.10.2 provides methods for users to require secondary, additional methods of authentication before creating a valid Appsuite session. These methods may include SMS messages, Time based authenticator methods, U2F compatible devices/keyfobs, and other custom methods.

== Enabling Multifactor ==

The open-xchange-multifactor package is required for the core of multifactor authentication. For some methods (such as SMS), additional packages will be required.

With SMS, for example, you must also install a provider, such as open-xchange-sms-sipgate.

Then, multifactor must be enabled as a capability. This can be done in the multifactor.properties file, or as a cascade value

com.openexchange.capability.multifactor=true

== Enabling SMS ==

First, the SMS provider must be installed and configured. Most will require a configured username and password, or AUTH_TOKEN. Install the needed package and configure.

At that point, you should enable SMS in the multifactor.properties file

com.openexchange.multifactor.sms.available=true

The following properties are also available

* com.openexchange.multifactor.sms.tokenLength (default is 8 characters)
* com.openexchange.multifactor.sms.tokenLifetime (Number of minutes until challenge expires)
* com.openexchange.multifactor.maxTokenAmount (Maximum number of challenges before locked out)

== Enabling TOTP ==

TOTP is Time-based One Time Password. This works with several apps available in mobile stores, such as Google Authenticator.

To enable, just set in the multifactor.properties file

com.openexchange.multifactor.totp.available=true

== Enabling Backup String ==

This is a method to allow a user to log into their account if they lose their primary multifactor authentication device (say losing their phone or U2F token). It is a long string that they can copy, download, or print to use to unlock the account in the event of loss

To enable, set in the multifactor.properties file

com.openexchange.multifactor.backupString.available=true

== Enabling U2F ==

U2F is supported in Google Chrome, as well as Firefox (though requires user changing advanced settings).

In multifactor.properties, enable U2F

com.openexchange.multifactor.U2F.available=true

Then, the domain that the user will be using must be specified. This will be used with the requests to the U2F device, and must mach the website. This configuration is config-cascade aware

com.openexchange.multifactor.U2F.appId=https://yourdomain

== Login Page ==

By default, the UI will change from the login page, draw the customized toolbar, then display a prompt for the multifactor authentication.

If you would prefer to have your login screen, or a different second factor screen used as the background, then you can configure in the as-config.yml

For example:

default:
host: all
signinTheme: default
multifactorBackground: pages/secondFactor

AppSuite:Available Translations

2020-03-17T08:30:41Z

WolfgangRosenauer:

= Open-Xchange Server Translations for OX App Suite =

=== Available Language Translations ===

{| border="1" cellpadding="3" cellspacing="0"
!align="left" |Language
!align="left" |Status
!align="left" |Documentation
!align="left" |Contributor
|-
| [[Image:Flag_us.png]] US English
| Supported
| Online Help/Manual
| Open-Xchange
|-
| [[Image:Flag_gb.png]] British English
| Supported
| Online Help/Manual
| Open-Xchange
|-
| [[Image:Flag_de.png]] German
| Supported
| Online Help/Manual
| Open-Xchange
|-
| [[Image:Flag_fr.png]] French
| Supported
| Online Help/Manual
| Open-Xchange
|-
| [[Image:Flag_cn.png]] Canadian French
|Supported
|
| Open-Xchange
|-
| [[Image:Flag_es.png]] Spanish
|Supported
| Online Help/Manual
| Open-Xchange
|-
| [[Image:Flag_mx.png]] Mexican Spanish
|Supported
| Online Help/Manual
| Open-Xchange
|-
| [[Image:Flag_nl.png]] Dutch
| Supported
| Online Help/Manual
| Open-Xchange
|-
| [[Image:Flag_pl.png]] Polish
| Supported
|Online Help/Manual
| Open-Xchange
|-
| [[Image:japanese.jpeg]] Japanese
|Supported
|Online Help/Manual
| Open-Xchange
|-
| [[Image:Flag_it.png]] Italian
|Supported
|Online Help/Manual
| Open-Xchange
|-
| [[Image:china.jpg]] Simplified Chinese
|Supported
|Online Help/Manual
| Open-Xchange
|-
| [[Image:china.jpg]] Traditional Chinese
|Supported
|Online Help/Manual
| Open-Xchange
|-
| [[Image:ungarn.jpg]] Hungarian
|Supported
|
| Open-Xchange
|-
| [[Image:Slovakia.jpg]] Slovak
| Supported
|
| Open-Xchange
|-
| [[Image:Czech.jpg]] Czech
|Supported
|
| Open-Xchange
|-
| [[Image:latvia.jpg]] Latvian
| Supported
|
|Open-Xchange
|-
|[[Image:Flag_romania.png]] Romanian
| Supported
|
| Open-Xchange
|-
| [[Image:brazil.png|17px]] Brazilian Portuguese
| Supported
|
| Open-Xchange
|-
| [[File:Flag_se.png|17px]] Swedish
| Supported
|
| Open-Xchange
|-
| [[File:Flag_dk.png|17px]] Danish
| Supported
|
| Open-Xchange
|-
| [[File:Russian.png|17px]] Russian
| Supported
|
| Open-Xchange
|-
| [[File:flag_fin.png|17px]] Finnish
| Supported
|
| Open-Xchange
|-
| [[File:flag_Tur.png|17px]] Turkish
| Supported
|
| Open-Xchange
|}

'''Any other languages which may be provided by installation packages are not supported and might even have a bad UI/UX impact when installed. Please use at your own risk!'''

[[Category: OX7]]
[[Category: AppSuite]]

AppSuite:Available Translations

2020-03-17T08:30:18Z

WolfgangRosenauer:

= Open-Xchange Server Translations for OX App Suite =

=== Available Language Translations ===

{| border="1" cellpadding="3" cellspacing="0"
!align="left" |Language
!align="left" |Status
!align="left" |Documentation
!align="left" |Contributor
|-
| [[Image:Flag_us.png]] US English
| Supported
| Online Help/Manual
| Open-Xchange
|-
| [[Image:Flag_gb.png]] British English
| Supported
| Online Help/Manual
| Open-Xchange
|-
| [[Image:Flag_de.png]] German
| Supported
| Online Help/Manual
| Open-Xchange
|-
| [[Image:Flag_fr.png]] French
| Supported
| Online Help/Manual
| Open-Xchange
|-
| [[Image:Flag_cn.png]] Canadian French
|Supported
|
| Open-Xchange
|-
| [[Image:Flag_es.png]] Spanish
|Supported
| Online Help/Manual
| Open-Xchange
|-
| [[Image:Flag_mx.png]] Mexican Spanish
|Supported
| Online Help/Manual
| Open-Xchange
|-
| [[Image:Flag_nl.png]] Dutch
| Supported
| Online Help/Manual
| Open-Xchange
|-
| [[Image:Flag_pl.png]] Polish
| Supported
|Online Help/Manual
| Open-Xchange
|-
| [[Image:japanese.jpeg]] Japanese
|Supported
|Online Help/Manual
| Open-Xchange
|-
| [[Image:Flag_it.png]] Italian
|Supported
|Online Help/Manual
| Open-Xchange
|-
| [[Image:china.jpg]] Simplified Chinese
|Supported
|Online Help/Manual
| Open-Xchange
|-
| [[Image:china.jpg]] Traditional Chinese
|Supported
|Online Help/Manual
| Open-Xchange
|-
| [[Image:ungarn.jpg]] Hungarian
|Supported
|
| Open-Xchange
|-
| [[Image:Slovakia.jpg]] Slovak
| Supported
|
| Open-Xchange
|-
| [[Image:Czech.jpg]] Czech
|Supported
|
| Open-Xchange
|-
| [[Image:latvia.jpg]] Latvian
| Supported
|
|Open-Xchange
|-
|[[Image:Flag_romania.png]] Romanian
| Supported
|
| Open-Xchange
|-
| [[Image:brazil.png|17px]] Brazilian Portuguese
| Supported
|
| Open-Xchange
|-
| [[File:Flag_se.png|17px]] Swedish
| Supported
|
| Open-Xchange
|-
| [[File:Flag_dk.png|17px]] Danish
| Supported
|
| Open-Xchange
|-
| [[File:Russian.png|17px]] Russian
| Supported
|
| Open-Xchange
|-
| [[File:flag_fin.png|17px]] Finnish
| Supported
|
| Open-Xchange
|-
| [[File:flag_Tur.png|17px]] Turkish
| Supported
|
| Open-Xchange
|}

Any other languages which may be provided by installation packages are not supported and might even have a bad UI/UX impact when installed. Please use at your own risk!

[[Category: OX7]]
[[Category: AppSuite]]

AppSuite:Capabilities

2020-02-26T15:55:58Z

WolfgangRosenauer:

'''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":"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.

Note that the LinkedIn support was removed since 7.10.0

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

To just list all:

_(ox.serverConfig.capabilities).pluck("id").sort();

== 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]]

OX as a Service Provisioning using SOAP

2020-02-04T11:26:53Z

WolfgangRosenauer:

= Tutorial: Provision OX as a Service using SOAP =

== Overview ==

[[OX_as_a_Service_Guide|OX as a Service]] is using the same code everybody can download and install using our
various guides. Since it is a hosted service using a reseller model, the provisioning api is using the [[Reseller_Bundle|Reseller Bundle]]
to extend the usual two administrative layers by an additional one.

Open-Xchange does also not contain a mail server in general, but requires one in order to act like a mail client. OX as a Service
is using [https://www.open-xchange.com/portfolio/ox-dovecot-pro/ OX Dovecot Pro] as mail server and thus extends the usual Open-Xchange provisioning capabilities by mechanisms
to manage some email specific settings.

== Open-Xchange concept of Contexts ==

In order to provision users and groups into Open-Xchange, it is important to understand, that Open-Xchange is designed
for shared hosting environments in a way that it has to serve multiple tenants, customers, domains, or however you want to
name it. In Open-Xchange, we call that a '''Context'''. A context is a sealed container for users and groups. Users in a
context can not see users of other contexts, nor can they share data with users of other contexts (with the exception of
Open-Xchange publish and subscribe functionality).

A usual scenario is to have a company, a family or in general one end customer in a context. One can also say, a context
is a domain, and usually that makes sense, since a company has one domain. However, Open-Xchange contexts are not limited
to one domain only.

== Open-Xchange concept of provisioning ==

A plain Open-Xchange installation consists of two administrative levels.

# root level, usually we call that oxadminmaster
# context level

=== oxadminmaster / root ===

The root, or oxadminmaster account is used to

* add, remove and configure filestores attached to Open-Xchange
* add, remove and configure databases attached to Open-Xchange
* add, remove and configure contexts

and change parameters like add/remove domains, change per context filesystem quota, etc.

Depending on the OX configuration, it is not able to add or remove users and groups, nor any other data within a context!

=== Context admin ===

The context admin is like an ordinary Open-Xchange user, except that it can add, remove and edit
users and groups within Open-Xchange using the provisioning API.
In addition, it inherits shared data of users, that are deleted.
'''In OX as a Service, however, the context admin cannot read, send or receive mail.'''

== OX as a Service concept of provisioning ==

As written before, plain Open-Xchange only has one root account. In a reseller scenario, that would
mean if we want resellers to be able to create contexts for their customers, we would have to hand out our
root account. Since that is not desirable, we added another layer via the [[Reseller_Bundle|Reseller Bundle]] as
mentioned earlier.

# root level, usually we call that oxadminmaster
# subadmin level / brand level
# context level

root and context level don't change, except that context level can be [[Reseller_Bundle#Restrictions|restricted]].

The subadmin account can only add, remove or configure contexts. Depending on the configuration of the
OX as a Service tenant, it can or can NOT add, remove and configure users within contexts.
Contexts created by a subadmin account can not be seen by other subadmin accounts.

=== What is a brand? ===

A brand is a customers subadmin login to the OXaaS SOAP provisioning API.

== OX as a Service specifics ==

=== Shared domains, explicit domains and ordinary domains ===

==== Ordinary domains ====

In order to create a user in Open-Xchange, you have to set an email address for that user.
This will directly lead into a domain to be created into OXaaS bound to that user and its context,
if that domain does not already exists and is owned by a different context.

==== Shared domains ====

If you want to share domains between all contexts, you have to use shared domains.
Shared domains must be created in advance using the <tt>createSharedDomain</tt> method (see [[#OXaaS_specific_methods|OXaaS specific methods]])
or using the [https://documentation.open-xchange.com/components/cloudplugins/1.9.1/#tag/Shared-Domains REST API] (needs recent version).

==== Explicit domains ====

Recent versions support another type of domain called explicit domains. These domains must be explicitly added to contexts using the [https://documentation.open-xchange.com/components/cloudplugins/1.9.1/#tag/Explicit-Domains REST API] (needs recent version). You can add the same explicit domain to one or multiple contexts. If a context already contains an ordinary domain of the same name, it will be transformed into an explicit domain.

Note that the explicit domain feature is not available by default, it must be activated for each customer, individually.

You can use the <tt>existsMailAlias</tt> method to check for the existence of an alias before you create it.

=== Catchall accounts ===

If the feature is enabled in your contract, you can create catchall mail aliases bound to users
within contexts.

=== User permissions ===

See [[OX_as_a_Service_Provisioning_using_SOAP#Set_OXaaS_permissions|OXaaS permission]] description below.

=== User name/login uniqueness ===

Due to the architecture of OXaaS, a login/username must be unique across all created contexts. That means it is not
possible to create two "oxadmin" accounts. This limitation applies per brand.

=== Display name uniqueness ===

In contrary to the login/name of users, display names must only be unique within each context.
That is because it is used e.g. in the shared folder list of e.g. calendar, drive, contacts in OX.
Also it is used as folder name when mounting OX via WEBDAV.

It is no problem, however, to have one "Steve Smith" in one context, and another "Steve Smith” in another context.

=== No email for "oxadmin" ===

The architecture of OX as a Service does not allow the context admin to have email.

== Provisioning ==

=== OXaaS specific methods ===

==== SOAP API ====

The following SOAP methods are specific to OXaaS and are NOT part of the general Open-Xchange provisioning API.

{| border="1" class="wikitable"
|+ OXaaS specific SOAP calls and its authentication requirements
! Method
! Functionality
! Authentication
|-
! getQuotaUsage
| get the overall mail quota usage of all users within the given context
| Subadmin
|-
! createSharedDomain
| create a shared domain
| Subadmin
|-
! existsLogin
| check whether user login already exists. Note: a users login must be unique within all users for your subadmin account and NOT only per context!
| Subadmin
|-
! existsMailAlias
| check whether given mail alias already exists
| Subadmin
|-
! createDomainCatchall
| create a domain catchall
| Subadmin
|-
! getQuotaUsagePerUser
| get mail quota usage of the individual user within the given context
| Subadmin
|-
! listDomainCatchalls
| list all existing domain catchalls
| Subadmin
|-
! setMailQuota
| set the mail quota of the individual user within the context
| Context Admin
|-
! deleteDomainCatchall
| delete the given domain catchall
| Subadmin
|-
! getPermissions
| list given users permissions
| Subadmin
|-
! enablePermissions
| enable provided permissions for given user
| Subadmin
|-
! disablePermissions
| enable provided permissions for given user
| Subadmin
|-
! setExpiryDate
| store expiry date for the given user
| Context Admin
|-
! getExpiryDate
| get expiry date stored for user
| Context Admin
|-
! deleteExpiryDate
| delete the expiry date stored in the given user
| Context Admin
|-
! getExpiredUsers
| retrieve list of expired users
| Subadmin
|-
! getMailQuota
| get the mail quota of the individual user within the context
| Subadmin
|-
! setPasswordHash
| directly store provided pwHash into userPassword attribute of matching ldap entry. Note: Input will be validated against valid mechanisms.
| Context Admin
|}

The WSDL source file for these methods contain documentation for each of the calls and parameters.
You can download it here: http://software.open-xchange.com/products/appsuite/doc/oxasservice/OXaaSService.wsdl

'''Note that the mail quota usage and max values are the combined values of drive and mail quota in case the system has [https://documentation.open-xchange.com/latest/middleware/miscellaneous/quota.html#unified-quota unified quota] enabled.'''

==== REST API ====

There's a growing number of REST APIs to access OXaaS, see https://documentation.open-xchange.com/, section ''Cloud Plugins API''.

=== OX Core Provisioning API ===

The core provisioning API consists of four namespaces:

# Context management
# User management
# Group management
# Resource management

Some of these namespaces share the same data structures such as <tt>Credentials</tt>, <tt>Context</tt> and <tt>User</tt>.

[[File:provisioning-core.png|1000 px]]

=== Reference implementation ===

The reference implementation of the European OX as a Service system can be found in the {{APSPackage|name=OX as a Service}} APS package
for [http://www.odin.com/products/automation/ Odin Service Automation].

=== Workflow ===

==== Subadmin credentials ====

The first requirement is to get subadmin credentials for your company. Please follow the steps
[[OX_as_a_Service_Guide#How_to_become_a_customer.3F|documented here]] to get such an account.

Together with the login and password you will also retrieve the provisioning URL to be used by
all SOAP requests. In addition, it is required that you give us a list of ip addresses or network(s)
that should be allowed to access the provisioning system.

==== WSDL files ====

Just point your browser to the provisioning URL you got from us. You will find some services listed there.
You will need the following services from that list:

; https://hostname/webservices/OXaaSService?wsdl: OX as a Service specific functions
; https://hostname/webservices/OXResellerContextService?wsdl: Context management
; https://hostname/webservices/OXResellerUserService?wsdl: User management

and optionally

; https://hostname/webservices/OXResellerGroupService?wsdl: Group management
; https://hostname/webservices/OXResellerResourceService?wsdl: Resource management

==== SOAP API documentation ====

The general SOAP API documentation can be found at this URL:
http://software.open-xchange.com/products/appsuite/doc/SOAP/admin/OX-Admin-SOAP.html

That document contains links to the Javadoc documentation for the RMI api, but
that is more or less the same as the SOAP API.

In addition, there's the general, non OXaaS specific [[Open-Xchange_Provisioning_using_SOAP|wiki page]].

==== Create a context ====

Once you have the credentials in place, you are ready to create your first context.

Creating a context requires to create the first user in that context, that is the context admin, see above.

Mandatory settings for a context are

; name: name of the context
; quota: file quota in MB for that context ('''Note:''' that is file, not mail!)
; taxonomy: must be set to the login of your subadmin account, see below

'''Important:''' In OXaaS, the name of the context must always start with your subadmin login with an underscore appended. E.g. when
your subadmin login is <tt>johndoe</tt>, the all your context names must start with <tt>johndoe_</tt>!

Optional settings

; mainColor: io.ox/dynamic-theme//mainColor
; linkColor: io.ox/dynamic-theme//linkColor
; for further theme parameters, check https://documentation.open-xchange.com/latest/ui/theming/dynamic-theming.html

; id: A numerical id bound to the context. When you create a context, this id will be generated. You will need that later when you manage users. The id can be looked up via the context name.

===== userAttributes =====

The settings brandtaxonomy and the other optional settings except id are part of the userAttributes SOAP field.
All other settings can easily be set via simple SOAP settings. userAttributes is a hash that contains some settings
that are not available in all setups of Open-Xchange. It allows to extend Open-Xchange functionality dynamically like
done in OXaaS.

The hash looks like this:

userAttributes => entries => EntryArray

with EntryArray :=

[
{ key => "somekey"
value => somevalue },
{ key => "someotherkey"
value => someothervalue },
...
]

somevalue can be an array again, e.g.:

somevalue => entries => EntryArray

with EntryArray :=

[
{ key => "somekey"
value => somevalue },
{ key => "someotherkey"
value => someothervalue },
...
]

and so on

Example dump using perls <code>Data::Dumper</code>:

<syntaxhighlight lang="perl">
'userAttributes' => {
'entries' => [
{
'value' => {
'entries' => [
{
'value' => '#0000ff',
'key' => 'io.ox/dynamic-theme//topbarHover'
},
{
'value' => '#ff0000',
'key' => 'io.ox/dynamic-theme//linkColor'
},
{
'value' => '#00ff00',
'key' => 'io.ox/dynamic-theme//mainColor'
},
{
'value' => 'true',
'key' => 'com.openexchange.capability.dynamic-theme'
} ]
},
'key' => 'config'
},
{
'value' => {
'entries' => {
'value' => 'johndoe',
'key' => 'types'
}
},
'key' => 'taxonomy'
}
]
},
</syntaxhighlight>

===== Admin User =====

; name: login name of the context admin
; password: password
; email: email address of the context admin
; displayname: displayname (usually surname givenname)
; surname: surname
; givenname: given name
; lang: language, e.g. en_GB, en_US, de_DE, ...
; timezone: Java timezone such as Europe/Berlin,

====== Timezones ======

To get a list of all available timezones, you can run this short Java program:

<syntaxhighlight lang="java">
import java.util.TimeZone;

public class AllTimeZones {
public static void main(String[] args) {
for(final String zone : TimeZone.getAvailableIDs() ) {
System.out.println(zone);
}
}

}
</syntaxhighlight>

====== Languages ======

This is the list of currently supported languages in OXaaS:

ja_JP
de_DE
es_ES
es_MX
fr_FR
it_IT
nl_NL
pl_PL
zh_TW
en_US
en_GB

==== Create users ====

Creating users requires the following parameters

; name: login name of the context admin
; password: password
; email: email address of the context admin
; displayname: displayname (usually surname givenname)
; surname: surname
; givenname: given name
; lang: language, e.g. en_GB, en_US, de_DE, ...
; timezone: Java timezone such as Europe/Berlin,
; moduleaccess: the module access combination name
; mailquota: the mail quota of the user in MB

Timezones and languages like documented earlier.

Valid values for moduleaccess are:

* webmail_plus
* groupware_standard
* groupware_advanced
* groupware_premium

Other settings are not supported.

===== userAttributes =====

It might be required you have to set some specific attributes per user like the Edition Type as
done by the OXaaS APS package.

There's a choice of 7 different edition types:

; webmail: bound to webmail_plus
; basic: bound to groupware_standard
; advanced: bound to groupware_advanced
; pro: bound to groupware_premium
; pro_m: bound to groupware_premium
; pro_l: bound to groupware_premium
; pro_xl: bound to groupware_premium

which can be set within each users oxaas_edition_type within a tree oxaas:

'userAttributes' => {
'entries' => {
'key' => 'oxaas',
'value' => {
'entries' => {
'key' => 'oxaas_edition_type',
'value' => 'pro_l'
}
}
}
}

see [[#Standalone_example:_createOXaaSUser|createuser example script]]

===== Create the user in Open-Xchange =====

* Use the name and password of the context admin user of the context you created earlier and define
a Credentials object.
* Find the numerical id of the context e.g. in using <code>OXResellerContextService->getData(name="contextname")</code>

Use the <code>OXResellerUserService->createByModuleAccessName</code> to create users.

'''Note:''' Although there are three create methods in the SOAP user service API, you have to use the method <code>createByModuleAccessName</code>
and specify one of the names listed above.

===== Set mail quota =====

* Use the name and password of the context admin user of the context you created earlier and define
a Credentials object.
* Find the numerical id of the context e.g. in using <code>OXResellerContextService->getData(name="contextname")</code>
* Find the numerical id of the user either by using <code>OXResellerUserService->getData(name="username")</code> or use/store the return value of <code>OXResellerUserService->createByModuleAccessName</code>

Use the <code>OXaaSService->setMailQuota</code> call to set the mail quota for the user created above.

===== Set OXaaS permissions =====

====== Explanation ======

The OXaaS permissions allow to enable or disable a certain set of features.
Currently, the following permissions are available:

{| border="1" class="wikitable"
|+ OXaaS permissions
! Permission
! Description
|-
! SEND
| User is allowed to send mail
|-
! RECEIVE
| User is allowed to receive mail
|-
! MAILLOGIN
| User can login using IMAP from external; webmail is not affected
|-
! WEBLOGIN
| User can login to OX webmail.
|}

The permission names are case insensitive.
The WEBLOGIN permission is the same as the [http://software.open-xchange.com/products/appsuite/doc/RMI/admin-core/com/openexchange/admin/rmi/dataobjects/User.html#setMailenabled%28java.lang.Boolean%29 <tt>Mailenabled</tt>] permission in the user data of the Open-Xchange core api. The permission
OXaaS api provides another way to enable/disable it.

* Use the name and password of the context admin user of the context you created earlier and define
a Credentials object.
* Find the numerical id of the context e.g. in using <code>OXResellerContextService->getData(name="contextname")</code>
* Find the numerical id of the user either by using <code>OXResellerUserService->getData(name="username")</code> or use/store the return value of <code>OXResellerUserService->createByModuleAccessName</code>

Use one of <code>OXaaSService->enablePermissions</code>, <code>OXaaSService->disablePermissions</code> or <code>OXaaSService->getPermissions</code>
to change or retrieve permissions. Permissions must always be provided as an array of 1 or more permissions.

=== SOAP provisioning feature matrix ===

(WIP)

The table below shows what method(s) to use and what to set in order to configure the different feature sets.

The value in the row ''Module Access Name'' must be given as a parameter to <code>OXResellerUserService->changeByModuleAccessName</code>
or <code>OXResellerUserService->createByModuleAccessName</code>.

The values in the row ''Capabilities'' must be given as parameters to the <code>userAttributes</code> member of the <code>User</code> object that
should be changed and then passed to <code>OXResellerUserService->change</code> or <code>OXResellerUserService->createByModuleAccessName</code>.

'''Note: <code>OXResellerUserService->changeByModuleAccessName</code> does NOT change these capabilities!'''

{| border="1" class="wikitable"
|+ Provisioning Feature Matrix
! Feature
! Module Access Name
! Capabilities ''(mandatory values in bold, others are optional)''
|-
! Web Mail
| webmail_plus
| <tt>com.openexchange.capability.drive = '''false'''</tt><br><tt>com.openexchange.capability.document_preview = '''false'''</tt><br><tt>com.openexchange.capability.spreadsheet = '''false'''</tt><br><tt>com.openexchange.capability.text = '''false'''</tt><br><tt>com.openexchange.capability.presenter = '''false'''</tt><br><tt>com.openexchange.capability.remote_presenter = '''false'''</tt><br><tt>com.openexchange.capability.guard = '''false'''</tt><br><tt>com.openexchange.capability.guard-mail = '''false'''</tt><br><tt>com.openexchange.capability.guard-drive = '''false'''</tt>
|-
! Basic
| <tt>groupware_standard</tt>
| <tt>com.openexchange.capability.drive = '''true'''</tt><br><tt>com.openexchange.capability.document_preview = true/false</tt><br><tt>com.openexchange.capability.spreadsheet = true/false</tt><br><tt>com.openexchange.capability.text = true/false</tt><br><tt>com.openexchange.capability.presenter = true/false</tt><br><tt>com.openexchange.capability.remote_presenter = true/false</tt><br><tt>com.openexchange.capability.guard = true/false</tt><br><tt>com.openexchange.capability.guard-mail = true/false</tt><br><tt>com.openexchange.capability.guard-drive = true/false</tt>
|-
! Advanced
| <tt>groupware_advanced</tt>
| <tt>com.openexchange.capability.drive = '''true'''</tt><br><tt>com.openexchange.capability.document_preview = true/false</tt><br><tt>com.openexchange.capability.spreadsheet = true/false</tt><br><tt>com.openexchange.capability.text = true/false</tt><br><tt>com.openexchange.capability.presenter = true/false</tt><br><tt>com.openexchange.capability.remote_presenter = true/false</tt><br><tt>com.openexchange.capability.guard = true/false</tt><br><tt>com.openexchange.capability.guard-mail = true/false</tt><br><tt>com.openexchange.capability.guard-drive = true/false</tt>
|-
! Pro
| <tt>groupware_premium</tt>
| <tt>com.openexchange.capability.drive = '''true'''</tt><br><tt>com.openexchange.capability.document_preview = '''true'''</tt><br><tt>com.openexchange.capability.spreadsheet = '''true'''</tt><br><tt>com.openexchange.capability.text = '''true'''</tt><br><tt>com.openexchange.capability.presenter = '''true'''</tt><br><tt>com.openexchange.capability.remote_presenter = '''true'''</tt><br><tt>com.openexchange.capability.guard = true/false</tt><br><tt>com.openexchange.capability.guard-mail = true/false</tt><br><tt>com.openexchange.capability.guard-drive = true/false</tt>
|}

=== List of available capabilities (incomplete) ===

These features are controlled by the [[ConfigCascade]].

For drive and documents the following settings are responsible:

; OX Drive :
<tt>com.openexchange.capability.drive = true/false</tt>

; OX Docs :
<tt>com.openexchange.capability.document_preview = true/false</tt><br />
<tt>com.openexchange.capability.spreadsheet = true/false</tt><br />
<tt>com.openexchange.capability.text = true/false</tt><br />
<tt>com.openexchange.capability.presentation = true/false</tt><br />
<tt>com.openexchange.capability.remote_presenter = true/false</tt><br />
<tt>com.openexchange.capability.guard-docs = true/false</tt>

; OX Guard :
<tt>com.openexchange.capability.guard = true/false</tt><br />
<tt>com.openexchange.capability.guard-mail = true/false</tt><br />
<tt>com.openexchange.capability.guard-drive = true/false</tt><br />

Using [[OX_as_a_Service_Provisioning_using_SOAP#Standalone_example:_createOXaaSContext|this perl example]]:

e.g. this

logouturl => {
setting => "io.ox/core//customLocations/logout",
value => "logouturl"
}

is setting the ConfigCascade setting <tt>io.ox/core//customLocations/logout</tt> to the string “logouturl"

io.ox/core//customLocations/logout = "logouturl"

adding

oxdrive => {
setting => "com.openexchange.capability.drive",
value => "true"
}

in that example would turn on drive.

== Code Examples ==

=== Java ===

==== Generating the SOAP client ====

Since Open-Xchange is using [http://cxf.apache.org/ Apache CXF] for SOAP, we recommend to use the <tt>wsdl2java</tt>
code generator from that package.

The Open-Xchange SOAP services are divided into multiple parts, which makes the code generation a little
complex.

In OXaaS we need at least three services in order to create contexts and users:

* OXResellerContextService
* OXResellerUserService
* OXaaSService

The shell script below generates the stubs of these three services into the directory defined in the <tt>CODEBASE</tt>
variable. In addition, you have to set <tt>WSDLURL</tt> to point it to the provisioning URL you will get from us as
mentioned [[#Subadmin_credentials|earlier]].

Note: when running against a DEV container without valid SSL certs (e.g. self-signed SSL certs), it is required to add the servers cert into your java keystore first:

# Get the cert e.g. by <code>openssl s_client -connect my.oxaas.webservices.host.net:443</code> (the part between BEGIN CERTIFICATE and END CERTIFICATE) or by exporting from a web browser. Put it in a file named for example <code>my.oxaas.webservices.host.net.crt</code>.
# Import it in a custom TrustStore. Assign a password; in this example we assume "secret": <code>keytool -import -trustcacerts -alias my.oxaas.webservices.host.net -keystore my.oxaas.webservices.host.net.jks -file my.oxaas.webservices.host.net.crt -storetype JKS</code>
# Supply it to the JVM by patching the CXF wsdl2java script (e.g. <code>/opt/apache-cxf-3.1.14/bin/wsdl2java</code>) and add the following arguments: <code>-Djavax.net.ssl.trustStore=my.oxaas.webservices.host.net.jks -Djavax.net.ssl.trustStorePassword=secret -Djavax.net.ssl.trustStoreType=JKS</code>

Copy&paste the shell script below into a file and run it using the <tt>bash</tt> shell. <b>Warning:</b> the script assumes the CODEBASE target lives in its own dedicated ecplise project, and executes a <code>rm -rf $CODEBASE</code> for a clean start. For other usecases (shared eclipse project, etc), please adjust to your needs / be careful!

<syntaxhighlight lang="bash">
# 1. download apache-cxf tarball, extract it and "cd" into the directory, e.g.
# tar zxvpf apache-cxf-3.1.10.tar.gz; cd apache-cxf-3.1.10
# NOTE: cxf versions 3.0 do NOT work ootb with java-1.8!
# 2. change variables CODEBASE, JAVA_HOME and WSDLURL
# 3. run this script "bash oxaas-wsdl2java"
export JAVA_HOME="/usr/lib/jvm/java-1.8.0-openjdk-amd64/"
CODEBASE="/home/oxgit/workspace/OXaaSJClient/src"
WSDLURL="https://youroxaashost/webservices"

rm -rf $CODEBASE
frontend=jaxws21
dbinding=jaxb

JAXBTMP=/tmp/jaxb$$.xml
rm -f $JAXBTMP
cat<<EOF > $JAXBTMP
<jaxb:bindings version="2.1"
xmlns:jaxb="http://java.sun.com/xml/ns/jaxb"
xmlns:xjc="http://java.sun.com/xml/ns/jaxb/xjc"
xmlns:xs="http://www.w3.org/2001/XMLSchema">
<jaxb:globalBindings generateElementProperty="false"/>
</jaxb:bindings>
EOF

pname="com.openexchange.oxaas.context"
bin/wsdl2java -databinding $dbinding -frontend $frontend -client -impl -d $CODEBASE -keep -b $JAXBTMP \
-p "http://soap.reseller.admin.openexchange.com=${pname}" \
-p "http://dataobjects.rmi.reseller.admin.openexchange.com/xsd=${pname}.reseller.rmi.dataobjects" \
-p "http://dataobjects.soap.reseller.admin.openexchange.com/xsd=${pname}.reseller.soap.dataobjects" \
-p "http://dataobjects.soap.admin.openexchange.com/xsd=${pname}.soap.dataobjects" \
-p "http://dataobjects.rmi.admin.openexchange.com/xsd=${pname}.rmi.dataobjects" \
-p "http://exceptions.rmi.admin.openexchange.com/xsd=${pname}.rmi.exceptions" \
-p "http://rmi.java/xsd=${pname}.java.rmi" \
-p "http://io.java/xsd=${pname}.java.io" \
${WSDLURL}/OXResellerContextService?wsdl

pname="com.openexchange.oxaas.user"
bin/wsdl2java -databinding $dbinding -frontend $frontend -client -impl -d $CODEBASE -keep -b $JAXBTMP \
-p "http://soap.reseller.admin.openexchange.com=${pname}" \
-p "http://dataobjects.rmi.reseller.admin.openexchange.com/xsd=${pname}.reseller.rmi.dataobjects" \
-p "http://dataobjects.soap.reseller.admin.openexchange.com/xsd=${pname}.reseller.soap.dataobjects" \
-p "http://dataobjects.soap.admin.openexchange.com/xsd=${pname}.soap.dataobjects" \
-p "http://dataobjects.rmi.admin.openexchange.com/xsd=${pname}.rmi.dataobjects" \
-p "http://exceptions.rmi.admin.openexchange.com/xsd=${pname}.rmi.exceptions" \
-p "http://rmi.java/xsd=${pname}.java.rmi" \
-p "http://io.java/xsd=${pname}.java.io" \
${WSDLURL}/OXResellerUserService?wsdl

pname="com.openexchange.oxaas.extra"
bin/wsdl2java -databinding $dbinding -frontend $frontend -client -impl -d $CODEBASE -keep -b $JAXBTMP \
-p "http://soap.oxaas.admin.openexchange.com/=${pname}" \
${WSDLURL}/OXaaSService?wsdl

rm -f $JAXBTMP
</syntaxhighlight>

When you generate the code into an existing eclipse project, you should have three main packages as shown in
the image below

[[File:OXaaSSOAPClientEclipse.png]]

==== Example Client ====

In the following example, the context creation and the user creation is separated into different
programs.

To summarize some essential requirements from the example below:

* The name of each context you create must start with your subadmin name followed by an underscore <tt>_</tt>
* You must set the userAttribute <tt>taxonomy</tt> at least
* The context admin user must get the <tt>groupware_premium</tt> access permission

===== Build / run instructions =====

====== Eclipse ======

We assume, you have created the Java client stub(s) as documented above and have it as a separate eclipse project. The individual clients given below are assumed to live in a different ecplise project which references the Java client stubs in their classpath.

====== Command Line ======

For maximum simplicity let's assume you use the source files given below without the <code>package</code> statement. Put them in an <code>examples/</code> subdirectory.

Let's assume furthermore you created the Java client stubs in a different directory, e.g. <code>codebase/</code>.

Change into that directory to compile all the Java stub files

cd codebase/
find . -name \*.java | xargs javac

Back in the working directory where the source files given below are created, you can compile / run them like

cd ../examples/
javac -cp ../codebase MyContextClientExample.java
java -cp .:../codebase MyContextClientExample

====== SSL-related hints ======

When working against a dev machine with self-signed certs, the same certificate trust related options are required as explained above for the <code>wsdl2java</code> script (with the same TrustStore and password):

-Djavax.net.ssl.trustStore=my.oxaas.webservices.host.net.jks -Djavax.net.ssl.trustStorePassword=secret -Djavax.net.ssl.trustStoreType=JKS

It might be additionally helpful to enable SSL debug output: <code>-Djavax.net.debug=ssl</code>

As of now (2017-11) there is a flaw in the generated WSDL that it references HTTP SOAP addresses even when using HTTPS. This results in client programs trying to access the API via plain HTTP even after a successful SSL handshake and fetching the WSDL via HTTPS. This is bad as SOAP frames travel the network with credentials included in plain text.

A possible workaround for the time being is to forcefully rewrite the protocol part of the different port urls into https with something like:

After initializing the contextport using ...

<syntaxhighlight lang="java">
OXResellerContextServicePortType contextport = contextservice.getOXResellerContextServiceHttpSoap11Endpoint();
</syntaxhighlight>

... add the following code:

<syntaxhighlight lang="java">
// insert in your imports section:
// import javax.xml.ws.BindingProvider;
((BindingProvider)contextport).getRequestContext().put(
BindingProvider.ENDPOINT_ADDRESS_PROPERTY,
((String)((BindingProvider)contextport).getRequestContext()
.get(BindingProvider.ENDPOINT_ADDRESS_PROPERTY))
.replaceAll("^http:", "https:"));
</syntaxhighlight>

Similar adjustments are required for <code>userport</code> and <code>oxaasport</code>, where they occur.

===== Context creation =====

The example below shows how to create a context in OXaaS.

<syntaxhighlight lang="java">
package com.openexchange.oxaas.myclient;

import java.io.IOException;
import java.util.List;
import javax.xml.namespace.QName;
import com.openexchange.oxaas.context.ContextExistsExceptionException;
import com.openexchange.oxaas.context.DatabaseUpdateExceptionException;
import com.openexchange.oxaas.context.Delete;
import com.openexchange.oxaas.context.DuplicateExtensionExceptionException;
import com.openexchange.oxaas.context.InvalidCredentialsExceptionException;
import com.openexchange.oxaas.context.InvalidDataExceptionException;
import com.openexchange.oxaas.context.NoSuchContextExceptionException;
import com.openexchange.oxaas.context.OXResellerContextService;
import com.openexchange.oxaas.context.OXResellerContextServicePortType;
import com.openexchange.oxaas.context.RemoteExceptionException;
import com.openexchange.oxaas.context.StorageExceptionException;
import com.openexchange.oxaas.context.reseller.soap.dataobjects.ResellerContext;
import com.openexchange.oxaas.context.rmi.dataobjects.Credentials;
import com.openexchange.oxaas.context.soap.dataobjects.Entry;
import com.openexchange.oxaas.context.soap.dataobjects.SOAPMapEntry;
import com.openexchange.oxaas.context.soap.dataobjects.SOAPStringMap;
import com.openexchange.oxaas.context.soap.dataobjects.SOAPStringMapMap;
import com.openexchange.oxaas.context.soap.dataobjects.User;

/*
* Example SOAP client for OXaaS OXResellerContextService
*
* Create a context
*
*/
public class MyContextClientExample {

private static final QName SERVICE_NAME = new QName("http://soap.reseller.admin.openexchange.com", "OXResellerContextService");

public static void main(String[] args) {
final String subadminname = "mysubadmin";
final String subadminpw = "secret";
final String ctxname = subadminname + "_myctx";

Credentials creds = new Credentials();
ResellerContext ctx = new ResellerContext();
User oxadmin = new User();

OXResellerContextService contextservice = new OXResellerContextService(OXResellerContextService.WSDL_LOCATION, SERVICE_NAME);
OXResellerContextServicePortType contextport = contextservice.getOXResellerContextServiceHttpSoap11Endpoint();

creds.setLogin(subadminname);
creds.setPassword(subadminpw);

SOAPMapEntry taxonomy = new SOAPMapEntry();
taxonomy.setKey("taxonomy");
SOAPStringMap taxtypeval = new SOAPStringMap();
Entry taxtypeent = new Entry();
taxtypeent.setKey("types");
taxtypeent.setValue(subadminname);
taxtypeval.getEntries().add(taxtypeent);
taxonomy.setValue(taxtypeval);

SOAPMapEntry config = new SOAPMapEntry();
config.setKey("config");
SOAPStringMap configEntries = new SOAPStringMap();

Entry topbarHover = new Entry();
topbarHover.setKey("io.ox/dynamic-theme//topbarHover");
topbarHover.setValue("#0000ff");

Entry mainColor = new Entry();
mainColor.setKey("io.ox/dynamic-theme//mainColor");
mainColor.setValue("#ff0000");

Entry linkColor = new Entry();
linkColor.setKey("io.ox/dynamic-theme//linkColor");
linkColor.setValue("#00ff00");

Entry dynThemeCapa = new Entry();
dynThemeCapa.setKey("com.openexchange.capability.dynamic-theme");
dynThemeCapa.setValue("true");

configEntries.getEntries().add(topbarHover);
configEntries.getEntries().add(mainColor);
configEntries.getEntries().add(linkColor);
configEntries.getEntries().add(dynThemeCapa);
config.setValue(configEntries);

SOAPStringMapMap userattrs = new SOAPStringMapMap();
userattrs.getEntries().add(taxonomy);
userattrs.getEntries().add(config);

ctx.setName(ctxname);
ctx.setMaxQuota(10000l);
ctx.setUserAttributes(userattrs);

final String adminEmail = "oxadmin@example.com";
final String ctxadmname = "oxadmin";
final String ctxadmpw = "secret";
oxadmin.setName(ctxadmname);
oxadmin.setPassword(ctxadmpw);
oxadmin.setDisplayName("OX Admin");
oxadmin.setSurName("OX");
oxadmin.setGivenName("Admin");
oxadmin.setPrimaryEmail(adminEmail);
oxadmin.setEmail1(adminEmail);
oxadmin.setDefaultSenderAddress(adminEmail);
oxadmin.setLanguage("en_US");
oxadmin.setTimezone("Europe/Berlin");

try {
ResellerContext ret = contextport.createModuleAccessByName(ctx, oxadmin, "groupware_premium", creds, null);
System.out.println("created context with id=" + ret.getId());

System.out.println("existing contexts:");
List<ResellerContext> allctxs = contextport.listAll(creds);
for(final ResellerContext c : allctxs) {
System.out.println(c.getName() + " with id=" + c.getId());
}

System.in.read();

System.out.println("deleting created context again");
Delete del = new Delete();
del.setAuth(creds);
del.setCtx(ctx);
contextport.delete(del);
} catch (InvalidDataExceptionException e) {
e.printStackTrace();
} catch (ContextExistsExceptionException e) {
e.printStackTrace();
} catch (DuplicateExtensionExceptionException e) {
e.printStackTrace();
} catch (InvalidCredentialsExceptionException e) {
e.printStackTrace();
} catch (RemoteExceptionException e) {
e.printStackTrace();
} catch (StorageExceptionException e) {
e.printStackTrace();
} catch (IOException e) {
e.printStackTrace();
} catch (NoSuchContextExceptionException e) {
e.printStackTrace();
} catch (DatabaseUpdateExceptionException e) {
e.printStackTrace();
}
}

}
</syntaxhighlight>

===== User creation =====

The client below utilizes all SOAP services we have created so far.

The essential parts of the code are

* use OXResellerContextService to find out the ID of the context you want to create users
* create users using OXResellerUserService
* use one of the moduleaccess values as documented [[#Create_users|earlier]]
* use setMailQuota from OXaaSService to set each users mail quota individually
* use existsLogin from OXaaSService to check in advance of a login already exists

<syntaxhighlight lang="java">
package com.openexchange.oxaas.myclient;

import java.io.IOException;
import javax.xml.namespace.QName;
import com.openexchange.oxaas.context.OXResellerContextService;
import com.openexchange.oxaas.context.OXResellerContextServicePortType;
import com.openexchange.oxaas.extra.ExistsLoginFaultException;
import com.openexchange.oxaas.extra.OXaaSService;
import com.openexchange.oxaas.extra.OXaaSService_Service;
import com.openexchange.oxaas.extra.SetMailQuotaFaultException;
import com.openexchange.oxaas.user.DatabaseUpdateExceptionException;
import com.openexchange.oxaas.user.Delete;
import com.openexchange.oxaas.user.DuplicateExtensionExceptionException;
import com.openexchange.oxaas.user.InvalidCredentialsExceptionException;
import com.openexchange.oxaas.user.InvalidDataExceptionException;
import com.openexchange.oxaas.user.NoSuchContextExceptionException;
import com.openexchange.oxaas.user.NoSuchUserExceptionException;
import com.openexchange.oxaas.user.OXResellerUserService;
import com.openexchange.oxaas.user.OXResellerUserServicePortType;
import com.openexchange.oxaas.user.RemoteExceptionException;
import com.openexchange.oxaas.user.StorageExceptionException;
import com.openexchange.oxaas.user.reseller.soap.dataobjects.ResellerContext;
import com.openexchange.oxaas.user.rmi.dataobjects.Credentials;
import com.openexchange.oxaas.user.soap.dataobjects.User;

/*
* Example SOAP client for OXaaS OXResellerUserService
*
* Create users in a context
*
*/
public class MyUserClientExample {

private static final QName USER_SERVICE_NAME = new QName("http://soap.reseller.admin.openexchange.com", "OXResellerUserService");
private static final QName CONTEXT_SERVICE_NAME = new QName("http://soap.reseller.admin.openexchange.com", "OXResellerContextService");
private static final QName OXAAS_SERVICE_NAME = new QName("http://soap.oxaas.admin.openexchange.com/", "OXaaSService");

public static void main(String[] args) {
final String subadminname = "mysubadmin";
final String subadminpw = "secret";
final String ctxadmname = "oxadmin";
final String ctxadmpw = "secret";
final String ctxname = subadminname + "_myctx";

Credentials creds = new Credentials();
ResellerContext ctx = new ResellerContext();
User auser = new User();

OXResellerUserService userservice = new OXResellerUserService(OXResellerUserService.WSDL_LOCATION, USER_SERVICE_NAME);
OXResellerUserServicePortType userport = userservice.getOXResellerUserServiceHttpSoap12Endpoint();
OXResellerContextService contextservice = new OXResellerContextService(OXResellerContextService.WSDL_LOCATION, CONTEXT_SERVICE_NAME);
OXResellerContextServicePortType contextport = contextservice.getOXResellerContextServiceHttpSoap11Endpoint();
OXaaSService_Service oxaasservice = new OXaaSService_Service(OXaaSService_Service.WSDL_LOCATION, OXAAS_SERVICE_NAME);
OXaaSService oxaasport = oxaasservice.getOXaaSServiceSOAP();

// We need to use the ResellerContextService SOAP client stub to retrieve the context id
com.openexchange.oxaas.context.rmi.dataobjects.Credentials ctxCreds = new com.openexchange.oxaas.context.rmi.dataobjects.Credentials();
com.openexchange.oxaas.context.reseller.soap.dataobjects.ResellerContext ctxCtx = new com.openexchange.oxaas.context.reseller.soap.dataobjects.ResellerContext();
ctxCreds.setLogin(subadminname);
ctxCreds.setPassword(subadminpw);
ctxCtx.setName(ctxname);

creds.setLogin(ctxadmname);
creds.setPassword(ctxadmpw);

final String userEmail = "auser@example.com";
auser.setName("auser");
auser.setPassword("secret");
auser.setDisplayName("My User");
auser.setSurName("My");
auser.setGivenName("User");
auser.setPrimaryEmail(userEmail);
auser.setEmail1(userEmail);
auser.setDefaultSenderAddress(userEmail);
auser.setLanguage("en_US");
auser.setTimezone("Europe/Berlin");

try {
// we only have the name of the context, so we need to retrieve its id, first using ResellerContextService
com.openexchange.oxaas.context.reseller.soap.dataobjects.ResellerContext ctxRet = contextport.getData(ctxCtx, ctxCreds);
ctx.setId(ctxRet.getId());

// create the user via OXResellerUserService
User ret = userport.createByModuleAccessName(ctx, auser, "groupware_premium", creds);
System.out.println("created user with id=" + ret.getId());

// set mail quota for that user using OXaaSService
com.openexchange.oxaas.extra.Credentials oxaasCtxCreds = new com.openexchange.oxaas.extra.Credentials();
oxaasCtxCreds.setLogin(ctxadmname);
oxaasCtxCreds.setPassword(ctxadmpw);
oxaasport.setMailQuota(ctxRet.getId(), ret.getId(), 1000l, oxaasCtxCreds);

// check whether the login for the user has been created within my subadmin namespace
// NOTE: this check should be used beforehand usually: check whether login exists and then create it if not
com.openexchange.oxaas.extra.Credentials oxaasAdminCreds = new com.openexchange.oxaas.extra.Credentials();
oxaasAdminCreds.setLogin(subadminname);
oxaasAdminCreds.setPassword(subadminpw);
if( oxaasport.existsLogin("auser", oxaasAdminCreds) ) {
System.out.println("all ok, user login has been created");
}

System.in.read();

System.out.println("deleting created user again");
Delete del = new Delete();
del.setAuth(creds);
del.setCtx(ctx);
del.setUser(ret);
userport.delete(del);
} catch (InvalidDataExceptionException e) {
e.printStackTrace();
} catch (NoSuchContextExceptionException e) {
e.printStackTrace();
} catch (DuplicateExtensionExceptionException e) {
e.printStackTrace();
} catch (DatabaseUpdateExceptionException e) {
e.printStackTrace();
} catch (InvalidCredentialsExceptionException e) {
e.printStackTrace();
} catch (RemoteExceptionException e) {
e.printStackTrace();
} catch (StorageExceptionException e) {
e.printStackTrace();
} catch (NoSuchUserExceptionException e) {
e.printStackTrace();
} catch (IOException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.InvalidDataExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.NoSuchContextExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.DuplicateExtensionExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.InvalidCredentialsExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.RemoteExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.StorageExceptionException e) {
e.printStackTrace();
} catch (SetMailQuotaFaultException e) {
e.printStackTrace();
} catch (ExistsLoginFaultException e) {
e.printStackTrace();
}
}

}
</syntaxhighlight>

===== Email (alias) management =====

The next example shows how to manage email aliases and shared domains.
The essential information is:

* if you want to change the email address of a user, you have to add the new address to the list of aliases
* when you want to change individual settings of a user, only send the changed settings

<syntaxhighlight lang="java">
package com.openexchange.oxaas.myclient;

import java.util.List;
import javax.xml.namespace.QName;
import com.openexchange.oxaas.context.OXResellerContextService;
import com.openexchange.oxaas.context.OXResellerContextServicePortType;
import com.openexchange.oxaas.extra.CreateSharedDomainFaultException;
import com.openexchange.oxaas.extra.OXaaSService;
import com.openexchange.oxaas.extra.OXaaSService_Service;
import com.openexchange.oxaas.user.Change;
import com.openexchange.oxaas.user.DatabaseUpdateExceptionException;
import com.openexchange.oxaas.user.DuplicateExtensionExceptionException;
import com.openexchange.oxaas.user.InvalidCredentialsExceptionException;
import com.openexchange.oxaas.user.InvalidDataExceptionException;
import com.openexchange.oxaas.user.NoSuchContextExceptionException;
import com.openexchange.oxaas.user.NoSuchUserExceptionException;
import com.openexchange.oxaas.user.OXResellerUserService;
import com.openexchange.oxaas.user.OXResellerUserServicePortType;
import com.openexchange.oxaas.user.RemoteExceptionException;
import com.openexchange.oxaas.user.StorageExceptionException;
import com.openexchange.oxaas.user.reseller.soap.dataobjects.ResellerContext;
import com.openexchange.oxaas.user.rmi.dataobjects.Credentials;
import com.openexchange.oxaas.user.soap.dataobjects.User;

/*
* Example SOAP client for OXaaS OXResellerUserService
*
* Create users in a context
*
*/
public class OXaaSAliasManagement {

private static final QName USER_SERVICE_NAME = new QName("http://soap.reseller.admin.openexchange.com", "OXResellerUserService");
private static final QName CONTEXT_SERVICE_NAME = new QName("http://soap.reseller.admin.openexchange.com", "OXResellerContextService");
private static final QName OXAAS_SERVICE_NAME = new QName("http://soap.oxaas.admin.openexchange.com/", "OXaaSService");

public static void main(String[] args) {
final String subadminname = "mysubadmin";
final String subadminpw = "secret";
final String ctxadmname = "oxadmin";
final String ctxadmpw = "secret";
final String userlogin = "auser";
final String ctxname = subadminname + "_myctx";

Credentials creds = new Credentials();
ResellerContext ctx = new ResellerContext();

OXResellerUserService userservice = new OXResellerUserService(OXResellerUserService.WSDL_LOCATION, USER_SERVICE_NAME);
OXResellerUserServicePortType userport = userservice.getOXResellerUserServiceHttpSoap12Endpoint();
OXResellerContextService contextservice = new OXResellerContextService(OXResellerContextService.WSDL_LOCATION, CONTEXT_SERVICE_NAME);
OXResellerContextServicePortType contextport = contextservice.getOXResellerContextServiceHttpSoap11Endpoint();
OXaaSService_Service oxaasservice = new OXaaSService_Service(OXaaSService_Service.WSDL_LOCATION, OXAAS_SERVICE_NAME);
OXaaSService oxaasport = oxaasservice.getOXaaSServiceSOAP();

// We need to use the ResellerContextService SOAP client stub to retrieve the context id
com.openexchange.oxaas.context.rmi.dataobjects.Credentials ctxCreds = new com.openexchange.oxaas.context.rmi.dataobjects.Credentials();
com.openexchange.oxaas.context.reseller.soap.dataobjects.ResellerContext ctxCtx = new com.openexchange.oxaas.context.reseller.soap.dataobjects.ResellerContext();
ctxCreds.setLogin(subadminname);
ctxCreds.setPassword(subadminpw);
ctxCtx.setName(ctxname);

creds.setLogin(ctxadmname);
creds.setPassword(ctxadmpw);

try {
// we only have the name of the context, so we need to retrieve its id, first using ResellerContextService
com.openexchange.oxaas.context.reseller.soap.dataobjects.ResellerContext ctxRet = contextport.getData(ctxCtx, ctxCreds);
ctx.setId(ctxRet.getId());

/*
* now we want to add an alias to the user "auser"
*/
User auser = new User();
auser.setName(userlogin);
User ret = userport.getData(ctx, auser, creds);
List<String> aliases = ret.getAliases();
// list all mail aliases of that user
System.out.println("User has the following alias(es):" + aliases);
// now add another one
aliases.add("sales@example.com");

// we also want to add an alias within a shared domain
com.openexchange.oxaas.extra.Credentials oxaasCtxCreds = new com.openexchange.oxaas.extra.Credentials();
oxaasCtxCreds.setLogin(subadminname);
oxaasCtxCreds.setPassword(subadminpw);
/*
* Note: we can run this method as often as we want, it will ONLY return an error in case we want to add a shared domain
* that is already bound to another subadmin/customer
*/
oxaasport.createSharedDomain("shared.net", oxaasCtxCreds);
aliases.add("me@shared.net");

// store changes
// we need to created a clean user instance since we cannot just store back the returned user
User changeduser = new User();
changeduser.setId(ret.getId());
changeduser.getAliases().addAll(aliases);
Change change = new Change();
change.setAuth(creds);
change.setCtx(ctx);
change.setUsrdata(changeduser);
userport.change(change);

// control the result
ret = userport.getData(ctx, auser, creds);
aliases = ret.getAliases();
// list all mail aliases of that user
System.out.println("User has the following alias(es):" + aliases);

/*
* now changing the users email address:
* to do that, we have to do the following:
* 1. add the new email address to the aliases, if not yet present
* 2. change the email address in email1, defaultsenderaddress and primarymail
*
*/
String newaddress = "boss@mydomain.com"; // introduce another domain, not shared
changeduser = new User();
changeduser.setId(ret.getId());
changeduser.setEmail1(newaddress);
//reuse change from above
change.setUsrdata(changeduser);
try {
// this will throw an error since the new address is not in the aliases
userport.change(change);
} catch (Exception e) {
System.out.println("ERROR: " + e.getMessage());
}

// now add the new address to the aliases and try again
aliases = ret.getAliases();
aliases.add(newaddress);
changeduser.getAliases().addAll(aliases);
userport.change(change);

// control the result
ret = userport.getData(ctx, auser, creds);
aliases = ret.getAliases();
// list all mail aliases of that user
System.out.println("User has the following alias(es):" + aliases);
} catch (com.openexchange.oxaas.context.InvalidDataExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.NoSuchContextExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.DuplicateExtensionExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.InvalidCredentialsExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.RemoteExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.StorageExceptionException e) {
e.printStackTrace();
} catch (InvalidDataExceptionException e) {
e.printStackTrace();
} catch (NoSuchContextExceptionException e) {
e.printStackTrace();
} catch (DuplicateExtensionExceptionException e) {
e.printStackTrace();
} catch (DatabaseUpdateExceptionException e) {
e.printStackTrace();
} catch (InvalidCredentialsExceptionException e) {
e.printStackTrace();
} catch (RemoteExceptionException e) {
e.printStackTrace();
} catch (NoSuchUserExceptionException e) {
e.printStackTrace();
} catch (StorageExceptionException e) {
e.printStackTrace();
} catch (CreateSharedDomainFaultException e) {
e.printStackTrace();
}
}

}
</syntaxhighlight>

===== Catchall account management =====

The next example shows how to manage catchall accounts.
Please take into account that this is not necessarily enabled for your account.

<syntaxhighlight lang="java">
package com.openexchange.oxaas.myclient;

import javax.xml.namespace.QName;
import com.openexchange.oxaas.context.OXResellerContextService;
import com.openexchange.oxaas.context.OXResellerContextServicePortType;
import com.openexchange.oxaas.extra.CreateDomainCatchallFaultException;
import com.openexchange.oxaas.extra.DeleteDomainCatchallFaultException;
import com.openexchange.oxaas.extra.DomainCatchall;
import com.openexchange.oxaas.extra.ListDomainCatchallsFaultException;
import com.openexchange.oxaas.extra.OXaaSService;
import com.openexchange.oxaas.extra.OXaaSService_Service;

/*
* Example SOAP client for OXaaS OXResellerUserService
*
* Create users in a context
*
*/
public class OXaaSCatchAllManagement {

private static final QName CONTEXT_SERVICE_NAME = new QName("http://soap.reseller.admin.openexchange.com", "OXResellerContextService");
private static final QName OXAAS_SERVICE_NAME = new QName("http://soap.oxaas.admin.openexchange.com/", "OXaaSService");

public static void main(String[] args) {
final String subadminname = "mysubadmin";
final String subadminpw = "secret";
final String userlogin = "auser";
final String ctxname = subadminname + "_myctx";

OXResellerContextService contextservice = new OXResellerContextService(OXResellerContextService.WSDL_LOCATION, CONTEXT_SERVICE_NAME);
OXResellerContextServicePortType contextport = contextservice.getOXResellerContextServiceHttpSoap11Endpoint();
OXaaSService_Service oxaasservice = new OXaaSService_Service(OXaaSService_Service.WSDL_LOCATION, OXAAS_SERVICE_NAME);
OXaaSService oxaasport = oxaasservice.getOXaaSServiceSOAP();

// We need to use the ResellerContextService SOAP client stub to retrieve the context id
com.openexchange.oxaas.context.rmi.dataobjects.Credentials ctxCreds = new com.openexchange.oxaas.context.rmi.dataobjects.Credentials();
com.openexchange.oxaas.context.reseller.soap.dataobjects.ResellerContext ctxCtx = new com.openexchange.oxaas.context.reseller.soap.dataobjects.ResellerContext();
ctxCreds.setLogin(subadminname);
ctxCreds.setPassword(subadminpw);
ctxCtx.setName(ctxname);

try {
// we only have the name of the context, so we need to retrieve its id, first using ResellerContextService
com.openexchange.oxaas.context.reseller.soap.dataobjects.ResellerContext ctxRet = contextport.getData(ctxCtx, ctxCreds);

com.openexchange.oxaas.extra.Credentials oxaasCtxCreds = new com.openexchange.oxaas.extra.Credentials();
oxaasCtxCreds.setLogin(subadminname);
oxaasCtxCreds.setPassword(subadminpw);

/*
* Note: this will throw an error
* oxaas_catchall_domain capability not available for context XXX, user YYY in brand ZZZ
* unless you have domain catchall in your contract
*/
oxaasport.createDomainCatchall(ctxRet.getId(), "example.com", userlogin, oxaasCtxCreds);

for(final DomainCatchall dc : oxaasport.listDomainCatchalls(ctxRet.getId(), oxaasCtxCreds) ) {
System.out.println("Catchall account for domain " + dc.getDomain() + " is " + dc.getLogin());
}

// cleanup
oxaasport.deleteDomainCatchall(ctxRet.getId(), "example.com", userlogin, oxaasCtxCreds);
} catch (com.openexchange.oxaas.context.InvalidDataExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.NoSuchContextExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.DuplicateExtensionExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.InvalidCredentialsExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.RemoteExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.StorageExceptionException e) {
e.printStackTrace();
} catch (ListDomainCatchallsFaultException e) {
e.printStackTrace();
} catch (DeleteDomainCatchallFaultException e) {
e.printStackTrace();
} catch (CreateDomainCatchallFaultException e) {
e.printStackTrace();
}
}

}
</syntaxhighlight>

=== Perl ===

==== Standalone example: createOXaaSContext ====

http://software.open-xchange.com/products/appsuite/doc/oxasservice/createOXaaSContext.pl

==== Standalone example: createOXaaSUser ====

http://software.open-xchange.com/products/appsuite/doc/oxasservice/createOXaaSUser.pl

==== Standalone example: changeOXaaSUserPermissions ====

http://software.open-xchange.com/products/appsuite/doc/oxasservice/changeOXaaSUserPermissions.pl

==== OXaas APS(1.2) package ====

Just download the APS package as mentioned [[#Reference_implementation|here]]. When you extract the zip file, you will find
the perl code within the directory <tt>scripts</tt>.

;OXSOAP.pm: SOAP Wrapper functions
;configure-alias.pl: Mail alias management
;configure-catchall.pl: Catchall mail alias management
;configure-mbox.pl: User management
;configure.pl: Context management
;verify-account.pl: check for login existence (existsLogin)
;verify-catchall.pl: check for catchall existence
;verify-shared.pl: shared mail alias checks

Caldav carddav Bundles

2020-01-24T22:30:38Z

WolfgangRosenauer: added opensync

This article is valid until the version 7.10.2 of the Open Xchange Server. For newer versions please visit https://documentation.open-xchange.com/latest/middleware/miscellaneous/caldav_carddav.html

= 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 Calendar and Address Book clients.

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 Mac OS X 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 your existing <code>VirtualHost</code> entry. This is an <b>example</b> where <code>MYSERVER.TLD</code> is the domain-name of the ox-server:

# NameVirtualHost directive no longer has any effect since Apache >=2.4
# uncomment only for Apache Versions <2.4
#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>

ProxyPass / balancer://oxserver-sync/servlet/dav/

</VirtualHost>

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

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} Reminders [OR]
RewriteCond %{HTTP_USER_AGENT} DataAccess [OR]
RewriteCond %{HTTP_USER_AGENT} DAVKit [OR]
RewriteCond %{HTTP_USER_AGENT} DAVx5 [OR]
RewriteCond %{HTTP_USER_AGENT} OpenSync [OR]
RewriteCond %{HTTP_USER_AGENT} "DAVdroid" [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\ Book [OR]
RewriteCond %{HTTP_USER_AGENT} CalendarStore [OR]
RewriteCond %{HTTP_USER_AGENT} CalendarAgent [OR]
RewriteCond %{HTTP_USER_AGENT} CalDAV%20Sync%20Adapter [OR]
RewriteCond %{HTTP_USER_AGENT} accountsd [OR]
RewriteCond %{HTTP_USER_AGENT} "eM Client" [OR]
RewriteCond %{HTTP_USER_AGENT} "OX Sync" [OR]
RewriteCond %{HTTP_USER_AGENT} CalDav [OR]
RewriteCond %{HTTP_USER_AGENT} CoreDAV
RewriteCond %{HTTP_USER_AGENT} "!Open-Xchange Calendar Feed Client"
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.

'''Note:''' Depending on the specific configuration, such a global definition of the rewrite rules might not be appropriate. However, the rules may also be defined inside a <code>Directory</code> context. More details are available at http://httpd.apache.org/docs/current/mod/mod_rewrite.html#rewriterule.

== 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. The rewrite target must be the root of your DAV server.
The well-known aliases should be added for your DAV vhost and on the vhost serving the host matching the mail domain:

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

In the case of not serving the DAV service on the vhost root additionally some DNS TXT records are recommended:

_caldavs._tcp.MYSERVER.TLD. 10800 IN TXT path=/servlet/dav
_caldav._tcp.MYSERVER.TLD. 10800 IN TXT path=/servlet/dav
_carddavs._tcp.MYSERVER.TLD. 10800 IN TXT path=/servlet/dav
_carddav._tcp.MYSERVER.TLD. 10800 IN TXT path=/servlet/dav

== Installation on OX App Suite ==

=== Debian GNU/Linux 9.0===

Add the following entry to /etc/apt/sources.list.d/open-xchange.list if not already present:

deb https://software.open-xchange.com/products/appsuite/stable/backend/DebianStretch/ /

# if you have a valid maintenance subscription, please uncomment the
# following and add the ldb account data to the url so that the most recent
# packages get installed
# deb https://[CUSTOMERID:PASSWORD]@software.open-xchange.com/products/appsuite/stable/backend/updates/DebianStretch/ /

and run

$ apt-get update
$ apt-get install open-xchange-dav

=== Debian GNU/Linux 10.0===

Add the following entry to /etc/apt/sources.list.d/open-xchange.list if not already present:

deb https://software.open-xchange.com/products/appsuite/stable/backend/DebianBuster/ /

# if you have a valid maintenance subscription, please uncomment the
# following and add the ldb account data to the url so that the most recent
# packages get installed
# deb https://[CUSTOMERID:PASSWORD]@software.open-xchange.com/products/appsuite/stable/backend/updates/DebianBuster/ /

and run

$ apt-get update
$ apt-get install open-xchange-dav

=== SUSE Linux Enterprise Server 12===

Add the package repository using zypper if not already present:

$ zypper ar https://software.open-xchange.com/products/appsuite/stable/backend/SLE_12 ox

If you have a valid maintenance subscription, please run the following command and add the ldb account data to the url so that the most recent packages get installed:

$ zypper ar https://[CUSTOMERID:PASSWORD]@software.open-xchange.com/products/appsuite/stable/backend/updates/SLES11 ox-updates

and run

$ zypper ref
$ zypper in open-xchange-dav

=== RedHat Enterprise Linux 6===

Start a console and create a software repository file if not already present:

$ vim /etc/yum.repos.d/ox.repo

[ox]
name=Open-Xchange
baseurl=https://software.open-xchange.com/products/appsuite/stable/backend/RHEL6/
gpgkey=https://software.open-xchange.com/oxbuildkey.pub
enabled=1
gpgcheck=1
metadata_expire=0m

# if you have a valid maintenance subscription, please uncomment the
# following and add the ldb account data to the url so that the most recent
# packages get installed
# [ox-updates]
# name=Open-Xchange Updates
# baseurl=https://[CUSTOMERID:PASSWORD]@software.open-xchange.com/products/appsuite/stable/backend/updates/RHEL6/
# gpgkey=https://software.open-xchange.com/oxbuildkey.pub
# enabled=1
# gpgcheck=1
# metadata_expire=0m

and run

$ yum update
$ yum install open-xchange-dav

===RedHat Enterprise Linux 7===

Start a console and create a software repository file if not already present:

$ vim /etc/yum.repos.d/ox.repo

[ox]
name=Open-Xchange
baseurl=https://software.open-xchange.com/products/appsuite/stable/backend/RHEL7/
gpgkey=https://software.open-xchange.com/oxbuildkey.pub
enabled=1
gpgcheck=1
metadata_expire=0m

# if you have a valid maintenance subscription, please uncomment the
# following and add the ldb account data to the url so that the most recent
# packages get installed
# [ox-updates]
# name=Open-Xchange Updates
# baseurl=https://[CUSTOMERID:PASSWORD]@software.open-xchange.com/products/appsuite/stable/backend/updates/RHEL7/
# gpgkey=https://software.open-xchange.com/oxbuildkey.pub
# enabled=1
# gpgcheck=1
# metadata_expire=0m

and run

$ yum update
$ yum install open-xchange-dav

===CentOS 6===

Start a console and create a software repository file if not already present:

$ vim /etc/yum.repos.d/ox.repo

[ox]
name=Open-Xchange
baseurl=https://software.open-xchange.com/products/appsuite/stable/backend/RHEL6/
gpgkey=https://software.open-xchange.com/oxbuildkey.pub
enabled=1
gpgcheck=1
metadata_expire=0m

# if you have a valid maintenance subscription, please uncomment the
# following and add the ldb account data to the url so that the most recent
# packages get installed
# [ox-updates]
# name=Open-Xchange Updates
# baseurl=https://[CUSTOMERID:PASSWORD]@software.open-xchange.com/products/appsuite/stable/backend/updates/RHEL6/
# gpgkey=https://software.open-xchange.com/oxbuildkey.pub
# enabled=1
# gpgcheck=1
# metadata_expire=0m

and run

$ yum update
$ yum install open-xchange-dav

===CentOS 7===

Start a console and create a software repository file if not already present:

$ vim /etc/yum.repos.d/ox.repo

[ox]
name=Open-Xchange
baseurl=https://software.open-xchange.com/products/appsuite/stable/backend/RHEL7/
gpgkey=https://software.open-xchange.com/oxbuildkey.pub
enabled=1
gpgcheck=1
metadata_expire=0m

# if you have a valid maintenance subscription, please uncomment the
# following and add the ldb account data to the url so that the most recent
# packages get installed
# [ox-updates]
# name=Open-Xchange Updates
# baseurl=https://[CUSTOMERID:PASSWORD]@software.open-xchange.com/products/appsuite/stable/backend/updates/RHEL7/
# gpgkey=https://software.open-xchange.com/oxbuildkey.pub
# enabled=1
# gpgcheck=1
# metadata_expire=0m

and run

$ yum update
$ yum install open-xchange-dav

== CalDAV Configuration ==

The following configuration options are available in the configuration files <code>caldav.properties</code> and <code>caldav.yml</code>:

===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:

/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 <code>contextSets</code> 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]]

My.cnf

2020-01-17T14:23:32Z

WolfgangRosenauer:

== Introduction ==

This page lists some performance tuning parameters which we recommend for tuning MySQL database services used for Open-Xchange installations.

We cannot guarantee this is an exhaustive list of required settings. So treat this list of tunings as probably required, but not necessarily sufficient settings for optimal MySQL performance.

Furthermore, as MySQL changes over time, settings which have been correct as of the time of writing may become incorrect later.

However, this list of settings is the result of internal performance testing and real world customer feedback, so it should be valid to some extent.

In the end, proper configuration of the database service for performance, but also consistency, durability and high availability is in the responsibility of the customer.

=== Performance items ===

* You should adjust the <code>innodb_buffer_pool_size</code> parameter for reasonable memory usage. Our DB sizing is mainly memory-driven and this is where most of the memory goes. Our standard DB machine sizing assumption is 32 GB if MySQL dedicated memory on a 48 GB total memory machine. On such a machine, you would configure 32 GB for the innodb_buffer_pool size, being aware that MySQL does also require memory for other things, in particular there are some also per-connection related memory spendings, which can become substantial if you allow for a lot of maximum concurrent connections. Please watch your memory configuration carefully, use monitoring and tools like mysqltuner.pl.

* On bigger installations you should use <code>innodb_file_per_table = 1</code>, which is creating single files instead of one big blob. If you change this parameter after the database initialization you have to recreate (like dump/drop and re-import) the tables.

* It can help to put different parts of the mysql datadir (iblog, ibdata) on different filesystems / storage devices. This depends on your infrastructure. Settings herefore are <code>datadir</code>, <code>innodb_data_home_dir</code>, <code>innodb_log_group_home_dir</code>.

* If your storage is fast (handle a lot of IOPS), you may want to adjust the <code>innodb_io_capacity</code> setting, which defines a limit for the IOPS MySQL will create. The default is 200, which is sensible for single spindle disks. But if you have storage appliances with a lot of fast SAS drives, or even SSDs, this limit can be increased greatly.

=== Functional items ===

* Query cache is to be switched off; as we found in our own benchmarks and as backed up by upstreams, this hurts performance in load situations with high concurrency. [https://dev.mysql.com/doc/refman/5.7/en/query-cache.htm The query cache is deprecated as of MySQL 5.7.20, and is removed in MySQL 8.0], so we recommend also to switch that off.
* Starting with App Suite 7.10.0, <code>character_set_server</code> must be set to <code>utf8mb4</code> and <code>collation_server</code> to <code>utf8mb4_general_ci</code>. For older versions it must be <code>utf8</code> and <code>utf8_general_ci</code> respectively.
* Starting with MySQL 5.7 <code>innodb_strict_mode</code> must be disabled.
* Starting with MySQL 5.6 and MariaDB 10.1 <code>sql_mode</code> must be configured according to belows matrix.

==== SQL mode matrix ====

The default for the <code>sql_mode</code> setting changes regularly with MariaDB and MySQL releases and is not even consistent anymore between the two derivates. SQL modes affect how data and queries are handled at runtime. Enabling strict modes might lead to errors in terms of failing queries or even update tasks. We strongly recommend the following configuration to avoid according runtime errors:

{| class="wikitable"
|-
! scope="col"| sql_mode
! scope="col"| App Suite 7.8.4
! scope="col"| App Suite 7.10.x
|-
! scope="row"| MySQL 5.6
| <code>NO_ENGINE_SUBSTITUTION</code>
| <code>NO_ENGINE_SUBSTITUTION</code>
|-
! scope="row"| MySQL 5.7
| <code>NO_AUTO_CREATE_USER,NO_ENGINE_SUBSTITUTION</code>
| <code>NO_AUTO_CREATE_USER,NO_ENGINE_SUBSTITUTION,ONLY_FULL_GROUP_BY</code>
|-
! scope="row"| MariaDB >= 10.1
| <code>NO_AUTO_CREATE_USER,NO_ENGINE_SUBSTITUTION</code>
| <code>NO_AUTO_CREATE_USER,NO_ENGINE_SUBSTITUTION</code>
|-
|}

=== Sample config files ===

For easy deployment we recommend not to edit existing the existing my.cnf file, rather assume the distro provides sane settings for most of the items and override items where needed.

As in MySQL there is a [https://dev.mysql.com/doc/refman/5.7/en/option-files.html last instance wins] semantic in options file parsing, we propose to create a custom include directory "ox.conf.d", put our custom config files therein, and include this directory as latest directory in /etc/mysql/my.cnf.

To put in that directory, we have one main tuning file called tunings.cnf, one galera-related file if galera is in use, and one more galera host-specific file which contains per-host settings if using galera (separate in a file of its own for easier configuration management).

So, start with adding to the existing my.cnf at the very bottom:

!includedir /etc/mysql/ox.conf.d/

Create that directory and put in there the generic ox tunings file /etc/mysql/ox.conf.d/tunings.cnf:

[mysqld]
bind-address = *

#innodb_use_native_aio = 0

table_open_cache = 3072
table_definition_cache = 4096
max_heap_table_size = 64M
tmp_table_size = 64M
max_connections = 505
max_user_connections = 500
max_allowed_packet = 16M
thread_cache_size = 32
query_cache_size = 0
query_cache_type = 0
innodb_buffer_pool_size = 32G
# the default value in MySQL 5.6.6 and higher is 8 when innodb_buffer_pool_size is greater than or equal to 1GB. Otherwise, the default is 1.
innodb_buffer_pool_instances = 32
innodb_data_file_path = ibdata1:128M:autoextend
innodb_file_per_table = 1
# innodb_log_file_size should be 25% of the innodb_buffer_pool_size
innodb_log_file_size = 4GB
# default and recommended value is 2
innodb_log_files_in_group = 2
# adjust according to your storage
#innodb_io_capacity = 1000

# we are unsure about this setting. Newer versions of MariaDB seem to be fine with low (=1) settings for this value.
# Traditionally we encountered values up to 4x the number of cores.
# Default seems to be number of cores, so let's stick the default
# In the end, we need to leave this setting up to you: if you dont get full cpu utilization in cpu-bound situations, this might be a setting to increase.
#thread_pool_size = 32

binlog_cache_size = 1M
sync_binlog = 8
binlog_format = row

character_set_server = utf8mb4
collation_server = utf8mb4_general_ci

# default since MySQL 5.5.5 (was MyISAM previously)
default_storage_engine = InnoDB

innodb_autoinc_lock_mode = 2

# keep until 5.6, deprecated later
innodb_locks_unsafe_for_binlog = 1

# we found this has huge impact on (galera) performance
# default (consistent) setting of 1 greatly severs performance
# in galera (or async master-slave) deployments, you might be ok with setting this to 0 or 2,
# assuming our consistency / availability comes from replication / other cluster nodes
innodb_flush_log_at_trx_commit = 0

# for performance testing systems, to not use excessive disk space
#expire_logs_days = 1

# MySQL 5.7.7 has changed the default to 1. Disable it explicitly to prevent from errors based on invalid data stored by former App Suite or MySQL versions.
innodb_strict_mode = 0

# The following value refers to App Suite 7.10 on top of MySQL 5.7. For other combinations see the sql mode matrix at http://oxpedia.org/wiki/index.php?title=My.cnf.
sql_mode = NO_ENGINE_SUBSTITUTION,NO_AUTO_CREATE_USER,ONLY_FULL_GROUP_BY

If using galera, use the following galera configuration file <code>/etc/mysql/ox.conf.d/wsrep.cnf</code>. See the comments in that file for values to be adjusted.

[mysqld]
# adjust for your distros SO location
wsrep_provider=/usr/lib/libgalera_smm.so

# this is the big winner and enables us to switch off OX's replication monitor
wsrep_sync_wait=1

# pick a unique cluster name
wsrep_cluster_name=devcluster
# adjust for your IPs / hostnames
wsrep_cluster_address=gcomm://10.20.29.68,10.20.29.69,10.20.29.70

# put this in host.cnf
#wsrep_node_name=...
#wsrep_node_address=...

# For some MariaDB versions, xtrabackup-v2 no longer works, instead use "mariabackup"
# (needs to be installed separately, e.g. via the mariadb-backup-10.2 package)
# see upstream documentation for details:
# https://mariadb.com/kb/en/library/getting-started-with-mariadb-galera-cluster/#xtrabackup
#
# wsrep_sst_method=mariabackup
wsrep_sst_method=xtrabackup-v2

# wsrep_sst_auth if of format username:password
# pick whatever you configured on the donor node
wsrep_sst_auth=sstuser:...

# galera-specific tunings
wsrep_slave_threads = 32

# finally, enable wsrep: required for some MariaDB versions
wsrep_on=ON -- Enable wsrep replication (MariaDB starting 10.1.1)

Galera-related host-specific settings go in /etc/mysql/ox.conf.d/host.cnf:

[mysqld]
# the nodes hostname
wsrep_node_name=...
# and the IP of the wsrep relevant interface, if multiple
wsrep_node_address=10.20.29.68

SourceCodeAccess

2020-01-08T10:11:26Z

WolfgangRosenauer:

= How to download the Open-Xchange source code =

Starting with 6.22 the source code of Open-Xchange server is available from Git repositories.

The following repositories exist:

{| border="1" cellspacing="0" cellpadding="5" align="center"
! Repository
! content
|-
| https://gitlab.open-xchange.com/middleware/core
| The main repository containing most of the parts of Open-Xchange server
|-
| https://gitlab.open-xchange.com/frontend/core
| The user interface of OX App Suite
|-
| https://gitlab.open-xchange.com/appsuite/guard
| The server-code and UI for OX Guard (PGP implementation)
|-
| https://code.open-xchange.com/git/frontend6
| The AJAX user interface (version 6)
|-
| documentconverter-api
| The API of the server-based part of the documentconverter needed for OX Text
|-
| office
| The server-code for OX Text and OX Spreadsheet
|-
| office-web
| The frontend-code for OX Text and OX Spreadsheet
|-
| mobile-api-facade
|
|-
|}

== Git operations to access the code ==

To clone a repository in case of gitlab please follow the instructions shown there.
For cloning from code.open-xchange.com, run

$ git clone https://code.open-xchange.com/git/<repository>
$ cd <repository>
$ git checkout -t origin/<branch>

== The currently used Git branches ==

For a list of available branches, run

$ git branch -r

The main development process uses the following branches:

{| border="1" cellspacing="0" cellpadding="5" align="center"
! Git branch
! content
|-
| develop
| head development
|-
| release-<version>
| stabilizing for <version> release
|-
| master
| maintenance of current release
|-
| master-<version>
| maintenance of previous releases
|-
|}

[[Category: OX6]]
[[Category: AppSuite]]
[[Category: Developer]]

SourceCodeAccess

2020-01-08T10:02:20Z

WolfgangRosenauer:

= How to download the Open-Xchange source code =

Starting with 6.22 the source code of Open-Xchange server is available from Git repositories.

The following repositories exist:

{| border="1" cellspacing="0" cellpadding="5" align="center"
! Repository
! content
|-
| https://gitlab.open-xchange.com/middleware/core
| The main repository containing most of the parts of Open-Xchange server
|-
| https://gitlab.open-xchange.com/frontend/core
| The user interface of OX App Suite
|-
| https://gitlab.open-xchange.com/appsuite/guard
| The server-code and UI for OX Guard (PGP implementation)
|-
| https://code.open-xchange.com/git/frontend6
| The AJAX user interface (version 6)
|-
| documentconverter-api
| The API of the server-based part of the documentconverter needed for OX Text
|-
| office
| The server-code for OX Text and OX Spreadsheet
|-
| office-web
| The frontend-code for OX Text and OX Spreadsheet
|-
|}

== Git operations to access the code ==

To clone a repository in case of gitlab please follow the instructions shown there.
For cloning from code.open-xchange.com, run

$ git clone https://code.open-xchange.com/git/<repository>
$ cd <repository>
$ git checkout -t origin/<branch>

== The currently used Git branches ==

For a list of available branches, run

$ git branch -r

The main development process uses the following branches:

{| border="1" cellspacing="0" cellpadding="5" align="center"
! Git branch
! content
|-
| develop
| head development
|-
| release-<version>
| stabilizing for <version> release
|-
| master
| maintenance of current release
|-
| master-<version>
| maintenance of previous releases
|-
|}

[[Category: OX6]]
[[Category: AppSuite]]
[[Category: Developer]]

Mailclient autoconfiguration

2020-01-03T11:00:54Z

WolfgangRosenauer:

Mailclient autoconfiguration

2019-12-31T11:42:17Z

WolfgangRosenauer:

= Providing autoconfiguration for mail clients =

This article explains a solution for autoconfiguration for a set of mail clients which can be configured against a mail system automatically by just entering email address and password. There are three widely used approaches to do this via a self hosted lookup method, based on Microsoft's autodiscover, [https://developer.mozilla.org/en-US/docs/Mozilla/Thunderbird/Autoconfiguration Mozilla's autoconfig], and iOS/MacOS provisioning which are relevant to support detecting IMAP and SMTP server details for client configuration. Another option is solely based on DNS SRV discovery ([https://tools.ietf.org/html/rfc6186 RFC 6186]).

Since [[AppSuite:EM_Client_for_OX_App_Suite|eMClient for OX App Suite]] is using the Microsoft based solution this service is especially important to have a smooth user experience for customer environments offering it to their users.

autodiscover and autoconfig are based on XML schemas. Therefore for very simple deployments it might even be enough to serve some static XML files for both usecases. Please see the respective vendor standard documentation for more details.

In this article we show how to deploy a simple autoconfiguration service based on the open source solution [https://automx.org/en/ automx].

== Preparations ==

The autoconfiguration protocols use several ways to find the XML provided later by automx. In the following section there is listed in which order the protocols are looking for the XML. Depending where you would like to serve the XML files you can choose from those options.

The domain example.org as in those examples are the ones taken from the entered email address.

=== autoconfig ===

# http://autoconfig.example.org/mail/config-v1.1.xml
# http://example.org/.well-known/autoconfig/mail/config-v1.1.xml

=== autodiscover ===

# https://example.org/autodiscover/autodiscover.xml
# https://autodiscover.example.org/autodiscover/autodiscover.xml
# DNS SRV lookup for autodiscover.tcp.example.org

=== DNS SRV ===

A DNS SRV entry for autodiscover would look like this:

_autodiscover._tcp IN SRV 0 0 443 $HOSTNAME.example.org.

The following DNS SRV records can be used to provide configuration hints for mail clients supporting RFC 6186:

_submission._tcp SRV 0 1 587 mail.example.org.
_imap._tcp SRV 2 1 143 imap.example.org.
_imaps._tcp SRV 1 1 993 imap.example.org.
_pop3._tcp SRV 4 1 110 pop3.example.org.
_pop3s._tcp SRV 3 1 995 pop3.example.org.

== automx ==

=== Installation ===

If you would like to support eMClient for OX App Suite please make sure that you are using a version after 1.1.1 or an earlier patched version which supports the DAV and OX services.

For manual installation please refer to the [https://automx.org/en/#download automx download instructions].

RPM packages for SUSE and RHEL flavours are provided by the [https://software.opensuse.org/package/automx Open Build Service]. Those packages are currently version 0.10.2 with the above patches applied and are working with Python 2.

=== Configuration ===

==== automx ====

Please find detailed documentation via '''man automx.conf''' and for more dynamic setups automx_script, automx_ldap and automx_sql.

/etc/automx.conf:

<nowiki>
[automx]
provider = example.org
domains = example.org, example.com
debug = no
logfile = /var/log/automx/automx.log

# Protect against DoS
memcache = 127.0.0.1:11211
memcache_ttl = 600
client_error_limit = 20
rate_limit_exception_networks = 127.0.0.0/8, ::1/128

# The DEFAULT section is always merged into each other section. Each section
# can overwrite settings done here.
[DEFAULT]
account_type = email
account_name = example Mail
account_name_short = example Mail

# If a domain is listed in the automx section, it may have its own section. If
# none is found here, the global section is used.
[global]
backend = static
action = settings

# EAS (mobilesync)
server_url = https://eas.example.org
server_name = example

# If you want to sign mobileconfig profiles, enable these options. Make sure
# that your webserver has proper privileges to read the key. The cert file
# must contain the server certificate and all intermediate certificates. You
# can simply concatenate these certificates.
#sign_mobileconfig = yes
#sign_cert = /path/to/cert
#sign_key = /path/to/key

smtp = yes
smtp_server = mail.example.org
smtp_port = 587
smtp_encryption = starttls
smtp_auth = plaintext
smtp_auth_identity = %s
smtp_refresh_ttl = 6
smtp_default = yes

imap = yes
imap_server = mail.example.org
imap_port = 993
imap_encryption = ssl
imap_auth = plaintext
imap_auth_identity = %s
imap_refresh_ttl = 6
pop = yes
pop_server = mail.example.org
pop_port = 995
pop_encryption = ssl
pop_auth = plaintext
pop_auth_identity = %s
pop_refresh_ttl = 6

carddav = yes
carddav_server = https://dav.example.org/
carddav_auth_identity = %s

caldav = yes
caldav_server = https://dav.example.org/
caldav_auth_identity = %s

ox = yes
ox_server = https://ox.example.org/
ox_auth_identity = %s

follow = imap_starttls

[imap_starttls]
backend = static_append

imap = yes
imap_server = mail.example.org
imap_port = 143
imap_encryption = starttls
imap_auth = plaintext
imap_auth_identity = %s
imap_refresh_ttl = 6
</nowiki>

==== Apache ====

e.g. /etc/{apache2,httpd}/conf.d/automx.conf:

<nowiki>
<IfModule mod_wsgi.c>
WSGIChunkedRequest On

WSGIScriptAliasMatch \
(?i)^/.+/(autodiscover|config-v1.1).xml \
/usr/lib/automx/automx_wsgi.py

WSGIScriptAlias \
/mobileconfig \
/usr/lib/automx/automx_wsgi.py

<Directory "/usr/lib/automx">
Require all granted
</Directory>
</IfModule>
</nowiki>

In case the iOS/MacOS web provisioning should be provided there should also be a /etc/{apache2,httpd}/conf.d/automx-web.conf:

<nowiki>
Alias /automx "/usr/share/automx/"

<Directory "/usr/share/automx">
Options Indexes MultiViews
Require all granted
</Directory>
</nowiki>

eMClient for OX App Suite has a special requirement to make the autoconfiguration experience nice and straightforward. To make it ask directly for a password instead of later in the setup process (where it requires a restart of the application to be fully functional) it is required to protect the autodiscover.xml via basic auth. In our scenario there is nothing to protect really so in this example we allow any credentials for access but still ask for some.

For this add the following section to /etc/{apache2,httpd}/conf.d/automx.conf:

<nowiki>
<Location "/autodiscover/autodiscover.xml">
AuthType Basic
AuthName "Restricted"
AuthBasicProvider anon
Anonymous_NoUserID off
Anonymous_MustGiveEmail off
Anonymous_VerifyEmail off
Anonymous_LogEmail off
Anonymous *
Require valid-user
</Location>
</nowiki>

== Related links ==

[[Caldav_carddav_Bundles#Autodiscovery|DAV autodiscovery]]

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

My.cnf

2019-12-05T22:16:34Z

WolfgangRosenauer:

== Introduction ==

This page lists some performance tuning parameters which we recommend for tuning MySQL database services used for Open-Xchange installations.

We cannot guarantee this is an exhaustive list of required settings. So treat this list of tunings as probably required, but not necessarily sufficient settings for optimal MySQL performance.

Furthermore, as MySQL changes over time, settings which have been correct as of the time of writing may become incorrect later.

However, this list of settings is the result of internal performance testing and real world customer feedback, so it should be valid to some extent.

In the end, proper configuration of the database service for performance, but also consistency, durability and high availability is in the responsibility of the customer.

=== Performance items ===

* You should adjust the <code>innodb_buffer_pool_size</code> parameter for reasonable memory usage. Our DB sizing is mainly memory-driven and this is where most of the memory goes. Our standard DB machine sizing assumption is 32 GB if MySQL dedicated memory on a 48 GB total memory machine. On such a machine, you would configure 32 GB for the innodb_buffer_pool size, being aware that MySQL does also require memory for other things, in particular there are some also per-connection related memory spendings, which can become substantial if you allow for a lot of maximum concurrent connections. Please watch your memory configuration carefully, use monitoring and tools like mysqltuner.pl.

* On bigger installations you should use <code>innodb_file_per_table = 1</code>, which is creating single files instead of one big blob. If you change this parameter after the database initialization you have to recreate (like dump/drop and re-import) the tables.

* It can help to put different parts of the mysql datadir (iblog, ibdata) on different filesystems / storage devices. This depends on your infrastructure. Settings herefore are <code>datadir</code>, <code>innodb_data_home_dir</code>, <code>innodb_log_group_home_dir</code>.

* If your storage is fast (handle a lot of IOPS), you may want to adjust the <code>innodb_io_capacity</code> setting, which defines a limit for the IOPS MySQL will create. The default is 200, which is sensible for single spindle disks. But if you have storage appliances with a lot of fast SAS drives, or even SSDs, this limit can be increased greatly.

=== Functional items ===

* Query cache is to be switched off; as we found in our own benchmarks and as backed up by upstreams, this hurts performance in load situations with high concurrency. [https://dev.mysql.com/doc/refman/5.7/en/query-cache.htm The query cache is deprecated as of MySQL 5.7.20, and is removed in MySQL 8.0], so we recommend also to switch that off.
* Starting with App Suite 7.10.0, <code>character_set_server</code> must be set to <code>utf8mb4</code> and <code>collation_server</code> to <code>utf8mb4_general_ci</code>. For older versions it must be <code>utf8</code> and <code>utf8_general_ci</code> respectively.
* Starting with MySQL 5.7 <code>innodb_strict_mode</code> must be disabled.
* Starting with MySQL 5.6 and MariaDB 10.1 <code>sql_mode</code> must be configured according to belows matrix.

==== SQL mode matrix ====

The default for the <code>sql_mode</code> setting changes regularly with MariaDB and MySQL releases and is not even consistent anymore between the two derivates. SQL modes affect how data and queries are handled at runtime. Enabling strict modes might lead to errors in terms of failing queries or even update tasks. We strongly recommend the following configuration to avoid according runtime errors:

{| class="wikitable"
|-
! scope="col"| sql_mode
! scope="col"| App Suite 7.8.4
! scope="col"| App Suite 7.10.x
|-
! scope="row"| MySQL 5.6
| <code>NO_ENGINE_SUBSTITUTION</code>
| <code>NO_ENGINE_SUBSTITUTION</code>
|-
! scope="row"| MySQL 5.7
| <code>NO_AUTO_CREATE_USER,NO_ENGINE_SUBSTITUTION</code>
| <code>NO_AUTO_CREATE_USER,NO_ENGINE_SUBSTITUTION,ONLY_FULL_GROUP_BY</code>
|-
! scope="row"| MariaDB >= 10.1
| <code>NO_AUTO_CREATE_USER,NO_ENGINE_SUBSTITUTION</code>
| <code>NO_AUTO_CREATE_USER,NO_ENGINE_SUBSTITUTION</code>
|-
|}

=== Sample config files ===

For easy deployment we recommend not to edit existing the existing my.cnf file, rather assume the distro provides sane settings for most of the items and override items where needed.

As in MySQL there is a [https://dev.mysql.com/doc/refman/5.7/en/option-files.html last instance wins] semantic in options file parsing, we propose to create a custom include directory "ox.conf.d", put our custom config files therein, and include this directory as latest directory in /etc/mysql/my.cnf.

To put in that directory, we have one main tuning file called tunings.cnf, one galera-related file if galera is in use, and one more galera host-specific file which contains per-host settings if using galera (separate in a file of its own for easier configuration management).

So, start with adding to the existing my.cnf at the very bottom:

!includedir /etc/mysql/ox.conf.d/

Create that directory and put in there the generic ox tunings file /etc/mysql/ox.conf.d/tunings.cnf:

[mysqld]
bind-address = *

#innodb_use_native_aio = 0

table_open_cache = 3072
table_definition_cache = 4096
max_heap_table_size = 64M
tmp_table_size = 64M
max_connections = 505
max_user_connections = 500
max_allowed_packet = 16M
thread_cache_size = 32
query_cache_size = 0
query_cache_type = 0
innodb_buffer_pool_size = 32G
# the default value in MySQL 5.6.6 and higher is 8 when innodb_buffer_pool_size is greater than or equal to 1GB. Otherwise, the default is 1.
innodb_buffer_pool_instances = 32
innodb_data_file_path = ibdata1:128M:autoextend
innodb_file_per_table = 1
# innodb_log_file_size should be 25% of the innodb_buffer_pool_size
innodb_log_file_size = 4GB
# default and recommended value is 2
innodb_log_files_in_group = 2
# adjust according to your storage
#innodb_io_capacity = 1000

# we are unsure about this setting. Newer versions of MariaDB seem to be fine with low (=1) settings for this value.
# Traditionally we encountered values up to 4x the number of cores.
# Default seems to be number of cores, so let's stick the default
# In the end, we need to leave this setting up to you: if you dont get full cpu utilization in cpu-bound situations, this might be a setting to increase.
#thread_pool_size = 32

binlog_cache_size = 1M
sync_binlog = 8
binlog_format = row

character_set_server = utf8mb4
collation_server = utf8mb4_general_ci

# This was default_table_type previous to MySQL 5.5
default_storage_engine = InnoDB

innodb_autoinc_lock_mode = 2

# keep until 5.6, deprecated later
innodb_locks_unsafe_for_binlog = 1

# we found this has huge impact on (galera) performance
# default (consistent) setting of 1 greatly severs performance
# in galera (or async master-slave) deployments, you might be ok with setting this to 0 or 2,
# assuming our consistency / availability comes from replication / other cluster nodes
innodb_flush_log_at_trx_commit = 0

# for performance testing systems, to not use excessive disk space
#expire_logs_days = 1

# MySQL 5.7.7 has changed the default to 1. Disable it explicitly to prevent from errors based on invalid data stored by former App Suite or MySQL versions.
innodb_strict_mode = 0

# The following value refers to App Suite 7.10 on top of MySQL 5.7. For other combinations see the sql mode matrix at http://oxpedia.org/wiki/index.php?title=My.cnf.
sql_mode = NO_ENGINE_SUBSTITUTION,NO_AUTO_CREATE_USER,ONLY_FULL_GROUP_BY

If using galera, use the following galera configuration file <code>/etc/mysql/ox.conf.d/wsrep.cnf</code>. See the comments in that file for values to be adjusted.

[mysqld]
# adjust for your distros SO location
wsrep_provider=/usr/lib/libgalera_smm.so

# this is the big winner and enables us to switch off OX's replication monitor
wsrep_sync_wait=1

# pick a unique cluster name
wsrep_cluster_name=devcluster
# adjust for your IPs / hostnames
wsrep_cluster_address=gcomm://10.20.29.68,10.20.29.69,10.20.29.70

# put this in host.cnf
#wsrep_node_name=...
#wsrep_node_address=...

# For some MariaDB versions, xtrabackup-v2 no longer works, instead use "mariabackup"
# (needs to be installed separately, e.g. via the mariadb-backup-10.2 package)
# see upstream documentation for details:
# https://mariadb.com/kb/en/library/getting-started-with-mariadb-galera-cluster/#xtrabackup
#
# wsrep_sst_method=mariabackup
wsrep_sst_method=xtrabackup-v2

# wsrep_sst_auth if of format username:password
# pick whatever you configured on the donor node
wsrep_sst_auth=sstuser:...

# galera-specific tunings
wsrep_slave_threads = 32

# finally, enable wsrep: required for some MariaDB versions
wsrep_on=ON -- Enable wsrep replication (MariaDB starting 10.1.1)

Galera-related host-specific settings go in /etc/mysql/ox.conf.d/host.cnf:

[mysqld]
# the nodes hostname
wsrep_node_name=...
# and the IP of the wsrep relevant interface, if multiple
wsrep_node_address=10.20.29.68

AppSuite:Syslog Configuration

2019-11-22T16:35:54Z

WolfgangRosenauer:

=Open-Xchange Syslog Configuration=

This article is valid up to version '''7.4.1'''
For current information please check [[AppSuite:OX_Logging]]

==Abstract==
Open-Xchange provides the OSGi package ''open-xchange-log4j'' to enable remote logging via syslog. This is useful for distributed setups or if a logging strategy is already present at the environments the servers are running. If you choose syslog to be the logging mechanism, the syslog service needs some configuration to accept remote logging, even if the service is running on localhost.

The syslog remote logging will open port 514/udp, so don't forget to firewall it properly if it's a security risk for you. The default logging facility of Open-Xchange is defined at the ''/opt/open-xchange/etc/log4j.xml'' file. For more granular log filtering this facility can be changed. Please refer to the rsyslog, syslog and syslog-ng documentation for further information.

{{InstallPlugin|pluginname=open-xchange-log4j|toplevel=products|sopath=appsuite/stable/backend|version=App Suite}}

== Configuration ==
Please note, there are numerous syslog daemons available and the configuration may also differ between Linux distributions. To make open-xchange-log4j running in collaboration with the syslog
daemon of your choice, you have to enable logging via UDP protocol and listening port 514. Please
read for details the documentation of your running syslog service.
=== For RHEL, CentOS and Debian ===

The parameter configuration is done in a configuration file at ''/etc/rsyslog.conf'' in case you are running the popular rsyslog daemon.

# provides UDP syslog reception
$ModLoad imudp
$UDPServerRun 514

If you like to enable remote logging it is might be needed to enable this by "/etc/default/rsyslog" configuration file.

# Options for rsyslogd
# -m 0 disables 'MARK' messages (deprecated, only used in compat mode < 3)
# -r enables logging from remote machines (deprecated, only used in compat mode < 3)
# -x disables DNS lookups on messages received with -r
# -c compatibility mode
# See rsyslogd(8) for more details
RSYSLOGD_OPTIONS="-c4 -r"

'''Note:''' On a recent Debian version, you might have to set compat mode to 0-2 in order for -r to work

Then restart the rsyslog service to enable remote logging.
$ /etc/init.d/rsyslog restart

By default, all Open-Xchange log messages are put to ''/var/log/syslog''.

===For SUSE Linux Enterprise Server 11 ===
SLES11 comes up with syslog-ng, modify the configuration at ''/etc/syslog-ng/syslog-ng.conf'':

source src {
#
# include internal syslog-ng messages
# note: the internal() soure is required!
#
internal();

#
# the default log socket for local logging:
#
unix-dgram("/dev/log");

#
# uncomment to process log messages from network:
#
udp(ip("0.0.0.0") port(514));
};

Uncomment the last statement of the src definition and restart the syslog service to enable logging.
$ /etc/init.d/syslog restart

By default, all Open-Xchange log messages are put to ''/var/log/messages''.

[[Category: OX6]]

Tokenlogin form

2019-08-12T10:59:25Z

WolfgangRosenauer: /* Example */

= Interactive token login form =

== Example ==
<syntaxhighlight lang='html4strict'>
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
<html>
<head>
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
<meta http-equiv="cache-control" content="no-cache">
<title>Login</title>
<script type="text/javascript">
function uuid() {
function hex(len, x) {
if (x === undefined) x = Math.random();
var s = new Array(len);
for (var i = 0; i < len; i++) {
x *= 16;
var digit = x & 15;
s[i] = digit + (digit < 10 ? 48 : 87); // '0' and 'a' - 10
}
return String.fromCharCode.apply(String, s);
}
return [hex(8), "-", hex(4), "-4", hex(3), "-", hex(4, 0.5 + Math.random() / 4), "-", hex(12)].join("");
}

window.addEventListener("load", function () {
function sendData() {
var XHR = new XMLHttpRequest();
var target = "$BASEURL_TO_OX";

// Bind the FormData object and the form element
var FD = new FormData(form);
// enhance with clientToken
static_uuid = uuid();
FD.append('clientToken', static_uuid);
FD.append('jsonResponse', true);

// Define what happens on successful data submission
XHR.addEventListener("load", function(event) {
// successful login; now redirect into the session
var response=JSON.parse(event.target.responseText);
// check for errors
if (response.error || !response.url) {
error_message.innerHTML = response.error;
} else {
// finally point to the target
window.location.replace(target + response.url + "&clientToken=" + static_uuid);
}
});

// Define what happens in case of error
XHR.addEventListener("error", function(event) {
alert('Oops! Something went wrong.');
});

// Set up our request
XHR.open("POST", target + "/ajax/login?action=tokenLogin&authId=" + uuid());

// The data sent is what the user provided in the form
XHR.send(new URLSearchParams(FD));
}

// Access the form element...
var form = document.getElementById("myForm");
var error_message = document.getElementById("error");

// ...and take over its submit event.
form.addEventListener("submit", function (event) {
event.preventDefault();

sendData();
});
});
</script>
</head>

<body>
<form id='myForm'>
<label for="login">Username: </label>
<input type="text" name="login" id="login"><br>
<label for="password">Password: </label>
<input type="password" name="password" id="password"><br>
<input type="submit" value="Login">

<input type="hidden" name="autologin" value="false">
<input type="hidden" name="client" value="open-xchange-appsuite">
<input type="hidden" name="version" value="Sample Loginpage">
<input type="hidden" name="uiWebPath" value="/appsuite/">
</form>
<div id='error' />
</body>
</html>
</syntaxhighlight>

Dovecot Mailpush

2019-07-24T20:32:14Z

WolfgangRosenauer:

'''Please find the up-to-date version of this article [https://doc.dovecot.org/plugin-settings/push_notification/ here]'''

Tokenlogin form

2019-07-16T07:38:32Z

WolfgangRosenauer: Created page with "= Interactive token login form = == Example == <syntaxhighlight lang='html4strict'> <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">..."

= Interactive token login form =

== Example ==
<syntaxhighlight lang='html4strict'>
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
<html>
<head>
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
<meta http-equiv="cache-control" content="no-cache">
<title>Login</title>
<script type="text/javascript">
function uuid() {
function hex(len, x) {
if (x === undefined) x = Math.random();
var s = new Array(len);
for (var i = 0; i < len; i++) {
x *= 16;
var digit = x & 15;
s[i] = digit + (digit < 10 ? 48 : 87); // '0' and 'a' - 10
}
return String.fromCharCode.apply(String, s);
}
return [hex(8), "-", hex(4), "-4", hex(3), "-", hex(4, 0.5 + Math.random() / 4), "-", hex(12)].join("");
}

window.addEventListener("load", function () {
function sendData() {
var XHR = new XMLHttpRequest();
var target = "$BASEURL_TO_OX";

// Bind the FormData object and the form element
var FD = new FormData(form);
// enhance with clientToken
static_uuid = uuid();
FD.append('clientToken', static_uuid);
FD.append('jsonResponse', true);

// Define what happens on successful data submission
XHR.addEventListener("load", function(event) {
// successful login; now redirect into the session
var response=JSON.parse(event.target.responseText);
// check for errors
if (response.error || !response.url) {
error_message.innerHTML = response.error;
} else {
// finally point to the target
window.location.replace(target + response.url + "&clientToken=" + static_uuid);
}
});

// Define what happens in case of error
XHR.addEventListener("error", function(event) {
alert('Oops! Something went wrong.');
});

// Set up our request
XHR.open("POST", target + "/ajax/login?action=tokenLogin&authId=" + uuid());

// The data sent is what the user provided in the form
XHR.send(new URLSearchParams(FD));
}

// Access the form element...
var form = document.getElementById("myForm");
var error_message = document.getElementById("error");

// ...and take over its submit event.
form.addEventListener("submit", function (event) {
event.preventDefault();

sendData();
});
});
</script>
</head>

<body>
<form id='myForm'>
<label for="login">Username: </label>
<input type="text" name="login" id="login"><br>
<label for="password">Password: </label>
<input type="password" name="password" id="password"><br>
<input type="submit" value="Login">
<input type="hidden" name="autologin" value="true">
<input type="hidden" name="client" value="open-xchange-appsuite">
<input type="hidden" name="version" value="Sample Loginpage">
<input type="hidden" name="uiWebPath" value="/appsuite/">
</form>
<div id='error' />
</body>
</html>
</syntaxhighlight>

Login variations

2019-07-16T07:33:30Z

WolfgangRosenauer: /* Token Login */

<div class="title">Login variations</div>

'''Introduction:''' This paper describes Open-Xchanges's authentication and session handling. It gives an overview of all available mechanisms and on how to safely pass on sessions from external applications to the Open-Xchange Server (Single Sign On, SSO).

== Overview ==
The Open-Xchange Server web front-end is implemented in AJAX (Asynchronous JavaScript and XML). Thus the complete user interface (GUI) is running in a browser. Opposed to standard web applications there are no HTML pages generated and delivered by the browser.

The complete user front-end is rendered and displayed in the browser. Based on HTTP/S the data are exchanged with the server via JavaScript Object Notation (JSON). That means it is not possible to simulate front-end actions via HTTP/S request by simulating respectively formatted GET/POST calls. Instead, another abstraction is taking place that exclusively transfers data from GUI to server and vice versa.

The Open-Xchange Server includes a session daemon (sessiond) that keeps the current data of a logged in user. If successfully authenticated the information kept in the session are sufficient for accessing the Open-Xchange Server.

==Access to IMAP Back-End services==
To access external E-Mail systems (IMAP/SMTP) the Open-Xchange Server has to know the credentials of the current user for the system, i. e. the session object has to keep the respective password for the access in plain text. That means authenticating via SessionIDs alone is not sufficient. Authentication always has to take place by entering the username and password.

(There are two exceptions: either if one master password is used for all IMAP accounts, or if a very special implementation of MAL is used, which does not need a password.)

==Basic Implementation Rules==
* It must not be possible to get a valid session by e. g. guessing a SessionID. This is especially important when being passed on by an external system
* A session must not be verified by a single SessionID only, but has to compare at least two different data types, this is what the Session-Secret is for
* Both SessionID and Session-Secret must never be passed from the Open-Xchange server to the client in the same request. This ensures, that potential issues in the stack between the client and Open-Xchange (proxies, caches, loadbalancer, Apache, …) can not lead to wrong sessions
* To enhance security Session-Secret and SessionID are transferred as different data types. The Session-Secret will always be transferred as a cookie, the SessionID will be transferred as URL parameter if persistent auto-login is not activated for this session.
* It must never be possible to have conflicting session information per client (multiple cookies) within the same cookie store
* If any error in the session handling is detected, the relevant request is discarded and logged. It is not tried to fix the issue
* In memory data (SessionID) of the browser GUI must never be changed during a valid session
* All relevant information regarding session management must always be written to the relevant logfiles
* The whole mechanism is only secure when being used via encrypted connection
* ATTENTION: If persistent autologin is activated for the system and a user decided to use it, all information necessary to access the Open-Xchange server is stored within the browsers cookie store.  This means, that the security of the whole system depends on the level of security of the browsers cookie store

== Authentication and Session Tokens ==
Following tokens are used for the session management:

=== SessionID ===
The SessionID is used to identify every session. It is a UUID, generated by the backend via default Java UUID implementation. It is written into the OX logfiles for every log message. When no auto-login is used for the session, then the SessionID is transferred as an URL parameter. If auto-login is activated, then the SessionID is transferred as a cookie.

=== Session-Secret ===
The Session-Secret is used to verify every session. It is a UUID, generated by the backend via default Java UUID implementation. Only accesses, where the Session-Secret matches with the one stored in SessionD for the given SessionID are valid. Mismatches lead to immediate session termination.

=== Public Session ===
The public Session is used as a replacement for the SessionID. It is a UUID, generated by the backend via default Java UUID implementation. The Public Session is transferred as a cookie named <tt>open-xchange-public-session-uuid</tt>. Using the Public Session is limited to some non critical requests. By using this cookie instead of a request parameter, the browser is able to cache the response of special requests (e.g. contact images).

=== Random ===
The Random-Token is a one time token with a limited lifetime, which is used to initiate sessions through 3rd party applications or websites. It is a UUID, generated by the backend via default Java UUID implementation. This token is deprecated and subject to change.

=== Cookie Handling ===
In several situations, cookies are used to store and transfer the session tokens. The following rules for cookie creation and storage apply.

==== Only one cookie per client session type ====
It must never happen, that the same client has more than one session associated with an Open-Xchange server. Therefore the cookies need to have the same name. If a new cookie is set to the browser, the original one will be overwritten. With the next client access either the SessionID or the Session-Secret do not match anymore and the invalid session is terminated.
Multiple clients with same cookie store.

On the other hand it may happen, that several clients use the same cookie store. E.g. a standard browser GUI session and a browser plugin session. Therefore the cookie name needs to contain informations about the client.

==== Naming of cookies ====
The cookies are named following this schema:

open-xchange-session-<<name token>>=<<SessionID>>
open-xchange-secret-<<name token>>=<<Session-Secret>>

Where <<name token>> is generated from configurable data associated with the client. It is a md5-hash build from the client-id and the User-Agent is used to identify the client. Other parameters can be added through a configuration file. If a request is performed by a browser with an invalid hash the corresponding cookies and session are invalidated.

====Lifetime of cookies====
Normally, cookies are session cookies, which get invalid/deleted when the browser is shut down.
Using the persistent auto-login, the cookies are persistent cookies, with a configurable default. The default lifetime is one week.

====Security of a cookie====
Cookies can be configured in different ways to be secure. For further information visit [[OXSessionSecurityFeatures]]

All cookies get deleted when a logout is performed.

==IP Check==
Per default an IP check is activated to terminate every session immediately, if the IP address of the client changes during the session lifetime. This check is not processed, when a session is reactivated following the persistent auto-login process.
There are several configuration options to enable, disable the IP Check and to define IP Ranges to omit the check and/or accept recurring connections from within these ranges. For further information on the configuration see [https://oxpedia.org/wiki/index.php?title=AppSuite:Configuration_properties_7.8.2 configuration properties].

==Access via web browser with user credentials==
When directly logging in to the system by entering the credentials, following steps will be done to authenticate the user or verify the validity of the session after the authentication:

# The browser sends initial request to the Open-Xchange server. The client represented by the application:
## is not authenticated yet
## has no cookie
## has no session ID.
# Open-Xchange server sends an AJAX application to browser. The application is loaded into the browser and no data is exchanged between server and application.
# The AJAX application then will try to do an auto-login. Because the application has no knowledge of the cookies that may already be stored in the browser it will try to login the client. For further information on auto-login see [[OXSessionAutologin]]. With the precondition form 1. the auto-login try will be denied.
# The user enters username and password in the front-end.
# The username and password are sent to the server via JSON (SSL). If the user activated persistent auto-login on the login screen, this information is passed with the same request.
# The server authenticates the client and sends following data back to the browser via JSON (the data are saved in the session object):
## Session ID via JSON object
## (Optional) Random token for initial login via JSON object. For the random token to be send the server needs to be configured(see login.properties – com.openexchange.axaj.login.randomToken). CAUTION! The random token is deprecated and should no longer be used!
## Cookie with JSESSIONID. The JSESSIONID is set for loadbalancing to the browser
## Cookie containing the session secret. If persistent auto-login is selected, the cookie is configured with the relevant type and validity.
## Cookie containing the public identifier.
# The AJAX front-end saves the session ID in its memory. (Optional) Ignores the random token.
# If the persistent auto-login is enabled the AJAX front-end will send a store request. If no error occurs a configured cookie with the relevant type and validity containing the session ID is set to the browser.
# The AJAX front-end sends initial data request via JSON to the Open-Xchange server and provides the session ID as an URL parameter. The secret is send along as a cookie.
# The Open-Xchange server processes this data request and compares:
## Session ID for validity in sessiond
## Session-Secret from the cookie for validity with session
# The request is correctly authenticated and is answered by the server.
# (Optional) Random token is discarded after timeout from sessiond.
# Repeat 9. - 11. until end of session

If the user does not use the persistent auto-login, the session is only valid as long as the browser is opened. It will be cleared either on logout, on browser termination or with any occurring error.

For any details on the requests and responses please visit the [https://documentation.open-xchange.com/latest/middleware/http-api-gen/#_login_resource Technical Documentation]

==Access via web browser after authentication with external system==
The goal is to authenticate in the Open-Xchange system through an external system and to safely pass on the received session data to a browser. To do so the external system has to know the user data (username, password) in plain text.

The process is based on the session initialization in the Open-Xchange Server via the JSON interface and on passing on the received data to a browser. The browser finally initializes the session with an additional random token that is only valid for one single access.
# External tool sends initial JSON request directly to Open-Xchange Server
## not authenticated yet
## no cookie
## no SessionID
# The Open-Xchange Server authenticates and delivers back following data to external tool via JSON (all the data are stored in the session object in sessiond)
## SessionID in JSON object
## Random token for initial login via JSON object (required for SSO login)
## Cookie with Session-Secret is not set
# External tool starts browser with special URL, that contains at least following data:
## Random token for initial login
# Open-Xchange Server compares:
## Random token for validity in sessiond
# Open-Xchange Server sends to the browser:
## SessionID in JSON object
## Cookie with JSESSIONID for loadbalancing is set to the browser
# The second part of the tokens is delivered in a separate request
## Cookie with Session-Secret is set to the browser If persistent auto-login is selected, the cookie is configured with the relevant type and validity
# Open-Xchange removes random token from sessiond.

Then the process continues as described in the section above. The session is then verified with the SessionID and Session-Secret.

==Token Login==
A dedicated login action (tokenLogin) is used to acquire a server token bound to a given client token. The combination of these tokens allows another client to gain a valid session. This Login is intended to replace the random token login. With this method there is no request or response containing all necessary information to create a valid session.

An example how to use this method to implement an external interactive login page using XHR can be found [[Tokenlogin_form|here]]

==Form Login==
The Form Login provides a simple way of accessing the web frontend just by using standard HTML forms. The response contains a redirect link to the Web-UI. See [[OXSessionFormLogin]] for details.

==Redeem Token Login==
With a valid session it is possible to acquire a secret. Using this secret another system is able to generate a valid session.
This session may also contain the users password (configurable). The system in question needs to be registered at the server and has to identify itself with a key configured at the open-xchange server. This is only for internal communication and by default no keys are available.

== Authentication against other services ==
OX6 and AppSuite allow authentication using other services, too. This is not in the scope of this article. The Services team is available to build plugins for such services. Some standard ones are already implemented, see the following articles for that:
* [[Authentication IMAP Plugin description]]

For further information on the session see [[OXSessionLifecycle]].

For further information on HTTP API visit the [https://documentation.open-xchange.com/latest/middleware/http-api-gen/#_login_resource Technical Documentation]

[[Category:Server]]
[[Category:OX6]]
[[Category:AppSuite]]
[[Category:Auth]]