AppSuite:OX Drive

OX Drive

Description

OX Drive provides file and folder synchronization across devices. It does this in the simple way possible for the end user and is fully optimized for each device type.

Open-Xchange wants to enable end customers to synchronize data. In OX App Suite, Open-Xchange provides a cloud storage called OX Drive. End customers should be able to synchronize Windows, Mac OS, Android, and iOS devices.

This article explains how to set up the server-side components for OX Drive, as well as details about the client setup.

Availability

OX Drive is a combination of two components:

• OX Drive in OX App Suite
• OX Drive Clients (optional native client components for synchronization)

OX Drive is available for the following native clients:

• OX Drive for Windows
• OX Drive for Mac OS
• OX Drive for iOS
• OX Drive for Android

Requirements

Requirement	System / Platform	Tested Devices
OX App Suite	OX App Suite v7.4.2
OX Drive for Windows	Latest Versions of Windows 7, Windows 8 (no support of Mac OS X clients with emulators and Windows RT)
OX Drive for Mac OS	Mac OS X 10.8 (Mountain Lion), Mac OS X 10.9 (Mavericks)
OX Drive for iOS	Apple iOS 6, Apple iOS 7	Apple iPhone 5, Apple iPhone 5s
OX Drive for Android	Smartphone on Android Jelly Bean (4.1 - 4.2), Tablets on Android Jelly Bean (4.1 - 4.2)	Samsung Galaxy S3 mini, Samsung Galaxy S4, Nexus 4

The key features of OX Drive

• Native Apps for Windows, Mac OS, iOS and Android
• Easy and attractive upsell properties (e.g. Upsell based on Quota limitations)
• Clients are specially designed for the devices they run on taking into account limitations such as battery life, screen limitations, bandwidth etc.
• Controlled synchronization of files across devices
• Storage management (e.g. quota control, upload limits)
• Connection type recognition and adaptation (e.g. Wi-Fi, cell network)

Server-side Installation and Configuration

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

Prerequisites

• Open-Xchange Server v7.4.2 and above (open-xchange-core)
• Grizzly HTTP connector (open-xchange-grizzly), see AppSuite:Grizzly for details, with Comet support enabled in grizzly.properties
• Valid Push-Certificates / API keys for cloud-based notifications, see configuration below
• Enabled Hazelcast for inter-OX-communication, see AppSuite:Running_a_cluster for details

Available packages

Open-Xchange Drive is available with the following backend packages:

• open-xchange-drive - The main server components for OX Drive
• open-xchange-drive-comet - Provides the Push interface via long-polling for the desktop clients
• open-xchange-updater-drive - Adds the OX Drive application to the Windows desktop auto-updater
• open-xchange-appsuite-help-drive-* - Online help in various languages for the OX Drive applications

Install the above packages as usual.

Install on OX App Suite

Debian GNU/Linux 11.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/DebianBullseye/ /
# 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/DebianBullseye/ /

and run

$ apt-get update
$ apt-get install open-xchange-drive open-xchange-drive-comet

Debian GNU/Linux 12.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/DebianBookworm/ /
# 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/DebianBookworm/ /

and run

$ apt-get update
$ apt-get install open-xchange-drive open-xchange-drive-comet

Configuration

The following gives an overview about the most important settings to enable file synchronization via OX Drive, especially when it comes to real-time Push notifications for the client applications.

General

All settings regarding the OX Drive backend component are located in the configuration file drive.properties. The default configuration should be sufficient for a basic "up-and-running" setup (with the exception of defining the Push certificates and API keys for cloud-based client notifications, see next chapters). Please refer to the inline documentation of the configuration file for more advanced options.

Push via Google Cloud Messaging (GCM)

The OX Drive application for Android devices is able to receive Push notifications from the Open-Xchange Server via Google Cloud Messaging (GCM). To issue those Push messages, the backend needs to be provided with a suitable API key for the corresponding Android client application. This API key (a String) is specified in the drive.properties file:

# Specifies the API key of the server application. Required.
com.openexchange.drive.events.gcm.key=

Doing so, Push via GCM can be enabled via:

# Enables or disables push event notifications to clients using the Google
# Cloud Messaging (GCM) service. This requires a valid configuration for the 
# GCM API key, see options below. Defaults to "false". 
com.openexchange.drive.events.gcm.enabled=true

Depending on the used Android client application ("vanilla" or customized versions), different API keys are needed. Please refer to your Open-Xchange contact for details.

Push via Apple Push Notification service (APNs)

The OX Drive application for iOS and Mac OS devices is able to receive Push notifications from the Open-Xchange Server via Push via Apple Push Notification service (APNs). To issue those Push messages, the backend needs to be provided with a suitable keystore container file (PKCS #12) containing the APNs certificate and keys. Note that the Mac OS desktop client and the iOS mobile client are served with separately with different certificates, so that both needs to be configured independantly in the configuration file. The following only shows the setup for iOS. First, the path to the PKCS #12 container file needs to be specified at:

# Specifies the path to the local keystore file (PKCS #12) containing the APNS 
# certificate and keys for the iOS application, e.g. 
# "/opt/open-xchange/etc/drive-apns.p12". Required if 
# "com.openexchange.drive.events.apn.enabled" is "true".
com.openexchange.drive.events.apn.ios.keystore=

This file is opened by the backend using the password as supplied via:

# Specifies the password used when creating the referenced keystore containing
# the certificate of the iOS application. Note that blank or null passwords 
# are in violation of the PKCS #12 specifications. Required if 
# "com.openexchange.drive.events.apn.enabled" is "true".
com.openexchange.drive.events.apn.ios.password=

Configuration also allows to swith between development and production environments, however, this setting should be true normally:

# Indicates which APNS service is used when sending push notifications to iOS
# devices. A value of "true" will use the production service, a value of 
# "false" the sandbox service. Defaults to "true".
com.openexchange.drive.events.apn.ios.production=true

The OX backend contacts the APNs servers from time to time to get informed about clients no longer reachable clients where the applications was uninstalled. The interval can be defined with the following setting:

# Configures the interval between queries to the APN feedback service for the
# subscribed iOS devices. The value can be defined using units of measurement: 
# "D" (=days), "W" (=weeks) and "H" (=hours). Defaults to "1D" (one day). 
# Leaving this parameter empty disables the feedback queries on this node. 
# Since each received feedback is processed cluster-wide, only one node in the 
# cluster should be enabled here. 
com.openexchange.drive.events.apn.ios.feedbackQueryInterval=1D

Please note that if you have multiple backend nodes in the cluster, it's recommended that only one node is configured to contact the feedback query service. Finally, Push notifications via APN for iOS can be enabled via:

# Enables or disables push event notifications to clients using the Apple Push
# Notification service (APNS) for iOS devices. This requires a valid 
# configuration for the APNS certificate and keys, see options below. 
# Defaults to "false". 
com.openexchange.drive.events.apn.ios.enabled=false

As stated above, configuration for Push notifications via APN for the Mac OS desktop application is configured similarly, the relevant options are prefixed with com.openexchange.drive.events.apn.macos. Depending on the used iOS and Mac OS client applications for your Server ("vanilla" or customized versions), different PKCS #12 container files and passwords are needed. Please refer to your Open-Xchange contact for details.

Further Configuration

• The backend component of OX Drive supplies the clients with various hyperlinks, e.g. deep-links to files and folders in the groupware webinterface or an URL to the online help. In order to point to the suitable web interface, please ensure that the correct UI web path is configured via com.openexchange.UIWebPath located in server.properties.
• As already mentioned above, the backend relies on the Comet component of the Grizzly http connector for sending push notifications to the desktop clients. Therefore, com.openexchange.http.grizzly.hasCometEnabled needs to be set to true in grizzly.properties.

Obtaining Push keys

If you do have a valid contract for using OX Drive and are going to use the OX labeled clients you can retrieve a GCM and APN push key from OX.

OX will need the following informations to create a GCM push key and a APN push certificate:

GCM (Android)

• The IP(s) or subnet of the server(s) which will send push notifications to the GCM server

APN (iOS and Mac)

• One valid certificate signing request (CSR) for each client, iOS and Mac OS. A single CSR can not be used for both.

Generating a CSR for APN

To manually generate a Certificate, you need a Certificate Signing Request (CSR) file from your Mac. To create a CSR file, follow the instructions below to create one using Keychain Access.

Create a CSR file.

1. In the Applications folder on your Mac, open the Utilities folder and launch Keychain Access.
2. Within the Keychain Access drop down menu, select Keychain Access > Certificate Assistant > Request a Certificate from a Certificate Authority.
3. In the Certificate Information window, enter the following information:
   1. In the User Email Address field, enter your email address.
   2. In the Common Name field, create a name for your private key (e.g., Company Foo Key).
   3. The CA Email Address field should be left empty.
   4. In the "Request is" group, select the "Saved to disk" option.
4. Click Continue within Keychain Access to complete the CSR generating process.

The CSR file should then be sent to your Prof. Services contact. You will then receive a certificate file from OX. The certificate must then be exported with your private key that was used to create the CSR to a P12 container.

Generate a P12

1. Import the certificate to your Keychain
2. Select the certificate and your private key > export both as P12 container to disk

The P12 should be kept securely on your server.

Enabling OX Drive for Users

OX Drive is enabled for all users that have the capability com.openexchange.capability.drive. You can enable or disable this cabaility globally with the following setting in the drive.properties configuration file:

# Enables or disables the "drive" module capability globally.
com.openexchange.capability.drive=true

More details about capabilities can be found at AppSuite:Capabilities. Furthermore, this capability can be defined in a more granular way using the Config Cascade as described at ConfigCascade.

Installation of the Clients

Installation of Mac OS X Desktop Client

The OX Drive for Mac OS X will be provided via the Apple App Store.

Installation of Windows Desktop Client

The OX Drive for Windows will be provided direct at the OX App Suite via the OX Updater.

Redhat Enterprise Linux 6 or CentOS 6

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

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

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


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

$ yum install open-xchange-updater-drive open-xchange-drive open-xchange-drive-comet

Debian GNU/Linux 6.0

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

deb https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/appsuite/stable/updater/DebianSqueeze /
deb https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/appsuite/stable/usm/updates/DebianSqueeze /

deb https://software.open-xchange.com/products/appsuite/stable/usm/DebianSqueeze /

$ apt-get update
$ apt-get install open-xchange-updater-drive open-xchange-drive open-xchange-drive-comet

Debian GNU/Linux 7.0

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

deb https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/appsuite/stable/updater/DebianWheezy /
deb https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/appsuite/stable/usm/updates/DebianWheezy /

deb https://software.open-xchange.com/products/appsuite/stable/usm/DebianWheezy /

$ apt-get update
$ apt-get install open-xchange-updater-drive open-xchange-drive open-xchange-drive-comet

SUSE Linux Enterprise Server 11

$ zypper ar https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/appsuite/stable/updater/SLES11 updater
$ zypper ar https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/appsuite/stable/usm/updates/SLES11 usm-updates

$ zypper ar https://software.open-xchange.com/products/appsuite/stable/usm/SLES11 usm

$ zypper ref
$ zypper install open-xchange-updater-drive open-xchange-drive open-xchange-drive-comet

Installation on Mobile Clients

The OX Drive App is available via the different App Stores.

Client Configuration and Deployment

The user defines a folder on the client that should be used for the future synchronization. Within this folder, the application creates a subfolder (e.g. per device) to prevent a heavy amount of data being transferred during the initial synchronization if e.g., a “wrong” directory (like C:\) has been selected. This folder is called Client Sync Folder. We might consider to relax this rule for the power user and allow to manually select the Client Sync Folder.

Optionally, the user can select a private (user must be Admin of the folder) Server Sync Folder as source/target folder. If there is no folder selected a client specific folder can automatically be created and configured. If the Server Sync Folder is not selected, a device specific subfolder is created and configured as Server Sync Folder which of course is also created if not already existing.

Assumption: The Client Sync Folder as well as the Server Sync Folder can not be changed after the configuration.

• If the Client Sync Folder is not available, the synchronization will not be started.
• If the Server Sync Folder is not available, the sync process will be aborted.

As a default procedure, new sync folders should be created on the server as well as on the client. This ensures that objects are only synchronized as soon as this is done and the user has full control.

Sync Procedure

• The client creates a list of the Client Sync Folder and - together with extended attributes (e.g. md5sums, file name, and path) - sends it to the server. Also, the last sync state (if existing) is sent to the server.
• The server creates a list of the Server Sync Folder together with the extended attributes, compares them and creates an action list
• The client saves the last sync state (either calculated by the server or created by the client)