
	Version 6.3.13 for UNIX	SEARCH CONTENTS \| PDF BOOKS \| HOME UP PREV NEXT

— Natural Web I/O Interface —

Installing and Configuring the Natural Web I/O Interface Server

On UNIX, the server part of the Natural Web I/O Interface is implemented as a daemon.

This document covers the following topics:

Installing the Natural Web I/O Interface Daemon
Before You Start
Setting Up the Natural Web I/O Interface Components
Directories
Configuring the Natural Web I/O Interface Daemon on UNIX
Logging Information
SSL Support
Working with the UNIX Components of the Natural Web I/O Interface

Installing the Natural Web I/O Interface Daemon

The installation of the Natural Web I/O Interface daemon is part of the Natural for UNIX installation.

Before You Start

This section contains important information on the necessary activities before installing Natural Web I/O Interface daemon.

The Natural Web I/O Interface daemon $SAG/nat/$NATVERS/nwo/bin/nwosrvd

needs a Tcl shared library which is delivered in the directory $SAG/nat/$NATVERS/lib,
is linked with the runpath /opt/softwareag/nat/$NATVERS/lib,
will be installed with permissions 6755 (s-bit).

Since the s-bit is used, $LD_LIBRARY_PATH will not be searched. Therefore, ensure that the Natural Web I/O Interface daemon will find the Tcl shared library by

installing Natural into /opt/softwareag,
setting a symbolic link from opt/softwareag to your current $SAG directory, or
making the Tcl shared library available from a system directory.

Setting Up the Natural Web I/O Interface Components

Setting up the Natural Web I/O Interface on UNIX consists of the following steps:

Step 1: Stop the Natural Web I/O Interface Daemons
Step 2: Establish the Environment
Step 3: Install Natural and the Natural Web I/O Interface
Step 4: Check the Environment Variables for the Natural Web I/O Interface
Step 5: Read the READ_NWO Files

Step 1: Stop the Natural Web I/O Interface Daemons

This step is only required for an upgrade installation. It is not required when you install the Natural Web I/O Interface for the first time.

Stop the nwosrvd process using the following command:
```
nwosrvd.sh portnumber stop
```
Or use the script $NATDIR/$NATVERS/INSTALL/nwosrvd.bsh which will be generated during the Natural Web I/O Interface installation for a specified port.
```
nwosrvd.bsh stop
```
Repeat the above command (with an adapted port in script nwosrvd.bsh, if applicable) for each Natural Web I/O Interface service that is needed.

Step 2: Establish the Environment

Ensure that the environment settings in the file sagenv.new are correct and set. Note that the nwoenv environment script will be called by the natenv environment script.

Or use the shell script nwoenv.csh by entering the following command:
```
source nwoenv.csh
```
This script can be found after the installation in $NATDIR/$NATVERS/INSTALL.

Step 3: Install Natural and the Natural Web I/O Interface

The Natural Web I/O Interface can be selected in the Choose Packages screen during the Natural installation.

Optionally, you may install a runlevel script to start/stop a Natural Web I/O Interface daemon and start the Natural Web I/O Interface daemon on a specified port. After the Natural installation has finished, the Natural Web I/O Interface must be activated by starting Natural through a Natural Web I/O Interface client on Windows.

When a runlevel script is used, the Natural Web I/O Interface daemon can only be administered by the user "root".

When you install Natural with the Natural Web I/O Interface, the directory $NATDIR/nwo/$NWONODE is created. The template files located in $NATDIR/$NATVERS/nwo/node-name are then copied to this new directory.

Step 4: Check the Environment Variables for the Natural Web I/O Interface

The Natural Web I/O Interface-specific settings are shown below:

Environment Variable	Description
`NWODIR`	The home directory for the product located at $NATDIR/$NATVERS/nwo.
`NWONODE`	The name of the node on which the Natural Web I/O Interface is installed.
`NWO_SRVDCONF`	The configuration file $NATDIR/nwo/$NWONODE/nwosrvd.conf for the Natural Web I/O Interface daemon.
`NWO_TIMEOUT`	The maximum time, in seconds, that the Natural Web I/O Interface daemon will wait for a response. "0" means no timeout. The Natural Web I/O Interface daemon will terminate when it receives the timeout.

Step 5: Read the READ_NWO Files

Access the directory $NATDIR/$NATVERS and check the files READ_NWO.TXT and READ_NWO.FIX for any version-specific installation considerations concerning the particular platform.
Add the services as described in the file READ_NWO.TXT.

Directories

The following directories are created when Natural is installed together with the Natural Web I/O Interface on a UNIX system:

Directory	Description
$NATDIR	Top-level Natural directory.
$NATDIR/$NATVERS	Directory with all components for the current Natural version.
$NWODIR	Directory with the Natural Web I/O Interface components for the current version.
$NWONODE	Contains the name of the machine (`uname -n`).
$NATDIR/$NATVERS/INSTALL	Shell scripts and environment files for the Natural Web I/O Interface (nwoenv, nwoenv.csh).
$NWODIR/bin	Natural Web I/O Interface executable files (nwosrvd, nwosrvd.tr).
$NWODIR/node-name	Contains the template files (nwosrvd.sh, nwo.sh, nwosrvd.conf).
$NWODIR/nwoexuex/userexit1	Contains the files for building the libnwouserexit1.
$NWODIR/nwoexuex/userexit2	Contains the files for building the libnwouserexit2.
$NATDIR/nwo/$NWONODE	Work directory, contains the configuration files (nwosrvd.sh, nwo.sh, nwosrvd.conf).

Note:
The above table lists the most important directories and files.

Configuring the Natural Web I/O Interface Daemon on UNIX

When the Natural installation has finished, the directory $NATDIR/nwo/$NWONODE contains the files nwosrvd.conf, nwosrvd.sh and nwo.sh.

The configuration of the Natural Web I/O Interface daemon can be done using the Natural Web I/O Interface daemon commands or by editing the configuration file nwosrvd.conf.

The following topics are covered below:

Natural Web I/O Interface Daemon Commands
nwosrvd.conf - Configuration File for the Natural Web I/O Interface Daemon
nwosrvd.sh - Shell Script for Starting and Stopping the Natural Web I/O Interface Daemon
nwo.sh - Shell Script for Starting Natural
Environment Variables

Natural Web I/O Interface Daemon Commands

The following commands can be specified at the UNIX command prompt:

Command	Description
`nwosrvd –help`	Shows all available Natural Web I/O Interface daemon commands and subcommands.
`nwosrvd –v`	Shows the version of the Natural Web I/O Interface daemon.
`nwosrvd nnnn`	Defines the listening port number.
`nwosrvd –show`	Shows the configuration of the Natural Web I/O Interface daemon.
`nwosrvd -config keys`	Changes the configuration of the Natural Web I/O Interface daemon. The following keys can be specified: `-userexit1=pathname` The message defined with this key is saved in the `UserExit1` key of the configuration file nwosrvd.conf, section `[UserExits]`. `–userexit2=pathname` The message defined with this key is saved in the `UserExit2` key of the configuration file nwosrvd.conf, section `[UserExits]`. `–passparam=parameters` The message defined with this key is saved in the `Parameters` key of the configuration file nwosrvd.conf, section `[PasswdArguments]`. `–passold=message` The message defined with this key is saved in the `EnterOldPassword` key of the configuration file nwosrvd.conf, section `[PasswdMessages]`. `–passnew=message` The message defined with this key is saved in the `NewPassword` key of the configuration file nwosrvd.conf, section `[PasswdMessages]`. `–passreenter=message` The message defined with this key is saved in the `ReEnterNewPassword` key of the configuration file nwosrvd.conf, section `[PasswdMessages]`. `–passsuccess=message` The message defined with this key is saved in the `PasswordSuccessful` key of the configuration file nwosrvd.conf, section `[PasswdMessages]`. `–logging=option` The option defined with this key is saved in the `Logging` key of the configuration file nwosrvd.conf, section `[Miscellaneous]`. `-ssl=[yes\|no]` The option defined with this key is saved in the `ssl` key of the configuration file nwosrvd.conf, section `[SSL]`. `-pam=[yes\|no]` The option defined with this key is saved in the `pam` key of the configuration file nwosrvd.conf, section `[PAM]`. PAM itself also has a configuration file or section (depends on the PAM implementation); the PAM configuration name must be `nwosrvd`. To remove any user exits from the configuration, enter the following command: `nwosrvd –config –userexit1=` Once the configuration was changed, the Natural Web I/O Interface daemon must be restarted.

nwosrvd.conf - Configuration File for the Natural Web I/O Interface Daemon

The configuration file nwosrvd.conf contains information that the user exits need for the Natural Web I/O Interface daemon. It has the following content:

[Miscellaneous]
Logging=I

[UserExits]
; UserExit1=/FS/sag/nat/nwoexuex/userexit1/libnwouserexit1.so
; UserExit2=/FS/sag/nat/nwoexuex/userexit2/libnwouserexit2.so

[PasswdArguments]
Parameters=

[PasswdMessages]
EnterOldPassword=Enter existing login password:
NewPassword=New Password:
ReEnterNewPassword=Re-enter new Password:
PasswordSuccessful=passwd: password successfully changed for*

[SSL]
ssl=no

[PAM]
pam=no

Section in Configuration File	Description
`[Miscellaneous]`	The key `Logging` is used to define the amount of logging information that is to be reported. One of the following options can be specified: `E` for errors. `W` for warnings. `I` for information. See also Logging Information.
`[UserExits]`	Two user exits can be defined: `UserExit1` The library that is defined by `UserExit1` contains the following function: `int nwo_CheckUsernameAndPassword(const char pUsername, const char pPassword, const char pNewPassword, char pErrorMessage)` If the key `UserExit1` is defined in the configuration file, the function `nwo_CheckUsernameAndPassword` is responsible for checking the user name and password. If a new password is received, user exit 1 is also responsible for changing the password. In the case of an error, the return code of the function must be "0"; in this case, the `pErrorMessage` is returned to the client. When user name and password are correct, the return code must be a value other than "0". "1" indicates that the Natural session runs under the user who started the daemon (authentication). "2" indicates that the Natural session runs under the login user (authentication and impersonation). `UserExit2` The library that is defined by `UserExit2` contains the following functions: `int nwo_Messages(int iNumberOfMessages, char pMessage[])` `iNumberOfMessages`: Number of messages returned in the array. `pMessage`: Array of messages. If the key `UserExit2` is defined in the configuration file, the function `nwo_Messages` is called when a new connection (client) is accepted and the messages returned by this function are sent to the client. User exit 2 may be used, for example, to send a message such as the following: "For maintenance reasons, the Natural application XXXXX will be down next monday, from 18:00 until 19:00". In the case of an error, the return code of the function must be "0". After the function `nwo_Messages` has been called, the function `nwo_FreeMessages` is called. `int nwo_FreeMessages(int iNumberOfMessages, char *pMessage[])` `iNumberOfMessages:` Number of messages. `pMessage`: Array of messages. If the key `UserExit2` is defined, the function `nwo_FreeMessages` is called to free any resources (normally memory) allocated in the function `nwo_Messages`. In the case of an error, the return code of the function must be "0".
`[PasswdArguments]`	The key `Parameters` is used to define any additional parameter(s) that have to be passed to the `passwd` command.
`[PasswdMessages]`	The keys in this section define the messages that are to be returned by the system (`passwd` command) when a user changes the password. If any of these messages is not identified by the daemon, an error will be returned to the client. Password Mechanism The password and new password are encrypted on the client side and decrypted on the UNIX side. A maximum of 8 characters is allowed. If user exit 1 is active, user name, password and new password are passed to the user exit. If user exit 1 is not active, the daemon checks whether user name and password are correct for the system. If a new password is sent, the daemon changes the password by calling the UNIX command `passwd`.
`[SSL]`	The key `ssl` is used to define whether the SSL protocol is to be used. One of the following values can be specified: "yes" or "no". See also SSL Support.
`[PAM]`	The key `pam` is used to define whether the PAM (Pluggable Authentication Modules) mechanism is to be used. One of the following values can be specified: "yes" or "no". PAM itself also has a configuration file or section (depends on the PAM implementation); the PAM configuration name must be `nwosrvd`.

nwosrvd.sh - Shell Script for Starting and Stopping the Natural Web I/O Interface Daemon

The shell script nwosrvd.sh is used to start and stop the Natural Web I/O Interface daemon. For further information, see Starting and Stopping the Natural Web I/O Interface Daemon.

nwo.sh - Shell Script for Starting Natural

In order to start a Natural session, the Natural Web I/O Interface service executes a shell script. The shell script prepares the environment for the Natural session and eventually starts Natural. It must therefore contain all environment settings needed to run the Natural session.

The shell script receives certain parameters from the Natural Web I/O Interface client. The parameters can either be evaluated by the shell script itself or passed on to Natural. A client who wants to start a Natural session can specify the shell script to be used.

The shell script nwo.sh is called from the Natural Web I/O Interface daemon in order to start a Natural session. It has the following content:

#!/bin/sh
 
echo "Number of arguments $#" > nwo.log

IPAddress=""
ClientId=""
CodePage=""
CustomParameters=""
NaturalParameters=""

if [ "$1" != "null" ]
then
  IPAddress="$1"
fi

if [ "$2" != "null" ]
then
  ClientId="$2"
fi

if [ "$3" != "null" ]
then
  CodePage="$3"
fi

if [ "$4" != "null" ]
then
  CustomParameters="$4"
fi

if [ "$5" != "null" ]
then
  NaturalParameters="$5"
fi

#echo "IP Address="$IPAddress >> nwo.log
#echo "Client Id="$ClientId >> nwo.log
#echo "Code Page="$CodePage >> nwo.log
#echo "Custom Parameters="$CustomParameters >> nwo.log
#echo "Natural Parameters="$NaturalParameters >> nwo.log
#echo "NWO_BROWSER_IO="$NWO_BROWSER_IO >> nwo.log

$NATDIR/$NATVERS/bin/natural $NaturalParameters etid=$$ > /dev/null 2>&1

You have to create such a shell script for each Natural application. It can have any name and it must be located in an directory which is defined in the environment variable PATH.

The name of the shell script is taken from the configuration file for the session. It is taken from the configuration file section that is defined for the session that the user has selected in the logon page. For further information, see Configuring the Client.

Arguments

The shell script will receive the following arguments:

Order	Argument	Description
1	`IPAddress`	The client IP address from where the session is opened. Note: If there is a proxy, this will not be the IP address of the client workstation. Instead, it will be the IP address of the proxy.
2	`ClientId`	The user name from the logon page is passed as the client ID.
3	`CodePage`	The encoding that is defined in the configuration file for the session. This value can be used to set the Natural system variable `*CODEPAGE`.
4	`CustomParameters`	From the logon page, it is possible to pass any values to the script in order to execute any desired action. Example: you pass a small text to the script which describes an error. When the script receives this error text, it sends it as an e-mail to the administrator.
5	`NaturalParameters`	These can be any Natural parameters. The parameters are either defined in the configuration file for the session, or they are entered in the logon page. The following is an example of the corresponding entry in the configuration file: `<natural_parameter>parm=nwoparm\ stack=(logon\ mylib;start-program;fin)<natural_parameter>` The language that is selected in the logon page is added as the first element to the Natural parameters in the form "ulang=x".

Arguments 1 to 4 can be used to audit the client, to allow to run an application from a specific PC (identifying the IP address), to build statistics, to do special actions, etc.

Environment Variables

In the shell script, several environment variables can be set for the Natural session that is started by the daemon:

NWO_ENABLE_ACK=["YES"|"NO"]

This environment variable is used for asynchronous screens (SET CONTROL N).

YES	When asynchronous screens are sent to the client, Natural will wait to receive an ACK package before the next screen can be sent.
NO	No waiting between asynchronous screens. Default value.

NWO_TIMEOUT=[number-of-seconds]

The maximum time, in seconds, that Natural waits to receive any input from the client before it closes the session. If the number of seconds is "0", Natural waits infinitely (no timeout). The default value is "0".

Error NAT5466 is returned at timeout. In Natural, the application can handle this error and decide how to continue or terminate.

Logging Information

The logging information system reports errors, warnings and/or session information, depending on the option that has been defined with the following Natural Web I/O Interface daemon command:

nwosrvd -config -logging=option

option can be one of the following:

Option Description

Option	Description
`E`	Error. When this option is specified, the Natural Web I/O Interface daemon reports only errors. In the case of an error, the daemon usually exits immediately.
`W`	Warning. When this option is specified, the Natural Web I/O Interface daemon reports errors and warnings for uncritical errors. In the case of a warning, the daemon continues to run.
`I`	Information. When this option is specified, the Natural Web I/O Interface daemon reports errors, warnings and information. The information messages allow to check the session parameters, IP address, etc.

E

Error.

When this option is specified, the Natural Web I/O Interface daemon reports only errors.

In the case of an error, the daemon usually exits immediately.

W

Warning.

When this option is specified, the Natural Web I/O Interface daemon reports errors and warnings for uncritical errors.

In the case of a warning, the daemon continues to run.

I

Information.

When this option is specified, the Natural Web I/O Interface daemon reports errors, warnings and information.

The information messages allow to check the session parameters, IP address, etc.

Help information, for example, on how to run, configure and install the Natural Web I/O Interface daemon is always provided. The messages which inform you when the daemon has been started or stopped are also part of the help information.

To find out which logging option is currently active, enter the following Natural Web I/O Interface daemon command:

nwosrvd -show

The logging messages are shown directly for the standard output. The format of the messages is as in the following example:

%NWOSRVD-E: 18.01.2008 14:55:20 NWO_SRVDCONF is not established.

The following information is provided:

%NWOSRVD is the internal name of the Natural Web I/O Interface daemon.
The message type is shown directly after %NWOSRVD. It can be one of the following: -E (error), -W (warning), -I (information), or -H (help).
Date and time when the message was reported.
Any text or message which pertains to the error, warning, information or help.

If you want to save these messages, you have to redirect the standard output to a file.

Example for csh:

nwosrvd 5454 >& nwosrvd_5454.log

Example for sh, ksh and bsh:

nwosrvd 5454 >& nwosrvd_5454.log 2>&1

SSL Support

SSL is used for a secure connection between the Natural Web I/O Interface server and the Natural Web I/O Interface client or Natural for Ajax. Server authentication cannot be switched off. A certificate and a private key is always required on the server.

To establish an SSL connection, you have to proceed as described in the following topics:

Creating an SSL Certificate and a Private Key
Configuring the Daemon
Configuring the Client

Creating an SSL Certificate and a Private Key

To create and use an SSL certificate and a private key on the server, proceed as described below.

Adapt the example configuration file openssl.cnf to your needs.

Note:
openssl.cnf and openssl are delivered in $NATDIR/$NATVERS/bin.

Set the environment variable so that it points to the file openssl.cnf:

set OPENSSL_CONF=$NATDIR\$NATVERS\bin\openssl.cnf
export OPENSSL_CONF;

Generate a certificate signing request:
```
openssl req –new > server.cert.csr
```

Generate a private RSA key:

openssl rsa –in privkey.pem –out server.cert.key

Generate a self-signed certificate:
```
openssl x509 –in server.cert.csr –out server.cert.crt –req –signkey server.cert.key –days 365
```
It is important that the name of the generated certificate is server.cert.crt and that the name of the generated private key is server.cert.key.

Note:
The certificate can be self-signed or it can be signed by a CA (Certificate Authority) such as VeriSign.
Put the generated files into the same directory as the scripts which start the Natural Web I/O Interface server.

Configuring the Daemon

After you have created an SSL certificate and a private key as described above, proceed as follows:

Change the configuration of the Natural Web I/O Interface daemon using the following command:
```
nwosrvd -config -ssl yes
```
Restart the Natural Web I/O Interface daemon.

Configuring the Client

After you have configured the daemon as described above, you have to import the generated server.cert.crt file to a truststore on the client. For information on how to do this for the Natural Web I/O Interface client, see Configuring SSL. If you are using Natural for Ajax as the client, see Configuring SSL in the Natural for Ajax documentation.

Working with the UNIX Components of the Natural Web I/O Interface

The UNIX components of the Natural Web I/O Interface are used to start the Natural applications linked with the Natural Web I/O Interface library.

The following topics are covered below:

Starting and Stopping the Natural Web I/O Interface Daemon
Starting a Natural Application

Starting and Stopping the Natural Web I/O Interface Daemon

The Natural Web I/O Interface daemons are responsible for accepting new sessions.

Since the daemon checks the user name and password, the following permissions must be set as follows (for setting the permissions, you must be super-user):

chmod 6755 nwosrvd.sh

chown root nwosrvd.sh

The Natural installation attempts to set permissions and owner. However, you have to verify this before you start the Natural Web I/O Interface daemon.

The daemon can be started and stopped using the following command:

cd $NATDIR/nwo/$NWONODE
nwosrvd.sh portnumber [start|stop]

Alternatively:

cd $NATDIR/$NATVERS/INSTALL
nwosrvd.bsh  [start|stop]

Note:
The daemon must be started on a port which is not yet used.

The shell script you have created must be in the same directory as the nwosrvd.sh script. It will be used by the Natural Web I/O Interface (configuration file for the session; see Configuring the Client). The following is an example of the corresponding entry in the configuration file:

<natural_program>your-shell-script.sh</natural_program>

Starting a Natural Application

Almost any Natural application can be used with the Natural Web I/O Interface. See also Differences between the Natural Web I/O Interface Client and Terminal Emulation.

To start a new Natural application with the Natural Web I/O Interface, proceed as follows:

Create a new parameter file from NWOPARM using the Configuration Utility.
In this new parameter file, modify the STACK command as follows:
```
logon library; startprogram; fin
```
Note:
Only "real" Natural applications can be used. The Natural Main Menu cannot be used as a Natural application.

Add the new service as follows:

Look for a port number which is not yet used.
Create a new shell script (similar to nwo.sh) for starting the Natural application:
```
cd $NATDIR/nwo/$NWONODE
copy nwo.sh your-shell-script.sh
vi your-shell-script.sh
```
You have to decide which (last) line you will use in the script. Use one of the following:
```
$NATDIR/$NATVERS/bin/natural parm=parameter-file etid=$$ >output-file 2>&1
```
```
$NATDIR/$NATVERS/bin/natural $5 etid=$$ >output-file 2>&1
```
When using the line with parm=parameter-file, the above step in which you modify the STACK command is mandatory.

When using $5, the Natural parameter (parameter-file and STACK command) is taken from the configuration file for the session (see Configuring the Client). The following is an example of the corresponding entry in the configuration file:
```
<natural_parameter>parm=myparm stack=(logon mylib;menu;fin)<natural_parameter>
```
If you want to define special settings for the Natural session, you can set the environment variables in your shell script. See above.
Set the permissions for the shell script which starts the service as follows:
```
chmod 775 script-name
```

The service is now available for use with a PC.

SEARCH CONTENTS | PDF BOOKS | HOME UP PREV NEXT