Search

Cross-Platform Edition

Version 23.0.9145

Cross-Platform Edition

You can configure and run the Cross-Platform Edition of CData API Server on the following servers:

  • an embedded server that is built on Eclipse Jetty

  • an external Jetty server

  • an external Apache Tomcat server

Each option is outlined below.

Embedded Eclipse Jetty Server

API Server comes bundled with a web server that is built on top of Jetty, which is ideal for most deployment scenarios. CData recommends that you use this embedded Jetty server unless your setup requires an alternative configuration.

Starting the Application

You can start the application using the methods described in the following sections.

Using a Java Command

To start API Server with a Java command:

  1. Open a terminal to the API Server installation directory.

  2. Issue the following Java command to run the apiserver.jar file:

    java -jar apiserver.jar

Using the Linux Service

If you install the API Server service on a Linux platform, you can use the terminal to issue start, stop, and restart commands for API Server, as shown in the following syntax:

systemctl [start | stop | restart] cdata-apiserver

Accessing the Admin Console

By default, the embedded server hosts the API Server on port 8080, and it accepts only plaintext connections (that is, HTTP but not HTTPS).

After you start the server, access the admin console by opening a web browser to this URL: http://localhost:8080. To access the UI, use the default username and password credentials (admin/admin).

Configuring the Application

The configuration for the embedded web server is contained within webapp/apiserver.xml, which you can modify to suit your deployment. Some examples of modifications are provided in XML comments within the contents of the apiserver.xml file, but you should accept any valid jetty.xml configuration.

Changing the Port

To configure the port on which the embedded server listens:

  1. Open the apiserver.xml file in the installation directory. Then, locate the definition of the HTTP connector that is shown below:

    <New id="httpConnector" class="org.eclipse.jetty.server.ServerConnector">

  2. Within this definition, locate the following line and replace the default port with the port that you want to use:

    <Set name="port">8080</Set>

Enabling SSL/TLS

To enable SSL/TLS connections (HTTPS):

  1. Open the apiserver.xml file in the installation directory and locate the definition of the HTTP connector that is shown below:

    <New id="httpConnector" class="org.eclipse.jetty.server.ServerConnector">

  2. Within this definition (as a direct child of the <New> element that is shown in step 1), supply an sslContextFactory argument by adding the following XML block:

        <Arg name="sslContextFactory">
       <New id="sslContextFactory" class="org.eclipse.jetty.util.ssl.SslContextFactory$Server">
          <Set name="KeyStorePath"><SystemProperty name="apiserver.home" default="." />/keystore</ Set>
          <Set name="KeyStorePassword">MyPassword</Set>
       </New>
    </Arg>

    Note: The <Arg> element that is shown above must be adjacent to other <Arg> elements at the beginning of the connector definition. This block must not be placed after the <Set> element that defines the server port, for example.

    The KeyStorePath property defines the location of the SSL/TLS certificate that is used when hosting the SSL/TLS server. The previous example assumes that a Java keystore file named keystore is created in the API Server data directory (by default, in C:\ProgramData\CData\apiserver). The KeyStorePassword property should be set to the password that corresponds to the configured certificate.

    In addition, you can reference a private key via a PFX file by using an additional key reference with a password, as shown in the following example:

      <Arg name="sslContextFactory">
    <New id="sslContextFactory" class="org.eclipse.jetty.util.ssl.SslContextFactory">
      <Set name="KeyStorePath"><SystemProperty name="apiserver.home" default="."/>MyCertificate.pfx</Set>
      <Set name="KeyStorePassword">MyPassword</Set>
      <Set name="KeyStoreType">PKCS12</Set>
    </New>
  </Arg>

    Note: If you obtain an external private key for configuration in API Server, make sure to change the owner of the certificate to the service account that is used to host API Server.

Changing User Credentials

User accounts (users) that can log into the API Server web UI are defined in the apiserverRealm.properties file in the installation directory. Each line in this file defines a user, with the following syntax:

Username:Password\[Roles]

Add a new line to define a new user or modify the existing line to change the default login credentials.

Setting Up a Load-Balancing Configuration

To set up a load-balancing configuration in the embedded Jetty server, you must ensure that synchronization is maintained for the following items:

  • The API Server application file (apiserver.war)

  • JDBC drivers that are used to connect to your data sources

You cannot access Jetty configuration files directly. Instead, you can configure the custom database resource in the <WebAppContext> element of the apiserver.xml file that is located in the webapp\ subdirectory of the installation location. The following example shows the <WebAppContext>configuration:

<WebAppContext>
  <Call name="setHandler">
    <Arg>
      <New id="apiserver" class="org.eclipse.jetty.webapp.WebAppContext">
        [...]
        <Call name="setInitParameter">
          <Arg>APP_DB</Arg>
          <Arg>jdbc:mysql:Server=MyServer;Port=3306;Database=MyDatabase;User=MyUser;Password=MyPassword</Arg>
        </Call>
        <Call name="setInitParameter">
          <Arg>APP_USERS</Arg>
          <Arg>jdbc:mysql:Server=MyServer;Port=3306;Database=MyDatabase;User=MyUser;Password=MyPassword</Arg>
        </Call>
        <Call name="setInitParameter">
          <Arg>APP_LOGS</Arg>
          <Arg>jdbc:mysql:Server=MyServer;Port=3306;Database=MyDatabase;User=MyUser;Password=MyPassword</Arg>
        </Call>
      </New>
    </Arg>
  </Call>
</WebAppContext>

If the base URL of API Server does not correspond to the server on which API Server is installed, you might need to configure the base URL manually. To do so, follow these steps:

  1. Log in to API Server as an administrator (admin).

  2. Select Settings > Server.

  3. In the OData section on the Server tab, enter the URL that you want in the Base URL text box.

When URLs that reference API Server are generated (for example, metadata URLs), they point to this custom base URL.

Enabling the Admin API

By default, the Admin API is not enabled. To manually enable it, follow these steps:

  1. Open WEB-INF/web.xml in a text editor of your choice.

  2. Navigate to the security-constraint section that has the display name Restrict direct access to the Management API.

  3. Locate the <auth-constraint/> and modify it by adding a role name, as shown below.

    <auth-constraint>
  <role-name>cdata_admin</role-name>
</auth-constraint>

  4. Save your changes to the file.

  5. Restart API Server.

After you complete these steps, the admin user can access the API Server Admin API at the endpoints admin.rst and admin.rsc.

Note: The Admin API is accessible only to the API user named admin. Access is denied to other API users.

Enabling API Server in the AWS AMI Environment

The AWS Amazon Machine Image (AMI) for API Server runs in Jetty, which is a Java servlet container. To enable the Admin API in this environment, follow the same directions that are in the previous section. In this case, the web.xml file is located here:

/opt/apiserver/work/jetty-0.0.0.0-8443-apiserver.war-_-any-/webapp/WEB-INF/web.xml

To restart the API Server service, use this command:

systemctl restart jetty

Managing Notifications

To configure API Server so that you receive email notifications:

  1. Select Settings > Notifications in the Admin console.

  2. In the Email category, specify values for the From, To, and Subject properties.

  3. Set the authentication and security properties for the SMTP server (User, Password, and Encryption Type).

  4. Click Send Test Email to verify that you are receiving notifications.

External Jetty Server

Although API Servercomes with an embedded Jetty web server, you can also use the application with an external Jetty setup.

To begin deployment to an external Jetty server:

  1. Deploy the WAR file into the Jetty webapps folder.

  2. Enable Jetty users to access the application by assigning the cdata_admin role. For example, you can add this role to the admin user by opening the realm.properties file that resides in JETTY_HOME/etc/. The properties for the user consist of the password followed by the user’s roles, as shown in this example:

    admin: MyPassword,server-administrator,content-administrator,admin,user,cdata_admin

After you perform these preliminary steps, you need to configure the login service, configure data-directory permissions, and set up load balancing, as explained in the following sections.

Configuring the Login Service for the Java Realm

You must configure a login service for the application with the name CDataRealm as shown in the following example for a HashLoginService class:

<Call name="addBean">
  <Arg>
    <New class="org.eclipse.jetty.security.HashLoginService">
      <Set name="name">CDataRealm</Set>
      <Set name="config"><Property name="jetty.home" default="."/>/etc/realm.properties</Set>
    </New>
  </Arg>
</Call>

Configuring Data-Directory Permissions

Specify Read/Write access to the appropriate data directory (listed below) for the user of the process that runs the Java servlet container.

  • Microsoft Windows: C:\\ProgramData\\CData\\

  • Linux: ~/cdata/

Restart the server and log in to the application.

Setting Up a Load-Balancing Configuration

To set up a load-balancing configuration in an external Jetty server, you must ensure that synchronization is maintained for the following items:

  • The API Server application file (apiserver.war)

  • JDBC drivers that are used to connect to your data sources

Follow these steps to configure these resources:

  1. Enable the jetty-plus module in $JETTY_HOME/start.ini by submitting the command --module=plus.

  2. Add the open source JDBC MySQL driver to $JETTY_HOME/lib/ext.

  3. Add the following entries to the jetty.xml file:

    <Configure id="Server" class="org.eclipse.jetty.server.Server">
   [...]
   <New Id="AppUsers" class="org.eclipse.jetty.plus.jndi.Resource">
     <Arg></Arg>
     <Arg>jdbc/APP_USERS</Arg>
     <Arg>
       <New class="com.mysql.cj.jdbc.MysqlConnectionPoolDataSource">
         <Set name="url">jdbc:mysql://MyServer:3306/MyDatabase</Set>
         <Set name="User">MyUsername</Set>
         <Set name="Password">MyPassword</Set>
       </New>
    </Arg>
   </New>
</Configure>

  4. Add the reference to the newly added resource to the apiserver.xml file, which is located in $JETTY_BASE/work/[AppName]/webapp/WEB-INF/web.xml. Add the reference inside the <web-app> tags, as shown below:

    <web-app>
   [...]
   <resource-ref>
     <description>App Security Datasource</description>
     <res-ref-name>jdbc/APP_USERS</res-ref-name>
     <res-type>javax.sql.DataSource</res-type>
     <res-auth>Container</res-auth>
   </resource-ref>
</web-app>

  5. Restart the Jetty service to enable API Server to use the newly defined database.

If the base URL of API Server does not correspond to the server on which API Server is installed, you might need to configure the base URL manually. To do so, follow these steps:

  1. Log in to API Server as an administrator (admin).

  2. Select Settings > Server.

  3. In the OData section on the Server tab, enter the URL that you want in the Base URL text box.

When URLs that reference API Server are generated (for example, metadata URLs), they point to this custom base URL.

Apache Tomcat Server

Deploying the WAR File

You have two options for deploying a WAR file to Tomcat.

  • Copy the WAR file into the webapps folder.

  • Deploy the WAR file from within the management console in Tomcat. The Tomcat documentation covers this method in more detail. See the documentation for your version of Tomcat.

It is possible that the WAR file might exceed the default maximum size that is allowed for file uploads in Tomcat. To overcome errors during deployment, you can edit the web.xml file of the manager application to allow larger files. Depending on your Tomcat configuration, this file might reside in /usr/share/tomcat7-admin/manager/WEB-INF or in another similar directory. In this file, you can change the size, in bytes, of the maximum allowed file size. For example, to allow deployment of a 200-MB WAR file, edit the following values to change the maximum allowed file size:

<multipart-config>
	<!-- 200MB max -->
	<max-file-size>209715200</max-file-size>
	<max-request-size>209715200</max-request-size>
	<file-size-threshold>0</file-size-threshold>
</multipart-config>

Allowing Apache Tomcat Users to Access CData API Server

Assign the cdata_admin role to the user that you want to be the administrator of the application. If you use the default user realm for Tomcat, you can add these roles by editing the tomcat-users.xml file, which resides in CATALINA_BASE/conf/. In the following example, the admin user has been given the necessary roles for administrative access to the application:

<user name="admin" password="admin" roles="cdata_admin,admin-gui,manager-gui,manager-status,manager-script,manager-jmx" />

Configuring Data-Directory Permissions

Specify Read/Write access to the appropriate data directory (listed below) for the user of the process that runs the Java servlet container.

  • Microsoft Windows: C:\\ProgramData\\CData\\

  • Linux: ~/cdata/

Note: In certain Linux distributions, some additional kernel security modules like Red Hat SELinux might disable Write access to the data directory. To enable access, please consult the documentation of the kernel security module.

Restart your Tomcat server for the changes to take effect. You can now log in to the application.

Setting Up a Load-Balancing Configuration

To set up a load-balancing configuration in Tomcat, you must ensure that synchronization is maintained for the following items:

  • the API Server application file (apiserver.war)

  • JDBC drivers that are used to connect to your data sources

In Tomcat, you can define those as resources in your server.xml file, within the <Host> tags. The following example shows this configuration:

<Host>
  <Context path="/apiserver">
    <Resource name="jdbc/APP_USERS" auth="Container" type="javax.sql.DataSource"
      maxActive="100" maxIdle="30" maxWait="10000"
      driverClassName="cdata.jdbc.mysql.MySQLDriver"
      url="jdbc:mysql:Server=MyServer;Port=3306;Database=MyDatabaseB;User=MyUser;Password=MyPassword;"/>
  </Context>
</Host>

An attribute factory might be required in the <Resource> path, depending on the version of Tomcat that you are using. If it is required, the configuration should resemble this example:

<Host>
  <Context path="/apiserver">
    <Resource name="jdbc/APP_USERS" auth="Container" type="javax.sql.DataSource"
      factory="org.apache.tomcat.jdbc.pool.DataSourceFactory"
      maxActive="100" maxIdle="30" maxWait="10000"
      driverClassName="cdata.jdbc.mysql.MySQLDriver"
      url="jdbc:mysql:Server=MyServer;Port=3306;Database=MyDatabase;User=MyUser;Password=MyPassword;"/>
  </Context>
</Host>

If the base URL of API Server does not correspond to the server on which API Server is installed, you might need to configure the base URL manually. To do so, follow these steps:

  1. Log in to API Server as an administrator (admin).

  2. Select Settings > Server.

  3. In the OData section on the Server tab, enter the URL that you want in the Base URL text box.

When URLs that reference API Server are generated (for example, metadata URLs), they point to this custom base URL.

Managing Users

The Java version of the API Server web application uses forms authentication.

In Java, the user roles and passwords are managed in the Java realm configuration for your web server. See your web server’s documentation from how to configure a user’s roles and password. The application requires the cdata_admin role.