Operating Natural Development Server

#### Search Results

Search

# Operating Natural Development Server

This document describes how to operate Natural Development Server in a Linux and Cloud-based environment.

The following topics are covered:

- Introduction

- Starting the Development Server

- Determining the Screen Size for Web I/O

- Terminating the Development Server

- Getting Help

- NDV Configuration File

- SSL (TLS) Support

- PAM Authentication and System User Impersonation

- Trace

- Error Messages

## Introduction

Natural Development Server for Linux and Cloud represents a listener process which waits for incoming Natural clients to connect. For every connection request, the listener starts a Natural process which will then communicate with the corresponding client. Natural Development Server can only be run in a valid Natural environment. For the currently applicable version of Natural for Linux and Cloud, refer to https://empower.softwareag.com/.

## Starting the Development Server

The development server can be started as follows:

    natdvsrv [start-options] [Natural-parameters]

where

`-p[ort][=]<port>` | Mandatory start option. Starts the server on the specified port.
`-c[lient][=]<type>` | Optional start option. Defines the types of clients which are permitted to connect to the server. <type> can be one of the following:
`NAT` | Only Natural for Windows (Natural Studio) clients are permitted to connect to this server.
`ONE` | Only NaturalONE clients are permitted to connect to this server.
`ANY` | Both Natural for Windows (Natural Studio) and NaturalONE clients are permitted to connect to this server.
If this start option is not specified, the server will use `ANY` as the default. If a client which is not permitted tries to connect to the server, Natural error `NAT7742` will be issued, indicating that the current IDE is not permitted. Note: If Natural Security is installed, the types of clients permitted to connect to the server can be controlled by setting the Natural Security option Natural client access.
`-s[tart][=]<image>` | Optional start option. The Natural image to be used as the server session. Any valid Natural image can be used. If this start option is not specified, the server will use "natural" as the default session image. For the currently applicable version of Natural for Linux and Cloud, refer to https://empower.softwareag.com/.
`[Natural-parameters]` | Optional. The Natural parameters to be used in conjunction with the session image. The syntax is identical to starting a Natural session with Natural parameters.

### Examples

    natdvsrv -port=1234

starts the listener on port 1234, (implicitly) uses the image "natural" as the server session, and (implicitly) permits all types of clients to connect to the server.

    natdvsrv -p=1234 -c=ONE

starts the listener on port 1234, (implicitly) uses the image "natural" as the server session, and permits only NaturalONE to connect to the server.

    natdvsrv -p1234 -cNAT parm=myparm stack=(LOGON mylib)

starts the listener on port 1234, (implicitly) uses the image "natural" as the server session, and permits only Natural for Windows (Natural Studio) to connect to the server. When a client session connects, the listener starts Natural with the parameter module "myparm" and applies a logon to "mylib".

    natdvsrv -p=1234 -s=naturalsql

starts the listener on port 1234, uses the image "naturalsql" as the server session, and (implicitly) permits all types of clients to connect to the server.

## Determining the Screen Size for Web I/O

By default, a screen size of 80x24 is used for web I/O with the Natural Web I/O Interface. This is determined by the following variables:

Variable Name | Description
--- | ---
`NWO_NCOLUMNS` | The number of columns to be used. Default: 80.
`NWO_NROWS` | The number of rows to be used. Default: 24.

If a different screen size is to be used, you have to set these variables before starting the development server.

### Example

    #!/bin/sh

    NWO_NCOLUMNS=100
    export NWO_NCOLUMNS
    NWO_NROWS=50
    export NWO_NROWS
    natdvsrv -port=4714 parm=myparm

This shell script starts a development server on port 4714 with a screen size of 100x50.

## Terminating the Development Server

The development server can be terminated as follows:

    natdvsrv -t[erminate][=]<port>

where <port> is the port number of the development server to be terminated.

Terminating the server will also terminate all Natural sessions started by the server.

Note:
Alternatively, a development server session can be terminated via the `kill <process-id>` command.

### Example

    natdvsrv -t1234

terminates the listener and all Natural sessions launched by the listener.

## Getting Help

    natdvsrv [-h[elp]]

displays the help information on the available options.

## NDV Configuration File

When a new development server is started, the file NDVSERVER.PRU located in your installation directory, in the subdirectory Natural\Prof, will be accessed to add information about the server.

When a server is terminated, the following steps are performed:

1. A search of the specified port takes place in order to find the server's process ID. This process ID is then used to terminate the server.

2. The entry of the terminated server in the configuration file will then be removed.

## SSL (TLS) Support

Although we are always talking about the commonly known phrase SSL (Secure Sockets Layer) the technology actually used is TLS (Transport Layer Security). SSL and TLS basically do the same thing. They are encrypted protocols for data transfer.

The development server is using SSL/TLS to enable a secured data transfer with the involved NDV clients, such as the NaturalONE clients. Server authentication cannot be switched off. Due to the fact that asymmetrical encryption is used, a certificate (including a public key) and a private key is always required on the server.

To establish an SSL connection, you have to proceed as described in the topics below.

- Creating an SSL Certificate and a Private Key

- Start the Natural Development Server

- Configuring the Client

### Creating an SSL Certificate and a Private Key

For sensitive public connections it is always a good idea to get an SSL certificate from a Certificate Authority (CA) such as Verisign. However, when using servers in a local environment it is also possible to use self-signed certificates. The following steps explain how a self-signed certificate can be created via the openssl tool:

To create a self-signed SSL certificate and a private key on the server, using openssl:

1. Copy the example configuration file openssl.cnf (located in <installdir>/common/security/openssl or, in case of Red Hat Linux, located in /etc/pki/tls) to a different directory, for example to the <yourdirectory>/bin directory of your Natural installation.

2. Adapt the copied configuration file openssl.cnf to your needs.

3. Set the environment variable (depending on the used shell) so that it points to the file openssl.cnf:

   - For csh and sh:

         setenv OPENSSL_CONF  <yourdirectory>/openssl.cnf

   - For bash:

         export OPENSSL_CONF=<yourdirectory>/openssl.cnf

4. Generate a certificate signing request:

       openssl req -new > ndv.server.cert.csr

   With the `openssl req -new` command we create a private key and a certificate signing request (CSR) for the root CA. You will be asked for a passphrase to protect the private key. The `openssl req` command uses the configuration parameters given in the `[req]` section of the configuration file openssl.cnf.

5. Generate a private RSA key issuing the following command:

       openssl rsa -in privkey.pem -out ndv.server.cert.key

6. Generate a self-signed certificate issuing the following command:

       openssl x509 -in ndv.server.cert.csr -out ndv.server.cert.crt -req -signkey ndv.server.cert.key -days 365

   It is important that the name of the generated certificate is ndv.server.cert.crt and that the name of the generated private key is ndv.server.cert.key.

An alternative to the steps above would be to use a certificate generator within your company, creating a certificate chain with a corresponding root CA and also a private key.

Once the certificate is available, it must be copied in conjunction with the private key into the bin directory of your Natural installation. These two files must always have the name ndv.server.cert.key (representing the private key) and ndv.server.cert.crt (representing the self-signed certificate).

### Start the Natural Development Server

Start the Natural development server with the option `-ssl`. For example:

    natdvsrv -port=4711 -ssl

### Configuring the Client

For information on how to use the certificate store in NaturalONE, refer to SSL under Setting the Preferences or Accessing a Remote Development Environment or Using SSL - all to be found in the section Using NaturalONE of the NaturalONE documentation.

## PAM Authentication and System User Impersonation

Natural Development Server optionally supports authentication via PAM (Pluggable Authentication Modules). This enables integration with our OpenID Connect PAM module for token-based authentication through NaturalONE.

Notes:

1. It is strongly recommended to use PAM authentication only in combination with SSL.
2. When running with Natural Security, PAM authentication is used as single sign-on (SSO) for Natural Security.

- Enabling PAM Authentication

- System User Impersonation

### Enabling PAM Authentication

PAM authentication is enabled when Natural Development Server is started with the `-use-pam-auth` option. The PAM configuration from /etc/pam.d/natdvsrv is then used.

Example:

    natdvsrv -port=4711 -ssl -use-pam-auth

Notes:

1. The `-use-pam-auth` option is optional. Without this option, authentication is performed as before.
2. The PAM configuration must be set up in /etc/pam.d/natdvsrv in advance.
3. If PAM authentication fails, access is denied.

When PAM authentication is enabled, client login attempts are validated according to the PAM policy defined in natdvsrv.

The following PAM types are supported:

- `auth`: Authentication.

- `account` (optional): Account management.

Account processing is not mandatory.

### System User Impersonation

After a successful PAM authentication, optional system user impersonation may be performed. This means that the Natural process runs in the context of the authenticated system user. To enable system user impersonation, you must either start Natural Development Server as root or ensure that it possesses the following Linux capabilities:

- `cap_setuid`: Allows setting the user ID (UID) of the process.

- `cap_setgid` (optional): Allows setting the group ID (GID) of the process.

These capabilities allow the server to switch to the respective system user's context after successful PAM authentication, without running as root.

#### Example

To set the required capabilities on the natdvsrv binary, use the following command:

    sudo setcap cap_setuid,cap_setgid+ep /path/to/natdvsrv

To verify the capabilities, use the following command:

    getcap /path/to/natdvsrv

## Trace

A server trace can be established via the built-in trace macros.

Important
In order to generate trace files for the listener and all started sessions, a plus sign (+) must be used as the trace file name. Otherwise, a new development server session will overwrite an existing trace file.

The name of the listener trace file is constructed as shown below:

    natdvsrv_port

where

`port` | is the assigned port number.

The name of a session trace is constructed as shown below:

    natdvsess_ipinfo_ pid_port

where

`ipinfo` | is the client connection's IP address/name.
`pid` | is the process ID of the development server session.
`port` | is the port of the listener process.

### Example

    setenv  NCTR_STATE    1
    setenv  NCTR_CONFIG   path/nctr.cfg
    setenv  NCTR_OUTPUT   /tmp/+

After a listener process was started on port 4712 and two clients have connected, the following trace files are generated into the directory /tmp:

    natdvsrv_4712
    natdvsess_pc1_1055_4712
    natdvsess_pc2_1045_4712

Note
Be careful when using the plus sign (+) notation. This could cause a lot of trace files to be generated.

## Error Messages

When a development server is started or terminated, the following error messages can occur:

Error Number | Error Message | Action
--- | --- | ---
66 | The port number is missing. | Provide a valid port number.
67 | The specified port number is already in use. | Use a port which is not yet occupied on the machine.
68 | Invalid syntax [%syntax%] encountered. | The options used to start or terminate the server are used wrongly according to [%syntax%].
70 | Invalid port number encountered. | Use a correct port number inside the valid range of 0 - 9999 and do not use other characters or digits.
71 | Listen on specified port failed. | Try again with a different port number.
78 | The specified server session [%session-name%] is not accessible. | Check that the specified session can be found via the `PATH` environment variable or that it is located inside `$NATBIN`.
79 | The port number [%number%] exceeds upper limit (99999). | Use a port inside the valid range.
80 | Invalid combination of options [%options%] encountered. | Check that the specified options can be used together.
81 | NDV server could not be terminated (Reason: %reason%). | Check the reason: Check that the server with the specified port is running. Check that you have the rights to terminate the server.
82 | Error accessing file `'NDVSERVER.PRU'`. | Check that the file is available and that it has a valid content. If the file is corrupted, delete the file.

### On this page

- Introduction
- Starting the Development Server
- Determining the Screen Size for Web I/O
- Terminating the Development Server
- Getting Help
- NDV Configuration File
- SSL (TLS) Support
- PAM Authentication and System User Impersonation
- Trace
- Error Messages