Version 25.3.9411

• Launching the CData API Server Instance
• Accessing CData API Server from Your Browser
• Managing the AMI
  • Accessing the Instance from a Secure Shell (SSH)
  • Controlling the CData API Server Service
  • Installation Directory
    • db Folder
    • libs Folder
    • Configuring the Application Directory
  • Application Database
  • Ports and SSL
  • Upgrading
  • Adding a New Connector

The Amazon Machine Edition of CData API Server is a Linux-based instance with API Server preconfigured and ready to run, with little additional configuration necessary. This offering is available in the Amazon Web Services Marketplace by searching for CData API Server.

Launching the CData API Server Instance

1. Click Continue to Subscribe in the upper right corner to subscribe to the Amazon Machine instance (AMI). Then, accept the terms and conditions. After you subscribe, you can configure a new instance of API Server.

2. Configure your instance, as follows:

   1. Choose the instance type.

   2. Set the security group. API Server runs on the default HTTPS port (443). Ensure that this port is accessible from the IP address that you use to connect to API Server.

   3. Create a new key pair or choose an existing one. Ensure that you save the PEM file. That file is used later to access the AMI via a secure shell (SSH).

3. Click Launch to create the EC2 instance and start API Server.

Accessing CData API Server from Your Browser

After you launch the API Server instance, it is listed in your Amazon EC2 management console. Then, you can access API Server in your browser with the following URL:

      https://InstancePublicDNS

Log in with the following credentials:

• User: The default username is admin.

• Password: The password is the instance’s randomly generated instance Id prefixed with APIServer24:. For example, if the instance identifier is i-1234a, the initial password to access API Server is APIServer24:i-1234a. After you log in, you can change the password for the admin user from the upper right corner of the browser.

Now, you can follow the instructions in Connections Page to create and manage your connections.

Managing the AMI

The CData API Server AMI works immediately, without additional configuration. The following sections provide information about management tasks for API Server that are AMI specific.

Accessing the Instance from a Secure Shell (SSH)

Connecting to the EC2 instance via SSH is useful for advanced configuration of the service. The CData API Server AMI is based on a standard Ubuntu 22 virtual machine (VM), and the main user is ubuntu. You can connect to the instance via SSH by using the key pair that you select when you launch the instance, as shown below:

ssh -i MyKeyPair.pem ubuntu@InstancePublicDNS

Controlling the CData API Server Service

API Server is run as a systemd service (rather than being run in-process) in an AMI deployment. The service definition file is available in the following location:

etc/systemd/system/apiserver.service

You should use the following systemd commands to stop, start, and restart API Server:

sudo systemctl restart apiserver
sudo systemctl stop apiserver
sudo systemctl start apiserver

Note: Before you make any changes to the API Server application, you should stop the service first.

Installation Directory

All the API Server configuration and application data resides in the application directory. The default application directory (_ApplicationDirectory_) is shown below:

/opt/apiserver

You can configure the application directory’s path in the apiserver.properties file, as described in Configuring the Application Directory.

db Folder

The db folder contains the database files for the default Derby database. Note that you can configure the application database to use an external database, as described in Application Database.

libs Folder

The libs folder is where the application reads external resources, like drivers for connectors that require an external driver. Place JAR files in this folder and restart API Server to enable the application to read these resources.

Configuring the Application Directory

You can configure the ApplicationDirectory location in the apiserver.properties file, which is located next to the apiserver.jar file.

To configure ApplicationDirectory to a non-default location:

1. Locate the following snippet within the apiserver.properties file:

   cdata.app.directory =
   

2. Add the path to the new location for the application directory, as shown in this example:

   cdata.app.directory=/mnt/shared/apiserver
   

Application Database

By default, API Server uses a Derby database for connection, application settings, and general application logs. This Derby database is in the db folder of the application directory, as described in the previous section.

You can configure API Server to use an external database like MySQL. As with the application directory, you configure the application database in the apiserver.properties file.

To configure the application database:

1. Locate the following snippet in the apiserver.properties file:

   cdata.app.db=
   

2. Set the connection string to the target database that you want, as shown in this example:

   cdata.app.db=jdbc:cdata:mysql:Server=MySQLServer;Port=3306;Database=mysql;User=User;Password=Password;useconnectionpooling=true
   

3. Restart the API Server service so that the changes in the previous steps take effect.

Ports and SSL

By default, API Server listens for SSL connections (HTTPS) on port 8443. API Server cannot bind to the default HTTPS port (443) because of permissions restrictions. Therefore, an iptables rule redirects traffic from port 443 to port 8443. No further action is required for standard HTTPS traffic to reach the API Server web server.

API Server AMIs include a self-signed certificate for use when it is hosting an SSL server. If the SSL server needs to be hosted by using a certificate signed by a certificate authority (CA), then you should contact the CA directly to obtain a certificate.

If you want to add a plaintext/non-SSL port (for example, HTTP instead of HTTPS), you need to edit the apiserver.properties file to enable the plaintext listener. Because of permissions restrictions, the listener cannot bind directly to port 80. Therefore, it is established on port 8181, and an iptables rule must be established to forward traffic from port 80 to port 8181, as follows:

1. Stop the API Server service by submitting this command:

   sudo systemctl stop apiserver
   

2. Locate the http.port snippet in the apiserver.properties file:

   cdata.http.port=
   

3. Set the port to 8181 and save the changes.

4. Create a new iptables rule to forward traffic from port 80 to port 8181:

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

5. Restart the API Server service so that the changes in the previous steps take effect.

Upgrading

Upgrading api server requires launching a new instance of the latest API Server AMI. Before launching the new instance, you should copy data from the old instance so that the application configuration is preserved in the new instance.

API Server includes a migration tool that enables you to export and import the configured connections easily in the application.

To use the migration tool:

1. Navigate to the Migration tab on the Settings page.

2. Click Export to export all settings (connections, users, and history) to a ZIP file.

3. Import the configuration settings from the same Migration tab into the new instance.

4. Click Import.

5. Navigate to the ZIP file that you created in step 2.

Adding a New Connector

You can add new connectors through the UI by following the steps outlined in Connections Page. However, you might be required to update or add the connector manually to your instance by following these steps:

1. Use SSH to navigate to your AMI.

2. Stop the Jetty service by submitting this command:

   sudo systemctl stop apiserver
   

3. Open a new command prompt and copy the connector to your instance by using the following scp command:

   scp -i ./FolderPath/MyKeyPair.pem ./FolderPath/cdata.jdbc.ProviderName.jar ubuntu@InstancePublicDNS:/home/ubuntu/cdata.jdbc.ProviderName.jar
   

4. Copy the connector to the libs folder by submitting this command:

   sudo cp ./home/ubuntu/cdata.jdbc.ProviderName.jar /opt/apiserver/libs/cdata.jdbc.ProviderName.jar
   

5. Restart the API Server service by submitting this command:

   sudo systemctl start apiserver