Progress will discontinue Telerik Platform on May 10th, 2018. Learn more

Setting Up Data Link Server on Linux

Setting Up Data Link Server on Linux

Before you can use Data Connectors you must have a running instance of the Data Link Server. The Data Link Server is a Java web application, hosted on an embedded Apache Tomcat HTTP server that relays and translates any requests made to your Telerik Platform app to your relational database.

This article explains the installation of a Data Link Server on a Linux machine. In order to install it on a machine running Microsoft Windows, follow the instructions in Setting Up Data Link Server on Windows.

This article is organized as follows:

Requirements

Before starting the Data Link Server installation make sure you have the following:

  • A machine running Linux that has network connectivity to the database server. This machine will host the Data Link Server.
  • Java SE Runtime Environment (JRE) or Java SE Development Kit (JDK) version 8 or later installed.
  • An environment variable named JAVA_HOME set to the path where the JDK (or the JRE) is installed. Detailed instructions can be found in the Oracle documentation
  • The Upstart daemon for running the server as a system service.

Acquiring the Installation Package

Follow these steps to download and extract the Data Link Server ZIP package.

  1. Navigate to the Downloads page.
  2. Under Select platform or tool, select Data Link Server.
  3. Click the Download button and save the ZIP file to your hard drive.
  4. Extract the files to a suitable location, for example, /opt/telerikdatalink.
user@linux:~$ unzip TelerikDataLinkServer.zip -d /opt/telerikdatalink

You can run the server application once or install it as a system service for continuous running.

When the server is starting it reads the application.properties configuration file. Always check if it is set up correctly otherwise the server uses default values. You can learn how and when to set some of the more important options in the remaining sections of this article. Keep in mind that configuration updates take effect after restarting the Data Link Server.

Running from the Command Line

The Data Link Server comes with a shell script that can be used to run the server without installing it.

To run the Data Link Server once, open a terminal and go to the bin directory inside the folder where you extracted the Data Link Server server zip package, then run the following command:

user@linux:~/TelerikDataLinkServer/bin$ ./DataLinkServer

Running as a Service

Running the server from the command line is not the best solution if you need it always running. A better alternative is to install it as a service, so it is started automatically when the machine boots. The Data Link Server comes with an installation script that generates an Upstart configuration and starts the service.

To install the service, open a terminal window and go to the bin directory inside the folder where you extracted the Data Link Server package, then run the command below as root. The only required parameter (datalinkuser in the example) is the name of a local user account that will be used to run the service.

For the following instructions, you need to be executing the commands as the root user.

root@linux:~/TelerikDataLinkServer/bin$ bash installLinuxService.sh datalinkuser

To restart the service (for example after modifying the application.properties configuration options), use the following command:

root@linux:~/TelerikDataLinkServer/bin$ service datalink restart

Testing the Server

The easiest way to check if the Data Link Server server is running is to access its URL (http://machine-name.domain:port) with the curl command. For example, if you are testing from the machine where the server is installed and it runs on the default port, the URL would be http://localhost:9090. The expected response is HTTP status code 200 and a simple JSON-formatted message:

user@linux:~/TelerikDataLinkServer/bin$ curl localhost:9090

Expected result:

{"Result":"OK"}

Setting Up Authentication

The security is not complete without configuring the server-to-server authentication between Telerik Platform and your instance of the Data Link Server. The integrated authentication mechanism restricts the access to your Data Link Server, allowing in only a Telerik Platform app authenticated with an appointed key known to both parties. The secret key is automatically generated for each Telerik Platform app.

Take these steps to set up authentication:

  1. Download the key from the Create a Data Connector/Edit page. You can access the page in your Telerik Platform app on Data > Data Connectors > Create a Data Connector/Edit > Download Authentication Key.

    Alternatively, you can use the RESTful API to download the authentication key.

    The file name of your download will be the Telerik Platform App ID followed by the .txt file extension (for example 3YVPn8Al5Vi8Yfe4.txt). The content of the file is a JSON Web Token, the secret key used by Telerik Platform and the Data Link Server to sign and validate requests.

  2. Copy the downloaded file to the keys subfolder of the Data Link Server installation folder.

  3. Open the application.properties configuration file and ensure that the security.token.enabled is uncommented and set to true.

If for some reason you believe that your secret key is compromised, you can regenerate it as discussed in Managing the Authentication Key Using the RESTful API.

Enabling SSL

By default, the Data Link Server works over HTTP. It is strongly recommended that you configure an SSL certificate so that Telerik Platform can communicate with the Data Link Server over HTTPS.

Take these steps to enable SSL:

  1. Acquire an SSL certificate.

    The supported format is the Java KeyStore (JKS) format, the standard Java format. You can generate a JKS using the keytool command-line utility. The same tool is also used for importing existing certificates into the keystore. For complete instructions see the official Apache Tomcat documentation.

  2. After you have acquired the keystore file containing the certificates, configure the ssl.* set of application.properties configuration options.

Use the information in this paragraph only when you have a running Data Link Server and want to update it with the latest version of the package. In the steps below you will learn how to install the new application package while preserving the already applied configuration.

  1. Follow the steps for Uninstalling the Service (in case you are running the server as a system service) or stop the running instance of the Data Link Server from the console window.
  2. Backup the following files from the current installation folder of the Data Link Server.
    • data-connectors.config—stores the database tables to content types mappings
    • application.properties file (if available)—stores the Data Link Server configuration
    • Java KeyStore (JKS) file (.keystore) (if available)—stores the SSL encryption key/certificate
    • keys/<security-key-file.txt> (if available)—stores the server-to-server authentication token
  3. Remove or rename the current directory to something else—for example "TelerikDataLinkServer.old".

    user@linux:~/$ mv TelerikDataLinkServer TelerikDataLinkServer.old
    
  4. Acquire and extract the installation package as explained in Acquiring the Installation Package.
  5. Locate the data-connectors.config file in the ".old" directory and copy it to the new one:

    user@linux:~/$ cp TelerikDataLinkServer.old/data-connectors.config TelerikDataLinkServer
    
  6. Examine and configure (if needed) the application.properties file.
  7. Optionally, restore your Java KeyStore (JKS) file (.keystore) and keys/<security-key-file.txt> file from the backup directory to their respective locations in the new Data Link Server folder.
  8. Follow the steps for Running as a Service or Running from the Command Prompt respectively.

Uninstalling the Service

You can run an uninstallation script to remove the service. It is located in the same bin folder as the installation script. It does not require any parameters.

To uninstall the service, run this command as root:

root@linux:~/TelerikDataLinkServer/bin$ bash uninstallLinuxService.sh

Next Steps

You are now ready to create your Data Connector in Telerik Platform. You can learn how in Creating an SQL Data Connector Using the Portal and Managing Content Types Using the Administration API.

See Also


Start a free trial Request a demo
Contact us: +1-888-365-2779
sales@telerik.com
Copyright © 2016-2017, Progress Software Corporation and/or its subsidiaries or affiliates. All rights reserved.