7 Configuring the Calendar Server Document Store

This chapter describes how to configure the Oracle Communications Calendar Server document store.

About Configuring the Document Store

The Calendar Server document store is used to store and retrieve large data, such as calendar events and todos with large attachments. You must configure one document store per each Calendar Server back-end database. That is, configure one document store for the calendar store (the MySQL Server database or Oracle Database), and one document store for the iSchedule database.

The document store can be either local or remote, or, if you use Oracle Database, within the database itself. When the document store is local, Calendar Server accesses the file systems directly. When the document store is remote, Calendar Server accesses the documents by using either HTTP or HTTPS. If you use Oracle Database, you can configure it to contain both the calendar data and the data that otherwise would need to be stored in the separate document store. That is, you would use a single, large Oracle database for both calendar data and the document store.

Configuring Oracle Database for Both Calendar Data and Large Data

In the case of Oracle Database, you can configure it to contain both the calendar data and the data that would otherwise need to be stored in the separate document store. This type of configuration is not possible with a MySQL database. If you are using MySQL Server, refer instead to "Configuring a Local Document Store" and "Configuring a Remote Document Store" to set up a local or remote document store.

To configure Oracle Database for both calendar data and large data:

  1. For each back end, set the store.dav.backend-name.attachstorehost parameter to a value of dbdocstore. For example:

    cd CalendarServer_home/sbin
    davadmin config modify -o store.dav.defaultbackend.attachstorehost -v dbdocstore
    
  2. Restart Calendar Server by restarting the GlassFish Server instance.

Configuring a Local Document Store

You can only configure a local document store when your deployment consists of a single Calendar Server front-end host. Do not configure a local document store on a front-end host if your deployment consists of multiple front-end hosts. Calendar Server requires that each front-end host needs access to each back-end host's database and document store pair.

To configure a local document store:

  1. Log in to the local document store host.

  2. Either use the default document store directory (/var/opt/sun/comms/davserver/db/), or create a data directory for the document store.

    mkdir path_to_docstore
    
  3. Set the directory access permissions to be readable and writable by the document store user only:

    chmod 700 path_to_docstore
    
  4. Configure Calendar Server to use the document store directory:

    davadmin config modify -u admin -o store.dav.defaultbackend.dbdir -v path_to_docstore
    
  5. Restart Calendar Server by restarting the GlassFish Server instance.

Configuring a Remote Document Store

Prerequisite: Install the Calendar Server software on the remote host. For more information, see "Installing Calendar Server".

To configure a remote document store:

  1. Log in to the remote document store host.

  2. Either use the default document store directory (/var/opt/sun/comms/davserver/db/), or create a data directory for the document store.

    mkdir path_to_docstore
    
  3. Set the directory access permissions to be readable and writable by the document store user only:

    chmod 700 path_to_docstore
    
  4. Run the configure-as script, which is located in the document store sbin directory:

    CalendarServer_home/sbin/configure-as
    
  5. Change the store.dav.backend.attachstorehost and store.dav.backend.attachstoreport parameters on each Calendar Server front-end host to specify the host name and port number of the document store hosts for the back-end database.

    For example:

    davadmin config modify -u admin -o store.dav.defaultbackend.attachstorehost -v ahost.example.com
    
    davadmin config modify -u admin -o store.dav.defaultbackend.attachstoreport -v 8008
    

    Each back-end database and iSchedule database have their own document store. See the davadmin command documentation in Calendar Server System Administrator's Guide for more information about how to change the store.dav.backend.attachstorehost and store.dav.backend.attachstoreport parameters.

  6. Restart Calendar Server by restarting the GlassFish Server instance.

If you must start or stop the document store, the commands are:

CalendarServer_home/sbin/start-as
CalendarServer_home/sbin/stop-as

Configuring the Remote Document Store to Run as a Non-Root User

This procedure assumes that you have already configured the remote document store to run as root, and are now changing it to run as a non-root user.

  1. On the remote document store host, make sure that the document store is stopped.

    CalendarServer_home/sbin/stop-as
    
  2. On the remote document store host, run the chown command to change the user and group ownership of the files in the davserver configuration and data directory (default is /var/opt/sun/comms/davserver), and for the start-as and stop-as commands.

    chown -R non-root_user:group /var/opt/sun/comms/davserver
    chown non-root_user:group CalendarServer_home/sbin/start-as
    chown non-root_user:group CalendarServer_home/sbin/stop-as
    
  3. If you have changed the default directory in the ashttpd.properties file for the store.datadir parameter, you must also change the ownership of that directory to the non-root user.

    For example, if store.datadir is set to /export/davstore/nab, then run the following command:

    chown -R non-root_user:group /export/davstore/nab
    
  4. Start the remote document store as the non-root user.

    su - non-root_user -c "CalendarServer_home/sbin/start-as"
    

Configuring Remote Document Store Authentication

You must configure password authentication of the connection between the remote document store server (which runs on the remote host where the store is located), and the document store client (which runs on every Calendar Server front end). The password must be known by both the document store client and the remote document store server. The password is stored in a password file (called a wallet) on each host where it is needed.

This procedure assumes you have already created the remote document store and that it is running.

  1. On the local Calendar Server host, use the davadmin passfile modify command to set the document store password.

    For example:

    cd CalendarServer_home/sbin
    davadmin passfile modify
    Enter the Password File password:
    
    Do you want to set the app server admin user password (y/n)? [n] n
    
    Do you want to set the database password (y/n)? [n] n
    
    Do you want to set the migration server user password (y/n)? [n] n
    
    Do you want to set the document store password (y/n)? [n] y
    Enter the document store password:
    Reenter the document store password:
    
    Do you want to set the document store SSL passwords (y/n)? [n] n
    

    Setting the document store password updates the store.document.password configuration parameter.

  2. On the remote document store host, configure the document store.

    cd CalendarServer_home/sbin
    configure-as
    
    Do you want to set the document store password (y/n)? [n] y
    Enter the document store password: password
    Reenter the document store password: password
    
    Do you want to set the document store SSL passwords (y/n)? [n] y
    Enter the document store SSL keystore password: <Enter the same password that you used when creating the self-signed certificate, that is, the keystore password>
    Reenter the document store SSL keystore password: password
    
    Enter the document store SSL certificate password: <Enter the same password that you used when creating the self-signed certificate, that is, the keystore password>
    Reenter the document store SSL certificate password: password
    
    Please check the values in /var/opt/sun/comms/davserver/config/ashttpd.properties
    are correct before starting the server with start-as
    To stop the server, run stop-as
    Document Store server is now configured
    

    To change the document store password, run the davadmin passfile modify -O command.

    For example:

    cd CalendarServer_home/sbin
    davadmin passfile modify -O
    
    Enter the Password File password:
    
    Do you want to set the document store password (y/n)? [n]
    
    Do you want to set the document store SSL passwords (y/n)? [n] y
    

    Note:

    After setting the initial password, if you must change the password, rerun the davadmin passfile modify command. If you change the password by using the davadmin config modify command instead, to modify the store.document.password configuration parameter, the document store password in the "davadmin" wallet may not be up-to-date.

Configuring Remote Document Store SSL

You can use SSL to secure the transmission of data between the Calendar Server host and the document store. Configuring SSL between Calendar Server and the document store consists of the following high-level steps:

  1. Configure the document store to accept SSL connections.

  2. Configure Calendar Server to connect to the document store over SSL.

For more information, see the topic on configuring SSL for the remote document store in Calendar Server Security Guide.

Configuring the Document Store for High Availability

You can configure Calendar Server for multiple document stores such that, when the current document store host fails, the back-end database host fails over to the next available document store host.

To configure the document store for high availability:

  1. Set up a shared file system, or some kind of data replication, for the document store data.

  2. Use the store.dav.backendid.attachstorehost configuration parameter to specify a comma-separated list of document store hosts.

    For example:

    davadmin config modify -o store.dav.backendid.attachstorehost -v "ahost1.example.com,ahost2.example.com"
    

    When the current document store host fails, the back-end host fails over to the next document store host on the list.

  3. Always keep the data on the document stores synchronized.

Migrating the Document Store

If, after installing the document store, you must migrate it to another location, you reconfigure the store location in the ashttpd.properties file, then manually move your existing documents in the astore directory. You also manually move the files in the config and logs directories to the new location before restarting the document store server and the front-end Calendar Server hosts. See the topic on document store configuration parameters in Calendar Server System Administrator's Guide for more information about the ashttpd.properties file.

To migrate the document store:

  1. Stop Calendar Server by stopping the GlassFish Server instance.

  2. If the document store is remote, stop it as well:

    CalendarServer_home/sbin/stop-as
    
  3. Manually move the existing documents from the old path to the new location.

  4. Use one of the following methods to reconfigure the document store server, depending on whether it is local or remote:

    • Remote store: Reconfigure the store.datadir parameter in the ashttpd.properties file.

      See the topic on document store configuration parameters in Calendar Server System Administrator's Guide for more information about these parameters.

    • Local store: Reconfigure the store.dav.defaultbackend.dbdir parameter.

  5. If the document store is remote, restart it:

    CalendarServer_home/sbin/start-as
    
  6. Restart Calendar Server by restarting the GlassFish Server instance.