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:
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 Software AG Directory Server. |
| local Adabas calls | dbid(adatcp://host:0) |
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 Software AG 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.
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.
The Adabas RESTful server supports file-based authentication.
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. |
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.
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 AG 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.
For local Windows authentification, use the Waffle Windows Authentication Framework.