Configuring the Natural Web I/O Interface Server

#### Search Results

Search

# Configuring the Natural Web I/O Interface Server

This document describes how to configure a Natural Web I/O Interface server.

The following topics are covered:

- Configuration Requirements for z/OS

- Web I/O Interface Server Configuration File for z/OS

- Web I/O Interface Server Configuration Parameters

- Web I/O Interface Server Configuration File Example

- Web I/O Interface Server Data Sets for z/OS

- Web I/O Interface Server User Exits

## Configuration Requirements for z/OS

The following topics are covered:

- Language Environment Parameter Settings

- External Security Configuration

- SSL TLS Support

- Configuring Port Sharing

### Language Environment Parameter Settings

A Natural Web I/O Interface server requires the following z/OS language environment parameter configuration:

Parameter | Definition
--- | ---
`POSIX(ON)` | Enables a Natural Web I/O Interface server to access the POSIX functionality of z/OS. If you start a Natural Web I/O Interface server server with `POSIX(OFF)`, it terminates immediately with a user abend U4093 and the system message EDC5167. IBM supplies the default "OFF".
`TRAP(ON,NOSPIE)` | Defines the abend handling of the LE/370 environment:
`ON` | Enables the Language Environment condition handler.
`NOSPIE` | Specifies that the Language Environment will handle program interrupts and abends via an ESTAE, that is, the Natural abend handler will receive control to handle program interrupts and abends.
If you do not specify `TRAP(ON,NOSPIE)`, the Natural abend handling does not work properly. IBM supplies the default (`ON,SPIE`).
`TERMTHDACT(UADUMP)` | Defines the level of information that is produced in case of an abend. The option `UADUMP` generates a Language Environment `CEEDUMP` and system dump of the user address space. The `CEEDUMP` does not contain the Natural relevant storage areas. IBM supplies the default (`TRACE`).
`ENVAR(TZ=…)` | The `ENVAR` option enables you to set Linux environment variables. The only environment variable applicable for the Natural Web I/O Interface server is `TZ` (time zone). This variable allows you to adjust the timestamp within the Natural Web I/O Interface server's trace file to your local time. Example:
    ENVAR(TZ=CET-1DST) CET
- 1 hour daylight saving time

You can set the z/OS language environment parameters:

- With the `PARM` parameter specified in the `EXEC` card of the Natural Web I/O Interface server startup job. The length of the options is limited by the maximum length of the `PARM` parameter.

- Assemble an LE/370 runtime option module `CEEUOPT` and link it to the Natural Web I/O Interface server load module.

### External Security Configuration

If you configure the Web I/O Interface server to impersonate the Web I/O Interface clients in the server (Web I/O Interface server configuration parameter `SECURITY_MODE``=IMPERSONATE or IMPERSONATE_LOCAL`), the Web I/O Interface server must run "program-controlled". Under RACF, the following definitions are required for the Web I/O Interface server:

- The resource `BPX.SERVER` must be defined and the Web I/O Interface server account must have READ access to this resource.

- The `LOAD` data sets defined in the Web I/O Interface server startup job definition must be defined to the program class "**".

      ralt program ** addmem('natural load library') uacc(read)
      ralt program ** addmem('NWO load library'//NOPADCHK) uacc(read)
      ralt program ** addmem('user load library'//NOPADCHK) uacc(read)

- `SETR WHEN(PROGRAM) REFRESH`

Additionally, each client connecting to the server must be defined in RACF and must be granted to use the z/OS Linux System Services.

### SSL TLS Support

- SSL/TLS over AT-TLS
- Maintenance of Certificates under z/OS
- Using RACF Key Rings
- Using Key Databases
- How to configure TCP/IP for AT-TLS?
- How to Verify AT-TLS Configuration?
- Frequently Asked Questions
- Generation of a Natural Web I/O Interface Server Certificate

#### SSL/TLS over AT-TLS

SSL/TLS support for the Natural Web I/O Interface server is based on the z/OS Communication Server component AT-TLS (Application Transparent-Transport Layer Security).

AT-TLS provides SSL/TLS encryption as a configurable service for sockets applications. It is realized as an additional layer on top of the TCP/IP protocol stack, which exploits the SSL/TLS functionality in nearly or even fully transparent mode to sockets applications. AT-TLS offers three modes of operation. See z/OS Communications Server, IP Programmer’s Guide and Reference. Chapter: Application Transparent Transport Layer Security (AT-TLS).

These modes are:

- #### Basic

  The sockets application runs without modification in transparent mode, unaware of performing encrypted communication via AT-TLS. Thus legacy applications can run in secured mode without source code modification.

- #### Aware

  The application is aware of running in secured mode and is able to query TLS status information.

- #### Controlling

  The sockets application is aware of AT-TLS and controls the use of AT-TLS encryption services itself. This means, the application is able to switch between secured and non secured communication.

Natural Web I/O Interface server uses the Basic mode for its SSL/TLS implementation. That is, a server configured as SSL/TLS server rejects requests from non-secured clients.

#### Maintenance of Certificates under z/OS

Certificates, which are to be used with AT-TLS, can be maintained in two ways under z/OS. They are stored either in RACF key rings or in key databases, which are located in the z/OS Linux file system. Which of these proceedings actually applies is defined in the AT-TLS Policy Agent Configuration file for the z/OS TCP/IP stack, which is used by the Natural HTTPS client.

IBM delivers a set of commonly used CA root certificates with each z/OS system delivery. If key rings are going to be used to hold server certificates, those root certificates must be manually imported into the key rings by the system administrator. If IBM delivers newer replacements for expired root certificates, all affected key rings have to be updated accordingly.

Unlike key rings, key databases contain the current set of root certificates automatically after they have been newly created. However, the need for maintaining always the latest set of root certificates applies to the key database alternative as well.

#### Using RACF Key Rings

In RACF, digital certificates are stored in so-called key rings. The RACF command `RACDCERT` is used to create and maintain key rings and certificates, which are contained in those key rings.

See z/OS Security Server RACF Security Administrator’s Guide, Chapter: RACF and digital certificates - RACF and key rings, and z/OS Security Server RACF, Command Language Reference, Chapter: RACF command syntax - RACDCERT.

#### Using Key Databases

Alternatively to RACF, certificates can be kept in key databases, which reside in the z/OS Linux services file system. For the creation and maintenance of key databases, the `GSKKYMAN` utility has to be used.

See z/OS Cryptographic Services PKI Services Guide and Reference, Chapter: Appendix B. Using a gskkyman key database for your certificate store.

#### How to configure TCP/IP for AT-TLS?

Proceed as follows:

1. In the TCP/IP configuration file, set the option `TTLS` in the `TCPCONFIG` statement.

2. Configure and start the AT-TLS Policy Agent. This agent is called by TCP/IP on each new TCP connection to check if the connection is SSL/TLS.

3. Create the Policy Agent file containing the AT-TLS rules. The Policy Agent file contains the rules to stipulate which connection is SSL/TLS.

See also z/OS Communications Server: IP Configuration Guide, Chapter: Application Transparent Transport Layer Security data protection.

The Sample Policy Agent file defines the server with the job name starting with `NWODEV` and listening at port 4843 to use SSL/TLS.

The sample expects the certificate database on the HFS file /u/admin/CERT.kdb.

    TTLSRule                          ConnRule01~1
    {
      LocalAddrSetRef                 addr1
      RemoteAddrSetRef                addr1
      LocalPortRangeRef               portR1
      RemotePortRangeRef              portR2
      Jobname                         NWODEV*
      Direction                       Inbound
      Priority                        255
      TTLSGroupActionRef              gAct1~NWO_Server
      TTLSEnvironmentActionRef        eAct1~NWO_Server
      TTLSConnectionActionRef         cAct1~NWO_Server
    }
    TTLSGroupAction                   gAct1~NWO_Server
    {
      TTLSEnabled                     On
    }
    TTLSEnvironmentAction             eAct1~NWO_Server
    {
      HandshakeRole                   Server
      EnvironmentUserInstance         0
      TTLSKeyringParmsRef             keyR1
    }
    TTLSConnectionAction              cAct1~NWO_Server
    {
      HandshakeRole                   Server
      TTLSCipherParmsRef              cipher1~AT-TLS__Silver
      TTLSConnectionAdvancedParmsRef  cAdv1~NWO_Server
    }
    TTLSConnectionAdvancedParms       cAdv1~NWO_Server
    {
      CertificateLabel                NDV_TEST_CERT
    }
    TTLSKeyringParms                  keyR1
    {
      Keyring                         /u/admin/CERT.kdb
      KeyringStashFile                /u/admin/CERT.sth
    }
    TTLSCipherParms                   cipher1~AT-TLS__Silver
    {
      V3CipherSuites                  TLS_RSA_WITH_DES_CBC_SHA
      V3CipherSuites                  TLS_RSA_WITH_3DES_EDE_CBC_SHA
      V3CipherSuites                  TLS_RSA_WITH_AES_128_CBC_SHA
    }
    IpAddrSet                         addr1
    {
      Prefix                          0.0.0.0/0
    }
    PortRange                         portR1
    {
      Port                            4843
    }
    PortRange                         portR2
    {
      Port                            1024-65535
    }

#### How to Verify AT-TLS Configuration?

Check Policy-Agent job output `JESMSGLG` for:

    EZZ8771I PAGENT CONFIG POLICY PROCESSING COMPLETE FOR <your TCP/IP address space>: TTLS

This message indicates a successful initialization.

Check Policy-Agent job output `JESMSGLG` for:

    EZZ8438I PAGENT POLICY DEFINITIONS CONTAIN ERRORS FOR <your TCP/IP address space>: TTLS

This message indicates errors in the configuration file. Check the syslog.log file for further information.

Does the configuration rule cover the server?

Try to connect the server and check syslog.log for:

    EZD1281I TTLS Map   CONNID: 00018BED LOCAL: 10.20.91.61..4843 REMOTE: 10.20.160.47..4889 JOBNAME: NWODEVvr USERID: NWOSRV TYPE: InBound STATUS: Enabled RULE: ConnRule01~1 ACTIONS: gAct1 eAct1~NWO_Server cAct1~NWO_Server

The above entry indicates that the connection to Port 4843 is SSL/TLS enabled.

#### Frequently Asked Questions

#### Is there more information about problem determination?

See z/OS Communications Server, IP Diagnosis Guide, Chapter: Diagnosing Application Transparent Transport Layer Security (AT-TLS)

#### How to switch on P-agent trace?

See z/OS Communications Server, IP Configuration Reference, Chapter: Syslog deamon, and z/OS Communications Server, IP Configuration Guide, Chapter: Base TCP/IP system – TCP/IP Customization - Configuring the syslog daemon (syslogd).

#### Error at connection establishment

Find return code RC and corresponding `GSK_` function name in P-agent trace.

Get description of the return code from z/OS Cryptographic Services, System Security Sockets Layer Programming, Chapter: : messages and codes – SSL function return codes.

Sample trace with `trace=255`:

    EZD1281I TTLS Map   CONNID: 00002909 LOCAL: 10.20.91.61..1751 REMOTE: 10.20.91.117..443 JOBNAME: KSP USERID: KSP TYPE: OutBound STATUS: A
    EZD1283I TTLS Event GRPID: 00000003 ENVID: 00000000 CONNID: 00002909  RC:    0 Connection Init
    EZD1282I TTLS Start GRPID: 00000003 ENVID: 00000002 CONNID: 00002909 Initial Handshake ACTIONS: gAct1 eAct1 AllUsersAsClient HS-Client
    EZD1284I TTLS Flow  GRPID: 00000003 ENVID: 00000002 CONNID: 00002909  RC:    0 Call GSK_SECURE_SOCKET_OPEN - 7EE4F718
    EZD1284I TTLS Flow  GRPID: 00000003 ENVID: 00000002 CONNID: 00002909  RC:    0 Set GSK_SESSION_TYPE -  CLIENT
    EZD1284I TTLS Flow  GRPID: 00000003 ENVID: 00000002 CONNID: 00002909  RC:    0 Set GSK_V3_CIPHER_SPECS -  090A2F
    EZD1284I TTLS Flow  GRPID: 00000003 ENVID: 00000002 CONNID: 00002909  RC:    0 Set GSK_FD - 00002909
    EZD1284I TTLS Flow  GRPID: 00000003 ENVID: 00000002 CONNID: 00002909  RC:    0 Set GSK_USER_DATA - 7EEE9B50
    EZD1284I TTLS Flow  GRPID: 00000003 ENVID: 00000002 CONNID: 00002909  RC:  435 Call GSK_SECURE_SOCKET_INIT - 7EE4F718
    EZD1283I TTLS Event GRPID: 00000003 ENVID: 00000002 CONNID: 00002909  RC:  435 Initial Handshake 00000000 7EEE8118
    EZD1286I TTLS Error GRPID: 00000003 ENVID: 00000002 CONNID: 00002909 JOBNAME: KSP USERID: KSP RULE: ConnRule01  RC:  435 Initial Handshake
    EZD1283I TTLS Event GRPID: 00000003 ENVID: 00000002 CONNID: 00002909  RC:    0 Connection Close 00000000 7EEE8118

#### Generation of a Natural Web I/O Interface Server Certificate

Under z/OS, SSL/TLS certificates can be produced with the Linux System Services utility `GSKKYMAN`. The following steps have to be executed for the production of a new certificate, which is to be used for the SSL/TLS secured communication between Natural Web I/O Interface client and server:

1. Start a shell session out of TSO or connect via telnet to the z/OS Linux shell.

2. Start `GSKKYMAN`.

3. Create a new – or open an existing key database.

4. Create a self-signed certficate, for example, of type "User or server certificate with 2048-bit RSA key".

5. Export the certificate to a (HFS) file. Choose Base64 ASN.1 DER as export format.

This generated file can now be copied to the Natural Web I/O Interface client(s) using FTP with ASCII transfer format. On the client side, the received file should be stored with the file name suffix .CER. The certificate can now be used by the Natural Web I/O Interface client.

If certificates are kept in a RACF key ring, the generated certificate has to be imported into the appropriate key ring using the `RADCERT` command.

Certificates, which are produced on a different platform, for example, on a Windows PC, can be imported into a RACF key ring or into a key database as well.

Detailed information about the use of the `GSKKYMAN` utility can be found in the IBM Communications server documentation, e.g in the following manuals:

z/OS Communications Server, IP Configuration Guide

or

z/OS Cryptographic Services, System Secure Sockets Layer Programming

For the generation of certificates under Windows, a free downloadable utility named Ikeyman is available on several websites. Ikeyman is an IBM product as well and maps the functionality of `GSKKYMAN` to the Windows platform.

### Configuring Port Sharing

The TCP/IP port sharing component of the z/OS TCP/IP Communications subsystem allows multiple listeners to listen on the same combination of port and IP address. To enable this in the TCP/IP stack, you must add the `SHAREPORT` or `SHAREPORTWLM` keyword to the PORT profile statement that reserves the TCP port for the server instances. You can find detailed information in section PORT Statement, chapter TCP/IP profile (PROFILE.TCPIP) and Configuration Statements of the IBM manual z/OS Communications Server: IP Configuration Reference.

You can start the NWO server as explained in section Starting the Natural Web I/O Interface Server. You must define the used port with the `PORT_NUMBER` parameter in the configuration file of the NWO server. If port sharing is enabled, the started task can be executed multiple times to start multiple instances of an NWO server that listens on the same port.

Note
All servers must be started with the same configuration file.

- Server ID
- Reliability
- Scheduling
- TRACE, STDOUT, and STDERR

#### Server ID

Since the server ID is used to identify a server in the server directory, you must set a unique server ID. The server ID is passed as a parameter to the NWO server. You must set the parameters in the PARM card of the started task. For example:

    //NWOSRV  EXEC PGM=NATRNWO,REGION=0M,TIME=20,
    //  PARM=('POSIX(ON) STACK(64K,32K,ANY,FREE) TRAP(ON,NOSPIE) ',
    //    'TERMTHDACT(UADUMP),ENVAR(TZ=CET+0DST) /SERVERID')

#### Reliability

If multiple NWO servers are listening on a port and one server fails, the workload can still be done by the remaining servers. From a user point of view, the service offered by the NWO server remains available.

#### Scheduling

If a request for a new connection arrives, it is in the responsibility of the z/OS operating system to pass the request to one of the listening servers. The connections are distributed across the available servers using a weighted round-robin distribution based on the Servers' accept Efficiency Fractions (SEFs). Once a session is started, it is executed on this server, until it is finished.

You can identify a session in the trace file with the following piece of code:

    Start of Session:
    26 10:16:45 0000000E Worker task active, SID=DED9D087D842B606, client: USER

    End of session:
    26 10:21:53 0000000E Worker task disconnect, client: USER
    26 10:21:53 0000000E Free LTCB...and finish

#### TRACE, STDOUT, and STDERR

Each server has its own `STGTRACE`, `STGSTDO`, and `STDSTGE`, which are part of the job log of each server. It is possible to redirect the output of the files to a sequential dataset, but you must ensure that each server is assigned its own sequential dataset. Otherwise, the output of the files cannot be assigned to a particular server.

## Web I/O Interface Server Configuration File for z/OS

A configuration file is allocated to the name `<serverid>`C (for example, `NWOS1C`) or `STGCONFG` alternatively.

The configuration file is a text file located on a data set or on an HFS file under z/OS.

The configuration file contains the server configuration parameters in the form of a `keyword=value` syntax. In addition, it may contain comments whose beginning is marked with a hash symbol (#).

See also the Web I/O Interface Server Configuration File Example shown below.

## Web I/O Interface Server Configuration Parameters

The following Web I/O Interface server configuration parameters are available:

- COMPATIBILITY_MODE

- CPU_TIME_TRACE

- CPU_TIME_HISTORY

- FORCE_IPV4

- FRONTEND_NAME

- FRONTEND_OPTIONS

- FRONTEND_PARAMETER

- HANDLE_ABEND

- HOST_NAME

- HTPMON_ADMIN_PSW

- HTPMON_PORT

- IGNORE_PRESENT_SERVER

- INITIAL_USERID

- KEEP_TCB

- O4I

- PASSWORD_MIXEDCASE

- PORT_NUMBER

- SECURITY_MODE

- SECURITY_SYSLOG

- SESSION_PARAMETER

- SESSION_TIMEOUT

- THREAD_NUMBER

- THREAD_SIZE

- TRACE_FILTER

- TRACE_LEVEL

- UPPERCASE_SYSTEMMESSAGES

### COMPATIBILITY_MODE

The current version of NWO presumes to run with the most recent version of Natural. An error `NAT7729 NWO and Natural version do not agree` is issued when running with older Natural versions. This is because NWO must negotiate a subset of functionality with the client at a time when the involved Natural version is not already known.

If you want to run NWO with a previous version of Natural, you can set this parameter to `YES`. It is recommended that you leave this parameter at its default value if you intend to run your NWO with the most recent version of Natural, because in this case `COMPATIBILITY_MODE=YES` would unnecessarily limit the functionality.

Value | Explanation
--- | ---
`YES` | Accept also older versions of Natural. Results in a limitation of the functionality documented with the most recent version.
`NO` | Presume to run with the most recent version of Natural. This is the default value.

Example:

    COMPATIBILITY_MODE=YES

### CPU_TIME_TRACE

This optional configuration parameter specifies a time limit of central processing unit (CPU) time of a transaction. Transactions with a higher CPU time usage than the specified time limit are traced in the trace file. Trace level 30 is required to enable the trace. There are two types of traces: one that shows the CPU time of a single transaction and one that shows the CPU time of an entire session.

Note
A session consists of several transactions.

Example of traces of session DEBE5E3816036616:

    04 14:21:34 00000052 Execute cpu time of session DEBE5E3816036616: 0.001295 s
    04 14:25:51 00000052 Total cpu time of session DEBE5E3816036616: 0.063536 s

The value of `CPU_TIME_TRACE` applies also to the `CPU_TIME_HISTORY` parameter if specified.

The parameter can be changed dynamically in the configuration menu of the HTML Monitor.

Value | Explanation
--- | ---
`time-limit` | CPU time limit in seconds written as a decimal. Valid values are from `0,0` to `65535,0`.
`120,0` | `120,0` seconds. This is the default value.

Example:

    CPU_TIME_TRACE=1,0

The setting in the example traces transactions and sessions with higher CPU time usage than 1,0 seconds.

### CPU_TIME_HISTORY

This optional configuration parameter specifies a buffer that stores the specified number of transactions with the highest central processing unit (CPU) time values.

The entries are sorted by CPU time in descending order. Each stored entry contains the CPU time, the session ID, the day and time, the user ID and type of transaction executed.

The list can be displayed with the HTML Monitor Client in a browser window or with Monitor Client NATMOPI. The number of stored entries can be filtered by setting a CPU time limit with `CPU_TIME_TRACE`. The parameter can be changed dynamically in the configuration menu of the HTML Monitor.

Value | Explanation
--- | ---
`time_history_integer` | Stores the number of highest CPU time values provided. The values are sorted by CPU time in descending order. Valid values are from 1 to 100, and `NO`.
`NO` | CPU time history is off. This is the default value.

Example:

    CPU_TIME_HISTORY=32

The setting in the example stores the 32 highest CPU time values sorted by cpu time.

### FORCE_IPV4

This parameter is only available with Natural Web I/O Interface Version 8.3 or above.

This parameter allows you to enforce the use of communication method IPV4.

Value | Explanation
--- | ---
`YES` | Enforce the use of communication method IPV4.
`NO` | First try communication method IPV6. If this fails give an error message and use communication method IPV4. This is the default value.

### FRONTEND_NAME

This configuration parameter specifies the name of the Natural front-end to be used to start a Natural session. The front-end resides on a PDS member.

Value | Explanation
--- | ---
`frontend-name` | Natural front-end to be used. Maximum length: 8 characters.

No default value is provided.

Example:

    FRONTEND_NAME=NATvrsSV

### FRONTEND_OPTIONS

The values of this configuration parameter may be used to specify additional options for the Natural front-end.

Value | Explanation
--- | ---
`01` | Do not use the Roll Server. This is the default value.
`02` | Clean up roll file at server termination.
`04` | Write GTF trace.
`08` | Write `ETRACE`.
`10` | Front-end automatic termination.
`20` | Write console information.

You may combine the above options as desired in that you add their values and set the result as shown in the example below.

Example:

    FRONTEND_OPTIONS=07

The setting in this example enables the Options `01`, `02` and `04`.

### FRONTEND_PARAMETER

This optional configuration parameter contains additional Natural front-end parameters as specified in the Startup Parameter Area.

Value | Explanation
--- | ---
`parameter-name` | You can define multiple parameters. Each parameter specification is a pair of 8-character strings, the first containing the parameter keyword and the second the parameter value, for example:
    FRONTEND_PARAMETER = 'MSGCLASSX       '

No default value is provided.

For further information, refer to the section Natural in Batch Mode in the Natural Operations for z/OS documentation.

Example:

    FRONTEND_PARAMETER='MSGCLASSX       '

The setting in this example specifies that the default output class for `CMPRINT` is "X".

### HANDLE_ABEND

If an abend occurs in the server processing outside the Natural processing the abend is not trapped by the Natural abend handling. For this reason the NWO server has its own abend recovery.

It is recommended that you leave this parameter on its default value in order to limit the impact of an abend to a single user. If you set the value of this parameter to `NO`, any abend in the server processing terminates the complete server processing. That is, it affects all users running on that server.

Value | Explanation
--- | ---
`YES` | Trap abends in the server processing, write a snap dump and abort the affected user. This is the default value.
`NO` | Suspend the server abend handling.

Example:

    HANDLE_ABEND=NO

### HOST_NAME

This optional configuration parameter is necessary only if the server host supports multiple TCP/IP stacks.

Value | Explanation
--- | ---
`host-name` | If `HOST_NAME` is specified, the server listens on the particular stack specified by `HOST_NAME`, otherwise the server listens on all stacks.

No default value is provided.

Example:

    HOST_NAME=node1

or

    HOST_NAME=157.189.160.55

### HTPMON_ADMIN_PSW

This configuration parameter defines the password required for some monitor activities (e.g. Terminate Server) performed by the HTML Monitor Client.

Value | Explanation
--- | ---
any character string | The password to be entered at the HTML Monitor Client for some monitor activities.

No default value is provided.

Example:

    HTPMON_ADMIN_PSW=GHAU129B

### HTPMON_PORT

A Web I/O Interface server can be configured to host an HTTP monitor task which serves the HTML Monitor Client running in a web browser. It is not required to run this monitor task on each server. A single task allows you to monitor all servers running at one node.

This configuration parameter defines the TCP/IP port number under which the server monitor task can be connected from a web browser.

Value | Explanation
--- | ---
`1 - 65535` | TCP/IP port number.

No default value is provided.

Example:

    HTPMON_PORT=3141

### IGNORE_PRESENT_SERVER

This configuration parameter applies in conjunction with the Web I/O Interface server CICS Adapter.

A Web I/O Interface (NWO) server allocates a so-called "server environment" which contains the server dependent common resources.

This environment is unique for each NWO server and relates to the server name. If an NWO server with Web I/O Interface Server CICS Adapter ends abnormally, it might leave a stuck NWO server environment within the CICS region. This causes that a restart of the server fails with error message NAT9913.

If you start an NWO server with `IGNORE_PRESENT_SERVER=YES`, it might damage an already running server which is using the same server name and the same CICS region.

Value | Explanation
--- | ---
`YES` | Terminate existing CICS server environment.
`NO` | Abort server initialization if a CICS server environment already exist. This is the default value.

Example:

    IGNORE_PRESENT_SERVER=YES

### INITIAL_USERID

At server initialization, the Natural Web I/O Interface server creates a temporary Natural session to obtain the properties of the installed Natural environment.

This configuration parameter specifies the user ID to be used for this Natural session.

Value | Explanation
--- | ---
`userid` | The specified value must not exceed 8 characters, otherwise it is truncated.
`STARGATE` | This is the default value.

Example:

    INITIAL_USERID=NWOINITU

See also Web I/O Interface clients must be defined to Natural Security in the operating-system-specific Natural Web I/O Interface server Installation section.

### KEEP_TCB

By default, the remote Natural session of a mapped environment terminates its TCB whenever you switch the focus within Natural Studio to a different mapped environment. If you toggle the focus back, the remote session is dispatched using a different TCB.

The maximum number of active TCBs is equal to the number of connected clients.

The configuration parameter `KEEP_TCB` specifies whether the remote Natural session should use the same TCB during its entire lifetime. This is required if you use Adabas and the Adabas parameter `ADANAME` is set to `ADAUSER` or if you want to access DB2. It could also be required if you access 3GL programs which need to be executed under the same TCB for successive calls.

Value | Explanation
--- | ---
`YES` | The remote Natural session uses the same TCB during its entire lifetime.
`NO` | This is the default value.

Example:

    KEEP_TCB=YES

### O4I

Note
This parameter is only available with Natural Web I/O Interface Version 8.3 or above.

This parameter allows you to collect server data for Optimize for Infrastructure.

Value | Explanation
--- | ---
`YES` | Collect server data for Optimize for Infrastructure.
`NO` | Do not collect server data for Optimize for Infrastructure. This is the default.

Example:

    O4I=YES

### PASSWORD_MIXEDCASE

This parameter allows you to define whether passwords specified in the connection dialog are translated into upper case or not.

This parameter does only apply with `SECURITY_MODE``=IMPERSONATE, IMPERSONATE_LOCAL` or `IMPERSONATE_REMOTE`.

Value | Explanation
--- | ---
`YES` | Passwords remain in mixed case.
`NO` | Passwords are translated into upper case. This is the default.

Example:

    PASSWORD_MIXEDCASE=YES

### PORT_NUMBER

This configuration parameter defines the TCP/IP port number under which the server can be connected.

Value | Explanation
--- | ---
`1 - 65535` | TCP/IP port number.

No default value is provided.

Example:

    PORT_NUMBER=3140

### SECURITY_MODE

The Natural Web I/O Interface server offers a security concept that also covers the operating system resources. The client credentials are validated at the operating-system-depending security system and the client request is executed under the client's account data.

Using the `SECURITY_MODE` parameter, you can specify at which rank (in batch mode z/OS or under CICS) you want to impersonate the activities of a Web I/O Interface client.

Value | Explanation
--- | ---
`IMPERSONATE_LOCAL` | Impersonation is done within the Natural Web I/O Interface server environment. If the session is dispatched in a remote TP environment (e.g. in CICS using the NWO CICS Adapter), it is still executed anonymous. The client must be defined in the security system of the Web I/O Interface server. It is not required to define the client in a remote TP environment. See also External Security Configuration.
`IMPERSONATE_REMOTE` | No impersonation is done within the Natural Web I/O Interface server environment. If the session is dispatched in a remote TP environment, the client is impersonated. The client must be defined in the security system of the remote TP environment. See also Web I/O Interface server security exit NATUXRFE and the section Product Interaction in the Web I/O Interface Server CICS Adapter documentation. Note Please verify the correct installation of `NATUXRFE`. A Map Environment attempt with a valid user ID and an invalid password should fail with a NAT0873 error.
`IMPERSONATE` | Impersonation is done within the Natural Web I/O Interface server environment and in a remote TP environment. The client must be defined in the security system of the Natural Web I/O Interface server and in the remote TP environment.

Note
For a batch server, `SECURITY_MODE=IMPERSONATE` and `SECURITY_MODE=IMPERSONATE_LOCAL` are the same. `SECURITY_MODE` requires Natural Security (NSC).

No default value is provided.

Example:

    SECURITY_MODE=IMPERSONATE

### SECURITY_SYSLOG

Write a console message in case of security problems with external security. One line is written to the console, for example '`Aug-23 16:22:46.77 S0305217 BPXM023I (INITUSER) SERVERID - Invalid userid specified.`' More information about the reason can be found in the appropriate trace or error log of the server.

The parameter applies to z/OS Batch servers only.

Value | Explanation
--- | ---
YES | Write security message to console.
NO | Do not write security message to console. This is the default value.

#### Example:

`SECURITY_SYSLOG=YES`

### SESSION_PARAMETER

This optional configuration parameter defines session parameters that precede the parameter string specified in the connection dialog of the Natural Web I/O Interface client.

Value | Explanation
--- | ---
`parameter-string` | This string may extend across several lines. A + sign at the end of a string line denotes that another line follows.

No default value is provided.

Example 1:

      SESSION_PARAMETER='NUCNAME=NATNUCvr' +
      'PROFILE=(NWOPARM,18006,48),ADAMODE=0,' +
      'BPI=(TYPE=NAT,SIZE=6044),BPI=(TYPE=EDIT,SIZE=2048)', +
      'BPI=(TYPE=SORT,SIZE=1024)'

Example 2:

    SESSION_PARAMETER=FNAT=(10,930)

The setting in the second example defines that every session on this Natural Web I/O Interface server is started with the session parameter `FNAT=(10,930)` appended to the user-specified parameters or the definitions in the configuration parameter `DEFAULT_PROFILE`.

### SESSION_TIMEOUT

Cancel inactive sessions when the `SESSION_TIMEOUT` parameter is met. Check for sessions inactive longer then `n` minutes once a day at `HH:MM` (24 hours) or every `n` minutes.

The server will not start if an invalid `SESSION_TIMEOUT` parameter is given.

Value | Explanation
--- | ---
`hh:mm,n <numeric value greater than 0>` or `m <numeric value greater than 0>,n <numeric value>0>` | If format is `hh:mm`, check once a day at `hh:mm` for sessions more than `n` minutes inactive. or If format is a numeric value, check every `m` minutes for sessions more than `n` minutes inactive.

Examples:

    SESSION_TIMEOUT=19:30,480

Every day at 19:30 cancel sessions more than 480 minutes inactive.

    SESSION_TIMEOUT=360,480

Every 360 minutes cancel sessions more than 480 minutes inactive.

### THREAD_NUMBER

This configuration parameter specifies the number of physical storage threads to be allocated by the Natural front-end, that is, the number of sessions that can be executed in parallel.

Note
This parameter is obsolete when the Natural Web I/O Interface Server CICS Adapter or Natural Web I/O Interface Server IMS Adapter is used.

Value | Explanation
--- | ---
`thread-number` | Number of physical storage threads to be allocated. Note This number does not limit the number of sessions within the server, but the number of sessions which can be in execution status concurrently. The number of sessions is limited by the size of the Natural swap medium.
3 | This is the default value.

Example:

    THREAD_NUMBER=5

### THREAD_SIZE

This configuration parameter specifies the size of each physical storage thread which contains the Natural session data at execution time.

Note
This parameter is obsolete when the Natural Web I/O Interface Server CICS Adapter or Natural Web I/O Interface Server IMS Adapter is used.

Value | Explanation
--- | ---
`thread-size` | Size (in KB) of each physical storage thread.
`500` | This is the default value.

Example:

    THREAD_SIZE=800

### TRACE_FILTER

This optional configuration parameter enables you to restrict the trace by a logical filter in order to reduce the volume of the server trace output, for example:

    TRACE_FILTER="Client=(KSP P*)"

Each request of the user ID "KSP" and each request of the user IDs starting with a "P" are traced.

See Trace Filter in the section Operating the Natural Web I/O Interface Server.

### TRACE_LEVEL

Value | Explanation
--- | ---
`trace-level` | See Trace Level in the section Operating the Natural Web I/O Interface Server.
`0` | This is the default value.

Example:

    TRACE_LEVEL=0x00000011

or alternatively

    TRACE_LEVEL=31+27

The setting in the example switches on Bits 31 and 27.

### UPPERCASE_SYSTEMMESSAGES

This configuration parameter is used to enable or disable the translation of all NWO error messages and trace outputs to uppercase. This feature is for customers who are using character sets with no lowercase characters defined.

Value | Explanation
--- | ---
YES | Enable uppercase translation.
NO | Disable uppercase translation. This is the default value.

## Web I/O Interface Server Configuration File Example

    # This is a comment
    SESSION_PARAMETER=profile=(stgqa,10,930) fuser=(10,32) CFICU=ON
    THREAD_NUMBER=2
    THREAD_SIZE=700
    FRONTEND_NAME=NATOSvrL       # and another comment
    PORT_NUMBER=4811

Where `vr` is the current product version and release number.

## Web I/O Interface Server Data Sets for z/OS

The Natural Web I/O Interface server requires the following data sets:

`STGCONFG` | Defines the server configuration file.
`STGTRACE` | The server trace output.
`STGSTDO` | The stdo data set.
`STGSTDE` | The stde error output.

Alternately, you can qualify each data set name by the server ID.

`NWOS1C` | Defines the server configuration file for the server NWOS1.
`NWOS1T` | The server trace output for the server NWOS1.
`NWOS1O` | The stdo data set for the server NWOS1.
`NWOS1E` | The stde error output for the server NWOS1.

## Web I/O Interface Server User Exits

The Natural Web I/O Interface server offers the following user exit:

### User Exit NSECUX01

This user exit is applicable only when the parameter `SECURITY_MODE` is set to `IMPERSONATE_LOCAL` or `IMPERSONATE`.

This user exit allows you to adapt the user ID used for the RACF login. It is useful if the RACF user IDs and the user IDs used in Natural differ according to a standardized rule. For example, each RACF user ID is the corresponding Natural user ID preceded by two dollar signs ($$).

If the exit (the load module `NSECUX01`) is found in the NWO load library concatenation, it is called using standard linkage conventions (direct branch using a BASR instruction) before the user is validated against RACF.

The following parameters are passed to the exit:

Name | Format | In/Out | Description
--- | --- | --- | ---
`sUid` | CL64 | I/O | User ID to be modified for RACF login.

The exit is called using standard linkage conventions.

Sample user exit implemented in C:

    #include <string.h>
    #include <stdio.h>

    #  pragma linkage (NSECUX01, FETCHABLE)

    void NSECUX01(char sUid[64])
    {
    char sUidTemp[64];

      printf("Uex got usid:%s\n", sUid);
      strcpy(sUidTemp, sUid);
      sprintf(sUid, "$$%s", sUidTemp);
      printf("Uex ret usid:%s\n", sUid);
      return;
    }

The exit above extends each user ID by two preceding dollar signs ($$) when it is used for RACF login.

### On this page

- Configuration Requirements for z/OS
- Web I/O Interface Server Configuration File for z/OS
- Web I/O Interface Server Configuration Parameters
- Web I/O Interface Server Configuration File Example
- Web I/O Interface Server Data Sets for z/OS
- Web I/O Interface Server User Exits