Adabas REST Server Configuration

#### Search Results

Search

# Adabas REST Server Configuration

The Adabas REST Interface is a sub-component of the Adabas installation. It is used to access data from any programming language that supports HTTP requests and to request and monitor Adabas administration tasks.

You must install The Adabas REST Interface separately from the Adabas product installation.

This document is organized as follows:

- Prerequisites

- Configuration

- Runtime

- Authentication

## Prerequisites

The Adabas REST server is initially installed as a service task. To manually uninstall or install the service task, use either the system_service.sh or system_service.bat script.

To configure the server, you must first access an Adabas database using one of the following methods.

To connect to an Adabas database with | Use
--- | ---
Adabas TCP/IP | `dbid(adatcp://host:port)`
Entire Net-Work | `dbid(tcpip://host:port)` To access a remote Adabas database via Entire Net-Work, configure the corresponding Adabas Directory Server.
local Adabas calls | `dbid(adatcp://host:0)`

## Configuration

The server is configured during the Adabas RESTful administration installation process. The configuration parameters are defined in config.xml. This file is located in the configuration subdirectory of the Adabas RESTful administration installation. The configuration file looks as follows:

    <RestServer>
        <Server>
            <Content directory="examples" />
            <Service port="8190" type="http" />
            <Service port="8191" type="https">
                <KeyStore file="keys/keystore.jks" />
                <KeyPassword password="test123" />
            </Service>
            <LoginService module="" webTokenExpires="24">
                <Administrators file="${SAG}/configuration/administrator.xml"></Administrators>
                <Users file="${SAG}/configuration/users.xml"></Users>
                <AuthenticationServer module="" type="file">
                    <Realm file="${SAG}/configuration/realm.properties"></Realm>
                </AuthenticationServer>
            </LoginService>
            <Shutdown passCode="shut123" />
        </Server>
        <Directory url="file:xtsurl.cfg" />
        <Mapping>
            <Database dbid="24" file="4" />
            <Database dbid="23" file="250" />
            <Database dbid="100(adatcp://databasehost:61100)" file="250" />
        </Mapping>
        <DatabaseAccess global="false">
            <Database dbid="100" />
        </DatabaseAccess>
    </RestServer>

`<Server>` contains the basic attributes for running the REST server:

- `<Content>` defines the directory of the static HTML files used to provide the REST service. The example subdirectory provides an example application to help you learn more about accessing Adabas using the REST interface.

- `<Service>` sets the TCP/IP listening port for HTTP and HTTPS requests. The access URL for the example application looks as follows: `https://localhost:/port`.

  For HTTPS access, define the `<KeyStore>` and `<KeyPassword>` attributes to set the necessary SSL certificates.

  Note
  The provided keystore.jks file is only an example keystore with self-signed certificates. You must not use them in a production environment.

- `<LoginService>` defines the authentication method used by the REST server.

  The possible values for `type` are: `file`, `pam` (using system login for UNIX), and `system` (using system login for Windows).

- `<Shutdown>` defines the password for the shutdown command of the REST server. This password is an additional validation measure against unauthorized shutdown of the server. You can shut down the server manually with the `service.sh stop` script.

`<Directory>` sets the reference to the Adabas Directory Server. All directory information required to accomplish communication between clients and servers is obtained from the Directory Server. A file reference such as `file:directory/xtsurl.cfg` points to a file which contains the access URLs of remote databases. A URL reference such as `tcpip://host:4952` points to the Directory Server URL.

`<Mapping>` connects the unique Adabas map definitions to the REST service. The Adabas Client for Java uses map definitions to map database names and long name fields to short names. Use Natural DDMs to define the long names. To create long field names, use the Adabas Data Designer. The Adabas data maps are stored in an Adabas file. Each database can contain multiple mapping files, but at least one mapping file must define the long name references.

`<DatabaseAccess>` determines whether direct database references are allowed. Direct database references use the Adabas database ID to request Adabas data. The two valid attributes for `<Database>` are: `dbid` (to set the database ID) and `url` (to set an access path to a remote database). If the `global` attribute is set to `true`, all known local databases can be accessed directly. If `global` is set to `false`, you will not be able to access the database directly using http://rest server:port/rest/db/dbid. You must explicitly enable access by setting the database ID using the `Databse` configuration.

## Runtime

The Adabas RESTful server is part of the system service startup process.

The wrapper.log file in the log directory stores the output of the server log. The server.log file stores trace and debug information.

You can also start the server manually with the `service.sh run` script on UNIX/Linux and `service.bat run` on Windows platforms. The manual start opens a console window where the REST server generates the output.

The REST server example page can be accessed via`http://localhost:port` or `https://localhost:port`. The default user name is "admin" with the password "manage". Change the password or remove the default user password of the admin from the realm.properties file. You can add new users with the service.sh or service.bat script.

## Authentication

The Adabas RESTful server supports file-based authentication.

The security.conf file configures the JAAS security classes used to set up the authorization. The following modules are predefined in the delivered configuration:

Module | Description
--- | ---
Adabas | Create file-based authorization with the realm.properties file.
LocalUnix | Use the Software AG local access security library (SSX) to enable system authentication.
LocalWindows | Use the local system authentication.

- Adabas

- UNIX Platforms

- Windows Platforms

### Adabas

With the Adabas module, you can create file-based authorization with the realm.properties file. The REST server supports a realm with minimal authentication.

In order to set up authentication with MD5 or SHASUM hash encoding, modify the realm.properties file from the configuration subdirectory. This file contains the username and password information. By default, the user is "admin" with password "manage".

The format of the password file is as follows: `user name:user password, roles of the user`. The user password can be prefixed with the hashsum MD5: or SHA: algorithm name, which represent the md5sum or shasum hash of the password.

For example:

    Administrator: MD5:70682896e24287b0476eff2a14c148f0, sagadmin, jobadmin
    sag:  MD5:20384856e54267b7488eefea1ac1a8fa, saguser
    user: MD5:d47f18dc7780fe47c24759714e2cd58f, saguser

The user roles are defined in the configuration file. For example, you can define the role for job control as follows:

    <Job role="jobadmin" use_role="false" />

This configuration can also apply to file upload and download rights for `<Directory>` and for controlling administration tasks with `<Admin>`.

To add a new user to realm.properties, start the `server.<sh or bat> add_user` command, and enter the new user and password.

### UNIX Platforms

The Software AG SSX modules use the Pluggable Authentication Module (PAM) to authenticate the username and password on UNIX.

For detailed information on how to use PAM, see Software GmbH security eXtensions Administrator's Guide > Using the Pluggable Authentication Module (PAM) on UNIX.

To configure PAM with Adabas REST service, add the PAM configuration file in config.xml for `module`:

    <AuthenticationServer module="file" type="pam"></AuthenticationServer>

Where “file” represents the PAM configuration file to use.

For example:

    <AuthenticationServer module="login" type="pam"></AuthenticationServer>

If AuthenticationServer module is an empty string, the default built-in login configuration file will be used.

### Windows Platforms

For local Windows authentification, use the Waffle Windows Authentication Framework.

### On this page

- Prerequisites
- Configuration
- Runtime
- Authentication