Configuring Synchrony for Data Center

Still need help?

The Atlassian Community is here for you.

Ask the community

When you install Confluence Server, Synchrony is automatically configured to run as a seperate process on your server.

For Confluence Data Center, we give you full control by allowing you to set Synchrony up yourself. This gives you the flexibility to deploy Synchrony standalone on the same nodes as Confluence, or in its own cluster with as many nodes as you need. 

On this page:

Here's an example architecture, with a 2 node Synchrony cluster to support a three node Confluence cluster.


To set up Synchrony in Data Center you'll need to:

  1. Copy the following files and directories from one of your Confluence nodes to wherever you plan to run Synchrony:
    • <install-directory>/bin/synchrony 
    • <local-home>/synchrony-standalone.jar
    • your database driver from <install-directory>/confluence/WEB-INF/lib 
  2. Edit the start-synchrony.sh or start-synchrony.bat file and follow the instructions in the script itself to insert the required parameters listed below. 
  3. Add any additional system properties in the Optional Overrides section. 

See Installing Confluence Data Center for a step by step guide to setting up Synchrony for Data Center. 

Required Synchrony properties (Data Center only)

Before you can run Synchrony, you need to edit the start-synchrony script to provide the following values. 

Property name Description
SERVER_IP Public IP address or hostname of this Synchrony node. It could also be a private IP address - it should be configured to the address where Synchrony is reachable by the other nodes.
DATABASE_URL This is the URL for your Confluence database. For example jdbc:postgresql://yourserver:5432/confluence . You can find this URL in <local-home>/confluence.cfg.xml .
DATABASE_USER This is the username of your Confluence database user.
DATABASE_PASSWORD

(Optional) This is the password for your Confluence database user.

Rather than hardcoding your password, we recommend setting your password with the environment variable SYNCHRONY_DATABASE_PASSWORD. Any dots (".") in variable names (identifiers) will need to be replaced with underscores ("_"). See

CLUSTER_JOIN_PROPERTIES

This determines how Synchrony should discover nodes. You'll be prompted to uncomment a set of parameters for either:

  • TCP/IP
  • Multicast
  • AWS

Follow the prompts in the script for the values you need to enter for each of these.

DATABASE_DRIVER_PATH This is the path to your database driver file. If you're running Synchrony on its own node, you'll need to copy your database driver to an appropriate location then provide the path to this location.
SYNCHRONY_JAR_PATH This is the path to the synchrony-standalone.jar file you copied to this node.
SYNCHRONY_URL

This is the URL that the browser uses to contact Synchrony. Generally this will be the full URL of the load balancer Synchrony will run behind plus the Synchrony context path, for example http://yoursite.example.com/synchrony.  

Note that it does not end with /v1 , unlike the synchrony.service.url system property passed to Confluence. If this URL doesn't match the URL coming from a users' browser, Synchrony will fail.

OPTIONAL_OVERRIDES You can choose to specify additional system properties. See the table below for recognised Synchrony system properties.


Optional Synchrony system properties (Data Center only)

When you start Synchrony, we pass default values for the properties listed below. You can choose to override these values by specifying any of these properties when you start Synchrony. 

Property name Default Description
cluster.listen.port 5701

This is Synchrony's Hazelcast port. Specify this property if you do not want to use port 5701 or if it is not available.

As with the Confluence Hazelcast port (5801) you should ensure that only permitted  cluster nodes are allowed to connect to Synchrony's Hazelcast  port, through the use of a firewall and or network segregation.

synchrony.cluster.base.port
25500 This is the Aleph binding port. Synchrony uses Aleph to communicate between nodes. Specify this property if you don't want to use the default.
cluster.join.multicast.group 224.2.2.3

If the cluster join type is multicast, you can specify an IP address for the multicast group if you don't want to use the default.

cluster.join.multicast.port 54327 If the cluster join type is multicast, you can specify a multicast port if you don't want to use the default.
cluster.join.multicast.ttl
32 If the cluster join type is multicast, this is the time to live threshold. The default, 32, means the scope is restricted to the same site, organization or department. Specify this property if you want to use a different threshold.

cluster.join.aws.access.key


If the cluster join type is AWS, this is your AWS access key.

cluster.join.aws.secret.key


If the cluster join type is AWS, you can authenticate by IAM role or Secret key. This is your AWS secret key.

cluster.join.aws.iam


If the cluster join type is AWS, you can authenticate by IAM role or Secret key. This is your AWS IAM role.

cluster.join.aws.region

us-east-1 If the cluster join type is AWS, this is the AWS region your Synchrony nodes will be running in.

cluster.join.aws.security.group


If the cluster join type is AWS, and you want to narrow the members of your cluster to only resources in a particular security group, specify the name of your AWS security group.

cluster.join.aws.tag.key


If the cluster join type is AWS, and you want to narrow the members of your cluster to only resources with particular tags, specify the AWS tag key.

cluster.join.aws.tag.value


If the cluster join type is AWS, and you want to narrow the members of your cluster to only resources with particular tags, specify the AWS tag key value.

cluster.join.aws.host.header


If the cluster join type is AWS, this is the AWS endpoint for Synchrony to use (the address where the EC2 API can be found, for example 'ec2.amazonaws.com').

cluster.join.aws.timeout

5 If the cluster join type is AWS, this is the joining timeout (in seconds).
cluster.interfaces Defaults to the same value as SERVER_IP  This is the network interface Synchrony will use to communicate between nodes. Specify this property if you don't want to use the default, which uses the value of the required property Defaults to the same value as SERVER_IP (also known as synchrony.bind).
synchrony.cluster.bind Defaults to the same value as SERVER_IP

This is the Aleph binding address. This should be set to the same value as cluster.interfaces.

Specify this property if you did not use the default value for cluster.interfaces.

synchrony.port 8091 This is the HTTP port that Synchrony runs on. If port 8091 is not available, specify this property to choose a different port.
synchrony.context.path Defaults to the context path of SYNCHRONY_URL This is the context path for Synchrony. There should be no need to change this.
hazelcast.prefer.ipv4.stack
True If you're running Confluence in an IPv6 environment, you will need to set this property to False.


Start and stop Synchrony

To start Synchrony, run start-synchrony.sh or start-synchrony.bat.  A process ID (PID) file will be created in your synchrony directory. 

To stop Synchrony, run stop-synchrony.sh or stop-synchrony.bat.  This will destroy the PID file that the start script created in your Synchrony directory.  If you've customised the location for storing the PID file in the start-synchrony script, you'll need to also update this in the stop-synchrony script. 

If you're unable to start Synchrony, check that there is not an existing PID file in your Synchrony directory. 

You can only use these scripts to start and stop Synchrony in Confluence Data Center.

To restart Synchrony in Confluence server head to  > General Configuration > Collaborative editing.


Accessing Synchrony logs 

Your Synchrony logs will be stored in the Synchrony directory in each node (wherever you run the start and stop scripts from). 

Notes

If your users are unlikely to be able to get a WebSocket connection to Synchrony (for example your load balancer or reverse proxy does not support WebSockets) you can enable XHR fallback by passing the synchrony.enable.xhr.fallback system property to Confluence. Note that this is a Confluence system property and must be passed to Confluence, it is not part of your start Synchrony command. 

You will need to open Synchrony's port, as you can't use the built-in Synchrony proxy with Data Center. The synchrony.proxy.enabled system property mentioned in the Confluence Server documentation has no effect in Data Center. 

Run Synchrony in an IPv6 environment

If you're running Confluence Data Center in an IPv6 environment, you will need to start Synchrony with the following JVM argument:

-Dhazelcast.prefer.ipv4.stack=false

If you're using the start-synchrony scripts, you'll just need to uncomment this line in the script.  

Run Synchrony as a service

If you'd prefer to run Synchrony as a service, see Run Synchrony-standalone as a service on Linux

It's currently not possible to run Synchrony as a service on Windows. 

Provide credentials to Synchrony using environment variables (Linux)

If you prefer to store sensitive information in your environment, rather than directly in the Synchrony startup scripts you can create a synchronyenv file, and use it to provide your database credentials. 

These instructions are for Linux users. We'll assume your dedicated Synchrony user is named synchrony.

Create the synchronyenv file

  • Change to your Synchrony user, for example:

    sudo su - synchrony
  • In your <synchrony-home> directory, create a new file called synchronyenv
  • Add the following lines to the synchronyenv file, and include your database credentials.

    export SYNCHRONY_DATABASE_USERNAME="database-username"
    export SYNCHRONY_DATABASE_PASSWORD="database-password"

Modify your Synchrony startup script

  1. Edit your start-synchrony.sh  script. 

  2. Comment out the following lines

    DATABASE_USER="<DB_USERNAME>"
    DATABASE_PASSWORD="<DB_PASSWORD>"

    Note that they may already be commented out, or have slightly different information. 

  3. Uncomment the following line, and include the path to the synchronyenv file you've just created.

    SYNCHRONY_ENV_FILE=<PATH_TO_ENV_FILE>
  4. Save your changes. 

Modify your shell profile

Bash as login shell will load the following profiles in order. Your environment may vary, but this is an example for Ubuntu:

  • /etc/profile
  • ~/.bash_profile
  • ~/.bash_login
  • ~/.profile

Note: Bash as non-login interactive shell will load ~/.bashrc

  1. Edit the appropriate profile as noted above, and to add the following code:

    # Defines the absolute path to the synchronyenv file. 
    # For example, if your synchronyenv file was located in
    /opt/synchrony-home/synchrony, you would use the example:
    source /opt/synchrony-home/synchrony/synchronyenv
  2. Confirm the variables are in place by exiting the bash session of the Synchrony user, then re-entering it, and running the following command:

    env
  3. Your database credentials defined should appear in your env output. Here's a sanitized example:

    XDG_SESSION_ID=15
    SYNCHRONY_DATABASE_PASSWORD=<sanitized>
    ...
    SYNCHRONY_DATABASE_USERNAME=<sanitized>
    ...
    _=/usr/bin/env

If the info you defined in your synchronyenv file appears correctly in the output above, you should be good to start Synchrony once again. If they don't appear, you may need to define them in a different profile config, based on your operating system and shell.

Last modified on Sep 20, 2018

Was this helpful?

Yes
No
Provide feedback about this article
Powered by Confluence and Scroll Viewport.