AWS AMI Edition


AWS AMI Edition


The CData Sync Amazon Machine Instance (AMI) comes as a Linux-based instance with CData Sync pre-configured and ready to run, with very little additional configuration necessary. The AMI can be found in the AWS Marketplace as CData Sync.

Launch the CData Sync Instance

  1. Subscribe to the AMI and accept the Terms and Conditions. Once you are scubscribed, you can configure a new instance of CData Sync
  2. Configure your instance:
    • Choose the instance type. Refer the the CData Sync Licensing Page for more information.
    • Set the Security Group. CData Sync runs on the default HTTPS port (443); ensure this port is accessible from the IP address you connect to CData Sync.
    • Create a new key-pair or choose an existing one. Make sure you save the pem file as it will be used to acess the Instance via SSH
  3. Hit the Launch button to create the EC2 instance and start CData Sync.

Access CData Sync from Browser

Once the instance has launched, it will be listed in your EC2 management console. You can then access CData Sync in your browser at the URL.

https://<instance_public_dns>

To log in, the default username is ‘admin’ and the password is the instance’s randomly generated Instance-ID prefixed with Sync21:. For example, if the Instance-ID is i-1234a, the initial password to access Sync is Sync21:i-1234a. After logging in, you can change the password for the ‘admin’ user in the top right corner of the browser.

You can now follow the Getting Started section to create your connections and manage your jobs.

Managing the AMI

The CData Sync AMI works out-of-the-box without additional configuration. Below provides information on AMI-specific management tasks for CData Sync.

Accessing the instance via SSH

Connecting to the EC2 instance via SSH can be useful for advanced configuration of the service. The CData Sync AMI is based on a standard Ubuntu 16 VM, and the main user is ubuntu. You can connect to it via SSH using the key-pair selected when launching the instance:

ssh -i my_key_pair.pem ubuntu@<instance_public_dns>

Controlling the CData Sync service

CData Sync is run as a systemd service in an AMI depoyment, rather than in-process. The service definition file can be found here:

etc/systemd/system/cdatasync.service

Sync should be started, stopped, and restarted using standard systemd commands:

sudo systemctl restart cdatasync
sudo systemctl stop cdatasync
sudo systemctl start cdatasync

Before making any changes to the Sync Application, it is best to first stop the service.

Application Directory

All of Sync’s configuration and application data is held in the Application Directory. By default, the Application Directory is located here:

/opt/sync

The Application Directory path can be configured via the sync.xml file in the webapp folder, as described in the Configuring the Application Directory section.

DB Folder

The db folder contains the database files for the default Derby database. Note that the application database can be configured to use an external database as described in the next section.

Lib Folder

The libs folder is where the application reads external resources, like drivers for connectors that require an external driver. Place .jar or .class resources in this folder and restart Sync to allow the application to read these resources.

Webapp Folder

The webapp folder contains the sync.xml file that determines the configuration of the Jetty server hosting the application. This file can be used to change the port the server listens on, enable a plaintext listener (i.e. HTTP instead of HTTPS), and configure any other Jetty server settings.

Additionally, the sync.xml file determines the location of the Application Directory and the database connection for the Application Database.

Configure the Application Directory

The Application Directory is configured using the sync.xml file in the webapp folder, described in the previous section.

To configure the Application Directory to a non-default location, first find the following snippet within the sync.xml file

<!-- The APP_DIRECTORY setting is used to explicitly configure a path where profile information is stored.
<Call name="setInitParameter">
  <Arg>APP_DIRECTORY</Arg>
  <Arg><SystemProperty name="sync.home" default="."/></Arg>
</Call -->

Uncomment the <Call> tag within this snippet, and fill in the APP_DIRECTORY argument to the desired folder location. For example:

<Call name="setInitParameter">
   <Arg>APP_DIRECTORY</Arg>
   <Arg>/example/path</Arg>
</Call>

Application Database

By default, Sync uses a Derby database for connection, jobs, application settings and general application logs. This Derby database is located in the db folder of the Application Directory, as described in the previous section.

Sync can be configured to use an external database like MySQL. Similar to configuring the Application Directory, the Application Database is configured in the sync.xml file within the webapp folder.

To configure the Application Database, first find the following snippet within the sync.xml file:

<!-- By default, CData Sync will use a local Derby database to store information on jobs, connections application settings and logs. The APP_DB setting may be used to configure a database external to the application that will be used to store this information.
<Call name="setInitParameter">
  <Arg>APP_DB</Arg>
  <Arg>jdbc:mysql:Server=MySQLServer;Port=3306;Database=mysql;User=user;Password=password</Arg>
</Call> -->

Uncomment the <Call> tag within this snippet, and fill in the APP_DB with a connection string for the target database.

Ports and SSL

By default, Sync listens for SSL connections (HTTPS) on port 8443. Sync is unable to bind to the default HTTPS port (443) due to permissions restrictions, so an iptables rule redirects traffic from port 443 to port 8443. No further action is required for standard HTTPS traffic to reach Sync’s web server.

Sync AMIs include a self-signed certificate for use when hosting an SSL server. If the SSL server needs to be hosted using a certificate signed by a Certificate Authority, then the CA should be contacted directly to procure a certificate.

Enabling HTTP Connections

To add a plaintext/non-SSL port (i.e. HTTP instead of HTTPS), you will need to edit the sync.xml file to enable the plaintext listener. Due to permissions restrictions, this listener cannot directly bind to port 80, so it is established on port 8080 and an iptables rule must be established to forward traffic from port 80 to port 8080.

First, find the snipet within the sync.xml files that enables the HTTPS listener:

<!-- Set the connectors on the server object -->
  <Call name="setConnectors">
   <Arg>
    <Array type="org.eclipse.jetty.server.ServerConnector">
      <!-- Remove this comment to allow plaintext connections.
      <Item>
        <Ref refid="httpConnector" />
      </Item>
      -->
      <Item>
        <Ref refid="httpsConnector" />
      </Item>
    </Array>
  </Arg>
</Call>
<!-- / Set the connectors on the server object -->

Within this snippet, uncomment the <Item> element that references the ‘httpConnector’ configuration.

Then, create a new iptables rule to forward traffic from port 80 to port 8080:

iptables -t nat -I PREROUTING -p tcp --dport 80 -j REDIRECT --to-port 8080
/usr/libexec/iptables/iptables.init save

Finally, restart the Sync service so that the above changes come into effect.

Upgrading

Upgrading Sync requires launching a new instance of the latest Sync AMI. Before launching the new instance, data should be copied over from the old instance so that the application configuration is preserved in the new instance.

Sync includes a migration tool to easily export and import the configured Connections and Jobs in the application. Navigate to the Settings page and the Migration tab. Select ‘Export’ to export all settings (Connections, Jobs, Users, History) to a .zip file.

On the new instance, import the configuration settings from the same Migration Tab. Select ‘Import’ then navigate to the .zip file downloaded previously.

Add a New Connector

New connnectors can be added through the UI following the steps outlined on the Connections page. However, you may be required to manually update or add the connector to your instance following the below steps:

  • SSH into the AMI
  • Stop the jetty service
    sudo systemctl stop cdatasync
    
  • Open new command prompt and copy the connector to your instance using scp:
    scp -i ./path/to/my_key_pair.pem ./path/to/cdata.jdbc.<providername>.jar ubuntu@<instance_public_dns>:/home/ubuntu/cdata.jdbc.<providername>.jar
    
  • Back in previous command prompt, copy to libs folder:
    sudo cp ./home/ubuntu/cdata.jdbc.<providername>.jar /opt/sync/libs/cdata.jdbc.<providername>.jar
    
  • Start the jetty service:
    sudo systemctl start cdatasync