On Linux, the server part of the Natural Web I/O Interface runs in the background as a so-called daemon.
This document covers the following topics:
The Natural Web I/O Interface daemon is installed with Natural for Linux if the corresponding option is set during the installation. See the Installation documentation for further information.
Setting up the Natural Web I/O Interface on Linux consists of the following steps:
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 $NAT_HOME/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.
Besides the settings for the Natural environment, additional settings for the Natural Web I/O Interface environment must be set. Ensure that the environment settings for Natural are set by the natenv environment script. The nwoenv environment script is called by the natenv environment script. Therefore, the Natural Web I/O Interface environment will be set with the Natural environment if it is set after the Natural Web I/O Interface installation.
If the Natural Web I/O Interface environment is to be separate from the Natural environment, use the shell script nwoenv or nwoenv.csh by entering one of the following commands:
source nwoenv
source nwoenv.csh
These scripts can be found after the installation in $NAT_HOME/INSTALL.
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 when the machine starts/stops.
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 $NAT_HOME/nwo/$NWONODE is created. The template files located in $NAT_HOME/nwo/node-name are then copied to this new directory.
The Natural Web I/O Interface-specific settings are shown below:
| Environment Variable | Description |
|---|---|
NWODIR |
The home directory for the product located at $NAT_HOME/nwo. |
NWONODE |
The name of the node (machine) on which the Natural Web I/O Interface is installed. |
NWO_SRVDCONF |
The configuration file $NAT_HOME/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. |
Access the directory $NAT_HOME/nwo 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.
The following directories are created when Natural is installed together with the Natural Web I/O Interface on a Linux system:
| Directory | Description |
|---|---|
| $NAT_HOME | Top-level Natural directory. |
| $NATDIR | Only used for compatibility with previous versions. Top-level Natural directory. |
| $NATDIR/$NATVERS | Only used for compatibility with previous versions. The version subdirectory has been removed. Since $NATVERS is set to ".", it equals $NAT_HOME and $NATDIR. |
| $NWODIR | Directory with the Natural Web I/O Interface components for the current version. |
| $NWONODE | Contains the name of the machine (uname
-n).
|
| $NAT_HOME/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). |
| $NAT_HOME/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.
When the Natural installation has finished, the directory $NAT_HOME/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:
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
The following commands can be specified at the Linux 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:
|
The configuration file nwosrvd.conf contains information needed for the Natural Web I/O Interface daemon. It has the following content:
[Miscellaneous] Logging=I [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 [HA] ha=no
| Section in Configuration File | Description |
|---|---|
[Miscellaneous] |
The key
See also Logging Information. |
[Host] |
The hostname used. (optional) |
[PasswdArguments] |
The key |
[PasswdMessages] |
The keys in this section define the messages that are to be returned by the
system ( Password Mechanism
The password and new password are encrypted on the client side and decrypted on the Linux side. A maximum of 8 characters is allowed. 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
Linux command |
[SSL] |
The key See also SSL Support. |
[PAM] |
The key PAM itself also has a configuration file or section (depends on the PAM
implementation); the PAM configuration name must be Note: |
[HA] |
The key ha is used to define whether HA
protocol is to be used. One of the following values can be specified:
"yes" or "no".
|
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.
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 $NAT_HOME/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 a 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.
The shell script will receive the following arguments:
| Order | Argument | Description |
|---|---|---|
| 1 | IPAddress |
The client IP address from where the session is opened.
Note: |
| 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:
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.
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_PF_MSG_LINES_NATIVE_FORMAT=["YES"|"NO"]
This environment variable defines how the PF keys and the message line are to be shown.
YES The PF key prompting lines and the message line are shown as output text, as in the native Linux environment. NO The PF keys are rendered as buttons and the message line is rendered as a special message line element. 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.
PAM_OIDC is a Pluggable Authentication Module (PAM) that authenticates users with an OpenID Connect (OIDC) token.
A version of OpenSSL 3 or OpenSSL 1.1.1 must be installed on the system.
For version 1.1.1, the pam_oidc.so from the subfolder openssl1.1.1 should be used.
The PAM module is located at ...
$NWODIR/pam
The package brings along the following resources:
|
readme.txt |
A readme with instructions |
|
nwosrvd_example |
An example configuration for /etc/pam.d/nwosrvd |
|
pam_oidc.so |
Contains the Pluggable Authentication Modules for OpenID Connect build for OpennSSL 3 |
|
openssl1.1.1/pam_oidc.so |
Contains the Pluggable Authentication Modules for OpenID Connect build for OpennSSL 1.1.1 |
The following signing algorithms are supported:
RS256
RS384
RS512
PS256
PS384
PS512
ES256
ES384
ES512
|
|
Required |
Path to the JSON Web Key Set (JWKS) file. |
|
|
Required |
The issuer URL of the OpenID Connect provider. |
|
|
Required |
The audience claim that the token must contain. |
|
|
Required |
The claim that contains the username. |
|
|
Optional |
A regex to extract the username from the userClaim. |
|
|
Optional |
The party to which the ID Token was issued. |
|
|
Optional |
Authentication Context Class Reference of the token. |
|
|
Optional |
Limit the the max age of the iat. The value is in seconds. 0 is interpreted as no limit. If the iat is older then iatLimit the token is rejected. |
|
|
Optional |
The maximum age of the token in seconds. If the token is older, it will be rejected. |
|
|
Optional |
If verbose is set to true, additional system logs are written. |
A JSON Web Key Set (JWKS) is a JSON document that contains a set of public keys used to verify the signatures of tokens.
A JWKS is obtained from an OIDC provider. Typically, it is available at a well-known URL, following a pattern such as https://example.com/.well-known/openid-configuration, which points to the JWKS URL. In the configuration, the JWKS URL is specified in the field jwks_uri.
Note:
Providers may update their JWKS over time, so it is important to fetch the latest
version periodically. Also, ensure that the JWKS file has appropriate permissions to
prevent unauthorized access.
curl -o exampleJwks.json https://example.com/protocol/openid-connect/certscurl -o googleJwks.json https://www.googleapis.com/oauth2/v3/certs
To validate if the PAM user and the user that issues the tokens match, pam_oidc.so needs a claim that includes the user.
If the user is only part of the user claim, the
userClaimRegex configuration can be used to extract the
username. The username is the sum of all regex capturing groups.
(\w*)@softwareag.com
johnsmith@softwareag.com --> User: johnsmith
(\w*).(\w*)@softwareag.com
John.Smith@softwareag.com --> User: JohnSmith
Leeway is a time buffer used to account for small
differences in system time between the token issuer and the token receiver. It allows
for a tolerance when verifying timestamps in the token, such as the validity period. The
pam_oidc module uses a leeway of 60 seconds.
The pam_oidc.so module uses the Linux Syslog for logging. By default, only a single Syslog entry is added. This entry provides information on whether the authentication was successful or not. Should the authentication fail, the reason will be written into the logs.
If you need additional information, you can use the verbose option. The token itself will never be written to the logs.
With a configuration in rsyslog.d it is possible to redirect the syslog output of the pam_oidc.so.
:msg, contains, "pam_oidc" /var/log/pam_oidc.log & stop
You need to create the log file manually and set the appropriate permissions.
Restart the rsyslog service to apply the changes.
A PAM service can be added in /etc/pam.d/<service_name>.
Commonly, a configuration would look like the following:
auth required pam_oidc.so <arguments>
auth required pam_oidc.so \
jwks=/tmp/googleJwks.json \
issuer=https://accounts.google.com \
userClaim=email aud=account \
userClaimRegex=(.*)@.*\.com
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 |
|---|---|
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 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:
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 is delivered in
<install-dir>/common/security/openssl
and openssl is delivered in
<install-dir>/common/security/openssl/bin.
Set the environment variable so that it points to the file openssl.cnf:
set OPENSSL_CONF=<install-dir>/common/security/openssl/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.
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.
See also Configuring the Natural Web I/O Interface Daemon on Linux.
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.
The Linux 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:
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 $NAT_HOME/nwo/$NWONODE nwosrvd.sh portnumber [start|stop]
Alternatively:
cd $NAT_HOME/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>
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 $NAT_HOME/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:
$NAT_HOME/bin/natural parm=parameter-file etid=$$ >output-file 2>&1
$NAT_HOME/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.