IBM Connect:Direct for UNIX

6.1

Documentation

IBM
This edition applies to Version 5 Release 3 of IBM® Connect:Direct and to all subsequent releases and modifications until
otherwise indicated in new editions.
© Copyright International Business Machines Corporation 1993, 2018.
US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contract with
IBM Corp.
Contents

Chapter 1. Release Notes....................................................................................... 1

New Features and Enhancements...............................................................................................................1
Hardware and Software Requirements....................................................................................................... 3
Support policy for Container Delivery Models.............................................................................................5
Known Restrictions...................................................................................................................................... 5
Upgrade Considerations.............................................................................................................................. 7
Upgrading Connect:Direct File Agent on AIX.............................................................................................. 7
Special Considerations................................................................................................................................ 7
Special Considerations for Connectivity with the HP NonStop Kernel Operating System................... 8
Connect:Direct for UNIX Guidelines............................................................................................................ 8
Libraries to Install........................................................................................................................................ 8

Chapter 2. Getting Started Guide......................................................................... 11

Connect:Direct for UNIX Overview............................................................................................................ 11
Process Manager.................................................................................................................................. 11
Command Manager.............................................................................................................................. 11
Session Manager.................................................................................................................................. 12
User Authorization................................................................................................................................12
Process Restart.................................................................................................................................... 12
Archive Statistics Files......................................................................................................................... 13
Sample Processes, Shell Scripts, and API Programs.......................................................................... 13
Connect:Direct for UNIX Configuration Files.......................................................................................14
Connect:Direct for UNIX Directory Structure...................................................................................... 15
Installation Overview.................................................................................................................................15
Installing Connect:Direct for UNIX............................................................................................................16
Preparing to Install Connect:Direct for UNIX in a Cluster Environment............................................. 16
Conventions to Observe When Installing Connect:Direct for UNIX....................................................18
Installation Worksheets....................................................................................................................... 18
Installing IBM Connect:Direct..............................................................................................................26
Customizing Connect:Direct for UNIX................................................................................................. 27
Setting Up the IBM Connect:Direct Server.......................................................................................... 28
Setting Up the Connect:Direct for UNIX Client....................................................................................29
Installing Connect:Direct File Agent.................................................................................................... 31
Installing Connect:Direct Secure Plus................................................................................................. 32
Defining High-Availability Settings in the Configuration Files.............................................................34
Setting Up Additional Configuration Requirements for IBM HACMP.................................................. 35
Setting Up Additional Configuration Requirements for Hewlett-Packard MC/ServiceGuard ............35
Verifying the Installation...................................................................................................................... 36
Deploying IBM Connect:Direct for UNIX using a Docker container..........................................................37
Prerequisites to Deploy Connect:Direct® for UNIX using a Docker container.................................... 37
Deploying the Software........................................................................................................................ 41
Validating the Deployment...................................................................................................................44
Post Deployment Configurations......................................................................................................... 45
Container Stop/Restart procedure.......................................................................................................45
Container Recovery.............................................................................................................................. 46
Known Limitations................................................................................................................................46
Upgrading IBM Connect:Direct for UNIX using a Docker Container................................................... 47
Migrating IBM Connect:Direct for Unix using a Docker Container...................................................... 48
Deploying IBM Connect:Direct for UNIX using an IBM Certified Container Software............................. 49
Planning................................................................................................................................................ 50

iii
 Installing...............................................................................................................................................53
Post-installation tasks..........................................................................................................................70
Upgrade, Rollback, and Uninstall.........................................................................................................70
Known Limitations................................................................................................................................71
Migrating to Connect:Direct for UNIX using Certified Container Software......................................... 72
Migration from Helm 2 to Helm 3 ........................................................................................................73
Troubleshooting your deployment in an IBM Certified container and Docker environment................... 73
Troubleshooting IBM Certified container and Docker Container issues.............................................73
Troubleshooting in a Docker Container environment..........................................................................76
Troubleshooting your IBM certified Containerized environment........................................................77
Managing Files with Sterling Connect:Direct File Agent...........................................................................79
Connect:Direct File Agent Operation................................................................................................... 80
Connect:Direct File Agent Logging Capabilities...................................................................................80
Connect:Direct File Agent Configuration Interface and Help............................................................. 80
Planning the Connect:Direct File Agent Configuration........................................................................80
IBM Connect:Direct Worksheet........................................................................................................... 81
Sterling Connect:Direct File Agent Configuration Examples...............................................................82
Connect:Direct Manual Pages....................................................................................................................84
Accessing IBM Connect:Direct Manual Pages.....................................................................................85
Virtualization support................................................................................................................................ 85
IBM Control Center Director Support........................................................................................................ 85
Configuring Connect:Direct for UNIX for Server and Upgrade Management......................................86
Configuring Connect:Direct for UNIX for License Governance........................................................... 87
Configuring Connect:Direct for Unix for New Install Task...................................................................87
Configuring Connect:Direct for Unix for Custom Locations of Connect:Direct Backups and
Installation Programs......................................................................................................................88

Chapter 3. Administration Guide.......................................................................... 89

Password Storage...................................................................................................................................... 89
Maintaining configuration files.................................................................................................................. 89
Modifying configuration files................................................................................................................90
Maintaining the Initialization Parameters................................................................................................. 90
Contents of the initialization parameters file...................................................................................... 91
Updating records.................................................................................................................................. 92
Firewall navigation record TEST........................................................................................................ 105
Maintaining the client configuration file..................................................................................................105
Contents of the client configuration file............................................................................................ 106
Maintaining the network map file............................................................................................................107
Contents of the network map file...................................................................................................... 107
Local node connection record............................................................................................................108
TCP/IP Default Record....................................................................................................................... 113
Remote Node Connection Record..................................................................................................... 116
Maintaining access information files.......................................................................................................119
User Authorization Information File.................................................................................................. 119
Strong Access Control File................................................................................................................. 127
Automatic Detection of Shadow Passwords..................................................................................... 128
Limiting Access to the Program Directory......................................................................................... 128
Security Exit........................................................................................................................................128
Maintaining client and server authentication key files........................................................................... 128
Key File Format.................................................................................................................................. 129
Key File Parameters........................................................................................................................... 129
Sample Client Authentication Key File.............................................................................................. 129
Authentication Process...................................................................................................................... 130
Firewall Navigation.............................................................................................................................131
Session Establishment.......................................................................................................................132
Specifying connection information......................................................................................................... 133
IP Addresses...................................................................................................................................... 133

iv
 Host Names........................................................................................................................................ 134
Port Numbers..................................................................................................................................... 134
Multiple Addresses, Host Names, and Ports..................................................................................... 134
About Using Masks for IP Address Ranges....................................................................................... 134
Using Connect:Direct in a test mode.......................................................................................................135
Processing Flow of the Test Mode..................................................................................................... 135
Preparing the NDMPXTBL Parameter Table...................................................................................... 136
Sample Test Scenarios.......................................................................................................................138

Chapter 4. User Guide........................................................................................ 141

Controlling and Monitoring Processes.................................................................................................... 141
Starting the CLI.................................................................................................................................. 141
Stopping the CLI.................................................................................................................................141
CLI Commands................................................................................................................................... 141
CLI Job Control...................................................................................................................................143
CLI History Commands...................................................................................................................... 144
Overview of IBM Connect:Direct Commands....................................................................................144
Submitting a Process......................................................................................................................... 146
Changing Process Parameters........................................................................................................... 153
Deleting a Process from the TCQ....................................................................................................... 155
Removing a Process from the Execution Queue............................................................................... 157
Stopping IBM Connect:Direct............................................................................................................ 158
Viewing a Process in the TCQ.............................................................................................................159
Monitoring Process Status in the TCQ............................................................................................... 162
Determining the Outcome of a Process.............................................................................................165
Generating a Detailed Output Report for a Process..........................................................................173
Generating a Summary Report for a Process.................................................................................... 173
Running System Diagnostics..............................................................................................................174
Process Queuing...................................................................................................................................... 177
Scheduling IBM Connect:Direct Activity............................................................................................177
Progression of a Process Through the TCQ....................................................................................... 178
Connect:Direct Utilities............................................................................................................................182
Creating a Translation Table.............................................................................................................. 182
Compiling a Translation Table Using the ndmxlt Utility.................................................................... 183
Example—Creating a Translation Table............................................................................................. 184
Example—Modifying a Model Translation Table................................................................................184
Using Translation During File Transfer Operations........................................................................... 185
Translation Table Error Messages......................................................................................................185
Accessing IBM Connect:Direct Messages......................................................................................... 185
Precompressing/Decompressing Files Using the Standalone Batch Compression Utility.............. 187
Validate Configuration Files............................................................................................................... 191
Configuration Reports........................................................................................................................ 192
Writing Custom Programs........................................................................................................................195
Compiling Custom Programs............................................................................................................. 195
Writing Custom C Programs............................................................................................................... 197
Writing Custom C++ Programs...........................................................................................................206
Writing User Exits.................................................................................................................................... 210
User Exit Functions............................................................................................................................ 211
Overview of User Exit Messages........................................................................................................ 213
Exit Log Files.......................................................................................................................................217

Chapter 5. Using FASP with IBM Aspera High-Speed Add-on for Connect:Direct
for UNIX (V4.2.0.3 or later) ............................................................................219
Activating FASP........................................................................................................................................219
Licensed bandwidth for FASP transactions............................................................................................ 219
FASP Process Language.......................................................................................................................... 220

v
 Using Connect:Direct for UNIX with IBM Aspera High-Speed Add-on and Secure Proxy (V4.2.0.4
or later)............................................................................................................................................... 221
Configuring FASP..................................................................................................................................... 223
FASP Messages........................................................................................................................................ 226
Monitoring FASP transactions................................................................................................................. 227
Limitations............................................................................................................................................... 228

Chapter 6. Using S3 object store providers with IBM Connect:Direct for UNIX .....229
Setting up Connect:Direct Node on S3 object store providers...............................................................229
Using IBM Connect:Direct® for Unix with AWS S3.................................................................................. 234
Limitations............................................................................................................................................... 235

Chapter 7. IBM Connect:Direct Secure Plus for UNIX.......................................... 237

Introduction to Connect:Direct Secure Plus for UNIX............................................................................237
Security Concepts.............................................................................................................................. 237
Secure Plus UNIX Video Tutorials......................................................................................................237
Protocol Support................................................................................................................................ 238
Connect:Direct Secure Plus Tools......................................................................................................239
Before You Begin................................................................................................................................240
Plan Your Implementation of the TLS Protocol...................................................................................... 241
Overview of the TLS Protocol.............................................................................................................241
Self-Signed and CA-Signed Certificates............................................................................................ 242
Set Up Connect:Direct Secure Plus......................................................................................................... 244
Install Connect:Direct Secure Plus....................................................................................................244
Starting the Secure+ Admin Tool....................................................................................................... 244
Populating the Secure+ Parameters File...........................................................................................245
Configure Nodes...................................................................................................................................... 245
Import Existing Certificates............................................................................................................... 246
Create CMS Key Store ....................................................................................................................... 246
Configuring the Connect:Direct Secure Plus .Local Node Record.....................................................247
Customize Remote Node Records..................................................................................................... 250
Configuring a Remote Node Record ..................................................................................................250
Validating the Configuration.............................................................................................................. 253
Configure External Authentication in the .SEAServer Record...........................................................253
Configure Strong Password Encryption............................................................................................. 254
Configure Certificate Authentication for Client API Connections.......................................................... 255
Automate Setup.......................................................................................................................................255
Start and Set Up the Secure+ CLI...................................................................................................... 256
Encrypt Passwords to Use with the Secure+ CLI.............................................................................. 257
Sample Script..................................................................................................................................... 257
Maintain the Secure+ Parameters File.............................................................................................. 257
Manage CMS Keystore .......................................................................................................................260
Update the .Local Node Record......................................................................................................... 261
Manage Remote Node Records......................................................................................................... 262
Update the .Client Node Record........................................................................................................ 266
Maintain the Sterling External Authentication Server Record.......................................................... 267
Strong Password Encryption..............................................................................................................268
Maintain Connect:Direct Secure Plus......................................................................................................269
Node List Field Descriptions.............................................................................................................. 269
Viewing Node Record Change History............................................................................................... 270
Viewing Information about the Secure+ Parameters File.................................................................270
Modify a Connect:Direct Secure Plus Configuration......................................................................... 270
Accessing Connect:Direct Secure Plus Statistics................................................................................... 272
IBM Connect:Direct CLI Select Statistics Detail................................................................................273
Session Start (SSTR) Record.............................................................................................................. 274
Copy Termination (CTRC) Record...................................................................................................... 275
Connect:Direct Secure Plus Audits......................................................................................................... 276

vi
 Access Secure+ Parameters File Audit Logs..................................................................................... 276
Secure+ Parameters File Audit Log Entries.......................................................................................276
IBM Connect:Direct Secure Plus Certificate Auditing....................................................................... 277
Troubleshooting.......................................................................................................................................279
Configuration Worksheets....................................................................................................................... 282
Local Node Security Feature Definition Worksheet.......................................................................... 282
Remote Node Security Feature Definition Worksheet...................................................................... 282
Certificate File Layout..............................................................................................................................283
Formats.............................................................................................................................................. 284
Sample Certificate Files..................................................................................................................... 285
Automation Scripts.................................................................................................................................. 286
Configure Connect:Direct Secure Plus to Use the TLS Protocol....................................................... 286
Use the LCU to Configure Encrypted Passwords.................................................................................... 288

Chapter 8. Solaris Service Management Facility and IBM Connect:Direct for

UNIX............................................................................................................. 289
Place IBM Connect:Direct under Solaris Service Management Facility Control....................................289
Installing and Configuring the SMF Script...............................................................................................289
Controlling IBM Connect:Direct Using the SMF Script........................................................................... 294
Implementing Solaris Role-Based Access Control with SMF for IBM Connect:Direct.......................... 295
Starting and Stopping IBM Connect:Direct under SMF Control............................................................. 295
Starting the Connect:Direct FTP+ Service......................................................................................... 296
Stopping the IBM Connect:Direct Service......................................................................................... 296
Correcting Errors in the Script or FMRI File............................................................................................ 296
Removing IBM Connect:Direct from SMF Control.................................................................................. 296

Notices..............................................................................................................297
Trademarks.............................................................................................................................................. 298
Terms and conditions for product documentation................................................................................. 299

vii
viii
Chapter 1. Release Notes
The IBM® Connect:Direct® for UNIX Release Notes document supplements Connect:Direct for UNIX
documentation. Release notes are updated with each release of the product and contain last-minute
changes and product requirements, as well as other information pertinent to installing and implementing
Connect:Direct for UNIX.

New Features and Enhancements

IBM Sterling Connect:Direct for UNIX 6.1 and its related software have the following features and
enhancements:
FixPack 3 (v6.1.0.3)

New Features or Enhancements

To install this software, you should go to the Fix Central website and install the latest available fix pack.
• Helm 2 support will be revoked from this release. All the Helm 2 commands can still be used for
versions prior to 6.1.0.3.
• Dynamic provisioning support is added in IBM Certified Container Software. For more information,
refer “Creating storage for Data Persistence” on page 60 and “Creating secret” on page 62.
• IBM Certified Container Software validity is extended till January 2022.
• You can now pull the container image from IBM Entitled registry also. For more information, refer
“Downloading the Certified Container Software image” on page 55.

iFix013 (v6.1.0.2)

New Features or Enhancements

To install this software, you should go to the Fix Central website and install the latest available fix pack.
IBM Connect:Direct for UNIX has been configured to extend support for specifying custom
Connect:Direct backup paths and installation program paths. For more information see, Custom
Locations of Connect:Direct Backups and Installation Programs.

FixPack 2 (v6.1.0.2)

© Copyright IBM Corp. 1993, 2018 1

 New Features or Enhancements
To install this software, you should go to the Fix Central website and install the latest available fix pack.
Connect:Direct for UNIX (v6.1.0.2) has the following features and enhancements:
• LDAP support is introduced for the docker containers. For more information, refer “Understanding
LDAP deployment parameters” on page 42.
• LDAP support is introduced for upgrading Connect:Direct using docker containers. For more
information, refer “Understanding LDAP deployment parameters” on page 47.
• LDAP support is introduced for IBM certified container software. For more information, refer
“Understanding LDAP deployment parameters” on page 67.
• You can now easily migrate to Helm version 3 from Helm version 2. For more information, refer
“Migration from Helm 2 to Helm 3 ” on page 73.
• Support for Helm (client) version (>= 2.12 and < 3.0 or >= 3.2.1) is extended. For more information,
refer “Verifying System Requirements” on page 51.
• IBM Certified Container Software now supports Redhat OpenShift 4.4. For more information, refer
“Verifying System Requirements” on page 51.
• Licensing and Metering is supported using IBM License Operator. For more information, refer License
Service and Licensing Operator.

FixPack 1 (v6.1.0.1)

New Features or Enhancements

To install this software, you should go to the Fix Central website and install the latest available fix pack.
IBM Connect:Direct for UNIX introduces support for installing new Connect:Direct servers from IBM
Control Center Director. For more information see, “IBM Control Center Director Support” on page 85.

Base Release (v6.1)

New Features or Enhancements

To install this software, you should go to the Passport Advantage website, and follow instructions
described to complete the download.
Connect:Direct for UNIX has the following features and enhancements:
• With this release Connect:Direct for UNIX introduces support to cache certificate validation responses
from External Authentication Server when it interfaces External Authentication Server during a TLS
session. This minimizes the overhead associated with requesting certificate validation from External
Authentication Server, thus eliminating the need for Connect:Direct Secure Plus to query External
Authentication Server each time. For related documents see
– Parameters File>.SEAServer
– Enable Caching SEAS certificate validation response via Connect:Direct Secure Plus Admin Tool
– Enable Caching SEAS certificate validation response via Connect:Direct Secure Plus CLI
• Support for TLS v1.3 for Connect:Direct for UNIX introduced to secure communication sessions with
traders partners. For more information see, IBM Connect:Direct for UNIX Secure Plus documentation.
• Connect:Direct for UNIX is supported on any point release of Red Hat Enterprise Linux version 8.x.
• Connect:Direct for UNIX introduces support for Emergency restore procedure, added to Control Center
Director Web Console in release 1.0.0.2.
• Support for IBM Aspera High-Speed Add-on for Connect:Direct for UNIX using (Fast and Secure
Protocol) has been re-introduced with this GA release. For related documents see, Chapter 5, “Using
FASP with IBM Aspera High-Speed Add-on for Connect:Direct for UNIX (V4.2.0.3 or later) ,” on page
219.

2 IBM Connect:Direct for UNIX: Documentation

Hardware and Software Requirements
IBM® Connect:Direct® for UNIX and its related software require the following hardware and software: It
supports systems running in 64-bit mode.

Component or Hardware Software RAM (min.) Disk Space

Functionality (min.)
IBM HP Integrity HP-UX version 11iv3 or higher 2 GB 1 GB*
Connect:Direct system with
Note: Not supported with FASP.
for UNIX with Intel Itanium
TCP/IP or FASP processor
connectivity
IBM System AIX versions 7.1 and 7.2 2 GB 1 GB*
pSeries,
POWER7 or
greater
processor
required
IBM System SuSE Linux Enterprise Server 2 GB 1 GB*
pSeries, (ppc64le) version 12.4 and
POWER8 or greater.
greater
Note: Not supported with FASP.
processor
required
Sun SPARC Solaris version 10, update to 2 GB 1 GB*
system level 11 (Jan 2013) or higher, and
Solaris 11.
Note: Not supported with FASP.

Intel and AMD Red Hat Enterprise Linux version 2 GB 1 GB*

x86-64 7 (7.2 or above)
Any point release of Red Hat
Enterprise Linux version 8.x

Any point release of CentOS

version 7 (7.2 or above)
Any point release of CentOS
version 8.x
Note: Supported, but not
certified**

Any point release of SuSE Linux 2 GB 1 GB*

Enterprise Server version 12.x or
15.x

Chapter 1. Release Notes 3

 Component or Hardware Software RAM (min.) Disk Space
Functionality (min.)
Linux® zSeries Any point release of Red Hat 2 GB 1 GB*
Enterprise Linux version 7.x.
Any point release of Red Hat
Enterprise Linux version 8.x

Any point release of SuSE Linux 2 GB 1 GB*

Enterprise Server version 12.x or
15.x.
Note: Not supported with FASP.

Sterling Same as Same as requirements for IBM 2 GB 275 MB

Connect:Direct requirements Connect:Direct for UNIX
File Agent for
Java™ Standard Edition 6,
Connect:Direct
installed with Sterling
for UNIX
Connect:Direct File Agent
Note: On Linux zSeries, the JRE is
not bundled with Sterling
Connect:Direct File Agent. You
must obtain and install Java
Standard Edition 8 before you
install Sterling Connect:Direct
File Agent.

Connect:Direct Same as Same as requirements for 2 GB 70 MB

Secure Plus requirements Connect:Direct Secure Plus.
for IBM
Java Standard Edition 8, installed
Connect:Direct
with Connect:Direct Secure Plus.
for UNIX.
High- IBM System IBM HACMP
Availability pSeries,
support POWER7 or
greater
processor
required
Sun SPARC SunCluster 2.2, 3.0 or 3.2
system

* When upgrading Connect:Direct for UNIX through Control Center Directer, an extra 3 GB is required for
temporary storage.
** IBM does not formally test and certify Connect:Direct on CentOS. However as CentOS is derived from
the sources of Red Hat Enterprise Linux (RHEL), we believe that the product should work correctly. IBM
will investigate and troubleshoot a problem until it is determined that the problem caused by a difference
in behavior between CentOS and RHEL. Defect support will only be available for problems that can be
reproduced on a certified platform as documented in the Software Product Compatibility Reports (link:
https://www.ibm.com/software/reports/compatibility/clarity/index.html?
lnk=uctug_ratl_dw_2013-02-01_clarity_updated).

Virtualization and public cloud support

IBM cannot maintain all possible combinations of virtualized platforms and cloud environments. However,
IBM generally supports all enterprise class virtualization mechanisms, such as VMware ESX, VMware

4 IBM Connect:Direct for UNIX: Documentation

 ESXi, VMware vSphere, Citrix Xen Hypervisor, KVM (Kernel-based virtual machine), and Microsoft Hyper-V
Server.
IBM investigates and troubleshoots a problem until it is determined that the problem is due to
virtualization. The following guidelines apply:
• If a specific issue is happening because the system is virtualized and the problem cannot be reproduced
on the non-virtualized environment, you can demonstrate the issue in a live meeting session. IBM can
also require that further troubleshooting is done jointly on your test environment, as there is not all
types and versions of VM software installed in-house.
• If the issue is not able to be reproduced in-house on a non-virtualized environment, and
troubleshooting together on your environment indicates that the issue is with the VM software itself, you
can open a support ticket with the VM software provider. IBM is happy to meet with the provider and
you to share any information, which would help the provider further troubleshoot the issue on your
behalf.
• If you chose to use virtualization, you must balance the virtualization benefits against its performance
impacts. IBM does not provide advice that regards configuring, administering, or tuning virtualization
platforms.

Support policy for Container Delivery Models

The support policies for container delivery models are as follows.

Support statement for IBM Connect:Direct for UNIX certified containers for Red Hat
that are deployed using OpenShift Container Platform
IBM Connect:Direct for UNIX certified containers for Red Hat are built to deploy on the Red Hat OpenShift
Container Platform. The product containers and deployment model are certified by IBM to be production
ready, enterprise-grade, resilient, secure and compliant in many public and private clouds which the
OpenShift Container Platform supports. IBM Technical Support supports this delivery model across the
lifecycle management of IBM Connect:Direct for UNIX certified containers, including container
orchestration scripts in OpenShift Container Platform and product documentation.

Support statement for IBM Connect:Direct for UNIX certified containers deployed
on non-OpenShift Container Platform
For users who choose to deploy the IBM certified containers on; proprietary container orchestration tools
such as EKS/GKE/AKS/PCF, on public cloud such as Amazon/Azure/ Google or in their private cloud using
native Kubernetes, the IBM Technical Support is limited to the base Connect:Direct for UNIX software,
certified containers, and HELM package manager. IBM provides limited support for the container editions
that are deployed in proprietary renderings for Kubernetes. The non-conformant characteristics of such
tools hinder the ability for IBM to assist users in all scenarios.

Support policy statement for containers that are created by users

For users who have created custom docker containers for IBM Connect:Direct for UNIX and have
deployed in any Kubernetes platform, the IBM Technical Support is limited to the technical inquiries in the
core Connect:Direct for UNIX. IBM recommends using IBM provided certified containers and not the user
created containers for Connect:Direct for UNIX.

Known Restrictions
Connect:Direct for UNIX has the following restrictions when using third-party hardware or software:
• Due to a system library change on Red Hat Enterprise Linux version 8, you must set your current
working directory (CWD) to {CDU install dir}/ndm/bin to invoke the executable modules there.
To invoke these modules from another CWD, there are two options:

Chapter 1. Release Notes 5

 – As root, create the following symbolic link in /lib64: ln -s /lib64/libtirpc.so.3 /lib64/
libtirpc.so.1
– Set the executor's environment variable LD_LIBRARY_PATH={CDU install dir}/ndm/lib .
• An issue occurs which causes invalid data to be written to the destination file when standard
compression is enabled and transfer is text mode when sending to another Connect:Direct Unix node.
This issue leads to inadvertent conversion of some spaces to EBCDIC space instead of ASCII. A possible
work-around of this issue is to use extended compression or no compression or use binary mode.
• If you use the Hummingbird Exceed terminal emulator to access a Solaris workstation, you may not
have all of the fonts needed to use Connect:Direct Secure Plus IBM Connect Direct for UNIX. Add the
following command to the spadmin.sh file:

xset fp default

Insert this command before the following line of code:

java -classpath $CLASSPATH:/SCI/USERS/... com.stercomm.csg.spadmin.spadmin

This command maps all unknown fonts to a default value and prevents IBM Connect:Direct for UNIX
from performing a core dump if it is unable to locate a font.
• Connect:Direct Secure Plus Connect Direct for UNIX is administered through Java and a graphical user
interface (GUI). The standard UNIX telnet server does not support a GUI client session. To use the UNIX
GUI you must be connected to the UNIX server via an X Windows client session, such as xterm. If you
are connected to the UNIX server using a telnet session, you will not be able to run the GUI sessions
required to install and administer IBM Connect:Direct for UNIX. If you do not have access to X Windows,
you can use the Connect:Direct Secure Plusfor UNIX Command Line Interface (Secure+ CLI).
• Connect:Direct Secure Plus IBM Connect Direct for UNIX does not support server gated crypto (SGC)
certificates.
• The Secure+ CLI does not support using $HOME or the tilde (~) to specify the path to your home
directory.
• When using the Secure+ CLI on the Solaris platform, command entries may be limited by the buffer size.
To resolve this limitation, add line breaks to a command entry. For example, enter the following
command with line breaks:

SslTlsEnableCipher=(TLS_RSA_WITH_AES_256_CBC_SHA,
TLS_RSA_WITH_AES_128_CBC_SHA,SSL_RSA_WITH_RC4_128_MD5,
SSL_RSA_WITH_RC4_128_SHA, SSL_RSA_WITH_3DES_EDE_CBC_SHA,
SSL_RSA_WITH_DES_CBC_SHA,SSL_RSA_EXPORT_WITH_RC4_40_MD5,
SSL_RSA_EXPORT_WITH_DES40_CBC_SHA,SSL_RSA_WITH_NULL_MD5);

• On the HP-UX, IBM System pSeries, and Linux platforms, when a run task defines an invalid UNIX
command, the operating system return code is 127 and the completion code (CCOD) reported by
Connect:Direct for UNIX is displayed in hexadecimal (7F) in the statistics output. This return code is
correct for the error received, even though most return codes are defined as 0, 4, 8, or 16.
If the return code value of 127 is the highest step return code, the Process End (PRED) statistics record
message ID is set to the Message ID of the run task step. On other platforms, the run task return code is
1, resulting in the message ID of XSMG252I in the PRED statistics record.
• Connect:Direct Browser User Interface IBM Connect Direct for UNIX is not supported running on HP
Integrity systems with Intel Itanium processors.
• Installation on Linux platforms displays the following message:

awk: cmd. line:6: warning: escape sequence `\.' treated as plain `.'

6 IBM Connect:Direct for UNIX: Documentation

 This is a known issue with Install Anywhere and does not affect installation or functionality of
Connect:Direct File Agent IBM Connect Direct for UNIX on Linux.
• When IBM Connect:Direct for UNIX 6.1 attempts a session as a PNode with CD i5/OS and CD i5/OS is
running on IBM i 7.3 or earlier, the session may fail if IBM Connect:Direct for UNIX 6.1 has TLS 1.3
enabled for the session. The resolution is to disable TLS 1.3 for sessions with the IBM Connect:Direct
for UNIX i5/OS snode.

Upgrade Considerations
If you are upgrading from an existing version of Connect:Direct for UNIX, observe the following guidelines:
• SNMP is no longer supported. If you are using SNMP and upgrade to this version, other functionality will
not be negatively impacted. However, you will no longer receive SNMP messages.
• Change the ownership on the statistics files in your work directory so that these files are owned by the
user who starts the cdpmgr daemon. Use the following command sequence to change the ownership of
the statistics files:

$ su root
Password: root_password
# cd cddir/work/node
# chown user_who_starts_cdpmgr S*.???

The upgrade considerations for installing Connect:Direct for UNIX on EC2 are described in section "
Prerequisites for activating Connect:Direct Unix on AWS cloud".
The following variable definitions apply:
– root_password - Root user's password
– cddir - Directory in which Connect:Direct for UNIX is installed
– node - Your Connect:Direct for UNIX node name
– user_who_starts_cdpmgr - User name of the user who will start the cdpmgr daemon
• If you are upgrading a collection of Connect:Direct for UNIX nodes in a load-balancing environment,
stop all of the nodes before you begin the upgrade. You can restart the nodes after they have been
upgraded.
• If you are upgrading on HPUXIT and SOLARIS, the netmap must be reconfigured. Add rpc.pmgr.port
to the local.node entry in the netmap.cfg file. If this entry is not added, the RPC Server utilizes port
1367 by default. If the default port is busy, the connection with Connect:Direct Server does not come
up.

Upgrading Connect:Direct File Agent on AIX

Procedure
1. Save the configuration files (all *.ser files) and Process files to a backup directory.
2. Remove the File Agent directory.
3. Install the new version of File Agent.
4. Copy the original configuration files and Process files back into the new File Agent directory.

Special Considerations
This section contains considerations in addition to the procedures defined. Refer to the following notes
before installing the product.
• Although Connect:Direct for UNIX Process names can be up to 255 characters long, some IBM
Connect:Direct platforms, such as Connect:Direct for z/OS® limit Process names to eight characters.

Chapter 1. Release Notes 7

 Processes running between UNIX and platforms that limit Process names to eight characters can have
unpredictable results if longer names are specified.
• The Connect:Direct Secure Plus initparms record and the user authority that have been added to
Connect:Direct for UNIX version 4.1.00 support remote configuration of Connect:Direct Secure Plus.
These configuration options are needed when using the Central Management feature available in
Control Center 5.0 and later.
• If you are using a certificate that was created with an older version of Certificate Wizard, the certificate
may contain a blank line between the "BEGIN" and "END" statements that define a private key. This
version cannot process the blank line, resulting in an error. If a certificate generates an error, delete the
blank line in the certificate.

Special Considerations for Connectivity with the HP NonStop Kernel

Operating System
This version of Connect:Direct for UNIX offers connectivity to Connect:Direct for HP NonStop Kernel
version 3.2.00 or later using TCP/IP. Refer to the following notes when transferring files from the UNIX
operating system to the HP NonStop Kernel operating system:
• Do not define the sysopts parameter with continuation marks. Type the text in a continuous string, with
blanks separating each subparameter. The sysopts parameter is valid for the copy statement.
• When copying files from the UNIX operating system to the HP NonStop Kernel operating system, define
the dcb parameter to allocate destination files. Define any additional options using the sysopts
parameter. The dcb and sysopts parameters are valid for the copy statement.
Use of the dcb parameter ensures that the attributes of the file being sent match the attributes of the
file that is created on the remote node. If you do not define the dcb parameter, the default file types on
the destination node are as follows:
– If you are transferring a text file, the file type on the HP NonStop Kernel node defaults to an
unstructured file, code 101.
– If you are transferring a binary file, the file type on the HP NonStop Kernel node defaults to an
unstructured file, code 0.
• When copying files from the HP NonStop Kernel operating system to the UNIX operating system, define
the sysopts parameter to allocate destination files.
For syntax and parameter descriptions for Process statements, see the Connect:Direct Processes Web
site.

Connect:Direct for UNIX Guidelines

Before you install Connect:Direct for UNIX, read all the information in this section and follow the
guidelines.
• Print and Review IBM Connect:Direct for UNIX Implementation Guide.
• To install Connect:Direct Secure Plus at the same time that you install Connect:Direct for UNIX,
following the instructions in IBM Connect:Direct for UNIX Getting Started Guide.
• When you upgrade from a previous version, the parameters file is converted and can be used with the
new version.

Libraries to Install
Ensure that you have the following libraries installed:

UNIX Platform Software Library

Intel and AMD All supported Linux • libtirpc.so.1
x86-64, Linux
• 64 bit libstdc++ x86-64
zSeries

8 IBM Connect:Direct for UNIX: Documentation

UNIX Platform Software Library
Linux zSeries All supported Linux. • libtirpc.so.1

Chapter 1. Release Notes 9

10 IBM Connect:Direct for UNIX: Documentation
Chapter 2. Getting Started Guide

The getting started with IBM Connect:Direct for UNIX workflow describes steps to set it up. This workflow
describes how to plan, install, and manage a Connect:Direct over UNIX deployment.

Connect:Direct for UNIX Overview

IBM Connect:Direct for UNIX links technologies and moves all types of information between networked
systems and computers. It manages high-performance transfers by providing such features as
automation, reliability, efficient use of resources, application integration, and ease of use. Connect:Direct
for UNIX offers choices in communications protocols, hardware platforms, and operating systems. It
provides the flexibility to move information among mainframe systems, midrange systems, desktop
systems, and LAN-based workstations.
Connect:Direct for UNIX is based on client-server architecture. The Connect:Direct for UNIX server
components interact with the user interfaces (API, CLI, Sterling Connect:Direct Browser User Interface,
and IBM Control Center) to enable you to submit, execute, and monitor Connect:Direct for UNIX
statements and commands.
Note: The connections between some clients and a Connect:Direct Server are unsecure. Passwords sent
by one of these clients to a C:D Server are obfuscated, but the session is not encrypted. The clients are:
UNIX CLI or any user-written UNIX ndampi client, the CD Requester, the Windows CLI, any user-written
Windows SDK client and FileAgent.

Process Manager
The Process Manager (PMGR) is the daemon that initializes the Connect:Direct for UNIX server
environment. Any application, including End User Applications (EUA), can run on any computer as long as
it can connect to the PMGR. The PMGR provides the following functions:
• Initializes Connect:Direct for UNIX
• Accepts connection requests from Connect:Direct for UNIX client APIs and remote nodes
• Creates Command Manager and Session Manager child Processes to communicate with APIs and
remote nodes
• Accepts requests from Command Managers and Session Managers when centralized Connect:Direct for
UNIX functions are required
• Stops Connect:Direct for UNIX
Command Manager

Command Manager
A Command Manager (CMGR) is created for every API connection that is successfully established. The
number of Command Managers that a PMGR can create is system-dependent and limited by the number
of file descriptors available for each UNIX Process. The number of file descriptors set up by the UNIX
operating system may affect Connect:Direct for UNIX operation. You must define enough file descriptors
to handle the number of concurrent Connect:Direct for UNIX sessions allowed, which can be as many as
999.
The CMGR provides the following functions:
• Executes commands sent by the API and sends the results back to the API
• Carries out the Connect:Direct for UNIX authentication procedure, in conjunction with the API, to
determine access to Connect:Direct for UNIX
• Interacts with the PMGR when executing commands

© Copyright IBM Corp. 1993, 2018 11

Session Manager
The Session Manager (SMGR) is created and invoked by the PMGR when resources are available and
either a Process is ready to run or a remote node requests a connection with a local node. The SMGR
provides the following functions:
• Performs the necessary Connect:Direct for UNIX work
• Acts as a primary node (PNODE) and initiates Process execution
• Acts as a secondary node (SNODE) to participate in a Process initiated by the PNODE
When an SMGR is created to execute a Process submitted to a node, it creates the connection to the
remote node. If the SMGR is started by the PMGR to execute local Processes, the SMGR runs each
Process on this session until all Processes are completed.
If an SMGR is created because a remote node initiated a connection, the SMGR completes the connection.
If the SMGR is started by the PMGR to execute remote Processes, the SMGR executes remote Process
steps supplied by the remote SMGR until the remote SMGR completes all of its Processes.
The SMGR depends on the PMGR for Transmission Control Queue (TCQ) services and other centralized
services.

User Authorization
Connect:Direct for UNIX can authorize local and remote users to perform certain Connect:Direct for UNIX
tasks. In order to use Connect:Direct for UNIX, each user must have a record defined in the user
authorization file, called userfile.cfg. Each local user must have a record in the user authorization file, and
remote users may be mapped to a local user ID in a proxy relationship.
To provide a method of preventing an ordinary user from gaining root access through Connect:Direct for
UNIX, a second access file called the Strong Access Control (SACL) file is created when you install
Connect:Direct for UNIX and is named sysacl.cfg. The root:deny.access parameter, which is specified in
the sysacl.cfg file, allows, denies, or limits root access to Connect:Direct for UNIX. If the SACL file is
deleted or corrupted, access to Connect:Direct for UNIX is denied to all users.

Process Restart
Several facilities are provided for Process recovery after a system malfunction. The purpose of Process
recovery is to resume execution as quickly as possible and to minimize redundant data transmission after
a system failure. The following Connect:Direct for UNIX facilities are available to enable Process recovery:
• Process step restart—As a Process runs, the steps are recorded in the TCQ. If a Process is interrupted
for any reason, the Process is held in the TCQ. When you release the Process to continue running, the
Process automatically begins at the step where it halted.
• Automatic session retry—Two sets of connection retry parameters are defined in the remote node
information record of the network map file: short-term and long-term. If you do not specify a value for
these parameters in the remote node information record, default values are used from the local.node
entry of the network map file. The short-term parameters allow immediate retry attempts. Long-term
parameters are used after all short-term retries are attempted. Long-term attempts assume that the
connection problem cannot be fixed quickly and retry attempts occur after a longer time period, thus
saving the overhead of connection retry attempts.
• Checkpoint restart—This feature is available with the copy statement.
Checkpoint restart can be explicitly configured within a copy step through the ckpt parameter. If it is not
configured in the copy step, it can be configured in the Initparms through the ckpt.interval parameter.
• Run Task restart—If a Process is interrupted when a run task on an SNODE step is executing,
Connect:Direct for UNIX attempts to synchronize the previous run task step on the SNODE with the
current run task step. Synchronization occurs in one of the following ways:
– If the SNODE is executing the task when the Process is restarted, it waits for the task to complete,
and then responds to the PNODE with the task completion status. Processing continues.

12 IBM Connect:Direct for UNIX: Documentation

 – If the SNODE task completes before the Process is restarted, it saves the task results. When the
Process is restarted, the SNODE reports the results, and processing continues.
If synchronization fails, Connect:Direct for UNIX reads the restart parameter in the run task step or
the initialization parameters file to determine whether to perform the run task step again. The restart
parameter on the run task step overrides the setting in the initialization parameter.
For example, if the SNODE loses the run task step results due to a Connect:Direct for UNIX cold
restart, Connect:Direct for UNIX checks the value defined in the restart parameter to determine
whether to perform the run task again.
Run task restart works differently when Connect:Direct for UNIX runs behind a connection load
balancer.
• Interruption of Process activity when the SNODE is a Connect:Direct for UNIX node—When the SNODE is
a Connect:Direct for UNIX node and the PNODE interrupts Process activity by issuing a command to
suspend Process activity, deleting an executing Process, or when a link fails or an I/O error occurs
during a transfer, the Process is placed in the Wait queue in WS status.
If Process activity does not continue, you must manually delete the Process from the TCQ. You cannot
issue a change process command from the SNODE to continue Process activity; the Process can only be
restarted by the PNODE, which is always in control of the session.

Archive Statistics Files

Connect:Direct for UNIX provides a utility to archive and purge statistics files. When you configure
Connect:Direct for UNIX, you identify when to archive a statistics file by setting the parameter, max.age, in
the stats record of the initialization parameters file. The max.age parameter defines how old a statistics
file must be before you want to archive the file.
Once a day, the script called statarch.sh is started. This script identifies the statistics files that are equal
to the max.age. It then runs the tar command and the compress command to create a compressed
archived file of all the statistics records that match the max.age parameter. Once the statistics files are
archived, these files are purged. For files archived on a Linux computer, the archived statistics files have
the .gz suffix since these files are compressed with the gzip format. Archived files on all other UNIX
platforms have the .Z suffix to indicate they are compressed using the compress format.
The archived files are stored in the directory where the statistics files and TCQ are stored. The shell script,
statarch.sh, is located in the ndm/bin directory. If necessary, modify the script to customize it for your
environment.
If you want to restore statistics files that have been archived, run the statrestore.sh script. It uses the
uncompress and tar commands to restore all the statistics files in the archive. You supply two arguments
to the statrestore command. The first argument is the directory path where the statistics files are located
and the second argument identifies the archived file name followed by as many archived file names as you
want to restore. Below is a sample statrestore command:
qa160sol: ./statrestore.sh /export/home/users/cd4000/ndm/bin archive1
After files are restored, the statistics records can be viewed using the select statistics command.

Sample Processes, Shell Scripts, and API Programs

Connect:Direct for UNIX provides sample Processes and shell scripts in d_dir/ndm/src, where d_dir
indicates the destination directory of the Connect:Direct for UNIX software. You can create similar files
with a text editor. In addition, instructions for creating sample Processes and shell scripts are in the
README file in the same directory.
The following list displays the file names of sample Processes and the type. Modify the Processes as
required.
cpunx.cd
copy

Chapter 2. Getting Started Guide 13

 rtunx.cd
run task
rjunx.cd
run job
sbunx.cd
submit
The following table displays the names of sample shell scripts. Modify the shell scripts as required.

File Name Type of Shell Script

selstat.sh select statistics
send.sh send
recv.sh receive
wildcard send multiple files to a PDS
statarch.sh archive statistics files
staterestore.sh restore statistics files that have been archived
lcu.sh launch the Local Connection Utility tool
spadmin.sh launch the Secure+ Admin Tool
spcli.sh launch the Secure+ CLI
spcust_sample1.sh configure Secure+ for the SSL or TLS protocol

The following information displays the names of sample programs and a description:
• apicheck.c - Submits a Process to copy a file to a remote system. MAXDELAY is used in this example,
which means that the program will not finish execution until the file has been transferred. A standard c
compiler is used to compile this module.
• apicheck.C - Same as apicheck.c, except that it is compiled with one of the C++ compilers listed in the
Connect:Direct for UNIX User Guide.
• exit_skeleton.c - This program is a skeleton of a user exit program that works in conjunction with
Connect:Direct for UNIX. It demonstrates usage of all three user exits.
• exit_skeleton.C - Same as exit_skeleton_c, except that it is compiled with one of the C++ compilers
listed in the Connect:Direct for UNIX User Guide.
• exit_sample.c - This is the same program as the skeleton user exit program, except that the security exit
is demonstrated with code that approximates PassTicket functionality.

Connect:Direct for UNIX Configuration Files

Connect:Direct for UNIX creates the following configuration files during installation and customization.
These files are required for the Connect:Direct for UNIX server to operate correctly.
Initialization parameters file
Provides information to the server to use at start up. During the installation, you identify the settings
necessary for the initialization parameters file.
User authorization information file
Contains the local user information and remote user information record types. You customize this file
during installation to map remote user IDs to local user IDs and create remote user information
records in the user authorization information file.

14 IBM Connect:Direct for UNIX: Documentation

 Strong access control file
Improves the security of Connect:Direct for UNIX and allows, denies, or limits root access control.
This file is created when you install Connect:Direct for UNIX. If the file is deleted or corrupted, access
to Connect:Direct for UNIX is denied to all users.
Network map file
Describes the local node and other Connect:Direct for UNIX nodes in the network. You can define a
remote node record for each node that Connect:Direct for UNIX communicates with.
Server authentication key file
Verifies client API connection requests. Only verified clients are granted a connection.
Client configuration file
Identifies the port and host name used by a client to connect to Connect:Direct for UNIX.
Client authentication key file
Identifies Connect:Direct for UNIX servers that a Connect:Direct for UNIX client connects to. You can
have multiple entries for multiple servers.

Connect:Direct for UNIX Directory Structure

The directory tree starts at d_dir/, the destination directory where the software is installed. This directory
structure provides for multiple nodes on the same network and possibly on the same computer. The
directory structure organization enables you to share Connect:Direct for UNIX programs, such as cdpmgr
and ndmcmgr. The secure+ directory is available only when Connect:Direct for UNIX Secure Plus is
installed.
If multiple nodes exist, each node must have its own d_dir/ndm/cfg/cd_node/ directory structure for
configuration files, where cd_node is the Connect:Direct for UNIX node name.
A d_dir/work/cd_node directory is created for each node.

Installation Overview
The Installing section provides a quick reference to the installation process for Connect:Direct for UNIX
followed by a detailed process. The installation and upgrade processes both include downloading
installation items, completing prerequisites, preparing systems, running the installer, and completing the
post-installation configurations.
Note: IBM Connect:Direct for UNIX can be deployed using an IBM Certified Container.
• The certified container offers a Red Hat certified IBM Connect:Direct for UNIX image and Helm chart
and can be used to deploy a production-ready IBM Connect:Direct image into Red Hat OpenShift/
Kubernetes Service. For more information on see, “Deploying IBM Connect:Direct for UNIX using an IBM
Certified Container Software” on page 49.
• Additionally, this Red Hat certified container image can also be deployed in a standalone Docker
environment. For more information see, “Deploying IBM Connect:Direct for UNIX using a Docker
container” on page 37.

Install/Deploy Connect:Direct for UNIX

You can install and/or deploy Connect:Direct for UNIX using any of the following methods.

Table 1. Installing Connect:Direct for UNIX for the first time

Scenario Resource
Install using the conventional method “Installing Connect:Direct for UNIX” on page 16
Silent Installation method Connect:Direct for UNIX Silent Installation

Chapter 2. Getting Started Guide 15

 Table 1. Installing Connect:Direct for UNIX for the first time (continued)
Scenario Resource
Deploy Connect:Direct for UNIX using a Docker “Deploying IBM Connect:Direct for UNIX using a
container Docker container” on page 37
Deploy Connect:Direct for UNIX using an IBM “Deploying IBM Connect:Direct for UNIX using an
certified container IBM Certified Container Software” on page 49

Installing Connect:Direct for UNIX

Before you install Connect:Direct for UNIX, complete the worksheets to identify all information required
to perform the installation.
Connect:Direct for UNIX requires that you install a server and at least one client location. You can install
Connect:Direct for UNIX in different configurations:
• Install the server on a local system and the clients on remote systems
• Install the server and at least one client on a local system and the remaining clients on remote systems
Install Connect:Direct for UNIX on a local drive. Do not install Connect:Direct for UNIX on a Network File
System (NFS) resource.
• Install using a Silent Installation. See IBM Connect:Direct for Unix silent installation in the Mass
Deployment documentation library.

Preparing to Install Connect:Direct for UNIX in a Cluster Environment

Connect:Direct for UNIX supports clustering software to allow two or more computers to appear to other
systems as a single system. All computers in the cluster are accessible through a single IP address.
Connect:Direct for UNIX can be installed in two types of clustering environments: high availability and
load balancing clustering environments.

High-Availability Cluster Environments

Consider the following information when planning to use Connect:Direct for UNIX in a high-availability
cluster environment.

Supported High-Availability Cluster Environments

Connect:Direct for UNIX is certified to operate in the following high-availability cluster environments:
• IBM high-availability cluster multiprocessing (HACMP) environment
• Hewlett-Packard MC/Service Guard
• SunCluster versions 2.2, 3.0, and 3.2.
If you plan to install Connect:Direct for UNIX in a high-availability cluster environment, complete the
following tasks:
• Install the clustering software on each computer in the cluster, including setting up a logical host or
application package.
• Create a user with the same name and user ID on each cluster node.
• Create a Connect:Direct Secure Plus subdirectory on a shared file system on a shared volume group.
• Ensure that the shared file system is owned by the IBM Connect:Direct user.
• Install IBM Connect:Direct on the shared file system.
• Perform the procedures necessary to define the high-availability settings and configure the cluster
environment.

16 IBM Connect:Direct for UNIX: Documentation

Limitations of High-Availability Clusters
When running Connect:Direct for UNIX in a high-availability cluster environment, be aware of the
following limitations:
• If a failure occurs, all Processes being held will be restarted when IBM Connect:Direct is restarted. This
includes Processes that are held by the operator as well as Processes held in error. This could cause a
security risk.
• When a IBM Connect:Direct ndmsmgr process associated with a IBM Connect:Direct Process is killed,
the Process is not automatically restarted and is put in the Held in Error state. It must be manually
restarted; otherwise, the IBM Connect:Direct Process is restarted when the cluster restart occurs.

Load-Balancing Cluster Environments

In a load-balancing cluster environment, an incoming session is distributed to one of the Connect:Direct
for UNIX instances based on criteria defined in the load balancer. Generally, from the point of view of the
nodes behind the load balancer, only incoming or SNODE sessions are affected by the load balancer.
PNODE, or outgoing sessions, operate the same way as non-cluster Connect:Direct for UNIX PNODE
sessions.

SNODE Server Considerations for Load-Balancing Clusters

Consider the following when planning and setting up the Connect:Direct for UNIX SNODE servers in a load
balancing cluster:
• The servers used for the Connect:Direct for UNIX instances behind the load balancer must all have
access to common shared disk storage because of the following:
– Any copy statement source and destination files for SNODE processes must reside in directories
accessible to all servers.
– All nodes must have access to a common SNODE work area and that area must be on a cluster file
system or a Network File System version 4 (NFSv4) or greater resource. This includes the Amazon
Elastic File System (EFS), as it is mounted via NFSv4 protocol. NFSv3 is not supported.
– All servers must be of the same platform type (for example, all Solaris SPARC or all Linux Intel) and
the same Connect:Direct for UNIX version and maintenance level.
• The system clocks on all servers must be synchronized in order for copy checkpoint/restart and run task
synchronization to work.
• The administrator user ID used to install Connect:Direct for UNIX must be defined on each server and
must be the same user and group number on each server.

SNODE Setup for Load-Balancing Clusters

Consider the following when planning and setting up the Connect:Direct for UNIX SNODEs in a load-
balancing cluster:
• One Connect:Direct for UNIX node should be installed on each server behind the load balancer.
• Each node should be installed by the same user ID.
• Each node should have the same Connect:Direct for UNIX node name.
• Each node should have the same node-to-node connection listening port.
• A directory should be established for the shared SNODE work area used by the Connect:Direct for UNIX
nodes behind the load balancer. This directory should be owned by the Connect:Direct for UNIX
administrator ID and must be accessible to all of the servers behind the load balancer.
• Each node should specify the same path to the directory used for the shared SNODE work area. Specify
this path in the snode.work.path parameter of the ndm.path record in the initialization parameter file.

Limitations of Load Balancing Clusters

When running Connect:Direct for UNIX in a cluster environment, be aware of the following limitations:

Chapter 2. Getting Started Guide 17

 • If an incoming session fails and is restarted by the PNODE, then the restarted session may be assigned
to any of the instances behind the load balancer and will not necessarily be established with the original
SNODE instance.
• When shared SNODE work areas are configured and the run task is on the SNODE, then at restart time,
Connect:Direct for UNIX cannot determine whether the original task is still active or not because the
restart session may be with a different server. If you set the global run task restart parameters to yes in
the initialization parameters file, a task could be restarted even though it may be active on another
machine. Therefore, exercise caution when specifying restart=y.
• Each SNODE instance that receives a session for a given Process creates a TCQ entry for the Process.
Each SNODE instance has its own TCQ file, and these files are not shared among SNODE instances. Only
the work files created in the shared work area are shared among SNODE instances.
• When a Process is interrupted and restarted to a different SNODE instance, the statistics records for
that Process is distributed between the two SNODE instances involved. As a result, you cannot select all
the statistics records for a Process.

Conventions to Observe When Installing Connect:Direct for UNIX

Observe the following conventions when you install Connect:Direct for UNIX:
• Characters used in Netmap Node Names (or Secure+ Node Names or Secure+ Alias Names) should be
restricted to A-Z, a-z, 0-9 and @ # $ . _ - to ensure that the entries can be properly managed by Control
Center, Sterling Connect:Direct Browser User Interface, or IBM Sterling Connect:Direct Application
Interface for Java for Java (AIJ) programs.
• Acceptable responses to prompts are listed in brackets, where y specifies yes, n specifies no, and a
specifies all.
• The default response is capitalized. Press Enter to accept the default value.
• Do not use colons (:) for values in the installation and customization scripts.
• Do not use keywords for values.
• Press Enter after each entry to continue.
• Terminate any procedure by pressing Ctrl-C.

Worksheet Instructions
Before you install IBM Connect:Direct for UNIX, complete the worksheets to help you gather the
information needed to complete the installation.
Complete the following worksheets before you begin the installation.
• Installation Worksheet
• User Authorization Information File Worksheet
• CLI/API Configuration File Worksheet
The following worksheets are provided for your convenience:
• Network Map Remote Node Information File Worksheet
• Server Authentication key File Worksheet
• Client Authentication key File Worksheet

Installation Worksheet
Complete this worksheet to assist you during the installation procedure.

Parameter Value
TCP/IP host name of the computer where the IBM Connect:Direct server is installed
Directory or path on which the distribution media will be mounted

18 IBM Connect:Direct for UNIX: Documentation

Parameter Value
Destination directory where IBM Connect:Direct will be installed, including the full
path name

Customization Worksheet
Use this worksheet during customization. Refer to the Customizing Connect:Direct for UNIX.

Parameter Default Value to Use

Value
Connect:Direct node name you are customizing, up to 16 characters long.
Important: Characters used in Netmap Node Names (or Secure+ Node
Names or Secure+ Alias Names) should be restricted to A-Z, a-z, 0-9 and @
# $ . _ - to ensure that the entries can be properly managed by Control
Center, Sterling Connect:Direct Browser User Interface, or IBM Sterling
Connect:Direct Application Interface for Java for Java (AIJ) programs.

Initialization Parameters File Information

TCP/IP port number that the server monitors for an API connection 1363
request.
TCP/IP port number that the server monitors for a remote Connect:Direct 1364
connection request:
Note: Use the default port number, if available. If the default port number
is being used by another service, use any other available port. Check
the /etc/services file for a list of ports.

TCP/IP RPC port on Solaris SPARC and HPUX-IT 1367

User Authorization Information File Worksheet

Use this worksheet when you are defining the user authorization information which includes the remote
user information records and local user information records.
All IBM Connect:Direct users must have an entry in the user authorization information file.

Remote User Information Record

IBM Connect:Direct uses the remote user information record to establish a proxy relationship between
remote and local user IDs. Remote user IDs are translated to valid local user IDs on the system where you
are installing Connect:Direct for UNIX. IBM Connect:Direct also uses the remote and local user
information records to determine the functionality of the user IDs that are translated and connected to it
through a client using a IBM Connect:Direct API.
Use the following table to create a list of remote user IDs and the local user IDs to which they will be
mapped. If necessary, make copies of this page to record additional remote user IDs and local user IDs.
For more information on creating remote user information records and for information on using special
generic characters to map remote user IDs, refer to the IBM Connect:Direct for UNIX Administration
Guide.

Remote User ID at Remote Node Name mapped to Local User ID

@ =
@ =
@ =

Chapter 2. Getting Started Guide 19

 Remote User ID at Remote Node Name mapped to Local User ID
@ =
@ =
@ =
@ =
@ =
@ =
@ =
@ =
@ =
@ =
@ =
@ =

Local User Information Record

Use the following table to record the local user ID records to create and the parameters to define. Define
the additional parameters by editing the userfile.cfg file using any standard UNIX editor.
Default values are shown as capital letters in brackets. Before you begin defining local user information
records, make copies of this worksheet for the number of users you plan to create.

Local User ID Parameter Description Value to Assign

admin.auth Determines if the user has
administrative authority.
y—All the other command
parameter capabilities in the local
user information record are
automatically assigned to this user.
n—You must grant specific
command parameters individually.

client.cert_auth Determines if the user can perform y | n

certificate authentication for client
API connections.
y—Enables client certificate
authentication for the user
n—Disables client certificate
authentication for the user

20 IBM Connect:Direct for UNIX: Documentation

Local User ID Parameter Description Value to Assign
client.source_ip Use this parameter to list all of the A comma-separated
IP addresses and/or host names list of client IP
that are valid for this user's API addresses or host
connection. If you specify values names associated
for this field, the IP address of this with client IP
user's API connection is validated addresses.
with the client.source_ip list. If the
IP address does not match the one The IP address of the
specified on the list, the connection client connection for
is rejected. this user must match
the address
configured in this
field.
For example:
nnn.nnn.nnn.nnn,
localhost

cmd.chgproc Specifies whether the user can

issue the change Process
command.
y—Allows the user to issue the
command.
n—Prevents the user from issuing
the command.
a—Allows all users to issue this
command.

cmd.delproc Specifies whether the user can y | n |a

issue the delete Process command.
y—Default
y—Allows the user to issue the
a—For all users
command.
n—Prevents the user from issuing
the command.
a—Allows all users to issue this
command.

cmd.flsproc Specifies whether the user can y | n |a

issue the flush Process command.
y—Default
y—Allows the user to issue the
a—For all users
command.
n—Prevents the user from issuing
the command.
a—Allows all users to issue this
command.

Chapter 2. Getting Started Guide 21

 Local User ID Parameter Description Value to Assign
cmd.selproc Specifies whether the user can
issue the select Process command.
y—Allows the user to issue the
command.
n—Prevents the user from issuing
the command.
a—Allows all users to issue this
command.

cmd.selstats Specifies whether the user can

issue the select statistics
command.
y—Allows the user to issue the
command.
n—Prevents the user from issuing
the command.
a—Allows all users to issue this
command.

cmd.stopndm Specifies whether the user can

issue the stop command.
y—Allows the user to issue the
command.
n—Prevents the user from issuing
the command.

cmd.submit Specifies whether the user can

issue the submit Process
command.
y—Allows the user to issue the
command.
n—Prevents the user from issuing
the command.

cmd.trace Specifies whether the user can

issue the trace command.
y—Allows the user to issue the
command.
n—Prevents the user from issuing
the command.

descrip Permits the administrator to add text string

descriptive notes to the record. ________________
name Specifies the name of the user. user name
________________
phone Specifies the telephone number of user phone
the user. ________________

22 IBM Connect:Direct for UNIX: Documentation

Local User ID Parameter Description Value to Assign
pstmt.copy Specifies whether the user can
issue the copy command.
y—Allows the user to issue the
command.
n—Prevents the user from issuing
the command.

pstmt.copy. Specifies the action to take when

the limit on a user output file size is
ulimit
exceeded during a copy operation.
The value for this parameter
overrides the equivalent value for
the ulimit parameter in the
initialization parameters file. If a
value is not defined in the
initialization parameters file, the
default is n.
y or n or nnnnnnnK or nnnnM or nG
where nnnnnnnK, nnnnM or nG
establishes a default output file
size limit for all copy operations.
K—Thousands of bytes.
M—Denotes millions of bytes.
G—Denotes billions of bytes.
The maximum value you can
specify is 1 trillion byte.

pstmt.download Specifies whether the user can

download files.
y—Allows the user to issue the
command.
n—Prevents the user from issuing
the command.

pstmt.download Specifies the directory to which the

user can download files.
_dir

pstmt.runjob Specifies whether the user can

issue the run job statement.
y—Allows the user to issue the
command.
n—Prevents the user from issuing
the command.

Chapter 2. Getting Started Guide 23

 Local User ID Parameter Description Value to Assign
pstmt.runtask Specifies whether the user can
issue the run task statement.
y—Allows the user to issue the
command.
n—Prevents the user from issuing
the command.

pstmt.submit Specifies whether the user can

issue the submit statement.
y—Allows the user to issue the
command.
n—Prevents the user from issuing
the command.

snode.ovrd Specifies whether the user can

code the snodeid parameter on the
submit command and Process and
submit statements.
y—Allows the user to issue the
command.
n—Prevents the user from issuing
the command.

pstmt.upload Specifies whether the user can

upload files.
y—Allows the user to issue the
command.
n—Prevents the user from issuing
the command.

pstmt.upload_dir Specifies the directory from which

the user can upload files.
run_dir Specifies the directory that
contains the programs and scripts
the user can execute.
submit_dir Specifies the directory from which
the user can submit Processes.

CLI/API Configuration File Worksheet

Use this worksheet to define the parameters needed to create a client configuration file. Create a separate
file for each client attached to the server.

Parameter Default Value Value To Use

Port number of the Connect:Direct for UNIX server to which 1363
this client will connect.
Note: Use the default port number if available. If the default
port number is being used by another service, use any other
available port. Check the /etc/services file for a list of ports.

24 IBM Connect:Direct for UNIX: Documentation

Parameter Default Value Value To Use
Host name of the Connect:Direct for UNIX server to which this
API will connect.
You can also type the IP address of the server.

Network Map Remote Node Information File Worksheet (TCP/IP)

The initial network map file containing a local node definition is created for you during the installation
procedure; however, you must add a remote node record to the network map for each remote node you
will communicate with unless you plan to specify the IP address or host name with the SNODE parameter
when you submit a Process.
You must define a remote node information record for any node you plan to communicate with using UDT.
You cannot specify a hostname or IP address for the SNODE in a Process if you are using UDT to
communicate with the remote node.
Use the information on this worksheet when you modify the network map. Make a copy of this worksheet
for each remote node in the network.

Parameter Default Value Value To Use

Remote Connect:Direct node name
Host name or IP address on which the remote IBM
Connect:Direct server will run.
Communication port number to call the remote Connect:Direct 1364
server:
comm.transport (UDT only)

Server Authentication Key File Worksheet

The initial server authentication key file is created during the installation procedure; however, you can
update your key later. Use the information on this worksheet when you modify your key.

Parameter Default Value Value To Use

The host name on which the API is executed. *
An asterisk (*) stands for any host.

IBM Connect:Direct security depends on a key (similar to a password) in a IBM Connect:Direct server and
an identical key in each API that communicates with that server. The keys are defined and coordinated by
the system administrator of the specific node or nodes, and should be kept secure. Be sure the
authentication keys are available during installation, but do not record them on this worksheet or where
they can be lost.

Client Authentication Key File Worksheet

The initial client authentication key file is created automatically during the installation; however, you can
update your key at a later date. Use the information on this worksheet when you modify the key.

Parameter Default Value Value To Use

The host name on which a IBM Connect:Direct is executed. *
An asterisk (*) stands for any host.

Chapter 2. Getting Started Guide 25

 IBM Connect:Direct security depends on a key, similar to a password, in a IBM Connect:Direct server and
an identical key in each API that will communicate with that server. The keys are defined and coordinated
by the system administrator of the specific node or nodes, and should be kept secure.
Have the authentication keys you will use available during installation, but do not record them on this
worksheet or anywhere else that could compromise security.

Installing IBM Connect:Direct

To install Connect:Direct for UNIX:

Procedure
1. If you downloaded the software from IBM Passport Advantage, extract the installation files from the
download folder.
Note: For information on the how to download software using Passport Advantage see, https://
www.ibm.com/software/passportadvantage/index.html.
2. Log on to the UNIX system with the privileges required to install software. You can create an account
specifically for this purpose. Do not install as root.
3. Type the following command and press Enter to change to the directory that correspond to the UNIX
platform:

cd /<platform directory>

Refer to the following information for the name of the platform directory for each platform.
HP UX Itanium
HP_Itanium
IBM System pSeries
IBM
Sun SPARC systems
Sun_Solaris
Red Hat
RedHat_linux
SuSE
SuSE_linux
Linux for zSeries
IBMS390_linux
4. Type the following command to start the installation and press Enter:

cdinstall

Installation on Linux platforms displays the following message: awk: cmd. line:6: warning: escape
sequence `\.' treated as plain `.'
This is a known issue with Install Anywhere and does not affect installation or functionality of Sterling
Connect:Direct File Agent for UNIX on Linux.
5. Read the information displayed and press Enter.
6. Type the path name of the directory where Connect:Direct for UNIX will be installed and press Enter.
7. Press Enter to confirm the location
8. Do one of the following:

26 IBM Connect:Direct for UNIX: Documentation

 • Press Enter to accept install the Server and Client on the same computer.
• Type 2 to install the Server only and press Enter.
• Type 3 to install the Client only and press Enter.
The following screen is displayed:
9. Type the path and filename of the installation file and press Enter.
If you are installing the Server and Client, a message is displayed to confirm that the server and client
are being installed. If you selected option 2 or 3, the screen displays the software that will be
installed.
10. Press Enter.
If the destination directory does not have enough disk space, delete files to provide the necessary
disk space. If disk space is available, the installation script copies files from the distribution media to
the destination directory and verifies that the correct number of files and blocks are copied.
The customization script starts automatically when the installation is complete.

Customizing Connect:Direct for UNIX

The customization script starts automatically after the installation is complete to set up the
Connect:Direct for UNIX operating environment. It is located in d_dir/etc, where d_dir is the IBM
Connect:Direct installation directory, and may be run by itself if needed for future configuration changes.
The option you select determines what Connect:Direct for UNIX operating environment is configured: the
Connect:Direct for UNIX Server only, the Connect:Direct for UNIX Client only, or the Connect:Direct for
UNIX Server and Client.

About this task

After you customize the environment, you need to configure Connect:Direct for UNIX for using root
privilege to create a Strong Access Control List (SACL) file and to set the owner and permissions of IBM
Connect:Direct executables. You must create the SACL file and set the owner and permissions before you
can run Connect:Direct for UNIX. See Configuring Connect:Direct for UNIX Using Root Privilege for more
information about this process.
The customization script prompts you to begin the customization procedure:

Procedure
1. Read the information and press Enter. The customization menu is displayed.
2. Do one of the following. Be sure to select the same configuration you selected during the installation.
• Type 3 to customize the Server and Client and press Enter.
If you are installing both the Client and the Server, complete the procedures in Setting Up the
Connect:Direct for UNIX Server and Setting Up the Connect:Direct for UNIX Client.
• Type 2 to customize the Client only and press Enter.
If you are installing the Client only, complete the procedure Setting Up the Connect:Direct for UNIX
Client.
• Type 1 to customize the Server only and press Enter.
If you are installing the Connect:Direct for UNIX Server only, complete the procedure, Setting Up the
Connect:Direct for UNIX Server.

Chapter 2. Getting Started Guide 27

Setting Up the IBM Connect:Direct Server
After you install Connect:Direct for UNIX, define the parameters needed by the Server for startup. If you
installed the Server, the process to customize the Server starts automatically. To customize the server,
enter the node to customize.

Procedure
1. Type the name of the node, up to 16 characters, that you want to customize and press Enter.
Important: Characters used in Netmap Node Names (or Secure+ Node Names or Secure+ Alias
Names) should be restricted to A-Z, a-z, 0-9 and @ # $ . _ - to ensure that the entries can be properly
managed by Control Center, Connect:Direct Browser User Interface, or IBM Sterling Connect:Direct
Application Interface for Java for Java (AIJ) programs. However, use of ‘@’ characters in a node name
is discouraged, as it will cause some clients to display proxy records incorrectly. If the ‘@’ character is
at the end of a node name, client display of a proxy record with this node name will fail.
2. Type the TCP/IP port number that Connect:Direct monitors for requests from remote nodes. If
available, use the default port, 1364. If the default port number is being used by another service, use
any other available port.
This value is entered into the initialization parameters file in the comm.info parameter.
3. Type the hostname or IP address that Connect:Direct Monitors for requests from remote nodes.
If you use 0.0.0.0, Connect:Direct will listen for requests from remote nodes on all network adapters
configured on the UNIX server.
This value is entered into the initialization parameters file in the comm.info parameter.
4. Type the TCP/IP port number that Connect:Direct monitors for requests from Clients. If available, use
the default value of 1363. If the default port number is being used by another service, use any other
available port.
This value is entered into the network map file in the tcp.api parameter.
5. Type the hostname or IP address that Connect:Direct monitors for requests from Clients.
This value is entered into the network map file in the tcp.api parameter.
Connect:Direct creates the network map file and displays the directory path and file name.
After you define the initialization parameters file, the customization script creates the network map
file. A remote node record is added to the network map file. The remote node record is assigned the
name of the local node you specified.
6. Type the TCP/IP port to listen for a PMGR RPC client request.
This value is entered in the network map file in the rpc.pmgr.port parameter.
Note: This prompt displays only on HPUXIT and SOLARIS-based deployments.
7. Press Enter. The netmap file is automatically created.

Customizing the User Authorization Information File

After the user authorization information file is created, you are ready to customize the file. Use this
procedure to map remote user IDs to local user IDs and create remote user information records in the
user authorization information file.

About this task

After the user authorization information file is created, the following message is displayed to prompt you
to create an authorization information record for a remote user:

Insert remote user record? [Y/n]

28 IBM Connect:Direct for UNIX: Documentation

 Procedure
1. Press Enter to add a remote user record.
2. Type the login or ID of the remote user and press Enter.
3. Type the name of the remote node and press Enter. The submitter ID and remote node name become
the record name for the remote user information record.
4. Type the local user ID where the remote user ID will be mapped and press Enter. The local user ID is
the UNIX account name. This value is associated with local.id in the remote user information record
and defines the local user ID used to check security for the remote user.
5. Do one of the following:
• To create another remote user record, press Enter and repeat steps 2-4.
• Type n and press Enter if you do not want to create another remote user record.
6. Do one of the following:
• If you do not want to create a local user record, type n and press Enter.
• To create a local user record, press Enter.
7. Type the user ID for the local user and press Enter. This value is associated with userid in the user
authorization information file.
8. Press Enter to grant administrative authority to the local user ID. All IBM Connect:Direct capabilities
that you specify in the local user information record are assigned to the user.
This value is assigned to admin.auth in the local user information record.
9. Do one of the following:
• Press Enter and repeat this procedure to create another local user record.
• Type n and press Enter to continue to the next task.

Creating an Authentication Key File

A server authentication key file verifies connection requests. Only authorized clients are granted a
connection. IBM Connect:Direct generates the server authentication key file automatically. A message is
displayed when the authenticaton key file is generated.

Before you begin

Press Enter to continue.

Setting Up the Connect:Direct for UNIX Client

After you install and customize Connect:Direct for UNIX Server, define the parameters needed by the
Client for startup. To configure the client, configure the client configuration file and the client
authentication key file to define all of the servers that this node connects to.

About this task

The Client configuration file is created during the customization process. A message is displayed after the
Client configuration file is created.
To set up the client:

Procedure
1. Type the port of the Server that the Client connects to and press Enter when ready.
This value is associated with tcp.port in the Client configuration file.
2. Press Enter to accept the host name. This value is displayed in the tcp.hostname parameter in the
Client configuration file.

Chapter 2. Getting Started Guide 29

 A message is displayed when the client authentication key file is created.
3. Press Enter .

Configuring Connect:Direct for UNIX Using Root Privilege

The Connect:Direct for UNIX Process Manager and Session Managers run as root to support
Connect:Direct's user impersonation model. Before Connect:Direct accesses a source or destination file
or executes a run task or a run job, it performs a programmatic logon to assume the identity of the
appropriate user. This model enables a Connect:Direct user to use file system permissions to tightly
control access to the user's data files. Supporting this model requires Connect:Direct to run as root.

About this task

You must create the SACL file and set the owner and permissions of the IBM Connect:Direct executables
to run Connect:Direct for UNIX.
To configure the SACL file:

Procedure
1. If you know the root password or if a system administrator is standing by who knows the root
password, select option 4.
2. If you do not know the root password, but are authorized to gain root authority using sudo or a similar
utility, type 5 to exit the Connect:Direct for UNIX customization script.
A message is displayed to warn you that the SACL was not configured.
3. Read the information displayed and press Enter.
A message is displayed to notify you of the creation of the test configuration.
4. To exit the customization, type n and press Enter.
5. If you did not select option 4 above, type cdcust (located in /<product install directory>/etc) using
sudo to become root before creating the SACL and setting the owner and permissions of the
executables.

Customizing the Owner and Permissions for the Executable Files

You must change the file attributes of the Session Manager (d_dir/ndm/bin/ndmsmgr), Process Manager
(d_dir/ndm/bin/cdpmgr), Command Manager (d_dir/ndm/bin/ndmcmgr) User Manager (d_dir/ndm/bin/
ndmumgr), Statistics Manager (d_dir/ndm/bin/cdstatm), Client Authenticator (d_dir/ndm/bin/ndmauthc),
and Server Authenticator (d_dir/ndm/bin/ndmauths).

About this task

To customize the SACL file and set the owner and permissions of the IBM Connect:Direct executable files:

Procedure
1. Type the full path of the IBM Connect:Direct destination directory and press Enter.
2. Press Enter to continue the customization. The following screen is displayed:
3. Type 4 to select Configurations requiring root privilege and press Enter.
4. Press Enter to configure the SACL file.
5. Press Enter to use root authority to create and check the SACL file.
6. If you have already assumed root authority by using a utility such as sudo, press Enter. Otherwise,
type the root password and press Enter.
If you type the root password incorrectly, a message informs you that the configuration tasks were not
completed. Otherwise, a SACL file is created, the owner and permissions of the IBM Connect:Direct
executable files are set, and the following messages and prompt are displayed.

30 IBM Connect:Direct for UNIX: Documentation

 7. Type y or n and press Enter. You are returned to the Customization menu.
The following parameters are modified during the customization:

Parameter Value File

comm.info Identifies the IP address and port Initialization
that IBM Connect:Direct monitors parameters file
for requests from remote nodes
tcp.api Identifies the IP address and port Network map file
monitored by IBM Connect:Direct
for requests from clients
rnode.listen Identifies the host used to monitor Initialization
LU 6.2 connections parameters file
admin.auth Determines if user ID has User authorization
administrative authority information file
tcp.port Specifies port number of the server Client configuration
that the client connects to file
tcp.hostname Specifies host name of the server Client configuration
that the client connects to file

Installing Connect:Direct File Agent

After you install IBM Connect:Direct, install Connect:Direct File Agent at any time.

About this task

If you are installing on Linux for zSeries, download the Java 1.6 software from the manufacturer's Web
site before continuing the installation. Your PATH environment variable must include the full path to the
installed Java software.
To install Connect:Direct File Agent:

Procedure
1. Log on to the UNIX system with the privileges required to install software. Do not install as root.
2. Type the following command and press Enter to change to the directory for your UNIX platform:

cd /cdrom/<platform directory>

Refer to the following list for the name of the platform directory for each platform:
HP UX Itanium
HP_Itanium
IBM System pSeries
IBM
Sun SPARC systems
Sun_Solaris
Red Hat
RedHat_linux
SuSE
SuSE_linux

Chapter 2. Getting Started Guide 31

 Linux zSeries
IBMS390_linux
3. Type the following command to start the installation and press Enter:

cdinstall
4. Read the information displayed and press Enter.
5. Type the path and press Enter. A warning that the directory exists is displayed:
6. Press Enter to continue. The following message is displayed:

Installed components detected in this directory.

A previous version of C:D for UNIX was detected.
Would you like this procedure to detect and upgrade your currently installed
options with minimal interaction?
If yes, the configuration files will be left in place and reused.
If not, the full installation procedure will prompt to either reuse, or purge
and rebuild, each configuration file.
Caution: If you are upgrading from earlier version of C:D for UNIX,
existing Processes in the tcq may encounter conversion error.
They will need to be deleted and resubmitted.
Type y or press Enter to continue with the upgrade procedure, or
type n to run the full installation procedure:[Y/n]

7. Type n and press Enter. The installation options menu is displayed:

8. Select 4 and press Enter.
9. Type the full Connect:Direct for UNIX installation path and filename and press Enter.
10. Press Enter to confirm the installation.
If sufficient space is available, the installation begins. If not, you are prompted to delete files to
provide the necessary disk space and the installation exits. After you have enough space, restart the
installation.
11. After the installation completes, press Enter to return to the installation menu.

Installing Connect:Direct Secure Plus

After you install Connect:Direct for UNIX, you can install Connect:Direct Secure Plus at any time.

About this task

To install Connect:Direct Secure Plus:

Procedure
1. Log on to the UNIX system with the privileges required to install software. You can create an account
specifically for this purpose. Do not install as root.
2. From the distribution media, type the following command and press Enter to change to the directory
that correspond to the UNIX platform:

cd /cdrom/<platform directory>

Refer to the following list for the name of the platform directory for each platform:
HP UX Itanium
HP_Itanium
IBM System pSeries
IBM

32 IBM Connect:Direct for UNIX: Documentation

 Sun SPARC systems
Sun_Solaris
Red Hat
RedHat_linux
SuSE
SuSE_linux
Linux zSeries
IBMS390_linux
3. Type the following command to start the installation and press Enter:

cdinstall
4. Read the information displayed and press Enter.
5. Type the path and press Enter. A warning that the directory exists is displayed.
6. Press Enter to continue. The message that installed components are detected is displayed.
7. Type n and press Enter to run the full installation procedure. The following screen is displayed:

Connect:Direct for UNIX installation directory specified:

[directory path]
Please select one of the following installation options:

(1) Connect:Direct for UNIX Server and Client(CLI/API)

(2) Connect:Direct for UNIX Server
(3) Connect:Direct for UNIX Client(CLI/API)
(4) Connect:Direct for UNIX File Agent
(5) Connect:Direct for UNIX Secure+ Option for UNIX
(6) EXIT

Enter your choice:[1]

8. Type 5 and press Enter.

9. Type the full installation path and filename and press Enter.
10. Press Enter to confirm the installation.
The program determines if space exists to complete the operation. If so, the Connect:Direct Secure
Plus installation script and cpio files are extracted. If not, you are prompted to delete enough files.
After you clear enough space, restart the installation procedure.
11. Read the information and press Enter.
12. Press Enter to confirm the installation location. A message is displayed regarding the amount of disk
space required to install Connect:Direct Secure Plus. If sufficient space is available, press Enter. If
not, you are prompted to delete enough files to provide the enough space. The installation then exits.
After you have cleared enough space, restart the installation.A screen is displayed as the files are
extracted and the JRE is configured. After the JRE is configured, the following prompt is displayed:
13. Press Enter if your node name is displayed. If your node name is not displayed, type your node name
and press Enter.
14. Type a passphrase of at least 32 random characters and press Enter. The installation is complete.
15. Press Enter to return to the installation menu.

Chapter 2. Getting Started Guide 33

 Connect:Direct Server and its Client connections
For client-server connections between a Connect:Direct Server and its clients be aware of the following
limitations.
The connections between a Connect:Direct Server and the following clients are not secure:
• Connect:Direct Requester
• Windows CLI
• User-defined Windows SDK Client
• Connect:Direct for UNIX CLI
• User-defined UNIX ndampi Client
• Sterling File Agent
Though passwords sent by any of these clients to the Connect:Direct Server are obfuscated, the session is
still not encrypted.

Defining High-Availability Settings in the Configuration Files

After you install Connect:Direct for UNIX on a shared file system, modify IBM Connect:Direct parameters
to support a clustering environment. Install Connect:Direct for UNIX on a shared cluster file system to use
it in a cluster environment. Complete the following procedure to modify the configuration files for a
cluster environment:

Procedure
1. Modify the following parameters:
• In the initialization parameters file (initparm.cfg), set :comm.info=0.0.0.0;nnnn:\ where nnnn is the
number of the listening port you defined during installation.
• In the api.parms record of the NDMAPI configuration file (ndmapi.cfg),
set :tcp.hostname=logical_host_ip_name:\ where logical_host_ip_name is the virtual address of the
cluster.
• In the network map file (netmap.cfg), set :tcp.api=logical_host_ip_name;nnnn:\ where nnnn is the
API port you defined during installation.
2. In the network map file (netmap.cfg), set the outgoing address parameter in the local.node record to
specify the local host IP name or address of the floating address to the following value. The remote
node will also use this value for network map checking.

:outgoing.address=(host name |nnnnnn.nnn):\

3. Modify the following records in the network map file:
• Set :comm.info=logical_host_ip_name;1364:\ to configure the loopback remote node record.
• Set tcp.max.time.to.wait to a value other than zero and less than the value set in the resource group
manager of the cluster software to allow for clean shutdowns.
4. In the same volume group as the installation file system, create a user data file system that is shared
by all cluster nodes.

Setting Up Additional Configuration Requirements in a SunCluster 3.X

Environment
The High-Availability cluster commands shown below are not intended to be a complete set of
instructions for setting up the High-Availability cluster software. Additional steps may be required to
complete the configuration of the High-Availability environment. High-Availability cluster expertise is the
responsibility of the customer. White papers detailing specific environments, setup steps, and testing of
various High-Availability clusters are available on the Support On Demand web site. In addition to
modifying the configuration files, complete the following procedure to set up a SunCluster 3.X cluster:

34 IBM Connect:Direct for UNIX: Documentation

 Procedure
1. Type the following command to create the cluster resource:

scdscreate -V SCI -T cd

Use the V parameter to define the vendor ID and T parameter to define the resource ID.
2. Type the following command to configure the custom resource scripts:

scdsconfig
3. Edit the SCI.cd resource file and change the value of RT_BASEDIR as follows:

RT_BASEDIR=/opt/SCIcd/bin;
RT_BASEDIR=/global/vol1/sci/cduserk1/3.5.00/suncluster+scripts/SCIcd/bin;

Configuring Additional Requirements in a SunCluster 2.2 Environment

In addition to modifying the configuration files, complete the following steps to complete the SunCluster
2.2 setup:

Procedure
1. Place the following sample scripts and configuration files in a directory that is available to SunCluster
2.2 software:
• cd_start.sh
• cd_stop.sh
2. Update the scripts as required for your environment.
3. Copy the sample scripts to all nodes in the cluster.
4. Issue the hareg command to register the IBM Connect:Direct data service. Refer to the SunCluster
documentation for more information. Following is a sample command:

hareg -r cd \

Setting Up Additional Configuration Requirements for IBM HACMP

In addition to modifying the configuration files, complete the following steps to complete the IBM high-
availability cluster multiprocessing (HACMP) setup:

Procedure
1. Place the following sample scripts and configuration files in a directory that is available to the IBM
HACMP software:
• cd_start_net.sh
• cd_stop_net.sh
2. Update the scripts as required for your environment.
3. Copy the sample scripts to all nodes in the cluster.

Setting Up Additional Configuration Requirements for Hewlett-Packard MC/

ServiceGuard
The HP Solutions Competency Center (SCC) has successfully integrated IBM Connect:Direct with MC/
Service Guard. The implementation and certification of IBM Connect:Direct followed the SCC’s high
availability Implementation and Certification Process. Refer to the Implementation and Certification With

Chapter 2. Getting Started Guide 35

 Hewlett-Packard’s MC/ServiceGuard High Availability Software document located on the Support on
Demand Web site.

Verifying the Installation

Procedure
1. Type the following command to identify the release and platform operating system release, where
d_dir is the destination directory and binaryx is a file in the bin/ directory (for example, cdpmgr):

% d_dir/etc/cdver d_dir/ndm/bin/[binary1 binary2 ...]

2. Log in with the user account under which IBM Connect:Direct was installed.
3. Type the following command to start Connect:Direct for UNIX Server, where d_dir is the destination
directory and cd_node is the IBM Connect:Direct node name.

$ d_dir/ndm/bin/cdpmgr -i d_dir/ndm/cfg/cd_node/initparm.cfg
4. Do one of the following to set the environment variable NDMAPICFG to point to the client
configuration file:
• If you are using the Bourne or Korn shell, type the following command:

$ NDMAPICFG=d_dir/ndm/cfg/cliapi/ndmapi.cfg
$ export NDMAPICFG

• If you are using the C shell, type the following command:

% setenv NDMAPICFG d_dir/ndm/cfg/cliapi/ndmapi.cfg

5. Type the following command to invoke the IBM Connect:Direct client:

$ d_dir/ndm/bin/direct
6. Type the following command:

Direct> select statistics;

Read the statistics information and ensure that the initialization started with no errors. If any errors
are displayed, resolve the errors before continuing.
7. Type the following command to submit a sample Process:

Direct> submit file=d_dir/ndm/bin/sample.cd;

This sample Process copies a binary file named msgfile.cfg to the file cddelete.me in your HOME
directory (your node is both the PNODE and the SNODE). The checkpointing interval is set to 2M and
extended compression is used.
8. Type the following select process command to monitor data transmission activity:

Direct> select process pnumber=1;

IBM Connect:Direct generates a report with the Process name and number, user, submitter node,
queue, and status.
9. After the Process is complete, type the following select statistics command to review the statistics
log for the Process:

Direct> select statistics pnumber=1;

10. Do one of the following:
• Type the following command to manually shut down the IBM Connect:Direct server:

36 IBM Connect:Direct for UNIX: Documentation

 Direct> stop;
• Type the following command to quit the IBM Connect:Direct client without shutting down the
server: Direct> quit;
The client terminates automatically when you stop the server.

Deploying IBM Connect:Direct for UNIX using a Docker container

A Red Hat certified container image is now available to deploy IBM Connect:Direct for UNIX in a
standalone Docker environment.

Overview
Docker is a tool designed to make it easier to create, deploy, and run applications by using containers. A
container image is an executable package that includes everything that is needed to run the software,
including the code itself, application settings and all required runtime files, system tools and libraries.
For more information about Docker and its commands, see https://www.docker.com/.

Components
IBM Connect:Direct for UNIX Docker Image is created with the Red Hat UBI as the base layer. It is a Red
Hat certified Docker image. The image contains the following components:
• application
• license files
• docker image help file
The deployment process for Connect:Direct for UNIX consists of several phases. Before starting
installation, roadmap for the installation must be planned.
The deployment process for Connect:Direct for UNIX consists of the following steps:
• Prerequisites
• Installation
• Post-installation configurations

Network
The IBM Connect:Direct for Unix Docker container is tested with bridge and overlay type Docker networks.
For more information, see Docker Network.

Prerequisites to Deploy Connect:Direct® for UNIX using a Docker container

Before you deploy the application, you must complete certain prerequisite tasks:
1. Verifying System Requirements
2. Downloading the Docker image
3. Configuring Docker Containers
4. Adding Certificate Files
5. Configuring Storage
6. Exposing Ports to other Containers

Chapter 2. Getting Started Guide 37

 Verifying System Requirements
Before you begin deployment procedure, verify that your system meets the hardware and software
requirements that are specified for this release.
The IBM Connect:Direct for UNIX container has been verified on Red Hat Linux and requires the following
minimum hardware resources.
Hardware Requirements
• 1 GB Disk space
• 500m core
• 2 GB RAM
• 100 MB for volume storage on Storage Volume
Software Requirements
• Install Docker version >= v1.13.1
• NFS version used for storage >= 4.0 (for optional Storage Volume)
• Ensure that the docker image for IBM Connect:Direct for UNIX is available in docker registry.
Note: Storage volume types, NFS server and Host have been referred to as Storage Volume in the
following sections.

Downloading the Docker image

You can download the IBM Connect:Direct for UNIX Docker image from Fix Central.
To download the Docker image, complete the following steps:
1. Log on to the Fix Central web site by using necessary credentials.
2. Select the item to download:

6.1.0.x-IBMConnectDirectforUNIX-Certified-Container-Linux-x86-iFix000.tar

3. Untar the downloaded tar file to extract the following file:

cdu6.1_certified_container_6.1.0.x_ifix000.tar

4. Load the Docker image into registry using the downloaded image file by running the following
command.

docker load -i cdu6.1_certified_container_6.1.0.x_ifix000.tar

5. Invoke the docker images command to verify if the image is loaded successfully.

Configuring Docker Containers

The following section describes configuration information available in the cd_param_file. These
parameters are required to deploy Connect:Direct for UNIX in a Docker container.
• Ensure that this configuration file is named as cd_param_file and placed on the Storage Volume that
is mapped to /opt/cdfiles path inside the container.
At Docker startup, the cd_param_file is looked up at location /opt/cdfiles to complete
deployment of Connect:Direct for UNIX in a Docker container.
• During deployment, a default admin user cduser with group cduser is created. A mandatory
parameter, cdai_adminPassword is added to cd_param_file to update the password required by
cduser at container start up. The default UID and GID of cduser is 45678.
• The UID and GID of cduser can be set to some real user on the host system. By setting the same UID
and GID as on the host system, the host system user would have suitable permissions on the files

38 IBM Connect:Direct for UNIX: Documentation

 present on the host path so that this user can be used to edit any setting or configuration files related to
Connect:Direct for Unix running inside container.

Example: If you have a user, host-user having UID and GID set to 2000 and 4000 respectively on the
host system. There are 'upload' (for files to be sent) and 'download' (for files to be received) directories
created by this user. These directories can be mounted on the CDU container so that these folders are
available inside container.

In order to give cduser access to these directories inside the container, the UID and GID of cduser can
be set to 2000 and 4000 respectively.

Similarly, you can set the UID and GID of appuser which is a non-admin user of Connect:Direct for
Unix running inside container. The user appuser is created only if you have passed its password to be
set inside container using cdai_appuser_pwd parameter in cd_param_file.
• Sample parameter file

cdai_localNodeName=cd_node
cdai_serverPort=1364
cdai_clientPort=1363
cdai_localCertFile="cdcert.pem"
cdai_localCertPassphrase="certpassword"
cdai_keystorePassword="keypassword"
cdai_adminPassword="abc123"
cdai_appuser_name="appuser"
cdai_appuser_pwd="appuserpassword"
cdai_appuser_uid="9001"
cdai_appuser_gid="9001"
cdai_admin_uid="2020"
cdai_admin_gid="2020"

Note: For security reasons, passwords are removed from the parameter file at installation.

Parameter Mandatory/Optional Default Value Description

cdai_localNodeName Optional container-id The node-name to be
configured during silent
installation of
Connect:Direct.

cdai_clientPort Optional 1363 API Port

cdai_serverPort Optional 1364 Server Port

cdai_localCertFile Mandatory NA Certificate file name
(File name only)
cdai_localCertPassphras Mandatory NA Certificate password
e
cdai_keystorePassword Mandatory NA Password to be used
during the creation of
KeyStore created with
silent installation.
cdai_adminPassword Mandatory NA Password for admin
account cduser
cdai_appuser_name Optional appuser Name of Non-Admin
Connect:Direct user

Chapter 2. Getting Started Guide 39

 Parameter Mandatory/Optional Default Value Description
cdai_appuser_pwd Optional NA Password of Non-Admin
Connect:Direct user
The appuser user is
created inside the
container only when
cdai_appuser_pwd is
defined inside
cd_param_file
irrespective
ofcdai_appuser_name
, cdai_appuser_uid
and
cdai_appuser_gid
values defined inside the
parameter file.

cdai_appuser_uid Optional NA UID of Non-Admin

Connect:Direct user
cdai_appuser_gid Optional NA GID of Non-Admin
Connect:Direct user

cdai_admin_uid Optional 45678 UID of Admin User

cduser
cdai_admin_gid Optional 45678 GID of Admin User
cduser

Apart from the configuration using cd_param_file, there is SACL configuration which can be done by
passing an environment variable to docker run command with correct possible values of SACL
configuration. Add following sub-command to main docker run command -

--env SACL_CONFIG=<configuration value>

If the passed value is not correct for SACL configuration, then SACL configuration would be done using
default value which is `n`.
Related concepts
“Strong Access Control File” on page 127

Adding Certificate Files

Certificate files are required when Secure Plus is being configured. The user must provide the key
certificate and trusted certificate files in PEM format.
Certificate files must be placed on the Storage Volume that is mapped to /opt/cdfiles path inside the
container. At Docker startup, certificates are looked up at /opt/config/cdfiles during the
deployment process.
Example: Suppose the cd_param_file is placed under <some-path>/CDFILES. Then, you need to
create a directory inside CDFILES, suppose `cdcert` and place all the certificate files inside this directory.

Configuring Storage
The containers are ephemeral entity, all the data inside the container is lost when the containers are
destroyed/removed. So, data must be saved to Storage Volume by using the volume. For more information
see, Volumes.

40 IBM Connect:Direct for UNIX: Documentation

 Special Considerations
• Map work, cfg, security and secure+ directories to Storage Volume
• For data persistence, either host path or NFS mounted shared directories should be used.
It is recommended that NFS mounted shared drive be used to map these directories.
• Saving the configuration on Storage Volume mounted shared drive enables creating a new container
using the saved configuration on a different node that can access the mapped path.
• To send/receive files, user must map the source/destination directory path on host/NFS to inside the
container mounted path of upload/download directory while running the container.
Note: For using the hostpath with SELinux policy enforced, you need to set the proper SELinux policy
label for each mounted directory. One can set it using the following command:

chcon -Rt svirt_sandbox_file_t <Path_Of_Directory_To_Be_Mounted>

Exposing Ports to other Containers

To enable IBM Connect:Direct for UNIX container communication with another container running on a
different host, map API and Server ports (default 1363 and 1364 respectively) to available host ports
when you create a container.
To map API and Server ports to available host ports use -p option at Docker run command in the
following format:

-p <host mapped client port: CD client port>

-p <host mapped server port: CD server port>

Deploying the Software

After you have completed the prerequisite tasks, you are ready to deploy IBM Connect:Direct for UNIX in
a Docker container.
The installation step has further following steps as listed in the section below.

Understanding Docker deployment parameters

• Mapping directories for data persistence
In production environment, cfg, secure+, security and work directories inside the container
should be mapped to directories on Storage Volume. It enables saving the content of these directories
even if the container is destroyed. Use -v option at docker run command to complete this action.
Note: cfg, secure+, security and work directories are created at fresh installation. Users must
not create these directories on Storage Volume's mounted path.
• Mapping ports
IBM Connect:Direct for Unix client and server ports, default 1363 and 1364 respectively, can be
mapped to available host ports. This is required to communicate with Connect:Direct for Unix nodes
running on different hosts and to configure the node using Connect:Direct Web Services. Use -p
option at docker run command to complete this action.
• Adding Linux capabilities to the Docker container
Following capabilities are required in a container for IBM Connect:Direct for Unix application to attempt
a successful file transfer:
– FOWNER
– SETUID
– SETGID

Chapter 2. Getting Started Guide 41

 – DAC_OVERRIDE
– CHOWN
– IPC_OWNER
– IPC_LOCK
– SYS_CHROOT
• Container Name
Container name must be unique for containers running on same host machine. This helps identify
docker instances. Use --name option to set a container name.
• Host Name
Host name should be set for the container or container-id is set as hostname.
Note: Hostname is required for container recovery. It is recommended you provide a hostname when
IBM Connect:Direct for UNIX is deployed using a Docker container.
• To transfer files present on host machines, user must map the source and destination paths inside the
container.

Understanding LDAP deployment parameters

This section demonstrates the steps required to implement the PAM and SSSD configuration with
Connect:Direct UNIX to authenticate external user accounts through Open LDAP.
• Updating initparam file: When the LDAP authentication is enabled, the container startup script
automatically updates the initparam configuration to support the PAM module. The following line is
added to initparam.cfg

ndm.pam:service=login

• The following packages are pre-installed in the container image to enable the LDAP support:

openldap-client, sssd, sssd-ldap, openssl-perl, authselect

• The following default configuration file (/etc/sssd/sssd.conf) is added to the image. You must
provide the values highlighted in bold with the values of environment variables as explained in next
section.

[domain/default]
id_provider = ldap
autofs_provider = ldap
auth_provider = ldap
chpass_provider = ldap
ldap_uri = LDAP_PROTOCOL://LDAP_HOST:LDAP_PORT
ldap_search_base = LDAP_DOMAIN
ldap_id_use_start_tls = True
ldap_tls_cacertdir = /etc/openldap/certs
ldap_tls_cert = /etc/openldap/certs/LDAP_TLS_CERT_FILE
ldap_tls_key = /etc/openldap/certs/LDAP_TLS_KEY_FILE
cache_credentials = True
ldap_tls_reqcert = allow

• Provide the following values as environment variables:

Table 2. LDAP Deployment Parameters

Environment Variables Description
LDAP_ENABLE If “TRUE”, LDAP needs to be configured
LDAP_HOST Mandatory if “LDAP_ENABLE” is true. (IP or
Hostname)
LDAP_PORT Mandatory if “LDAP_ENABLE” is true.

42 IBM Connect:Direct for UNIX: Documentation

 Table 2. LDAP Deployment Parameters (continued)
Environment Variables Description
LDAP_DOMAIN Mandatory if “LDAP_ENABLE” is true. (Top level
domain to search)
LDAP_TLS If “TRUE”, TLS is enabled. “LDAP_PROTOCOL” in
config file is set to LDAPS
LDAP_CACERT Mandatory if “LDAP_TLS” is true. Name of CA
certificate
LDAP_ENABLE_CLNT_VAL If “TRUE”, Client validation is enabled.
LDAP_CLIENT_CERT Mandatory if “LDAP_ENABLE_CLNT_VAL” is true.
Name of client certificate.
LDAP_CLIENT_KEY Mandatory if “LDAP_ENABLE_CLNT_VAL” is true.
Name of client certificate key.
• Description of the Certificates required for the configuration:
– Copy certificates to Container Docker Image:
- Copy the certificates in the cdcert dir, where Secure plus certificate files were copied.
– DNS Resolution: If the TLS is enabled and hostname of LDAP server is passed in “LDAP_DOMAIN”,
then it must be ensured that the hostname is resolved inside the container. It could also be done as
below -:
- --addhosts: Use this option to update the /etc/hosts of the container with the domain and IP of
LDAP server.
Note: It is the responsibility of the administrator to ensure that LDAP server hostname is resolved
inside container.
– Certificates creation and configuration: This external link provides a sample way to generate the
certificates:
- LDAP_CACERT - The root and all the intermediate CA certificates needs to be copied in one file.
- LDAP_CLIENT_CERT – The client certificate which the server must be able to validate.
- LDAP_CLIENT_KEY – The client certificate key
• Sample Environment file:

LDAP_ENABLE=True
LDAP_HOST=cddock-01
LDAP_PORT=636
LDAP_DOMAIN=dc=my-domain,dc=com
LDAP_TLS=True
LDAP_CACERT=cddockca.pem
LDAP_ENABLE_CLNT_VAL=True
LDAP_CLIENT_CERT=cddock01.pem
LDAP_CLIENT_KEY=cddock01.key

• Docker run command:

docker run --cap-drop=ALL \

--cap-add=FOWNER \
--cap-add=SETUID \
--cap-add=SETGID \
--cap-add=DAC_OVERRIDE \
--cap-add=CHOWN \
--cap-add=IPC_OWNER \
--cap-add=IPC_LOCK \
--cap-add=SYS_CHROOT \
--name=CD_CONTAINER_1 \
--hostname=cdhost1 \
--env-file=/home/<user>/env_file \
--add-host=<LDAP Server domain>:<LDAP Server IP> \

Chapter 2. Getting Started Guide 43

 -v /home/<user>/config:/opt/cdfiles \
-v /home/<user>/cdunix/cfg:/opt/cdunix/ndm/cfg \
-v /home/<user>/cdunix/secure+:/opt/cdunix/ndm/secure+ \
-v /home/<user>/cdunix/security:/opt/cdunix/ndm/security \
-v /home/<user>/cdunix/work:/opt/cdunix/work \
-v /home/<user>/Download:/opt/Download \
-p 2363:1363 \
-p 2364:1364 \
-it -d <image_id>

• Validation of Successful LDAP configuration: The following commands should be executed inside
container and return success for the users not present inside the container but present in the LDAP
server:

id <userid>

getent passwd <userid>

Deploying IBM Connect:Direct for UNIX using a Docker Container

Invoke the following command to start a docker container running IBM Connect:Direct for UNIX .

docker run --cap-drop=ALL \

--cap-add=FOWNER \
--cap-add=SETUID \
--cap-add=SETGID \
--cap-add=DAC_OVERRIDE \
--cap-add=CHOWN \
--cap-add=IPC_OWNER \
--cap-add=IPC_LOCK \
--cap-add=SYS_CHROOT \
--name=CD_CONTAINER_1 \
--hostname=cdhost1 \
-v /home/<user>/config:/opt/cdfiles \
-v /home/<user>/cdunix/cfg:/opt/cdunix/ndm/cfg \
-v /home/<user>/cdunix/secure+:/opt/cdunix/ndm/secure+ \
-v /home/<user>/cdunix/security:/opt/cdunix/ndm/security \
-v /home/<user>/cdunix/work:/opt/cdunix/work \
-v /home/<user>/Download:/opt/Download \
-p 2363:1363 \
-p 2364:1364 \
-it -d <image_id>

Validating the Deployment

After IBM Connect:Direct for UNIX is deployed using a Docker container you should validate the
deployment to ensure that everything is working as expected.
Complete the following tasks to validate the deployment:
• Invoke the docker ps -a command to get the container-id

docker ps -a

Sample Output

CONTAINER IMAGE COMMAND CREATED STATUS PORTS NAMES

ID
<container- <image-id> “./ About an Up About an 0.0.0.0:1136 <container-
id> CDStartup.sh hour ago hour 4->1364/ name>
” tcp, 11363-
>1363/tcp

• Check the docker container logs and verify the below successful logs are displayed:

44 IBM Connect:Direct for UNIX: Documentation

 # docker logs <container name/id>

Output

[2020/04/25 11:39:10] | [INFO] | Installation Successful

[2020/04/25 11:39:10] | [INFO] | CD Unix new installation version: IBM(R) Connect:Direct(R)
for UNIX Version 6.1.0.x, Build date 22Apr2020, Intel x86 Linux
[2020/04/25 11:39:10] | [INFO] | Installation completed

Post Deployment Configurations

The post deployment configuration steps can be performed via:
• Connect Direct Web services
Login to the Connect Direct Web services using the IP address of the host where container is running
and the host ports to which container API and server ports are mapped to. For configuration steps, see
Connect:Direct Web Services Help Videos.
• Attaching to the container
Follow the steps given below:
– Issue the docker inspect command to get the container IP

docker inspect <container-name/id>

– Issue the docker exec command to attach to the container

docker exec -it <container-name/id> bash

– Go to the installation path /opt/cdunix and complete the steps followed to configure conventional
Connect:Direct for Unix here, Administering Connect:Direct for UNIX.
• Changing Non-Admin Connect:Direct user password
The password for Non-Admin Connect:Direct user (by default appuser) can be changed by invoking the
following command on the host machine where the container is running:

docker exec -it <container name> sh -c "echo -e

"<sudo password of cduser>\\\\nappuser:<new password for appuser>"
| sudo -S chpasswd"

Container Stop/Restart procedure

The following section describes commands used to Start/Stop a Docker container.
• Stop a running container

docker stop <container_name/id>

Container name/id can be obtained using docker ps command.

• To verify if the container has stopped run docker ps -a command. The status of the stopped
container would display as Exited.

docker ps -a

• Start a Docker container in a stopped state

docker start <container_name/id>

Connect:Direct service automatically starts inside the container.

Chapter 2. Getting Started Guide 45

 • To destroy a stopped container permanently, all configuration data and information such as statistics
and TCQ not mapped to a Storage Volume are lost and cannot be recovered. Use the following command
to remove a container:

docker rm <container_name/id>

Container Recovery
Containers are like any other data source that needs to be protected. As your organization comes to rely
on Docker containerization technology for critical IT functions, you need to ensure appropriate safeguards
are in place to minimize disruptions to your business operations.
This section describes container backup and disaster recovery methods.
• When configuring IBM Connect:Direct for UNIX running inside a container ensure that you have mapped
it over Storage Volume. This ensures all configuration made to the container is intact and still available
on the Storage Volume when a container is no longer available.
• IBM Connect:Direct for UNIX node configurations of a destroyed container such as, cfg, security,
work, secure+ can be reused to start a new container. To start a new container with backup
configurations:
– Configuration paths for the new container must be mapped to persistent configurations.
– In cd_param_file, passwords need to be mentioned again, as they would have been deleted after
the previous deployment.
Note: cd_param_file file content should match file content at fresh deployment.
– Host name of new container must be same as the destroyed container
– Invoke the docker run command using the same host name and configuration paths as described in
the example below:

docker run --cap-drop=ALL \

--cap-add=FOWNER \
--cap-add=SETUID \
--cap-add=SETGID \
--cap-add=DAC_OVERRIDE \
--cap-add=CHOWN \
--cap-add=IPC_OWNER \
--cap-add=IPC_LOCK \
--cap-add=SYS_CHROOT \
--name=<container-name> \
--hostname=<host-name of previous container> \
-v <host_dir>:/opt/cdfiles \
-v <host mapped path>/cfg:/opt/cdunix/ndm/cfg \
-v <host mapped path>/secure+:/opt/cdunix/ndm/secure+ \
-v <host mapped path>/security:/opt/cdunix/ndm/security \
-v <host mapped path>/work:/opt/cdunix/work \
-v <upload directory path on host>:<mount point inside container> \
-v <download directory path on host>:<mount point inside container> \
-p <host mapped client port: CD client port> \
-p <host mapped server port: CD server port> \
-it -d <image-id OR image-name:tag>

Known Limitations
• Interaction with IBM Control Center Director is not supported.
• FASP feature is not supported.
• The container does not include X-Windows support, so SPAdmin cannot run inside the container. SPCli
will run in the container and Connect Direct Web Services (CDWS) can be used outside the container
instead of using SPAdmin.

46 IBM Connect:Direct for UNIX: Documentation

Upgrading IBM Connect:Direct for UNIX using a Docker Container
You can use the Docker container to upgrade an existing Connect:Direct for UNIX container.

Prerequisites to upgrade IBM Connect:Direct for UNIX using a Docker

Container
Apart from the newer container image before you upgrade you must ensure certain prerequisites are in
place. For more information see, “Prerequisites to Deploy Connect:Direct® for UNIX using a Docker
container” on page 37.

Understanding Docker deployment parameters

• Mapping directories for data persistence
In production environment, cfg, secure+, security and work directories inside the container
should be mapped to directories on Storage Volume. It enables saving the content of these directories
even if the container is destroyed. Use -v option at docker run command to complete this action.
Note: cfg, secure+, security and work directories are created at fresh installation. Users must
not create these directories on host machine’s mounted path.
• Mapping ports
IBM Connect:Direct for Unix client and server ports, default 1363 and 1364 respectively, can be
mapped to available host ports. This is required to communicate with Connect:Direct for Unix nodes
running on different hosts and to configure the node using Connect:Direct Web Services. Use -p
option at docker run command to complete this action.
• Adding Linux capabilities to the Docker container
Following capabilities are required in a container for IBM Connect:Direct for Unix application to attempt
a successful file transfer.
– FOWNER
– SETUID
– SETGID
– DAC_OVERRIDE
– CHOWN
– IPC_OWNER
– IPC_LOCK
– SYS_CHROOT
• Container Name
Container name must be unique for containers running on same host machine. This helps identify
docker instances. Use --name option to set a container name.
• Host Name
Host name should be set as same as the previous container.
• To transfer files present on host machines, user must map the source and destination paths inside the
container.

Understanding LDAP deployment parameters

You can upgrade IBM Connect:Direct for UNIX using a docker container through LDAP parameters. For
more information, refer “Understanding LDAP deployment parameters” on page 42.

Chapter 2. Getting Started Guide 47

 Upgrading Connect:Direct for UNIX using a Docker Container
Perform the following step to complete the Connect:Direct for UNIX upgrade process using Docker:
1. Stop the existing container if it is in running state:

docker stop <container id or container name>

2. Remove the stopped container:

docker rm <container id or container name>

3. Create new container using same mount path of following directories -

• config
• security
• work
• secure+
• cfg
• Any other directories which you had mounted earlier and wish them to be mounted in this container
too
4. Execute docker run command using the sample command as given below:
Sample Command

docker run --cap-drop=ALL \

--cap-add=FOWNER \
--cap-add=SETUID \
--cap-add=SETGID \
--cap-add=DAC_OVERRIDE \
--cap-add=CHOWN \
--cap-add=IPC_OWNER \
--cap-add=IPC_LOCK \
--cap-add=SYS_CHROOT \
--name=CD_CONTAINER_1 \
--hostname=cdhost1 \
-v /home/<user>/config:/opt/cdfiles \
-v /home/<user>/cdunix/cfg:/opt/cdunix/ndm/cfg \
-v /home/<user>/cdunix/secure+:/opt/cdunix/ndm/secure+ \
-v /home/<user>/cdunix/security:/opt/cdunix/ndm/security \
-v /home/<user>/cdunix/work:/opt/cdunix/work \
-v /home/<user>/Download:/opt/Download \
-p 2363:1363 \
-p 2364:1364 \
-it -d <image_id>

Validating the Upgrade

After IBM Connect:Direct for UNIX deployment in a Docker container is complete, you should validate the
installation to ensure that everything is working as expected.
For more information see, “Validating the Deployment” on page 44.
Additionally, check that existing stats, configuration and TCQ are preserved. This can be verified through
IBM Connect:Direct Web Services.

Migrating IBM Connect:Direct for Unix using a Docker Container

Before you migrate you must ensure certain prerequisites are in place. For more information see,
“Prerequisites to Deploy Connect:Direct® for UNIX using a Docker container” on page 37. Follow the steps
below to migrate Connect:Direct for Unix installed in conventional mode to container:
1. A file must be created in a work directory before taking backup. The file can be created by invoking the
following command:

48 IBM Connect:Direct for UNIX: Documentation

 <path to cdunix install directory>/etc/cdver > <path to cdunix install directory>/work/
saved_cdunix_version

2. Create a backup of configuration data and other information such as stats and TCQ, present in installed
path of Connect:Direct instance. The backup of the following directories will be needed:
• work
• security
• cfg
• secure+
3. Copy the backup of the directories taken in Step 2 to the mount path which will be used for deploying
Connect:Direct for Unix in container.
4. After verifying the prerequisites mentioned at the beginning. Go to “Deploying IBM Connect:Direct for
UNIX using a Docker container” on page 37 section for deploying Connect:Direct for Unix in container.
5. Note: The nodename of Connect:Direct for Unix running on traditional system should be same for
migration inside container.
6. Update various values in initparm.cfg and netmap.cfg for the Connect:Direct installation path,
hostname/IP and port numbers. The installation path is /opt/cdunix/, hostname would be
hostname of the system where container is being deployed and client port is 1363 and server port is
1364.

Deploying IBM Connect:Direct for UNIX using an IBM Certified

Container Software
IBM Certified Container Software offers a Red Hat certified IBM Connect:Direct for UNIX image and Helm
chart and can be used to deploy a production-ready IBM Connect:Direct image into Red Hat OpenShift/
Kubernetes cluster.
IBM Certified Containers are more than a simple Helm chart. IBM Certified Containers accelerate time to
value and improve enterprise readiness at a lower cost than containers alone
An IBM Certified Container meets standard criteria for packaging and deployment of containerized
software with platform integrations.

Prerequisites
The following are prerequisites to successfully use a Certified Container:
• Installing a Kubernetes cluster and configuring kubectl client for the user
• Applying security configurations to your deployment. For minimum security configuration, see “Creating
Pod Security Policy for Kubernetes Cluster ” on page 56 (Kubernetes) and “Creating security context
constraints for OpenShift Cluster ” on page 58 for Openshift.
• Installing and configuring Helm
Note: For more information on how to install and secure a Helm installation, see Installing Helm.

Overview
A Certified Container provides the basic features of a package manager (Helm chart) to help with the
installation and maintenance of software. Using a Certified Container you can perform flowing action on
helm chart:
• Deploy
• Upgrade
• Configure

Chapter 2. Getting Started Guide 49

 Key Concepts
• Chart
A Certified Container Software uses a packaging format called Charts.
IBM Connect:Direct for Unix Chart is a collection of files that consists of a few YAML configuration files
and templates rendered into Kubernetes manifest files.
Charts are created as files laid out in a directory tree that you can package into versioned archives that
the system deploys.
• Release
Release is a running instance of a chart combined with a specific configuration
• A certified container release uses:
– A command line tool, helm to provide a user interface.
– Packaging format called Charts.

Key Components
A Certified Container Software has two major components:
• Helm Client
It manages charts and is a command line interface for end users. Use Helm client to:
– Develop charts
– Manage repositories
– Send charts to be used for deployment
– Ask for information about Releases
– Request upgrades or uninstallation of existing Releases

Network
The IBM Certified Container Software release is tested with Weave Net-type network for Kubernetes. For
more information, refer to Kubernetes Networking.

Planning
Before you deploy the application, you must use the following information to plan the deployment:
• Verifying system requirements
• Application license requirements
• IBM Licensing and Metering service
• Certificates files for Secure Plus
• PSP and SCC requirements

User Roles
Deployment tasks can be performed by cluster administrator and project administrator. The following
table illustrates the type of task that are typically associated with each administrative role. The list is not
intended to be exhaustive -

50 IBM Connect:Direct for UNIX: Documentation

Role Task
Cluster Administrator • Creating namespaces (projects)
• Creating PSP or SCC and assigning them to
namespace (project)
• Configuring Storage for data persistence
• Providing environmental details
• Installing and configuring IBM Licensing and
Metering Service

Project Administrator • Creating Secrets

• Installing IBM Certified Container Software for
Connect Direct UNIX
• Validating the install
• Post deployment tasks

Verifying System Requirements

Before you begin the deployment process, verify that your system meets the hardware and software
requirements specified for this release.
The Certified Container Software for IBM Connect:Direct for UNIX has been verified on Red Hat Linux and
requires the following minimum hardware and software resources:
Hardware Requirements
• 1 GB Disk space
• 500m CPU core
• 2 GB RAM
• 100 MB for Persistent Volume
Software Requirements
• Docker version available is = 1.13
• Kubernetes version available is >= 1.11
• OpenShift version available is 3.11 or 4.4
• Helm (client) version available is >= 2.12 and < 3.0 or >= 3.2.1
• Tiller (server) version available is >= 2.12 and < 3.0
• kubectl and helm commands are available on Kubernetes cluster
• oc and helm commands are available on OpenShift 3.11 or 4.4
• podman client compatible with OpenShift 4.4
• Ensure that cluster has 1 master node and at least 1 worker node
• If NFS is used as storage, ensure version >= 4.0
Note: For helm 3.2.1 and greater, no Tiller (server) is required.
A certified container deployment strictly enforces the following system requirements. If any of these
requirements are not met, the deployment fails. If the deployment fails, review the deployment log for a
list of non-compliant items.

Chapter 2. Getting Started Guide 51

 Application license requirements
You must read the IBM Connect:Direct for Unix License agreement terms before deploying the software.
The license number is 'L/N: L-BCHE-BSLHNW'.
To accept the license, set license variable to true at Helm CLI installation command. If license
variable is set to false then deployment of IBM Certified Container Software for Connect:Direct for UNIX
would not be successful. For more information see, “Configuring - Understanding values.yaml ” on page
63.
The IBM Certified Container Software for Connect:Direct for UNIX is deployed as non-production by
default. You can override this default behavior by changing the licenseType variable to prod. The
licenseType value would be used to annotate the IBM Certified Container Software for Connect:Direct for
UNIX, which would be eventually used by Licensing and Metering service tool.

IBM Licensing and Metering service

The IBM Certified Container Software for Connect Direct UNIX has been integrated with IBM Licensing
and Metering service using Operator. This service collects information about license usage of IBM
Certified Container Software for Connect Direct UNIX.
You can use the `ibm-licensing-operator` to install the IBM Licensing and Metering service on any
Kubernetes License Service collects information about license usage of IBM Containerized Products. You
can retrieve license usage data through a dedicated API call and generate an audit snapshot on demand
cluster without IBM Cloud Pak.
For the overview and documentation see, License Service deployment without an IBM Cloud Pak.

Certificates files for Secure Plus

The IBM Certified Container Software for Connect:Direct UNIX application provided enhanced security for
IBM Connect:Direct and is available as a separate component. It uses cryptography to secure data during
transmission. By default security protocols are TLS 1.2 and TLS.13.
For configuring Secure Plus while installing IBM Certified Container Software for Connect:Direct UNIX you
need certificate file. You must ensure valid certificates files are used during the deployment. Keep the
certificates files handy during the IBM Certified Container Software for Connect Direct UNIX deployment.
Related concepts
“Certificate Files” on page 283
The TLS security protocol use a secure server RSA X.509V3 certificate to authenticate your site to any
client that accesses the server and provides a way for the client to initiate a secure session. You obtain a
certificate from a certificate authority or you can create a self-signed certificate. When you obtain a
certificate file, a trusted root certificate file and key file are created. This topic describes the layout of the
trusted root certificate file and the key certificate file.
“Introduction to Connect:Direct Secure Plus for UNIX” on page 237
The Connect:Direct Secure Plus for UNIX application provides enhanced security for IBM Connect:Direct
and is available as a separate component. It uses cryptography to secure data during transmission. You
select the security protocol to use with Connect:Direct Secure Plus.

Pod Security Policy and Security Context Constraints requirements

Both Pod Security Policy (PSP) and Security Context Constraints (SCC) are cluster-level resource and
allows administrator to control the security aspects pods in Kubernetes and OpenShift clusters
respectively.
Depending on the cluster environment, IBM Certified Container Software for Connect Direct UNIX requires
PSP or SCC to be tied to the target namespace prior to deployment. Since, it is a cluster level resource,
discuss this with your Cluster Administrator as they are needed to create these resources.

52 IBM Connect:Direct for UNIX: Documentation

 For more information on PSP see, Creating Pod Security Policy for Kubernetes cluster and Security
Context Constraints for OpenShift cluster.

Installing
After you review the system requirements and other planning information, you install IBM Certified
Container Software for Connect Direct UNIX by completing the pre-installation tasks and installation
process. Before you begin consider the following:
• A Helm chart is organized as a collection of files inside a directory by the name of the Chart itself. For
more information see, Helm Charts.
Example Helm Chart

<Name of a Chart/>
Chart.yaml # A YAML file containing information about the Chart.
LICENSE # OPTIONAL: A plain text file containing the license for the Chart.
README.md # OPTIONAL: A README file.
requirements.yaml # OPTIONAL: A YAML file listing dependencies for the Chart.
values.yaml # The default configuration values for this Chart.
Charts/ # A directory containing any Charts upon which this Chart depends.
templates/ # A directory of templates that, when combined with values, generates
valid Kubernetes manifest files.
templates/NOTES.txt # OPTIONAL: A plain text file containing short usage notes.

– This Helm chart deploys IBM Connect:Direct for Unix on a container management platform with the
following resource deployments:
- statefulset pod <release-name>-IBM-connect-direct-0
1 replica by default
- configMap <release-name>-ibm-connect-direct
This is used to provide default configuration in cd_param_file.
- service <release-name>-ibm-connect-direct
This is used to expose the IBM Connect:Direct services for accessing using clients.
- service-account <release-name>-ibm-connect-direct-serviceaccount
This service will not be created if serviceAccount.create is false.
- persistence volume claim <release-name>-ibm-connect-direct.
• Certified Container Software commands
For more information on other commands and options, see Helm Commands.
1. To install a Chart

$ helm install

2. To upgrade to a new release

$ helm upgrade

3. To rollback a release to a previous version

$ helm rollback

4. To delete the release from Kubernetes.

$ helm delete

Chapter 2. Getting Started Guide 53

 Pre-installation tasks
Before you install IBM Certified Container Software for Connect:Direct for UNIX, complete the following
tasks:
1. Setting up your registry server: You must have a registry server where you can host the image required
for installation.
2. Setting up Namespace or project: You must have an existing namespace/project or create a new if
required.
3. Installing and configuring IBM Licensing and Metering service: Ensure that this service is installed on
your cluster.
4. Downloading the Certified Container Software image: Ensure that the installation files are available on
your client system.
5. Creating Pod Security policy for Kubernetes cluster: Ensure you have created the required PSP using
provided scripts.
6. Creating the security context constraints for OpenShift cluster: Ensure you have created the required
SCC using provided scripts.
7. Creating storage for data persistence: Ensure you have required storage option ready to be used.
8. Creating secret: Ensure you have secrets needed for Connect:Direct for Unix configuration and pull
secret (if required).
9. Configuring the deployment: Ensure you go through various parameters of values.yaml with their
default values. Update those default values required and supported by IBM Certified Container
Software for Connect:Direct for UNIX.

Setting up your registry server

To install IBM Certified Container Software for Connect:Direct for UNIX, you must have a registry server
where you can host the image required for installation.

Using the existing registry server

If you have an existing registry server, you can use it, provided that it is in close proximity to cluster where
you will deploy IBM Certified Container Software for Connect:Direct for UNIX. If your registry server is not
in close proximity to your cluster, you might notice performance issues. Also, before the installation,
ensure that pull secrets are created in the namespace/project and are linked to the service accounts. You
will need to properly manage these pull secrets. This pull secret can be updated in values.yaml file
`image.imageSecrets`.

Using Docker registry in Kubernetes cluster

Kubernetes does not provide a registry solution out of the based. However, you can create your own
registry server and host your images. Please refer to the deployment of registry server.

Using OpenShift internal registry

Alternatively, you can use the internal registry in your Red Hat OpenShift cluster. This option is
recommended because it does not require you to manage pull secrets. For information on the internal
registry, see:
For OpenShift 3.11: Internal Registry Overview
For OpenShift 4.4: Integrated Red Hat OpenShift Container Platform registry
Ensure that you can access the registry externally:
For OpenShift 3.11: Securing and Exposing the Registry
For OpenShift 4.4: Exposing the registry

54 IBM Connect:Direct for UNIX: Documentation

Setting up Namespace or project
To install IBM Certified Container Software for Connect:Direct for UNIX, you must have an existing
namespace/project or create a new if required.
You can either use an existing namespace or create a new one in Kubernetes cluster. Similarly, you either
use an existing project or create a new one in OpenShift cluster. A namespace or project is a cluster
resource. So, it can only be created by a Cluster Administrator. Refer the following links for more details -
For Kubernetes - Namespaces
For OpenShift - Working with projects
The IBM Certified Container Software for Connect:Direct for UNIX has been integrated with IBM Licensing
and Metering service using Operator. You need to install this service. For more information, refer to
License Service deployment without an IBM Cloud Pak.

Installing and configuring IBM Licensing and Metering service

The IBM Certified Container Software for Connect:Direct for UNIX has been integrated with IBM Licensing
and Metering service using Operator.
You need to install this service. For more information, refer to License Service deployment without an IBM
Cloud Pak.

Downloading the Certified Container Software image

Before you install IBM Certified Container Software for Connect:Direct for UNIX, ensure that the
installation files are available on your client system.
The installation file comprises of two files:
• A helm chart
• A container image
You can download the installation files from the following locations-

Downloading the IBM Certified Container Software image from IBM Entitled
Registry
You can pull the container image from IBM Entitled registry into your cluster or download and load the
image into your registry.
The following Container image is available on IBM Entitled Registry:
• IBM Connect Direct for Unix v6.1 Certified Container
• cp.icr.io/cp/ibm-connectdirect/connectdirect:6.1.0.3
Create the entitled registry secret
Complete the following steps to create a secret with the entitled registry key value:
1. Ensure that you have obtained the entitlement key that is assigned to your ID.
a. Log in to My IBM Container Software Library by using the IBM ID and password that are associated
with the entitled software.
b. In the Entitlement keys section, select Copy key to copy the entitlement key to the clipboard.
c. Save the entitlement key to a safe location for later use.

To confirm that your entitlement key is valid, click View library that is provided in the left of the
page. You can view the list of products that you are entitled to. If IBM Connect:Direct for Unix is not
listed, or if the View library link is disabled, it indicates that the identity with which you are logged
in to the container library does not have an entitlement for IBM Connect:Direct for Unix. In this
case, the entitlement key is not valid for installing the software.
2. Set the entitled registry information by completing the following steps:

Chapter 2. Getting Started Guide 55

 a. Log on to machine from where the cluster is accessible
b. export ENTITLED_REGISTRY=cp.icr.io
c. export ENTITLED_REGISTRY_USER=cp
d. export ENTITLED_REGISTRY_KEY=<entitlement_key>
3. This step is optional. Log on to the entitled registry with the following docker login command:

docker login "$ENTITLED_REGISTRY" -u "$ENTITLED_REGISTRY_USER" -p

"$ENTITLED_REGISTRY_KEY"

4. Create a Docker-registry secret:

kubectl create secret docker-registry <any_name_for_the_secret> --docker-username=

$ENTITLED_REGISTRY_USER --docker-password=$ENTITLED_REGISTRY_KEY --docker-
email=<your_docker_email_address> --docker-server=$ENTITLED_REGISTRY -n <your namespace/
project name>

5. Update the service account or helm chart image pull secret configurations using
`image.imageSecrets` parameter with the above secret name.

Downloading the IBM Certified Container Software for Connect:Direct for UNIX
Helm chart from IBM Chart repository
You can download the IBM CCS for CDU helm 3 chart from IBM Public chart repository.

Downloading the IBM Certified Container Software for Connect:Direct for UNIX
image from IBM Fix Central
You can download the IBM Connect:Direct for UNIX Certified container image from Fix Central. The
bundle will have both IBM Certified Container Software for Connect:Direct Container image and Helm
chart.
To download the Connect:Direct for UNIX certified container image, complete the following steps:
1. Log on to the Fix Central web site by using necessary credentials.
2. Select the item to download that is, Chart Image bundle.

6.1.0.x-IBMConnectDirectforUNIX-Certified-Container-Linux-x86-iFix000.tar

3. Extract the downloaded Chart image bundle to extract the following files:

cdu6.1_certified_container_6.1.0.x_ifix000.tar(Docker Image)
ibm-connect-direct-1.1.x.tgz (Chart Bundle)

4. Load the Docker image to registry with following command.

docker load -i cdu6.1_certified_container_6.1.0.x_ifix000.tar

docker tag <image-name>:<tag> <repository-url>/<image-name>:<tag>
docker push <repository-url>/<image-name>:<tag>

5. Refer this image during chart installation using image.repository and image.tag keys defined in
values.yaml at Helm CLI command.
The image.repository should include <repository-url>/<image-name> value and
image.tag should include <tag> values.
Note: The steps mentioned above can also be executed in an Air-Gap environment.

Creating Pod Security Policy for Kubernetes Cluster

• In Kubernetes the Pod Security Policy (PSP) control is implemented as optional (but recommended).
Click here for more information on Pod Security Policy.

56 IBM Connect:Direct for UNIX: Documentation

 Based on your organization security policy, you may need to decide the pod security policy for your
Kubernetes cluster.

The IBM Connect Direct for UNIX chart defines a custom Pod Security Policy which is the minimum set
of permissions/ capabilities needed to deploy this chart and the Connect Direct for Unix container to
function properly. This is the recommended PSP for this chart and it can be created on the cluster by
cluster administrator.

The PSP and cluster role for this chart is defined below. The cluster administrator can either use the
snippets given below or the scripts provided in the Helm chart to create the PSP, cluster role and tie it to
the namespace where deployment will be performed. In both the cases, same PSP and cluster role will
be created. It is recommended to use the scripts in the Helm chart so that required PSP and cluster role
is created without any issue.
• Below is the Custom PodSecurityPolicy definition that the cluster admin can use:

apiVersion: policy/v1beta1
kind: PodSecurityPolicy
metadata:
name: ibm-connect-direct-psp
labels:
app: "ibm-connect-direct-psp"
spec:
privileged: false
allowPrivilegeEscalation: true
hostPID: false
hostIPC: false
hostNetwork: false
requiredDropCapabilities:
allowedCapabilities:
- FOWNER
- SETUID
- SETGID
- DAC_OVERRIDE
- CHOWN
- IPC_OWNER
- AUDIT_WRITE
- IPC_LOCK
- SYS_CHROOT
allowedHostPaths:
runAsUser:
rule: MustRunAsNonRoot
runAsGroup:
rule: MustRunAs
ranges:
- min: 1
max: 4294967294
seLinux:
rule: RunAsAny
supplementalGroups:
rule: MustRunAs
ranges:
- min: 1
max: 4294967294
fsGroup:
rule: MustRunAs
ranges:
- min: 1
max: 4294967294
volumes:
- configMap
- emptyDir
- projected
- secret
- downwardAPI
- persistentVolumeClaim
- nfs
forbiddenSysctls:
- '*'

• Custom ClusterRole for the custom PodSecurityPolicy

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole

Chapter 2. Getting Started Guide 57

 metadata:
name: "ibm-connect-direct-psp"
labels:
app: "ibm-connect-direct-psp"
rules:
- apiGroups:
- policy
resourceNames:
- ibm-connect-direct-psp
resources:
- podsecuritypolicies
verbs:
- use

• From the command line, you can run the setup scripts included in the Helm chart as cluster admin
(untar the downloaded Helm chart archive).

ibm-connect-direct/ibm_cloud_pak/pak_extensions/pre-install/clusterAdministration/
createSecurityClusterPrereqs.sh

ibm-connect-direct/ibm_cloud_pak/pak_extensions/pre-install/namespaceAdministration/
createSecurityNamespacePrereqs.sh <Namespace where deployment will be performed>

Note: If the above scripts are not executable, you will need to make the scripts executable by executing
following commands:

ibm-connect-direct/ibm_cloud_pak/pak_extensions/pre-install/namespaceAdministration/
createSecurityNamespacePrereqs.sh

ibm-connect-direct/ibm_cloud_pak/pak_extensions/pre-install/clusterAdministration/
createSecurityClusterPrereqs.sh

Creating security context constraints for OpenShift Cluster

• The IBM Connect:Direct for Unix chart requires an SecurityContextConstraints (SCC) to be tied to the
target namespace prior to deployment.

Based on your organization security policy, you may need to decide the security context constraints for
your OpenShift cluster.

This chart has been verified on privileged SCC which comes with Redhat OpenShift. For more info,
please refer this link. This chart defines a custom SCC which is the minimum set of permissions/
capabilities needed to deploy this chart and the Connect Direct for Unix container to function properly.
It is based on the predefined restricted SCC with extra required privileges. This is the recommended
SCC for this chart and it can be created on the cluster by cluster administrator.

The SCC and cluster role for this chart is defined below. The cluster administrator can either use the
snippets given below or the scripts provided in the Helm chart to create the SCC, cluster role and tie it to
the project where deployment will be performed. In both the cases, same SCC and cluster role will be
created. It is recommended to use the scripts in the Helm chart so that required SCC and cluster role is
created without any issue.
• Below is the Custom SecurityContextConstraints definition that the cluster admin can use

apiVersion: security.openshift.io/v1
kind: SecurityContextConstraints
metadata:
name: ibm-connect-direct-scc
labels:
app: "ibm-connect-direct-scc"
allowHostDirVolumePlugin: false
allowHostIPC: false
allowHostNetwork: false
allowHostPID: false
allowHostPorts: false
privileged: false
allowPrivilegeEscalation: true
allowedCapabilities:

58 IBM Connect:Direct for UNIX: Documentation

 - FOWNER
- SETUID
- SETGID
- DAC_OVERRIDE
- CHOWN
- IPC_OWNER
- IPC_LOCK
- SYS_CHROOT
- AUDIT_WRITE
defaultAddCapabilities: []
defaultAllowPrivilegeEscalation: false
forbiddenSysctls:
- "*"
fsGroup:
type: MustRunAs
ranges:
- min: 1
max: 4294967294
readOnlyRootFilesystem: false
requiredDropCapabilities: []
runAsUser:
type: MustRunAsNonRoot
seLinuxContext:
type: RunAsAny
supplementalGroups:
type: RunAsAny
ranges:
- min: 1
max: 4294967294
volumes:
- configMap
- downwardAPI
- persistentVolumeClaim
- projected
- secret
- nfs

• Custom ClusterRole for the custom SecurityContextConstraints

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
name: "ibm-connect-direct-scc"
labels:
app: "ibm-connect-direct-scc"
rules:
- apiGroups:
- security.openshift.io
resourceNames:
- ibm-connect-direct-scc
resources:
- securitycontextconstraints
verbs:
- use

• From the command line, you can run the setup scripts included in the Helm chart (untar the
downloaded Helm chart archive).

ibm-connect-direct/ibm_cloud_pak/pak_extensions/pre-install/clusterAdministration/
createSecurityClusterPrereqs.sh

ibm-connect-direct/ibm_cloud_pak/pak_extensions/pre-install/namespaceAdministration/
createSecurityNamespacePrereqs.sh <Project name where deployment will be perfromed>

Note: If the above scripts are not executable, you will need to make the scripts executable by executing
following commands:

ibm-connect-direct/ibm_cloud_pak/pak_extensions/pre-install/namespaceAdministration/
createSecurityNamespacePrereqs.sh

ibm-connect-direct/ibm_cloud_pak/pak_extensions/pre-install/clusterAdministration/
createSecurityClusterPrereqs.sh

Chapter 2. Getting Started Guide 59

 Creating storage for Data Persistence
The containers are ephemeral entity, all the data inside the container will be lost when the containers are
destroyed/removed, so data must be saved to Storage Volume using Persistent Volume. Persistent
volume is recommended for Connect:Direct for UNIX deployment files. A Persistent Volume (PV) is a
piece of storage in the cluster that is provisioned by an administrator or dynamically provisioned using
storage classes. For more information see:
• Kubernetes - Persistent Volumes
• OpenShift - Persistent Volume Overview

As a per-requisite, create a persistent volume supported via NFS, and host path mounted across all
worker nodes. IBM Certified Container Software for CDU supports:

• Dynamic Provisioning using storage class

• Pre-created Persistent Volume
• Pre-created Persistent Volume Claim
• The only supported access mode is `ReadWriteOnce`

Apart from required Persistent Volume, you can bind extra storage mounts using the parameters provided
in values.yaml. These parameters are extraVolume and extraVolumeMounts. This can be a host path or a
NFS type.

Prerequisite
• For non-dynamic provisioning, Storage Volume should have Connect:Direct certificate files to be used
for installation. Create a directory named "CDFILES" inside mount path and place certificate files in the
created directory. Similarly, the LDAP certificates should be placed in same directory.
• When creating Persistent Volume, make a note of the storage class and metadata labels, that are
required to configure Persistent Volume Claim's storage class and label selector during deployment.
This ensures that the claims are bound to Persistent Volume based on label match. These labels can be
passed to helm chart either by --set flag or custom values.yaml file. The parameters defined in
values.yaml for label name and its value are pvClaim.selector.label and
pvClaim.selector.value respectively.
Example: Create Persistent volume using NFS server

kind: PersistentVolume
apiVersion: v1
metadata:
name: <persistent volume name>
labels:
app.kubernetes.io/name: <persistent volume name>
app.kubernetes.io/instance: <release name>
app.kubernetes.io/managed-by: <service name>
helm.sh/chart: <chart name>
release: <release name>
purpose: cdconfig
spec:
storageClassName: <storage classname>
capacity:
storage: <storage size>
accessModes:
- ReadWriteOnce
nfs:
server: <NFS server IP address>
path: <mount path>

Example: Create Persistent volume using Host Path

kind: PersistentVolume
apiVersion: v1
metadata:
name: <persistent volume name>
labels:
app.kubernetes.io/name: <persistent volume name>

60 IBM Connect:Direct for UNIX: Documentation

 app.kubernetes.io/instance: <release name>
app.kubernetes.io/managed-by: <service name>
helm.sh/chart: <chart name>
release: <release name>
purpose: cdconfig
spec:
storageClassName: <storage classname>
capacity:
storage: <storage size>
accessModes:
- ReadWriteOnce
hostPath:
path: <mount path>

Invoke the following command to create a Persistent Volume:

Kubernetes:

kubectl create -f <peristentVolume yaml file>

OpenShift:

oc create -f <peristentVolume yaml file>

Setting permission on storage

When shared storage is mounted on a container, it is mounted with same POSIX ownership and
permission present on exported NFS directory. The mounted directories on container may not have
correct owner and permission needed to perform execution of scripts/binaries or writing to them. This
situation can be handled as below -
• Option A: The easiest and undesirable solution is to have open permissions on the NFS exported
directories.

chmod -R 777 <path-to-directory>

• Option B: Alternatively, the permissions can be controlled at group level leveraging the
supplementalGroups and fsGroup setting. For example - if we want to add GID to supplementalGroups
or fsGroup, it can be done using storageSecurity.supplementalGroups or storageSecurity.fsGroup.
Apart from above recommendation, during deployment, a default admin user cduser with group cduser is
created. A mandatory parameter, cdai_adminPassword is added to cd_param_file to update the password
required by cduser at container start up. The default UID and GID of cduser is 45678.

The UID and GID of cduser can be set to some real user on the host system. By setting the same UID and
GID as on the host system, the host system user would have suitable permissions on the files present on
the host path so that this user can be used to edit any setting or configuration files related to
Connect:Direct for Unix running inside container.

Example:
If you have a user, host-user having UID and GID set to 2000 and 4000 respectively on the host system.
There are 'upload' (for files to be sent) and 'download' (for files to be received) directories created by this
user. These directories can be mounted on the CDU container so that these directories are available inside
container.

In order to give cduser access to these directories inside the container, the UID and GID of cduser can be
set to `2000` and `4000` respectively. Similarly, you can set the UID and GID of `appuser` which is a
non-admin user of Connect:Direct for Unix running inside container. The user `appuser` is created only if
you have passed its password to be set inside container using cdai_appuser_pwd parameter in
cd_param_file.

Chapter 2. Getting Started Guide 61

 Creating secret
Passwords are used for KeyStore, by Administrator to connect to Connect:Direct server, and to decrypt
certificates files.
To separate application secrets from the Helm Release, a Kubernetes secret must be created based on
the examples given below and be referenced in the Helm chart as secret.secretName value.
To create Secrets using the command line, follow the steps below:
1. Create a template file with Secret defined as described in the example below:

apiVersion: v1
kind: Secret
metadata:
name: <secret name>
type: Opaque
data:
admPwd: <base64 encoded password>
crtPwd: <base64 encoded password>
keyPwd: <base64 encoded password>
appUserPwd: <base64 encoded password>

Here:
• admPwd refers to the password that will be set for the Admin user 'cduser' after a successful
deployment
• crtPwd refers to the password used to decrypt certificate files
• keyPwd refers to the Key Store password
• appUserPwd refers to password for a non-admin Connect:Direct user. This user will only be created
inside container if appUserPwd is defined in secret yaml to create Connect:Direct secret object.
• After the secret is created, delete the yaml file for security reasons. The password entered for
admPwd is set as password for the user cduser at pod initialization.
Note: Base64 encoded passwords need to be generated manually by invoking the below command:

echo -n “<password>” | base64

Use the output of this command in the <secret yaml file>.

2. Run the following command to create the Secret:

Kubernetes:

kubectl create -f <secret yaml file>

OpenShift

oc create -f <secret yaml file>

To check the secret created invoke the following command:

kubectl get secrets

For more details see, Secrets.

Default Kubernetes secrets management has certain security risks as documented here, Kubernetes
Security.
Users should evaluate Kubernetes secrets management based on their enterprise policy requirements
and should take steps to harden security.
3. For dynamic provisioning, one more secret resource needs to be created for all certificates (secure
plus certificates and LDAP certificates). It can be created using below example as required -

62 IBM Connect:Direct for UNIX: Documentation

 Kubernetes

kubectl create secret generic cd-cert-secret --from-file=certificate_file1=/path/to/

certificate_file1 --from-file=certificate_file2=/path/to/certificate_file2

OpenShift

oc create secret generic cd-cert-secret --from-file=certificate_file1=/path/to/

certificate_file1 --from-file=certificate_file2=/path/to/certificate_file2

Note: The secret resource name created above. It should be referenced by Helm chart for dynamic
provisioning using parameter `secret.certSecretName'

Configuring - Understanding values.yaml

Following table describes configuration parameters listed in values.yaml file in Helm charts and are
used to complete installation. Use the following steps to complete this action:
• Specify parameters that need to be overridden using the --set key=value[,key=value] argument
at Helm install.
Example:

helm version 2

helm install --name <release-name> \

--set cdArgs.cport=9898 \
...
ibm-connect-direct-1.1.x.tgz

helm version 3

helm install <release-name> \

--set cdArgs.cport=9898 \
...
ibm-connect-direct-1.1.x.tgz

• Alternatively, provide a YAML file with values specified for these parameters when you install a Chart.
Create a copy of values.yaml file such as, my-values.yaml and edit the values that you would like
to override. Use the my-values.yaml file for installation.
Example

helm version 2

helm install --name <release-name> -f my-values.yaml ... ibm-connect-direct-1.1.x.tgz

helm version 3

helm install <release-name> -f my-values.yaml ... ibm-connect-direct-1.1.x.tgz

• To mount extra volumes use any of the following templates.

For Hostpath

extraVolumeMounts:
- name: <name>
mountPath: <path inside container>
extraVolume:
- name: <name same as name in extraVolumeMounts>
hostPath:
path: <path on host machine>
type: DirectoryOrCreate

Chapter 2. Getting Started Guide 63

 For NFS Server

extraVolumeMounts:
- name: <name>
mountPath: <path inside container>
extraVolume:
- name: <name same as name in extraVolumeMounts>
nfs:
path: <nfs data path>
server: <server ip>

Alternatively, this can also be done using --set flag.

Example

helm install --name <release-name> --set

extraVolume[0].name=<name>,extraVolume[0].hostPath.path=<path on host
machine>,extraVolume[0].hostPath.type="DirectoryOrCreate",extraVolumeMounts[0].name=<name
same as name in extraVolume>,extraVolumeMounts[0].mountPath=<path inside container> \
...
ibm-connect-direct-1.1.x.tgz

OR

helm install --name <release-name> --set

extraVolume[0].name=<name>,extraVolume[0].nfs.path=<nfs data
path>,extraVolume[0].nfs.server=<NFS server IP>, extraVolumeMounts[0].name=<name same as name
in extraVolume>,extraVolumeMounts[0].mountPath=<path inside container> \
...
ibm-connect-direct-1.1.x.tgz

Parameter Description Default Value

licenseType Specify prod or non-prod for non-prod
production or non-production
license type respectively
license License agreement. Set true to false
accept the license.
env.timezone Timezone UTC
arch Node Architecture amd64
replicaCount Number of deployment replicas 1
image.repository Image full name including
repository
image.tag Image tag
digest.enabled Enable/Disable digest of image to false
be used
digest.value The digest value for the image sha256:9406f4eb04b75ea5e3f3
ce6fd762f57fd8ea555c7a45728
1b01cef33ec694565
image.imageSecrets Image pull secrets
image.pullPolicy Image pull policy IfNotPresent
cdArgs.nodeName Node name cdnode
cdArgs.crtName Certificate file name
cdArgs.cport Client Port 1363
cdArgs.sport Server Port 1364

64 IBM Connect:Direct for UNIX: Documentation

Parameter Description Default Value
saclConfig Configuration for SACL n
cdArgs.configDir Directory for storing CDFILES
Connect:Direct configuration files

appUser.name Name of Non-Admin appuser

Connect:Direct User

appUser.uid UID of Non-Admin

Connect:Direct User

storageSecurity.fsGroup Group ID for File System Group 45678

storageSecurity.supplementalGro Group ID for Supplemental group 5555

ups
appUser.gid GID of Non-Admin
Connect:Direct User
persistence.enabled To use persistent volume true
pvClaim.existingClaimName Provide name of existing PV claim
to be used
persistence.useDynamicProvision To use storage classes to false
ing dynamically create PV
pvClaim.accessMode Access mode for PV Claim ReadWriteOnce
pvClaim.storageClassName Storage class of the PVC
pvClaim.selector.label PV label key to bind this PVC
pvClaim.selector.value PV label value to bind this PVC
pvClaim.size Size of PVC volume 100Mi
service.type Kubernetes service type exposing LoadBalancer
ports
service.apiport.name API port name api
service.apiport.port API port number 1363
service.apiport.protocol Protocol for service TCP
service.ftport.name Server (File Transfer) Port name ft
service.ftport.port Server (File Transfer) Port 1364
number
service.ftport.protocol Protocol for service TCP

service.loadBalancerIP Provide the LoadBalancer IP

service.annotations Provide the annotations for {}

service
service.externalIP External IP for service discovery
secret.certSecretName Name of secret resource of
certificate files for dynamic
provisioning

Chapter 2. Getting Started Guide 65

 Parameter Description Default Value
secret.secretName Secret name for Connect:Direct
password store
resources.limits.cpu Container CPU limit 500mi
resources.limits.memory Container memory limit 2000Mi
resources.requests.cpu Container CPU requested 500m
resources.requests.memory Container Memory requested 2000Mi
serviceAccount.create Enable/disable service account true
creation
serviceAccount.name Name of Service Account to use
for container
extraVolumeMounts Extra Volume mounts
extraVolume Extra volumes
affinity.nodeAffinity.required k8sPodSpec.nodeAffinity.require
d
DuringSchedulingIgnoredDuring
DuringSchedulingIgnoredDuring
Execution
Execution

affinity.nodeAffinity.preferred k8sPodSpec.nodeAffinity.preferr
ed
DuringSchedulingIgnoredDuring
DuringSchedulingIgnoredDuring
Execution
Execution

affinity.podAffinity.required k8s PodSpec.podAntiAffinity.

DuringSchedulingIgnoredDuring requiredDuringSchedulingIgnore
d
Execution
DuringExecution

affinity.podAffinity.preferred k8sPodSpec.podAntiAffinity.
DuringSchedulingIgnoredDuring preferredDuringScheduling
Execution IgnoredDuringExecution

affinity.podAntiAffinity.required k8sPodSpec.podAntiAffinity.
DuringSchedulingIgnoredDuring requiredDuringSchedulingIgnore
d
Execution
DuringExecution

affinity.podAntiAffinity.preferred k8sPodSpec.podAntiAffinity.
DuringSchedulingIgnoredDuring preferredDuringSchedulingIgnor
ed
Execution
DuringExecution

livenessProbe.initialDelaySecond Initial delay for liveness 230

s
livenessProbe.timeoutSeconds Timeout for liveness 30

66 IBM Connect:Direct for UNIX: Documentation

Parameter Description Default Value
livenessProbe.periodSeconds Time period for liveness 60
readinessProbe.initialDelaySecon Initial delays for readiness 220
ds
readinessProbe.timeoutSeconds Timeout for readiness 5
readinessProbe.periodSeconds Time period for readiness 60
route.enabled Route for OpenShift Enabled/ false
Disabled
cduser.uid UID for cduser 45678
cduser.gid GID for cduser 45678
ldap.enabled Enable/Disable LDAP false
configuration
ldap.host LDAP server host
ldap.port LDAP port
ldap.domain LDAP Domain
ldap.tls Enable/Disable LDAP TLS false
lap.caCert LDAP CA Certificate name
ldap.clientValidation Enable/Disable LDAP Client false
Validation
ldap.clientCert LDAP Client Certificate name
ldap.clientKey LDAP Client Certificate key name

Affinity
The chart provides ways in form of node affinity, pod affinity and pod anti-affinity to configure advance
pod scheduling in Kubernetes. See, Kubernetes documentation for details.

Understanding LDAP deployment parameters

This section demonstrates the steps required to implement the PAM and SSSD configuration with
Connect:Direct UNIX to authenticate external user accounts through OpenLDAP.
• Updating initparam file: When the LDAP authentication is enabled, the container startup script
automatically updates the initparam configuration to support the PAM module. The following line is
added to initparam.cfg:

ndm.pam:service=login

• The following packages are pre-installed in the container image to enable the LDAP support:

openldap-client, sssd, sssd-ldap, openssl-perl, authselect

• The following default configuration file (/etc/sssd/sssd.conf) is added to the image. You must
replace the values highlighted in bold with the values of environment variables as explained in next
section.

[domain/default]
id_provider = ldap
autofs_provider = ldap
auth_provider = ldap
chpass_provider = ldap
ldap_uri = LDAP_PROTOCOL://LDAP_HOST:LDAP_PORT
ldap_search_base = LDAP_DOMAIN

Chapter 2. Getting Started Guide 67

 ldap_id_use_start_tls = True
ldap_tls_cacertdir = /etc/openldap/certs
ldap_tls_cert = /etc/openldap/certs/LDAP_TLS_CERT_FILE
ldap_tls_key = /etc/openldap/certs/LDAP_TLS_KEY_FILE
cache_credentials = True
ldap_tls_reqcert = allow

• Description of the Certificates required for the configuration:

– Mount certificates inside CDU Container:
- Copy the certificates needed for LDAP configuration in the mapped directory which is used to share
the Connect:Direct Unix secure plus certificates (CDFILES directory by default).
– DNS resolution: If TLS is enabled and hostname of LDAP server is passed as “ldap.host”, then it must
be ensured that the hostname is resolved inside the container. It is the responsibility of Cluster
Administrator to ensure DNS resolution inside pod's container.
– Certificates creation and configuration: This section provides a sample way to generate the
certificates:
- LDAP_CACERT - The root and all the intermediate CA certificates needs to be copied in one file.
- LDAP_CLIENT_CERT – The client certificate which the server must be able to validate.
- LDAP_CLIENT_KEY – The client certificate key.
– Use the below new parameters for LDAP configuration:
- ldap.enabled
- ldap.host
- ldap.port
- ldap.domain
- ldap.tls
- ldap.caCert
- ldap.clientValidation
- ldap.clientCert
- ldpa.clientKey

Installing OpenShift Container platform

Note: This step is optional. It is only needed if IBM Certified Container Software for Connect:Direct for
UNIX deployment is planned on OpenShift cluster.
OpenShift container platform brings together Docker and Kubernetes and provides an API to manage
these services. OpenShift Container Platform allows you to create and manage containers.
It is an on-premise platform service that uses Kubernetes to manage containers built on a foundation of
Red Hat Enterprise Linux. For more information on how to setup an OpenShift container platform cluster
environment, see Installing OpenShift.

Installing IBM Connect:Direct for Unix using Helm chart

After completing all “Pre-installation tasks” on page 54, you can deploy the IBM Certified Container
Software for Connect:Direct for UNIX by invoking following command:

Helm version 2

helm install --name my-release --set license=true,image.repository=<reponame> image.tag=<image

tag>,cdArgs.crtName=<certificate name>,image.imageSecrets=<image pull
secret>,secret.secretName=<C:D secret name> ibm-connect-direct-1.1.x.tgz

68 IBM Connect:Direct for UNIX: Documentation

Helm version 3

helm install my-release --set license=true,image.repository=<reponame> image.tag=<image

tag>,cdArgs.crtName=<certificate name>,image.imageSecrets=<image pull
secret>,secret.secretName=<C:D secret name> ibm-connect-direct-1.1.x.tgz

This command deploys ibm-connect-direct-1.1.x.tgz chart on a Kubernetes cluster using the default
configuration. “Creating storage for Data Persistence” on page 60 lists parameters that can be configured
at deployment.
Mandatory parameters required at the helm install command:

Parameter Description Default Value

license License agreement for IBM false
Certified Container Software
image.repository Image full name including
repository
image.tag Image tag
cdArgs.crtName Certificate file name
image.imageSecrets Image pull secrets
secret.secretName Secret name for Connect:Direct
password store

Validating the Installation

After the deployment procedure is complete, you should validate the deployment to ensure that
everything is working according to your needs. The deployment may take approximately 4-5 minutes to
complete.
To validate if the Certified Container Software deployment using Helm charts is successful, invoke the
following commands to verify the status (STATUS is DEPLOYED) for a Helm chart with release, my-release
and namespace, my-namespace.
• Check the Helm chart release status by invoking the following command and verify that the STATUS is
DEPLOYED:

helm status my-release

• Wait for the pod to be ready. To verify the pods status (READY) use the dashboard or through the
command line interface by invoking the following command:

kubectl get pods -l release my-release -n my-namespace -o wide

• To view the service and ports exposed to enable communication in a pod invoke the following
command:

kubectl get svc -l release= my-release -n my-namespace -o wide

The screen output displays the external IP and exposed ports under EXTERNAL-IP and PORT(S) column
respectively. If external LoadBalancer is not present, refer Master node IP as external IP.
Exposed Services
If required, this chart can create a service of ClusterIP for communication within the cluster. This type can
be changed while installing chart using service.type key defined in values.yaml. There are two ports where
IBM Connect:Direct processes run. API port (1363) and FT port (1364), whose values can be updated
during chart installation using service.apiport.port or service.ftport.port.

Chapter 2. Getting Started Guide 69

 IBM Connect:Direct for Unix services for API and file transfer can be accessed using LoadBalancer or
external IP and mapped API and FT port. If external LoadBalancer is not present then refer to Master
node IP for communication.
Note: NodePort service type is not recommended. It exposes additional security concerns and is hard to
manage from both an application and networking infrastructure perspective.
DIME and DARE Security Considerations
This topic provides security recommendations for setting up Data In Motion Encryption (DIME) and Data
At Rest Encryption (DARE). It is intended to help you create a secure implementation of the application.
1. All sensitive application data at rest is stored in binary format so user cannot decrypt it. This chart
does not support encryption of user data at rest by default. Administrator can configure storage
encryption to encrypt all data at rest.
2. Data in motion is encrypted using transport layer security (TLS 1.3). For more information see, Secure
Plus.

Post-installation tasks
The post deployment configuration steps can be performed via:
• Connect Direct Web services
– Login to the Connect Direct Web services using the master node IP/External IP address and the host
ports to which container API and server ports are mapped to. For configuration steps, see
Connect:Direct Web Services Help Videos.
– Issue the following command to get the external IP address

kubectl get svc

• Attaching to the container

Follow the steps given below:
– Issue the following command to get the pod name

kubectl get pods -n <namespace>

– Issue the following command to attach to the container

kubectl exec -it <pod name> bash

– Go to the installation path /opt/cdunix and complete the steps followed to configure conventional
Connect:Direct for Unix here, Administering Connect:Direct for UNIX.

Upgrade, Rollback, and Uninstall

After deploying IBM certified container software for Connect:Direct for UNIX, you can perform following
actions:
• Upgrade, when you wish to move to a new release
• Rollback, when you wish to recover the previous release version in case of failure
• Uninstall, when you wish to uninstall

Upgrade – Upgrading a Release

To upgrade your deployment with a new docker image for the application server or with a change in
configuration such as, new service ports to be exposed refer to the following example.
To upgrade the chart with the release name my-release:

70 IBM Connect:Direct for UNIX: Documentation

 • Ensure that the chart is downloaded locally and available.
• Invoke the following command to upgrade your deployments:

helm upgrade --reuse-values my-release -f values.yaml ibm-connect-direct-1.1.x.tgz

Note: Do not change/update the values of Connect Direct configuration parameters.

• If any new parameters are introduced in the new chart and you are upgrading using new chart. Then, all
those new parameters should be either passed with "--set" option or using a yaml file with "-f" option.
The parameter can have default values as specified in the new chart or you can change the values as per
your configuration requirement.

Rollback – Recovering on Failure

Procedure
1. To rollback a chart with release name my-release to a previous revision invoke the following
command:

helm rollback my-release <previous revision number>

2. To get the revision number execute the following command:

helm history my-release

Note: The rollback is only supported to a previous release. Subsequent rollbacks are not supported.
Rollback from Connect Direct Unix v6.1 is only supported if it was upgraded from Connect Direct Unix
6.0 iFix026 and later releases.

Uninstall – Uninstalling a Release

To uninstall/delete a Chart with release name my-release invoke the following command:

Helm version 2

helm delete --purge my-release

Helm version 3

helm delete my-release

Note:
This command removes all the Kubernetes components associated with the Chart and deletes the
Release. Certain Kubernetes resources created as an installation prerequisite for the Chart and a helm
hook ie ConfigMap will not be deleted using the helm delete command. Delete these resources only if
they are not required for further deployment of IBM Certified Container Software for Connect:Direct UNIX.
If deletion is required, you have to manually delete the following resources:
• The persistent volume
• The secret
• The Config Map

Known Limitations
• Scalability is supported with the conventional Connect:Direct for Unix release with load balancer
service.
• High availability can be achieved in an orchestrated environment.

Chapter 2. Getting Started Guide 71

 • IBM Connect:Direct for Unix chart is supported with only 1 replica count.
• IBM Connect:Direct for Unix chart supports only AMD64 architecture.
• Adding Connect:Direct users at runtime is not supported.
• File agent service is not available inside the container.
• Interaction with IBM Control Center Director is not supported.
• The container does not include X-Windows support, so SPAdmin cannot run inside the container. SPCli
will run in the container and Connect Direct Web Services (CDWS) can be used outside the container in
place of using SPAdmin.

Migrating to Connect:Direct for UNIX using Certified Container Software

Follow the steps given below to create a backup and restore IBM Connect:Direct for Unix using Certified
Container Software:
1. Create a backup
To create a backup of configuration data and other information such as stats and TCQ, present in the
persistent volume, follow the steps given below:
a. Go to mount path of Persistent Volume.
b. Make copy of the following directories and store them at a secured location:
• WORK
• SECURITY
• CFG
• SECPLUS
Note:
– Update the various values in initparm.cfg and netmap.cfg for the C:D installation path,
hostname/IP and port numbers. The installation path is `/opt/cdunix/` , hostname would be
<helm-release-name>-ibm-connect-direct-0 and client port is 1363 and server port is 1364.
– The nodename of Connect:Direct for Unix running on traditional system should be same while
migrating it inside container.
– If Connect:Direct for UNIX is installed in a conventional mode, create a backup of the following
directories:
- work
- security
- cfg
- secure+

A file must be created in a work directory before taking backup. The file can be created by
invoking the following command:

<path to cdunix install directory>/etc/cdver > <path to cdunix install directory>/

work/saved_cdunix_version

2. Restore the data in a new deployment

To restore data in a new deployment, follow the steps given below:
a. Create a Persistent Volume.
b. Copy all the backed-up directories to the mount path of Persistent Volume.
3. For other prerequisites such as secrets see, “Pre-installation tasks” on page 54.
4. Upgrade to Certified Container Software

72 IBM Connect:Direct for UNIX: Documentation

 Create a new instance of chart using the following helm CLI command:

Helm version 2

helm install --name <release-name> --set license=true,image.repository=<reponame>

image.tag=<image tag>,cdArgs.crtName=<certificate name>,image.imageSecrets=<image pull
secret>,secret.secretName=<C:D secret name> ibm-connect-direct-1.1.x.tgz

Helm version 3

helm install <release-name> --set license=true,image.repository=<reponame> image.tag=<image

tag>,cdArgs.crtName=<certificate name>,image.imageSecrets=<image pull
secret>,secret.secretName=<C:D secret name> ibm-connect-direct-1.1.x.tgz

Note: The nodename of Connect:Direct for Unix running on traditional system should be same for
migration to IBM Certified Container Software. Configure the nodename using "cdArgs.nodeName"
parameter.

Migration from Helm 2 to Helm 3

This migration only applies if you have IBM Certified Container Software instances/releases that are
running on Helm 2 and you want to use Helm 3 release. It is the responsibility of the Cluster Administrator
to decide on the migration strategy according to deployment requirement and specific use case scenario.
Although, there is a detailed and exhaustive documentation provided by the Helm on migration. Please
refer the this link, Helm.

Troubleshooting your deployment in an IBM Certified container

and Docker environment
The following sections describes troubleshooting tips for issues that most frequently occur when
deploying Connect:Direct for UNIX in an IBM certified container and stand-alone Docker environment.

Troubleshooting IBM Certified container and Docker Container issues

The following table describes possible reasons for occurrence and troubleshooting tips for issues that
most frequently occur when deploying Connect:Direct for UNIX in an IBM certified and Docker container.
The quickest way to check the reason of a failed installation is to check the container logs or
CDStartup.log in the work directory on Storage Volume mapped path.

Table 3. Troubleshooting deployment and functional issues

Issue Possible Reason Solution/Workaround
Deployment issues

Chapter 2. Getting Started Guide 73

 Table 3. Troubleshooting deployment and functional issues (continued)
Issue Possible Reason Solution/Workaround
C:D options file not provided Configuration file • Create cd_param_file with
cd_param_file has not been all installation parameters and
provided. place it at a preferred location.
For more information see,
“Configuring Docker
Containers” on page 38.
• Use -v option at docker run
command to map this location
to /opt/cdfiles path inside
the container. For more
information see, “Deploying
IBM Connect:Direct for UNIX
using a Docker Container” on
page 44.

C:D admin password not provided cdai_adminPasswordpasswor Define the

d was not defined in the cdai_adminPassword in
cd_param_file. cd_param_file.
For more information see,
“Configuring Docker Containers”
on page 38 and “Deploying IBM
Connect:Direct for UNIX using a
Docker Container” on page 44.

The certificate/password for Value not defined for the Define missing values in the
secure plus configuration is not following parameters in cd_param_file. For more
provided cd_param_file: information see, “Configuring
Docker Containers” on page 38
• cdai_localCertFile and “Deploying IBM
• cdai_localCertPassphrase Connect:Direct for UNIX using a
Docker Container” on page 44.
• cdai_keystorePassword

CD localcertfile: <cert file name> The certificate name defined in Ensure that the key certificate
do not exist at the path <path>. the cd_param_file is not and the trusted certificate are
Exiting present at the defined path. present at the path defined at
docker run command. For details
see, “Adding Certificate Files ” on
page 40 and “Deploying IBM
Connect:Direct for UNIX using a
Docker Container” on page 44.
Connect Direct not running. Installation of Connect:Direct Isolate the reason for failure in
Exiting. failed with a non-zero finalRc cdaiLog.txt file inside the
value in cdaiLog.txt. work directory present on
Storage Volume mounted path.
File "/opt/cdfiles/<certificate The certificate in use is not in Use a certificate in PEM format
name>" is not a PEM key recommended .PEM format. for installation. See, Generating
certificate. certificate in PEM format.

74 IBM Connect:Direct for UNIX: Documentation

Table 3. Troubleshooting deployment and functional issues (continued)
Issue Possible Reason Solution/Workaround
‘Permission denied’ error when If SELinux policy is set to Run the following command to
deploying C:D using certified enforced, the host mounted path set the proper SELinux policy
container software when SELinux is not writable. type label to be attached to the
is set to enforced host directory:
chcon -Rt svirt_sandbox_file_t
<host mounted path>

‘helm install’ command fails to Some mandatory parameters are Check that all mandatory
deploy C:D missing in the helm install parameters are provided when
command. executing the helm install
command. For more information
see, “Installing IBM
Connect:Direct for Unix using
Helm chart” on page 68.
Pod recovery fails when Possible reasons could be that NFS storage is the preferred
persistent volume is mapped to the pod recovered on a different storage volume. If NFS server is
the host path. worker node and the persistent not available, set the Pod Affinity
volume was mapped to a such that the pod is always
different host path. scheduled on the same worker
node where persistent volume
can be accessed.
Permission error occurs when Openshift Admin user was used Only the cluster Admin has
trying to create a persistent to create persistent volume or privileges to create persistent
volume or SecurityContextConstraints volume and
SecurityContextConstraints in an SecurityContextConstraints.
OpenShift environment Attempt creating these as a
cluster Admin. For more
information see, “Creating
security context constraints for
OpenShift Cluster ” on page 58.
Deployment fails with following The certificate file is not valid. Use the correct certificate file.
error: Check if conventional Check the chain sequence for a
Connect:Direct for UNIX can be chained certificate.
SPCLI> 20200401 17:19:17 8
installed using the automated
CDAI007E Secure+ configuration
install procedure using this
failed.
certificate.
20200401 17:19:17 0 CDAI010I
createExitStatusFile() entered.
20200401 17:19:17 0 CDAI010I
createExitStatusFile() exited.
command terminated with exit
code 137

Functional Issues

Chapter 2. Getting Started Guide 75

 Table 3. Troubleshooting deployment and functional issues (continued)
Issue Possible Reason Solution/Workaround
Error encountered during 1. Configurations of the previous The configurations of a container
Connect:Direct container node container are not mapped to should be mapped to the Storage
recovery. Storage Volume. Volume so that the container can
be recovered in future. Hostname
2. Hostname provided does not of the removed/destroyed
match the hostname of the container should be provided at
destroyed/removed container container recovery. Also, ensure
3. Passwords missing in cd_param_file contains all
cd_param_file passwords.

Error encountered in connecting Connect:Direct API port is not The Connect:Direct API port
to an installed Connect:Direct exposed to the host. (default 1363) running inside the
container node. container should be mapped to
an available host port.
Error encountered in performing Connect:Direct Server port is not • The server port (default 1364)
a file transfer with other exposed to host or its entry is of the Connect:Direct node
Connect:Direct nodes. missing inside the netmap.cfg running inside the container
file of the partner node. should be mapped to the
available host port.
• Define exposed port in partner
node's netmap.cfg file for a
successful file transfer.

Error encountered in file transfer Netmap check on Connect:Direct The IPs of all the worker nodes
from pod to Connect:Direct windows node is enabled and not should be mentioned in the
windows node. allowing file transfer. netmap of Connect:Direct
windows node using the
alternate.comminfo parameter,
like below:
Alternate Comminfo :
<worker node1 ip>,
<worker node2 ip>

Unable to add certificates for This functionality is not present Import the certificates using
Secure+ using Connect:Direct in the current version of Secure+ CLI by attaching to the
Web services Connect:Direct Web services and container.
will be available in the upcoming
release.
In case of migration of The local users defined in When migrating to container
Connect:Direct to container userfile.cfg are not present inside environment from a conventional
environment, local users in the container environment. Connect:Direct environment, the
userfile.cfg not available inside local users defined in
the container userfile.cfg should be added
inside the container using the
useradd command.

Troubleshooting in a Docker Container environment

This section describes how to troubleshoot in your Docker container environment.
When you encounter an issue in your containerized environment, run the following checks to assist you
with troubleshooting process.

76 IBM Connect:Direct for UNIX: Documentation

 Generic Checks
• Get container information such as, container-id and check the node status if it is Up

docker ps -a

• Retrieve the logs for a container

docker logs <container-id>

Rerun a failed container deployment job

When a container deployment fails investigate the cause and follow the procedure given below over
command line:
• Use the command below to stop the failed container, if it is still running

docker stop <container-id>

• Delete the stopped container

docker rm <container-id>

• Delete the Connect:Direct data mapped to Storage Volume

• Re-run the deployment steps described in “Deploying IBM Connect:Direct for UNIX using a Docker
container” on page 37.

View Container logs

• Check the container logs using the command

docker logs <container-name>

• From the mapped path on Storage Volume, check the silent installation logs cdaiLog.txt inside the
work directory.
• IBM Connect:Direct for UNIX traces for PMGR, SMGR or CMGR can be enabled using the Connect:Direct
Web Services. From the mapped path on Storage Volume, check the traces generated inside the work
directory.
• IBM Connect:Direct for UNIX statistics can be checked in the work directory inside the mapped path on
Storage Volume.

Troubleshooting your IBM certified Containerized environment

This section describes how to troubleshoot in your containerized environment.
The troubleshooting steps assumes that Kubectl command line tool is installed and configured in your
environment.
When you encounter an issue in your containerized environment, run the following checks to assist you
with troubleshooting process.

Generic Checks
• Get nodes information and check the status of nodes is Ready

kubectl get nodes -n <namespace> -o wide

• Review the Persistent Volume and Persistent Volume Claim information and ensure they match with
your deployment YAML files

Chapter 2. Getting Started Guide 77

 kubectl describe pv <pv name> -n <namespace>

• Get the status of the IBM Connect:Direct for Unix containers deployment job:

kubectl -n <namespace> rollout status deployment/<deployment name>

kubectl describe deployment <deployment name> -n <namespace>

• Get information about the pods after the IBM Connect:Direct for Unix containers have been deployed:

kubectl get pods -n <namespace> -o wide

• Retrieve the logs for a particular pod

kubectl logs -f <pod name> -c <deployment name> -n <namespace>

• Get details about a particular pod

kubectl describe pods <pod name> -n <namespace>

Rerun a failed container deployment job

When a container deployment fails investigate the cause and follow the procedure given below over
command line:
• Delete the failed deployment using the below command

helm delete --purge <release-name>

• Delete the persistent volume

kubectl delete pv <pv-name>

• Delete the secret

kubectl delete secret <secret-name>

• Delete the configMap

kubectl delete configmap <configmap name>

• Manually delete the data present in persistent volume

• Re-run the deployment steps described in “Deploying IBM Connect:Direct for UNIX using an IBM
Certified Container Software” on page 49.

View Container logs

• Check the container logs using the command

kubectl logs -f <pod name> -c <deployment name> -n <namespace>

• From the mapped path on Storage Volume, check the silent installation logs cdaiLog.txt inside the
work directory.
• IBM Connect:Direct for UNIX traces for PMGR, SMGR or CMGR can be enabled using the Connect:Direct
Web Services. From the mapped path on Storage Volume, check the traces generated inside the work
directory.
• IBM Connect:Direct for UNIX stats can be checked in the work directory inside the mapped path on
Storage Volume.

78 IBM Connect:Direct for UNIX: Documentation

Connect:Direct File Agent Overview
Connect:Direct File Agent is a component of IBM Connect:Direct that provides unattended file
management. Before using Connect:Direct for UNIX, you must plan how to configure it to automate file
management for your site. After planning what you need to accomplish, configure Connect:Direct File
Agent to connect to a IBM Connect:Direct server, watch the directories that files of interest will be added
to, and submit a specified IBM Connect:Direct Process to the server when a file is detected.
Connect:Direct File Agent provides monitoring and detection capabilities that enhance the automation
you accomplish with IBM Connect:Direct Processes. You cannot create Processes with Connect:Direct File
Agent; however, Connect:Direct File Agent variables can be used to pass arguments to a Process.
Connect:Direct File Agent does not delete, copy, or move files directly, but it helps you accomplish such
tasks by submitting the Process you specify in the configuration to the IBM Connect:Direct server. Before
you specify a IBM Connect:Direct Process in the Connect:Direct File Agent configuration, you must create
and test the Processes to ensure that it performs tasks as expected when Connect:Direct File Agent
submits the Process.
Using the Connect:Direct File Agent configuration interface and Help system, you define the default
configuration file (Default_Config.ser). The default configuration file defines the IBM Connect:Direct
server that Connect:Direct for UNIX communicates with; the directory, or directories, that Connect:Direct
File Agent monitors; and how a file added to a watched directory or a detected system event are
processed.
You can configure Connect:Direct File Agent to operate in either of the following ways:
• Watch for any file to appear in one or more watched directories and submit the default Process after
detecting the newly added file.
• Override the default Process specified and apply either watched file event rules (Submit Process rule) or
system event rules that is enabled for the configuration. Connect:Direct File Agent applies a watched file
event rule to a detected file by checking file properties to determine whether criteria specified by the
rule are met. A system event rule checks whether a system event meets criteria specified by the rule.
When all criteria for a rule are met, Connect:Direct File Agent submits the IBM Connect:Direct Process
associated with that rule.
You can create Connect:Direct File Agent rules based on the following properties:
• Full or partial name of the file detected in a watched directory
• Size of the file detected in a watched directory
• System event title
• System event contents (as included in a stack trace)
You can specify more than one rule in a Connect:Direct File Agent configuration; each rule can have
Connect:Direct File Agent submit a different Process.
Although you can create multiple rules as part of a Connect:Direct File Agent configuration,
Connect:Direct File Agent processing ends when all criteria for a rule are met. Therefore, you should
specify rules so that those with more specific criteria (properties) are listed first in the configuration.
For optimum performance, you should configure Connect:Direct File Agent to communicate with the IBM
Connect:Direct node where it is installed. You can configure Connect:Direct File Agent to use continuous
signon and remain connected to the API port for the IBM Connect:Direct server at all times, or configure it
to connect to the port only when it needs to. Connect:Direct File Agent can be installed on UNIX, Microsoft
Windows, and z/OS operating systems. When you use IBM Connect:Direct with UNIX or Microsoft
Windows, the watched directory is a UNIX pathname or a Microsoft Windows path to the directory. When
you use IBM Connect:Direct with z/OS, the watched directory can be the HFS pathname for a file or a
directory, the full MVS data set name, or a partial MVS data set name.
Connect:Direct File Agent can monitor multiple directories, including local and network directories.
Connect:Direct File Agent scans the watched directories you specify in the configuration for newly added
files (unless you specify a rule to force other operation). By default, Connect:Direct File Agent scans a
watched directory once per minute. For example, if you start Connect:Direct File Agent at 1:00 p.m., a file

Chapter 2. Getting Started Guide 79

 added to that watched directory at 12:55 a.m. is not detected as newly added. If you start Connect:Direct
File Agent at 1:00 p.m., and a file is placed in the watched directory at 1:01 p.m., then Connect:Direct File
Agent detects this newly added file. Connect:Direct File Agent detects a file only one time, unless the file
is accessed and saved with a later timestamp.
Using Connect:Direct File Agent requires an understanding of IBM Connect:Direct Processes, operating
systems, and scripting (for regular expression operator use with Connect:Direct File Agent rules).

Connect:Direct File Agent Operation

You can run Connect:Direct File Agent from a UNIX or command line, configure it to start automatically as
a Microsoft Windows Service at system startup, or configure it to run from a Microsoft Windows shortcut.
Use the command line to verify that Connect:Direct File Agent is working correctly or to specify an
alternate configuration file. After you run Connect:Direct File Agent from the command line to verify that
Connect:Direct File Agent is operating correctly, run it using the method that requires the least user
intervention.
When Connect:Direct File Agent runs as a Microsoft Windows service, it is fully automated, requiring little
user intervention. On UNIX, you can modify the initialization sequence of the computer to call the cdfa.sh
script and run Connect:Direct File Agent whenever you restart the computer. On z/OS, you must run the
appropriate job to start the Connect:Direct File Agent configuration interface, or start or shutdown the
Connect:Direct File Agent.
Depending on your network and how you use IBM Connect:Direct, there might be more than one
Connect:Direct File Agent running (on different hosts). The first Connect:Direct File Agent that connects to
a IBM Connect:Direct server becomes the Connect:Direct File Agent gate keeper. The gate keeper port is
used to keep track of locations monitored in case more than one Connect:Direct File Agent are configured
to watch a single directory. The gate keeper ensures that only one Connect:Direct File Agent detects a file
that appears in a watched directory.

Connect:Direct File Agent Logging Capabilities

Connect:Direct File Agent logging capabilities vary by platform. Running Connect:Direct File Agent from a
command line using the verbose argument turns on Connect:Direct File Agent logging when it is available.
When you run Connect:Direct File Agent as Microsoft Windows service, no information is logged unless an
error occurs.
Connect:Direct File Agent provides the following levels of status information when logging is available on
a platform:
• System log—Shows all system activity. This log is created only when you specify verbose mode or if an
error occurs. If you are running verbose mode from the command line, this log information is shown in
the command line window.
• First Failing Status (FFS) log—One or more logs created when an error occurs.
Using trace commands provided for your platform can also help capture details related to Connect:Direct
File Agent operation.

Connect:Direct File Agent Configuration Interface and Help

Instructions for configuring Connect:Direct File Agent are available in the online Help system that you
access from the configuration interface. Field-level Help is displayed in the bottom pane of the
configuration interface. Clicking Help displays the online configuration procedures.

Planning the Connect:Direct File Agent Configuration

Before you begin configuring Connect:Direct File Agent, you must use IBM Connect:Direct to choose or
create the Processes that perform the actions you want to automate. You will need to carefully configure
Connect:Direct File Agent to connect to the IBM Connect:Direct server and to monitor and detect
conditions (such as a file addition to a directory). At detection, Connect:Direct File Agent submits the
Process for executing actions that need to be performed in response to those conditions.

80 IBM Connect:Direct for UNIX: Documentation

 Refer to Connect:Direct for UNIX Configuration Examples to review some configuration scenarios that can
help you plan your Connect:Direct File Agent configuration. When you configure Connect:Direct File Agent,
it is best to take an incremental approach; that is, first specify the server connection, a default Process,
and the watched directories. Run a test from the command line to ensure that the default Connect:Direct
File Agent configuration is working correctly. After a successful test of the default configuration, you can
run the Connect:Direct File Agent Configuration Interface again to start building and testing any
Connect:Direct File Agent rules that you want to apply, one by one. After you successfully create a default
configuration, you can use the file as the basis for other configuration files.
Use the Connect:Direct File Agent Worksheet to gather the information to configure Connect:Direct File
Agent. Contact your system administrator for the site-specific information to establish a connection to the
IBM Connect:Direct server. As you complete the worksheet, run the Connect:Direct File Agent
Configuration Interface and use the Connect:Direct File Agent Help system to learn about entering
parameters. The Help system provides descriptions of parameters and arguments to specify in the
configuration file. Make copies of this worksheet if you have to configure Connect:Direct File Agent on
multiple IBM Connect:Direct servers.

IBM Connect:Direct Worksheet

Worksheet
Connect:Direct Server Connection Information
Userid for API (for connecting to the IBM
Connect:Direct server) Required
Must match the user ID used to submit the default
Process.

Password for API (for connecting to the IBM

Connect:Direct server) Required
Must match the password used to submit the
default Process.

API host DSN name (name of the host on which the

IBM Connect:Direct server is located) Required
API port (default =1363)1–5 digit port number that
Connect:Direct for UNIX uses to connect to the
IBM Connect:Direct server API. Required
Gatekeeper port (default=65530)Port used to track
directory monitoring and ensure that multiple
Connect:Direct File Agents do not monitor a single
directory. Required
Gate keeper DNS name (optional)
(default=127.0.0.1)
Default Process and Watched Directory Information
Watched directories:
For Microsoft Windows and UNIX, one or more
valid specifications of paths (Microsoft Windows)
or pathnames (UNIX). For z/OS, one or more fully
specified HFS pathnames of a file or directory, or a
full or partial MVS data set name. Required
List one valid entry per line.

Chapter 2. Getting Started Guide 81

 Worksheet
Default Process and Watched Directory
Information
Default Process:
Microsoft Windows and UNIX: Valid path and name
of the file that contains the default Process on the
IBM Connect:Direct server. z/OS: Member Name in
DMPUBLIB
Note: If you do not specify a default Process or
create a rule, no processing is performed when a
file or event is detected.

Default arguments.
Argument string to pass to the default Process in
the following format:
&FA_XXXX_XXX.
The percent sign (&) and period (.) are required.
Error Process:
Error arguments
Process class (default=1) Required
Process priority (default=1)
Watched file interval (default=1 minute)
File completion delay (default=1 minute)

If you are using X Windows, the X11 display variable is used to connect to the GUI server for terminal
emulation. The Connect:Direct File Agent Configuration Interface will display on the monitor specified for
the X11 display variable. If you want to display the Connect:Direct File Agent Configuration Interface on a
Microsoft Windows computer, you must specify the network ID of the terminal you want to use for
displaying the Connect:Direct File Agent Configuration Interface.

Sterling Connect:Direct File Agent Configuration Examples

The following examples illustrate three typical scenarios for using Connect:Direct File Agent. Fields that
are not required for the operation demonstrated in the example are not included in the configuration
parameters. Use the sample scenarios to become familiar with settings for parameters you must set using
the configuration interface in order to accomplish watched directory monitoring and file detection needs.
See the Connect:Direct File Agent Worksheet for a description of the parameters required to establish the
connection. The tables of sample data for these scenarios assume that you have already configured the
site-specific parameters required to establish a connection to the IBM Connect:Direct server where
Connect:Direct File Agent is installed. The sample scenarios also assume that the IBM Connect:Direct
Processes that will perform tasks associated with Connect:Direct File Agent file detection activities have
been created.

Example: Detecting a File Added to a Watched Directory on a z/OS System

Some users need to access a report file that is expected to be transferred to a location that only
administrators can access. Connect:Direct File Agent can be configured to perform the processing on a
z/OS system:
• Monitor the watched data set called EASTERN.Q1.REPTS.

82 IBM Connect:Direct for UNIX: Documentation

• Submit a default Process called DEFPROC. The default Process has been created to copy a file detected
in the watched data set to a specified location for access by users.

Tab Field Sample or Description

File agent Watched Type EASTERN.Q1.REPTS to specify the fully qualified MVS data set
directories name to watch.
Default Process Type DEFPROC, the member name for the Process in DMPUBLIB.
Note: If no default Process is specified and the file does not match a
rule, then no processing occurs.

Example: Detecting a System Event by Title on a Microsoft Windows System

IndexOutOfBoundsException is the title of an event that indicates a number is outside of an expected
range. In the following example, Connect:Direct File Agent is used to detect an event with
IndexOutOfBoundsException in the title, pass a string (the event title) to a IBM Connect:Direct Process,
and then submit a Process to the IBM Connect:Direct server that will perform actions the environment
requires for this type of event. In this scenario, the event IndexOutOfBoundsException could indicate
activity that a network administrator should investigate. Because the site uses a IBM Connect:Direct
mailbox system, the configuration will include the administrator's account to be notified when
Connect:Direct File Agent submits a Process for the IndexOutOfBounds rule.
The sample values in the following table accomplish the following processing:
• Override the default Process and submit \processfolder\oo_boundserrproc.cdp
• Send a message to the administrator's mailbox system account after submitting the
oo_boundserrproc.cdp Process for the rule.

Tab Dialog Box, Window, or Description/Example

Field
Rules Create rule dialog box Type index out of bounds as the name of the rule you are
creating.
Match criteria list for rule Select the default criteria Not enabled: System event title
“index out of bounds” matches “ ” and click Edit match.
window
Edit match criterion for rule • Click Enabled to enable the criteria you are about to specify.
“index out of bounds” dialog
• Click System event title as the criterion to match for the rule.
box
• Click Matches on the drop-down field to see the options for
comparison to a string.
• Click Contains to specify how the compare string should
relate to a system event title that Connect:Direct File Agent
detects.
• Type IndexOutoffBounds as the Compare String to indicate
that the system event title should include this string.
• Click OK.

Submit Process information Type information into the fields that will define the Process to
for system event rule “index submit and the mailbox user to notify after the Process is
out of bounds” window submitted.
Process name field Type c:\processfolder\errproc.cdp to specify the path and file
name for the Process Connect:Direct File Agent submits when
a file meets the rule criteria.

Chapter 2. Getting Started Guide 83

 Tab Dialog Box, Window, or Description/Example
Field
Notification userid field Type [email protected] to specify the user to notify
when Connect:Direct File Agent submits the Process.

Example: Passing the UNIX Pathname for a Detected File to a Process

Because Connect:Direct File Agent can watch multiple directories for the appearance of a new file, the
IBM Connect:Direct Process that Connect:Direct File Agent is to submit to the server at the appearance of
a new file might need to reference the Microsoft Windows Path or UNIX pathname for the detected file as
part of commands and statements in the Process.
In the following example, a UNIX pathname is passed to the default Process, copynewfile.cdp.

Tab Dialog box, Window, Sample Entry

or Field
File agent Watched directories Type one UNIX pathname per line for each location
Connect:Direct File Agent is to watch for the appearance of files:
user/bin/monthend/
quartend/easterndiv/errorfiles
managers/special/reports
Connect:Direct File Agent checks these pathnames for new files.

Default process Type the UNIX pathname and filename for the IBM
Connect:Direct Process that Connect:Direct File Agent is to run
when a file appears in any watched directory specified:
user/bin/admin/copynewfile.cdp
The pathname where Connect:Direct File Agent detected a new
file is passed to this Process.

Default arguments Type the Connect:Direct File Agent variable for passing a UNIX
pathname or Microsoft Windows path, including the leading
percent sign (%) and the ending period (.):
&FAP=%FA_PATH_FOUND.
In this example, &FAP is the variable to which Connect:Direct
File Agent will pass the UNIX pathname where the file was
detected. %FA_PATH_FOUND. is the IBM Connect:Direct File
Agent variable used to indicate the information to pass to the
IBM Connect:Direct Process.

Setting Up Connect:Direct for UNIX Manual Pages

The UNIX operating system organizes all Help into manual (man) pages.
1. For syntax of a UNIX command, type the following where command is the UNIX command:

% man command

Most UNIX systems store online manual pages in /usr/man/man1. IBM Connect:Direct stores its
manual pages in d_dir/ndm/man1,where d_dir is the IBM Connect:Direct installation directory.
2. Type the following command to copy the IBM Connect:Direct manual pages into the UNIX manual
pages directory:

84 IBM Connect:Direct for UNIX: Documentation

 % cp d_dir/ndm/man1/*.1 /usr/man/man1

You must have write privileges to the directory /usr/man/man1 to perform this command.
You can also use symbolic links instead of copying the files. Refer to UNIX manual pages.
3. Type the following command to access IBM Connect:Direct manual pages that you combined with
UNIX manual pages, where command can be cdpmgr, ndmxlt, or ndmmsg:

% man command

Accessing IBM Connect:Direct Manual Pages

To access the IBM Connect:Direct manual pages.

Procedure
Type the following command to access IBM Connect:Direct manual pages on IBM pSeries, or Sun Sparc
running the Solaris operating system, if the system is using the BSD version of the man command
(/usr/ucb/man). The command can be cdpmgr, ndmxlt, or ndmmsg.

% man -M d_dir/ndm command

Virtualization support
IBM cannot maintain all possible combinations of virtualized platforms. However, IBM generally supports
all enterprise class virtualization mechanisms, such as VMware ESX, VMware ESXi, VMware vSphere,
Citrix Xen Hypervisor, KVM (Kernel-based virtual machine), and Microsoft Hyper-V Server.
IBM investigates and troubleshoots a problem until it is determined that the problem is due to
virtualization. The following guidelines apply:
• If a specific issue is happening because the system is virtualized and the problem cannot be reproduced
on the non-virtualized environment, you can demonstrate the issue in a live meeting session. IBM can
also require that further troubleshooting is done jointly on your test environment, as there is not all
types and versions of VM software installed in-house.
• If the issue is not able to be reproduced in-house on a non-virtualized environment, and
troubleshooting together on your environment indicates that the issue is with the VM software itself, you
can open a support ticket with the VM software provider. IBM is happy to meet with the provider and
you to share any information, which would help the provider further troubleshoot the issue on your
behalf.
• If you chose to use virtualization, you must balance the virtualization benefits against its performance
impacts. IBM does not provide advice that regards configuring, administering, or tuning virtualization
platforms.

IBM Control Center Director Support

Control Center Director installs, upgrades and applies maintenance to Connect:Direct through a
Connect:Direct Agent instance.
After you have upgraded Connect:Direct for UNIX, to the required maintenance level complete the
following procedures to ensure Connect:Direct for UNIX servers are discovered dynamically by Control
Center Director.
Control Center Dir uses Certificate-based authentication to authenticate itself to a Connect:Direct® server.
For more information on how to configure Connect:Direct and Control Center Director for Certificate-
Based Authentication see the following sections:
• Enable Certificate-based authentication on Control Center Director

Chapter 2. Getting Started Guide 85

 • Enable Client Authentication on the Connect:Direct Secure Plus
• “Local User Information Record Format” on page 121
Known Restriction
Upgrade on target Connect:Direct nodes via ICC Director Web Console is currently not supported for
Connect:Direct servers running on a 32-bit Solaris system. You must upgrade to Connect:Direct for UNIX
v6.0.0 and above to support the upgrade process.

Configuring Connect:Direct for UNIX for Server and Upgrade Management

About this task

Control Center Director upgrades and applies maintenance to Connect:Direct through a Connect:Direct
Agent instance. Agent is included with the Connect:Direct software when it is at a required level of
maintenance for Agent inclusion.
To successfully move to a Connect:Direct version that supports a Control Center Director deployment,
there are a few scenarios to consider. Review the actions below to optimize your update experience:
• Download the required maintenance version of Connect:Direct software. For more information go to Fix
Central.
• Certificate-based authentication is enabled when you install and configure Connect:Direct Secure Plus
for UNIX.

Procedure
1. Configure the Agent listening port that Control Center Director will use to communicate with the Agent.

agent.port=<port> [Default:1365]

The Agent is now set to automatically listen for incoming connections from Control Center Director.

Attention: With multiple Connect:Direct instances on the same system you’re likely to run into
port conflict issues unless you allocate a unique Agent listening port per instance.
It is also recommended that having upgraded an instance, its unique port number must be
applied before upgrading the next instance. This prevents potential errors that you could
encounter during an upgrade process due to port conflict.
2. Configure the Control Center Director Open Server Architecture (OSA) URL, the target location where
Agent posts all the events to Control Center Director.

osa.rest.url=https;//<ip/hostname;port>/osa/events/post:
[Default:<blank>]

Note: Ensure that you insert a ';' and not a ':' between hostname and port and after https.
3. Set the following property to enable Agent to post all events to Control Center Director .

osa.disable=N

4. Invoke the following script for changes to take effect. This script is available
atcdinstallation_location/install/agent/bin.

startAgent.sh

86 IBM Connect:Direct for UNIX: Documentation

Configuring Connect:Direct for UNIX for License Governance
Set the following parameters (initparms) to automate license metrics collection from Connect:Direct for
UNIX.

Table 4. Initialization Parameters

Parameter (initparm) Possible Values

license.edition • Premium
• Standard
• Solo
• Default: Blank (undefined)

license.type • Production
• Non-Production
• Default: Non-Production

license.pvu A non-negative integer

• The license.pvu parameter is only applicable
for Connect:Direct Premium licenses
• This value can be calculated using the IBM
License Metric Tool (ILMT) or it can be looked up
at the IBM Processor Value Unit licensing
website.
• Default: 0

Note: All three Initparms are required, but can be unset and a user does not have to supply a value.
Solo license edition type constraints:
• A warning message is logged if the number of Netmap entries in netmap.cfg exceeds 2.
• A warning message is logged when a transfer is initiated with third or later remote entry, in order of
appearance.
• The number of concurrent sessions is restricted to 2 or fewer

Configuring Connect:Direct for Unix for New Install Task

You can initiate fresh installation of Connect:Direct servers from Control Center Director. To automate new
installation of Connect:Direct server for UNIX from Control Center Director, set the following parameters
(initparms) in the install.agent record of the initparm.cfg file:

Table 5. Initialization Parameters

Parameter (initparm) Definition Possible Values

agent.enable Use to enable/disable the agent • y (Default)

• n

osa.rest.url Use to connect Connect:Direct • blank (Default)

Agent with Control Center
• URL
Director.

Chapter 2. Getting Started Guide 87

 Table 5. Initialization Parameters (continued)
Parameter (initparm) Definition Possible Values

osa.disable Allows disabling OSA without • blank (Default)

deleting osa.rest.url
• y
• n

agent.installation_id Identifies the Connect:Direct Informational only, managed by

installation package installed by CCD.
Control Center Director

For more information on how to install new Connect: Direct server for UNIX from Control Center Dir , see
Installing new Connect:Direct server for UNIX.

Configuring Connect:Direct for Unix for Custom Locations of Connect:Direct

Backups and Installation Programs
Use the following parameters to set the Connect:Direct, Agent backup and installer locations to be used
before an upgrade.

Table 6. Initialization Parameters

Parameter (initparm) Definition Possible Values
cd.backup Set this parameter in • Any path on the system.
backup.locations initparm
Note: The path should be an
record to specify the location
absolute path, not same as
where backup of Connect:Direct
installation directory. It should
will be stored before an upgrade.
not be a sub directory of
<installation directory> or
agent.backup path.

agent.backup Set this parameter in • Any path on the system.

backup.locations initparm
Note: The path should be an
record to specify the location
absolute path, not same as
where backup of Install Agent
installation directory or
will be stored before an upgrade.
cd.backup path. It should not be
a sub directory of <installation
directory> or cd.backup path.

emergency_restore.installers Set this parameter in • Any path on the system.

backup.locations initparm
Note: The path should be an
record to specify the location
absolute path.
where installer will be stored,
which can be used during
emergency restore.

installer.location Set this parameter in • Any path on the system.

install.agent initparm record
Note: The path should be an
to specify the location of installer
absolute path.
download during upgrade via
Control Center Director.

88 IBM Connect:Direct for UNIX: Documentation

Chapter 3. Administration Guide
Use the Administration Guide to maintain configuration files, initialization parameters, client configuration
files, network map files, access information files, and client and server authentication key files, along with
specifying connection information and using IBM Connect:Direct in test mode.

Password Storage
Connect:Direct for UNIX enables you to use any of the following for password storage:
• /etc/passwd file
• /etc/shadow file when supported by the operating system
• HP-UX trusted security
• Network Information Service (NIS), formerly known as Yellow Pages
• Digital UNIX Enhanced Security
• Pluggable Authentication Modules (PAM)

Maintaining configuration files

Configuration files define the operating environment for IBM Connect:Direct. The following configuration
files are created during the customization procedure:
• Initialization parameters file
• Client configuration parameters file
• Network map file
• Two access files: userfile.cfg and sysacl.cfg
After the initial customization, you can modify these files, if necessary.
A configuration file is a text file composed of records. A record is a single logical line. A logical line is one
or more physical lines that can be continued with the backslash (\) character. In the sample format below,
physical lines 4 and 5 illustrate a logical line. Line 4 ends with a backslash (\) character, to indicate that
the line is continued on the next physical line. Line 1 of the sample begins with a pound (#) sign. The
pound sign indicates this line contains a comment.
A record consists of a record name and one or more parameter pairs. A parameter pair is a parameter
name and parameter value. Line 2 contains the record name, ndm.path. Line 2 also contains the
parameter pair, path and /ndm/users/c, where the parameter name is path and the parameter value
is /ndm/users/c. The parameter pair is bound by colons (:) and separated by an equal sign (=) in the
following format. The following example displays a complete record, where ndm.path is the record
name, path is the parameter name, and /ndm/users/c is the parameter value:

ndm.path:path=/ndm/users/c:

Record names and parameter names are not case sensitive. Parameter values are case sensitive.
Lines 7 through 23 illustrate a longer logical record. Line 7 contains the record name local.node
followed by an optional colon (:) and a backslash (\) character. All lines between 7 and 23 end with a
backslash (\) character. Line 23 does not contain a backslash (\) character, to indicate the end of the
record.

© Copyright IBM Corp. 1993, 2018 89

 Sample format of a configuration file
The following table displays a portion of the initialization parameters file to illustrate the format of IBM
Connect:Direct configuration files:

Line Contents Notes

1 #Miscellaneous Parameters # indicates a comment
2 ndm.path:path=/ndm/users/c: record name=ndm.path,
parameter=path, value= /ndm/
users/c
3 proc.prio:default=8: record name=proc.prio,
parameter=default, value= 8
6 #Local IBM Connect:Direct connection # indicates a comment
information
7 local.node:\ record name=local.node
13 .
... .
21 .
22 :tcp.api=rusty;3191:\ parameter= tcp.api, value=
rusty;3191
23 :tcp.api.bufsize=32768: parameter= tcp.api.bufsize,
value= 32768

Configuration files allow duplicate but not identical records, in some cases. For example, you can define
more than one remote node information (rnode.listen) record in the initialization parameters file.

Modifying configuration files

Before you begin

You can modify IBM Connect:Direct configuration files using any text editor or create a new configuration
file using the cdcust command provided with Connect:Direct for UNIX.
• Modifying configuration files with a text editor—You can modify IBM Connect:Direct configuration files
with any text editor, such as vi editor.
• Creating configuration files with cdcust—Type the following command to start the customization
procedure, where d_dir is the Connect:Direct for UNIX path name:

$ d_dir/etc/cdcust

Maintaining the initialization parameters file

Initialization parameters determine various IBM Connect:Direct settings that control system operation.
The initialization parameters file is created when you install Connect:Direct for UNIX and can be updated
as needed.
You can modify IBM Connect:Direct initialization parameters file using any text editor. Before changing a
value in the file, first shut down the IBM Connect:Direct server. After you change a value and save the file,
restart the server. Restarting the server validates the new values and generates an error message if a
value is invalid.

90 IBM Connect:Direct for UNIX: Documentation

 You can also use the Connect:Direct Browser User Interface to perform some of the procedures related to
the initialization parameters file. To learn more about the Connect:Direct Browser User Interface, see the
documentation related to that product in the IBM Documentation Library. If you use Connect:Direct
Browser User Interface to update parameters in the Local Node Connection Record, you do not have to
stop and restart the server.

Contents of the initialization parameters file

The initialization parameters file resides in d_dir/ndm/cfg/cd_node/initparm.cfg, where d_dir is the
destination directory where Connect:Direct for UNIX is installed and cd_node is the node name.
The initialization parameters file contains records. Each record includes parameters to define the
attributes of the record. The records are summarized as follows:
• Parameters—Provide information including the name of the Connect:Direct for UNIX node; the location
of Connect:Direct for UNIX, the Pluggable Authentication Modules (PAM) service configuration file, and
the shared work area for SNODE work files; the default Process priority; and whether commands with
special characters are restricted in the run directory.
• Remote node connection information—The rnode.listen record includes parameters to monitor inbound
connections.
• Transmission Control Queue (TCQ) information—The tcq record defines how long a Process is held in
error before being deleted.
• Global copy parameters—The copy.parms record defines default parameters used by the Copy
operation including checkpoint parameters, file size limitations, translation table information, exception
handling, CRC checking, file allocation retry parameters, and compression options.
• Global run task parameters—The runtask.parms record defines a parameter to define the restart
option.
• Statistics file information—The stats record includes parameters to define default statistics file
information including file size limitations, the type of information to write to the statistics file, and how
long to maintain statistics files before archiving them.
• Server authentication information—The authentication record parameters to authenticate the server.
• User exit parameters—The user.exits record defines the programs used during a user exit procedure.
• Firewall navigation information—The firewall.parms record defines the ports or range of ports to use for
outbound sessions when a server operates behind a firewall.
• AIX zFBA option—The zFBA parameter enhanced performance of large file transfers between z/OS and
AIX.
• Secure cdpmgr initialization—Used to sanitize inherited environment variables to prevent run task steps
from depending on one or more of the inherited environment variables from working properly.
• fsync.after.receive parameter—The fsync.after.receive parm allows the fsync function to be called when
attempting to flush all data to disk before closing file.

Sample initialization parameters file

The following example shows how some of these parameters are specified:

Chapter 3. Administration Guide 91

 # Miscellaneous Parameters
ndm.path:path=/sci/users/mscarbro/cd4000:\
:snode.work.path=/sci/users/mscarbro/cd4000/shared:

ndm.node:name=mws_joshua_4000:
ndm.pam:service=cdlogin:
ndm.quiesce:quiesce.resume=n:

proc.prio:default=10:
restrict:cmd=y:

# TCQ information
tcq:\
:max.age=8:\
:ckpt.max.age=8:

# Global copy parameters.

copy.parms:\
:ckpt.interval=2M:\
:ulimit=N:\
:xlate.dir=/sci/users/mscarbro/cd4000/ndm/xlate:\
:xlate.send=def_send.xlt:\
:xlate.recv=def_recv.xlt:\
:continue.on.exception=y:

# Global runtask parameters.

runtask.parms:\
:restart=y:

# Stat file info.

stats:\
:file.size=1048576:\
:log.commands=n:\
:log.select=n:

# Authenticator
authentication:\
:server.program=/sci/users/mscarbro/cd4000/ndm/bin/ndmauths:\
:server.keyfile=/sci/users/mscarbro/cd4000/ndm/security/keys.server:

# user exit information

user.exits:\
:security.exit.program=:\
:file.open.exit.program=:\
:stats.exit.program=:

# Remote CDU nodes

rnode.listen:\
:recid=rt.sles96440:\
:comm.info=0.0.0.0;9974:\
:comm.transport=udt33:

# Secure+ parameters
secure+:\
:certificate.directory=/home/nis02/jlyon/certs: \
:s+cmd.enforce.secure.connection=n:

Updating records
You can update various parameters in records that IBM Connect:Direct uses. Required parameters are
displayed in bold.

Path record
The ndm.path record identifies the path to IBM Connect:Direct files. The following table describes the
parameter available for this record:

Parameter Description Value

path The path to all IBM Connect:Direct subdirectories and path specification
files.

92 IBM Connect:Direct for UNIX: Documentation

SNODE work path parameter
The snode.work.path parameter is part of the ndm.path record and identifies the path to the shared
work area for SNODE work files. This path must point to a cluster file system, such as IBM's GPFS, or a
Network File System version 4 (NFSv4) or greater resource. This includes the Amazon Elastic File System
(EFS), as it is mounted via NFSv4 protocol. NFSv3 is not supported. This optional parameter provides a
means to share SNODE work files among nodes in a load balancing environment. SNODE return code files
(steprc files) and copy checkpoint information are created in this area when the snode.work.path
parameter is specified. The following table describes the snode.work.path parameter:

Parameter Description Value

snode.work.path The path to the shared work area for SNODE work files. path specification
Note: Specify the same path for all nodes in a cluster.

Node name record

The ndm.node record identifies the name of the IBM Connect:Direct node. The following table describes
the parameter available for this record:

Parameter Description Value

name The name of the The maximum length is 16 bytes. If a node name is longer,
node. the name will be truncated.

PAM service record

The ndm.pam record identifies the PAM service configuration file used to authenticate the user authority
for IBM Connect:Direct Processes. If the service initialization parameter is defined and if PAM is installed
on the IBM Connect:Direct server, PAM is used to authenticate users for service-providing application.
The service name required is typically defined in the /etc/pam.conf file for AIX, Solaris and HP
operating systems, or defined and named by a file in the /etc/pam.d directory for Linux operating
systems. Your system might also have a man page for PAM that provides further details.
The following table describes the parameter available for this record:

Parameter Description Value

service PAM service configuration file name. File name

Quiesce/resume record
The ndm.quiesce record specifies whether IBM Connect:Direct is operating in a “test” mode. Use this
record in conjunction with the NDMPXTBL table to enable the test mode. If you enable the
quiesce.resume parameter, you must have an NDMPXTBL parameter table updated for your environment
in the installation ndm/cfg/<nodename> directory. For more information on the test mode and the
NDMPXTBL table, see Processing Flow of the Test Mode.
The following table describes the parameter available for this record:

Parameter Description Value

quiesce.resume Enables/disables the test mode for IBM y|n
Connect:Direct.
y—Enables the test mode.
n—Disables the test mode. The
default is n.

Chapter 3. Administration Guide 93

 Priority record
The proc.prio record identifies the default value of the Process priority. The following table describes the
parameter available for this record:

Parameter Description Value

default The default value of the Process priority. 1–15. The default value is 10.
15 is the highest priority.

Restrict record
If a run directory restriction is defined in the user configuration file (userfile.cfg), the restrict record
determines if commands containing certain special characters are allowed. For more information on the
userfile.cfg file, see Local User Information Record Format and Remote User Information Record. The
following parameter is available for this record:

Parameter Description Values

cmd Determines if commands with certain y|n
special characters are allowed.
y—Restricts the ability to use commands
with any of the following special characters:
;&‘|
n—Does not restrict allowed commands.

Remote node connection record

The rnode.listen record contains parameters used by the local node to monitor inbound connection
requests. You can modify the IP address and port number in the rnode.listen record while the server is
running. However, you must recycle the server before the change is active. The following table describes
the remote node connection parameters:

Parameter Description Values

recid A unique identifier of an rnode.listen record. A text string

94 IBM Connect:Direct for UNIX: Documentation

Parameter Description Values
comm.info The information needed to monitor connection requests For TCP/IP connections,
from remote nodes using TCP/IP or LU6.2. This specify the host name or the
parameter is required. IP address and port number:
• For TCP/IP connections, specify the host name or the 10.23.107.5;1364
IP address and port number. If specifying an IP
Separate multiple IP/host
address and port, separate parameters with a
addresses with a comma (,):
semicolon (;). Separate multiple addresses/host
names with a comma, for example: fe00:0:0:2014::7;1364,
10.23.107.5;1364, fe00:0:0:2014::7;1364, msdallas- msdallas-dt;1364
dt;1364
A space can be added after the
For more information on specifying IP addresses and comma for readability.
host names, see IP Addresses, Host Names, and
Set the IP address to monitor
Ports.
a specific adapter or to
0.0.0.0, to monitor all
adapters.
The default port is 1364.
For LU6.2 connections, specify
a profile name, up to 8
characters.

comm.transport The transport protocol for the remote node. tcp | lu62 | blklu62
tcp—For TCP/IP connections
blklu62—For other LU6.2
connections

Transmission Control Queue record

The tcq record provides information that pertains to the Transmission Control Queue (TCQ). The following
parameters are available for this record:

Parameter Description Value

max.age The maximum number of days a A three-digit decimal number. IBM
Process with Held-in-Error status Connect:Direct does not automatically
remains in the TCQ before it is delete Processes when max.age=0.
automatically deleted.
The default is 8 days.

ckpt.max.age The maximum number of days a An integer in the range 0 - 2147483647,

Process' checkpoint file is stored inclusive. IBM Connect:Direct does not
unused before it is automatically automatically delete the checkpoint file
deleted. when ckpt.max.age=0.
The default is 8 days after a fresh
installation. If ckpt.max.age is left unset, it
defaults to 2147483647.

Connect:Direct Secure Plus record

The Connect:Direct Secure Plus record (Secure+ record) provides information pertaining to remote
configuration of Connect:Direct Secure Plus from the IBM Connect:Direct client API. This record is not
included in the initparm.cfg file by default. You must manually add the Secure+ record to the initparm.cfg
file. The following parameters are available for this record:

Chapter 3. Administration Guide 95

Parameter Description Value
certificate.directory Specifies a default certificate directory for Secure+ Directory path name
commands issued from the IBM Connect:Direct client
API. If the certificate directory is not configured, the
default directory created during installation is used.
s+cmd.enforce.secure. Specifies whether Secure+ commands are accepted y|n
connection from the IBM Connect:Direct client API on unsecure
y—Commands from
connections.
unsecure connections are
not accepted. The default
is y.
n—Commands from
unsecure connections are
accepted

Global Copy record

The Global Copy record called copy.parms provides default information for the IBM Connect:Direct copy
operation. The ecz parameters are only used when extended compression is defined in a Process. The
following parameters are available for this record:

Record Description Value

ckpt.interval The default number of bytes transmitted in a copy The maximum possible value is
operation before a checkpoint is taken. Following 1 terabyte (TB). The normal
is a list of the maximum number of digits for each value is 64KB.
byte interval:
no—No checkpointing
nnnnnnnn—Up to an 8-digit decimal
nnnnnnnnK—Up to an 8-digit decimal, where K
denotes 1024 bytes
nnnnnnnnM—Up to an 7-digit decimal, where M
denotes 1048576 bytes
nnnnG—Up to an 4-digit decimal, where G denotes
1073741824 bytes

ulimit The action taken when the limit on a user output n—Ignores the limit. n is the
file size is exceeded during a copy operation. default value.
y—Recognizes the user file size
limit. If this limit is exceeded
during a copy operation, the
operation fails.

xlate.dir The name of the directory containing the Any valid directory.
translation tables.
The default path is d_dir/ndm/
xlate.

xlate.send The default translation table used when sending Any valid directory.
data to a remote node.
The default file name is
def_send.xlt.

96 IBM Connect:Direct for UNIX: Documentation

Record Description Value
xlate.recv The name of the default translation table used The default file name is
when copying data from a remote node. def_recv.xlt in the directory
defined in the xlate.dir
parameter.
continue.on.exception The method to use to handle an exception y—Continues Processing with
condition in a Process. If a step fails due to a STOP the next step.
IMMEDIATE or FLUSH exception issued on the
n—Places a Process in the Hold
remote node, the Process is placed in the Hold HE
queue with a value of HE.
queue, regardless of the value of this parameter.
The default is n.

ecz.compression.level Sets the compression level. 1–9. The default is 1.

1—The fastest but offers the
least degree of compression.
9—Provides the greatest degree
of compression but is the
slowest.

ecz.memory.level How much virtual memory to allocate to 1–9. The default is 4.

maintaining the internal compression state.
1—Uses the least memory and 9
uses the most memory.

ecz.windowsize The size of the compression window and history Valid values are 9–15. The
buffer. The larger the window, the greater the default is 13.
compression. However, increasing the window
uses more virtual memory.

Chapter 3. Administration Guide 97

Record Description Value
retry.codes The codes to recognize as a file allocation retry Any valid error code
attempt. File allocation retry enables a Process
with a file allocation or open error on either the
local or remote node to run the Process again,
beginning at the copy step where the error
occurred. This feature supports the ability to retry
a Process that failed when a file is already in use.
When a file allocation or open error occurs on
either the local or remote node, the PNODE
searches for the error or message ID in the
retry.codes and retry.msgids parameters. If the
error code or message ID is found, the Process is
retried.
Since error codes can vary from one operating
system to another and the same error code can
have different meanings, use message IDs to
identify retry conditions when communicating
between two different platforms.
You can perform retry attempts based on codes
only, IDs only, or a combination of the two.
When a retry condition is detected, the session is
terminated cleanly and the Process is placed in
the Timer queue.
Note: If you are using the file allocation retry
function when communicating with a remote node
on an operating system that is not UNIX, identify
operating system retry codes using formats and
code values defined by the remote node.

retry.msgids Identifies the message IDs to use to support a file Any of the valid file allocation
allocation retry attempt. retry messages.
Since error codes can vary from one operating
system to another and the same error code can
have different meanings, use message IDs to
identify retry conditions when communicating
between two different platforms.
When a file allocation or open error occurs on
either the local or remote node, the PNODE
searches for the message ID in the retry.msgids
parameters. If the message ID is found, the
Process is retried.
You can perform retry attempts based on codes
only, message IDs only, or a combination of the
two.
When a retry condition is detected, the session is
terminated cleanly and the Process is placed in
the Timer queue.

98 IBM Connect:Direct for UNIX: Documentation

Record Description Value
tcp.crc Globally turn on or off the CRC function for TCP/IP y|n
Processes.
y—Turns on the CRC function
globally.
n—Turns off the CRC function
globally. The default is n.

tcp.crc.override Determines whether netmap remote node and y|n

Process statement overrides for CRC checking are
y—Allows netmap remote node
allowed. If this value is set to n, setting overrides
and Process statement
for CRC checking will be ignored.
overrides for CRC checking.
n—Prevents netmap remote
node and Process statement
overrides for CRC checking. The
default is n.

strip.blanks Determines whether trailing blank characters are y | n | i

stripped from the end of a record. If strip.blanks is
y—Strips blanks from the end of
not defined in the initialization parameter, the
a record
default value of i is used.
n—Does not strip blanks from
the end of a record
i—Setting for strip.blanks is
determined by the default value
of the remote node type as
follows:
• z/OS, VM, and i5OS—y
• All other platforms—n

insert.newline Arbitrarily appends an LF character at the end of y|n

each record when receiving a datatype=text file.
y—Arbitrarily appends an LF
By default, an LF character is not appended if one
character
already exists at the end of a record.
n—Appends an LF character if
needed

recv.file.open.perm recv.file.open.perm=nnn, where nnn is an Octal Integer

octal integer describing the desired default
permissions for new files received.
It is the same as the value documented for the
copy sysopt permiss.

Chapter 3. Administration Guide 99

Record Description Value
recv.file.open.ovrd recv.file.open.ovrd=x, where x is one of the y|n|p
following three values:
• Y: Allow copy step sysopt permiss value to
override recv.file.open.perm value when
receiving a new file. This is the default.
• N: Disallow copy step sysopt permiss value to
override recv.file.open.perm value when
receiving a new file.
• P: Allow copy step sysopt permiss value to
override recv.file.open.perm value when
pnode is receiving a new file.

fsync.after.receive Files received and closed by C:D to an NFS [y|n]. Default is y.

destination may not be immediately ready for
processing due to NFS cached writes. This
parameter optionally calls fsync function to
attempt to flush all data to disk before closing the
file.

Global Run Task record

The Global Run Task record called runtask.parms is used if the pnode and snode cannot resynchronize
during a restart. If a Process is interrupted when a run task on an SNODE step is executing, IBM
Connect:Direct attempts to synchronize the previous run task step on the SNODE with the current run task
step. If synchronization fails, IBM Connect:Direct reads the restart parameter to determine whether to
perform the run task step again. The following parameter is available for this record:

Parameter Description Value

restart If processing is interrupted when a run task y|n
on an SNODE step is executing and if
y—The run task program runs again.
synchronization fails after a restart, IBM
The default is y.
Connect:Direct reads the restart parameter
to determine whether to perform the run task n—The Process skips the run task
step again. Set this parameter in the step.
initialization parameters file of the SNODE.
Note: When a load balancing cluster is used
and the snode.work.path is specified, the
restart parameter takes effect only when
resynchronization fails.

100 IBM Connect:Direct for UNIX: Documentation

Statistics file information record
The statistics file information record called stats defines the statistics facility. The following parameters
are available for this record:

Parameter Description Value

file.size The maximum size in bytes of an individual nnnnnnnn, nnnnnnnnK,
statistics data file. The statistics file name is nnnnnnnM, or nnnnG—
written in the format of Syyyymmdd.ext, where Establishes a default
yyyy indicates year, mm indicates month, and dd output file size limit for the
indicates day. The extension (ext) begins as 001. statistics files. K denotes
When a statistics file reaches the defined size 1024 bytes. M denotes
within a 24-hour period, a new file is created with 1048576 bytes. G denotes
the same file name. The extension value is 1073741824 bytes. The
incremented by one. maximum value you can
specify is 1 TB.
log.commands Determines whether commands are written to the y|n
statistics file. If you want to log all commands
y—Commands are written
except the select statistics and select process
to the statistics file.
commands, set this parameter to y and the
log.select parameter to n. n—Commands are not
written to the statistics file.
The default is n.

log.select Specifies whether IBM Connect:Direct creates a y|n

statistics record when a select process or select
y—A statistics record is
statistics command is executed.
created.
n—A statistics record is not
created. The default is n.

max.age Specifies how old a statistics file must be before it A 3-digit decimal number.
is archived. Once a day, a shell script is executed The default is 8 days.
that identifies the statistics files that are as old as
0—no archiving.
the max.age, runs the tar command and the
compress command to create a compressed
archive, and then deletes the statistics files that
have been archived.

Running a Process generates multiple statistics records. To accommodate the large number of statistics
records generated, IBM Connect:Direct closes the current statistics file and creates a new statistics file at
midnight every day. It can also close the current file before midnight if the file size exceeds the value set
for the file.size initialization parameter. The default file size is 1 megabyte.
Statistics files are stored in the d_dir/work/cd_node directory. Names of the statistics files are in the
format Syyyymmdd.ext, where yyyy indicates year, mm indicates month, and dd indicates day. The
extension (ext) begins as 001. The extension is incremented by one each time a new statistics file is
created in a single day.
Connect:Direct for UNIX provides a utility to archive and purge statistics files. You identify when to archive
a statistics file by setting the parameter, max.age. The max.age parameter defines how old a statistics
file must be before you want to archive the file. Once a day, the script called statarch.sh is started. This
script identifies the statistics files that are greater than or equal to the max.age. It then runs the tar
command and the compress command to create a compressed archived file of all the statistics records
that match the max.age parameter. Once the statistics files are archived, these files are purged.
The archived files are stored in the directory where the statistics files and TCQ are stored. The shell script,
statarch.sh, is located in the ndm/bin directory. If necessary, modify the script to customize it for your
environment.

Chapter 3. Administration Guide 101

 If you want to restore statistics files that have been archived, run the statrestore.sh script. It uses the tar
command to restore all the statistics files in the archive. Once files are restored, the statistics records can
be viewed using the select statistics command.

Server authentication record

The server authentication record called authentication is used during the authentication procedure. The
following parameters are available for this record:

Parameter Description Value

server.program The name and location of the server program used The default is
during the authentication procedure. ndmauths.
server.keyfile The name and location of the key file used during the The default is
authentication procedure. keys.server.

User exit record

The user exit record called user.exits provides interfaces to specified programs. The available user exits
include Statistics Exit, File Open Exit, and Security Exit. The following parameters are available for this
record:

Parameter Description Value

stats.exit.program The gateway control program used during the Name of the gateway control
user exit procedure. This exit is given control for program.
each statistics record that is written.
file.open.exit.program The file open exit program used during the user Name of the file open exit
exit procedure. It enables you to control file program.
names on both the sending and receiving node.
The exit is located so that it takes control on the
receiving (remote) node before the file is
opened.
This exit applies only to the copy statement and
provides access to all file control parameters
(including the data set name file name, sysopt
parameters, and disposition).

security.exit.program The security exit program used during the user Name of the security exit
exit procedure. This exit generates and verifies program.
passtickets, and it also supports other password
support programs, such as PASSTICKET, part of
the RACF security system available on MVS hosts
and also supported by IBM on UNIX AIX and
OS/2 computers using the NETSP product.

102 IBM Connect:Direct for UNIX: Documentation

Parameter Description Value
security.exit.flag Modifies the default behavior of snode_sec_exit_only |
security.exit.program. This is an optional sec_exit_only
parameter.
snode_sec_exit_only— Causes
IBM Connect:Direct to use the
security exit, when it is acting in
the role of the SNODE. After IBM
Connect:Direct receives a valid
message, it evaluates the proxy
and the secure point-of-entry to
establish the local user. The
security exit is not used when
IBM Connect:Direct is the
PNODE.
sec_exit_only—Causes IBM
Connect:Direct to always use the
security exit. After IBM
Connect:Direct receives a valid
message, it evaluates the proxy
and the secure point-of-entry to
establish the local user.

zFBA for large file transfer

The zFBA parameter has functionality that provides enhanced performance of large file transfers between
z/OS and AIX; CPU utilization on the z/OS node is greatly reduced and the data throughput is increased by
utilizing parallel data paths to the device both from z/OS as well as the AIX system.
The parameter is as follows:

# zFBA parameter
zFBA:\
:on=y:

Note: When zFBA is set to on, CRC checking is disabled for sessions using the DS8K device for data
transfers. If Secure+ is configured between two nodes, the transfers will use the standard TCP/IP protocol
and ignore the zFBA option.

Secure cdpmgr initialization procedure

Secure cdpmgr initialization is used to sanitize inherited environment variables to prevent run task steps
from depending on one or more of the inherited environment variables from working properly.

Parameter Description Value

ndm.env_vars:sanitize Implementing standard safe initialization [y|n]. Default is y.
procedures, cdpmgr sanitizes environment
variables inherited from the user that starts it.
This sanitization procedure may prevent some
run task steps from working properly if the tasks
were designed to rely on these inherited
variables. While IBM recommends designing run
tasks so that they don't rely on inherited
environment variables, this parameter provides
the option to prevent cdpmgr from sanitizing
inherited environment variables.

Chapter 3. Administration Guide 103

 License record
The license record identifies Connect:Direct license metrics. Following table lists the parameters and
their possible values:

Parameter Possible Values

license.edition • Premium
• Standard
• Solo
• Default: Blank (undefined)

license.type • Production
• Non-Production
• Default: Non-Production

license.pvu A non-negative integer

• The license.pvu parameter is only applicable
for Connect:Direct Premium licenses
• This value can be calculated using the IBM
License Metric Tool (ILMT) or it can be looked up
at the IBM Processor Value Unit licensing
website.
• Default: 0

install.agent record
The install.agent record contains IBM Sterling Connect:Direct parameters to control the Connect:Direct
Install Agent, used by Control Center Director to manage applying upgrades and maintenance.

Parameter Description Value

agent.port Configures the Agent Port number
listening port that
Control Center Default Value: 1365
Director will use to
communicate with
the Agent.
osa.rest.url Configures the Valid URL
Control Center
Example:
Director Open Server
Architecture (OSA) osa.rest.url=https;//<ip/hostname;port>/osa/events/
URL, the target post:
[Default:<blank>]
location where Agent
posts all the events to
Note: Ensure that you insert a ';' and not a ':' between
Control Center
hostname and port and after https.
Director.

Default Value: blank

osa.disable Allows disabling OSA Y|N
without deleting
osa.rest.url.

104 IBM Connect:Direct for UNIX: Documentation

 agent.enable Specifies whether the Y | N
agent is enabled to
run, or disabled and
will be stopped.
agent.installation Identifies the Informational only, managed by CCD.
Connect:Direct
installation package
installed by Control
Center Director.
installer.location Specifies the location Valid path on system
of installer download
Note: The path should be an absolute path.
during upgrade via
Control Center
Director.

Firewall navigation record TEST

The firewall navigation record, called firewall.parms, enables you to assign a specific TCP/IP source port
number or a range of port numbers with a particular TCP/IP address for outbound IBM Connect:Direct
sessions. These ports also need to be open on the firewall of the trading partner to allow the inbound IBM
Connect:Direct sessions. This feature enables controlled access to an IBM Connect:Direct server if it is
behind a packet-filtering firewall without compromising security policies.
Before you configure firewalls, review all information regarding firewall navigation and rules beginning
with Firewall Navigation.
The following parameters are available for this record:

Parameter Description Value

For TCP/IP connections, remote IP Valid IP address with an optional mask for
addresses and the ports permitted for the the upper boundary of the IP address
tcp.src.ports
addresses when using a packet-filtering range and the associated outgoing port
firewall. This parameter is required only if number or range of port numbers for the
the local node acts as a PNODE. specified IP address, for example:
Place all values for an address inside (199.2.4.*, 1000), (fd00:0:0:2015:*::*,
parentheses and separate each value for 2000-3000), (199.2.4.0/255.255.255.0,
an address with a comma. 4000-5000),(fd00:0:0:2015::0/48, 6000,
7000)
A wildcard character (*) is supported to
define an IP address pattern. If the
wildcard character is used, the optional
mask is not valid.
For more information on specifying IP
addresses and host names, see IP
Addresses, Host Names, and Ports.

The number of times that IBM Any numeric value from 1–255. The default
Connect:Direct scans the list of available value is 2.
tcp.src.ports.list. ports to attempt a connection before going
iterations into a retry state.

Maintaining the client configuration file

The client configuration file consists of parameter records that interface with End User Applications (EUA).
The client file includes the following parameters:

Chapter 3. Administration Guide 105

 • IBM Connect:Direct API configuration parameters
• IBM Connect:Direct CLI configuration parameters
• Client authentication parameters
You can modify IBM Connect:Direct configuration files using any text editor. If you want to create a new
configuration file, use the cdcust command.

Contents of the client configuration file

The client configuration file is created during the customization procedure and resides in d_dir/ndm/cfg/
cliapi/ndmapi.cfg, where d_dir is the directory where IBM Connect:Direct is installed.

Sample client configuration file

The following example shows a sample client configuration file:

# Connect:Direct for UNIX Client configuration file

cli.parms:\
:script.dir=/home/qatest/jsmith/cdunix/hp/ndm/bin/:\
:prompt.string=”Test CD on Medea”:

api.parms:\
:tcp.hostname=alicia:\
:tcp.port=1393:\
:wait.time=50:

# Authenticator
authentication:\
:client.program=/home/qatest/jsmith/cdunix/hp/ndm/bin/ndmauthc:\
:client.keyfile=/home/qatest/jsmith/cdunix/hp/ndm/sc/keys.client:

API configuration record

The IBM Connect:Direct API Configuration record, api.parms, is used by the API to communicate. The
parameters for the API configuration record are described in the following table:

Parameter Description Value

tcp.hostname The host name or IP address to Host name or IP address.
which the API usually connects.
For more information on specifying IP addresses
and host names, see IP Addresses, Host Names,
and Ports.

tcp.port The TCP/IP port number to which Port number. The default is 1363.
the API usually connects.
wait.time The number of seconds to wait for Seconds to wait. The default is 50 seconds.
responses from the server. If this
limit is exceeded, the message ID
XCMG000I is displayed.

CLI configuration record

The CLI configuration record, cli.parms, identifies the location of the script files to format the output of the
select statistics and select process commands and allows you to customize the CLI prompt. If you
customize the script to format the output of the select statistics and select process command, update
the script.dir parameter to identify the location of the scripts. If you want to display a customized prompt
at the CLI command line, in place of the default “Direct” prompt, identify the prompt to use in the
prompt.string parameter. The cli.parms parameters are described in the following table:

106 IBM Connect:Direct for UNIX: Documentation

 Parameter Description Value
script.dir The directory where customized script files are stored. Specify Directory name.
this parameter if you have created a custom script to format
The default
the output of the select statistics and select process
commands. The file names must be ndmstat and ndmproc. directory is
ndm/bin/.

prompt.string Identifies the CLI prompt to display on the command line when Prompt string up to
the client is started. 32 characters. The
default is “Direct”.
If the prompt string includes spaces or special characters,
enclose it in single or double quotation marks.
You can set the customized prompt in this parameter and at the
command line (using the -P parameter). If the prompt string is
specified in both places, the -P parameter at the command line
takes precedence.
When the default prompt is overridden, the new prompt string
is displayed in the Welcome banner and at the command
prompt.

Client authentication record

The client authentication record, authentication, is used during the authentication procedure. The client
authentication parameters are described in the following table:

Parameter Description Value

client.program The client program to use during authentication. Client program name.
The default is ndmauthc.

client.keyfile The key file to use during authentication. Client key file. The default is
keys.client.

Maintaining the network map file

The network map file is created when you install IBM Connect:Direct. If necessary, use a text editor to
add or modify remote node records in the network map file. You can modify the network map file
dynamically while the server is running.
You can also use the Connect:Direct Browser User Interface to perform some of the procedures related to
the initialization parameters file. To learn more about the Connect:Direct Browser User Interface, see the
documentation related to that product in the IBM Documentation Library.

Contents of the network map file

The network map contains connectivity information that describes the local node and the remote nodes in
the network. One remote node information record is created for each node with which the local node
communicates.
The network map file resides in d_dir/ndm/cfg/cd_node/netmap.cfg where d_dir is the location where
IBM Connect:Direct is installed and cd_node is the node name.
If you are using TCP/IP, the local node can communicate with a remote node without a remote node
information record. Specify the required connection information in the submit command or the Process
statement.

Chapter 3. Administration Guide 107

 Sample remote node records in a network map
The following sample shows network map remote node entries for a TCP/IP connection and a Sun LU6.2
connection to remote nodes. To insert comments about fields in the network map, be sure to place a # in
the first column. If the # is not in the first column, the comment is not ignored and the field is read.

# Sample Network Map remote node entry for a TCP/IP connection

remote.customer.node:\
:conn.retry.stwait=00.00.30:\
:conn.retry.stattempts=3:\
:conn.retry.ltwait=00.10.00:\
:conn.retry.ltattempts=6:\
:tcp.max.time.to.wait=180;\
:runstep.max.time.to.wait=0:\
:contact.name=:\
:contact.phone=:\
:descrip=:\
:sess.total=255:\
:sess.pnode.max=255:\
:sess.snode.max=255:\
:sess.default=1:\
:comm.info=10.20.246.49;9974:\
:comm.transport=tcp:\
:comm.bufsize=65536:\
:pacing.send.delay=0:\
:pacing.send.count=0:
# Sample Network Map remote node entry for a Sun LU6.2 connection
# hostl1 is the profile name
MVS.SAM1.NODE:\
:conn.retry.stwait=00.00.30:\
:conn.retry.stattempts=3:\
:conn.retry.ltwait=00.10.00:\
:conn.retry.ltattempts=6:\
:contact.name=:\
:contact.phone=:\
:descrip=:\
:sess.total=255:\
:sess.pnode.max=128:\
:sess.snode.max=127:\
:sess.default=1:\
:comm.info=hostl1:\
:comm.transport=blklu62:\
:comm.bufsize=65536:

Local node connection record

The local.node record serves two separate purposes:
• Configures settings for the local node
• Provides default configuration values that can be overridden in the remote node entries.
Two sets of connection retry parameters are created:
• Short-term parameters define retry attempts in the event of a short-term connection failure.
• Long-term parameters are used after exhausting short-term attempts. Long-term attempts are set for
less frequent retries, because long-term attempts assume that the connection problem cannot be fixed
quickly.
Following are the local.node parameters. The parameters in bold are required.

108 IBM Connect:Direct for UNIX: Documentation

Parameter Description Value
api.max.connects The maximum number of concurrent API 1–256
connections permitted for the local node.
The default is 16.
The value of api.max.connects and
sess.total cannot exceed the number
of file descriptors available. This value is
system dependent.
A Command Manager (CMGR) is created for
every API connection that is successfully
established. The number of Command
Managers that a PMGR can create is
system-dependent and limited by the
number of file descriptors available for
each UNIX Process. The number of file
descriptors set up by the UNIX operating
system may affect Connect:Direct
operation.

comm.bufsize The buffer size for transmitting data to and The value for TCP/IP has no limit (up to
from a remote node for TCP/IP 2,147,483,623).
connections.
For LU6.2, the maximum is 32000.
The default is 65536 bytes.

conn.retry.stwait The time to wait between retries The maximum value is limited to the
immediately after a connection failure highest value in the clock format,
occurs. The format is hh.mm.ss, where hh 23.59.59. The default is 00.00.30,
specifies hours, mm specifies minutes, and which is 30 seconds.
ss specifies seconds.
conn.retry.stattempt The number of times to attempt connection 0–9999
s after a connection failure occurs.
The default is 6.

conn.retry.ltwait The time to wait between long-term retry 00.00.00–23.59.59

attempts after all short-term retry attempts
The default is 00.10.00, or 10 minutes.
are used. The format is hh.mm.ss, where
hh specifies hours, mm specifies minutes,
and ss specifies seconds.
conn.retry.ltattempt The number of times to attempt a 0–9999
s connection after all short-term retry
The default is 6.
attempts are used.
Action to take after the specified short and hold | delete
conn.retry.exhaust.
long-term retries have been used.
action hold—Places Processes in the hold queue
in “Held in Error” status, after all retry
attempts are used. This is the default
value.
delete—Causes the Processes to be
deleted from the TCQ.

contact.name The name of the Connect:Direct Name

administrator or operator.
contact.phone The phone number of the Connect:Direct Phone number
administrator or operator.

Chapter 3. Administration Guide 109

Parameter Description Value
descrip Comments to include as part of the record. An unlimited text string
netmap.check Enhanced security testing performed on y|n
the SNODE. For TCP/IP connections, the
y—Specifies that the security checks are
remote IP address of the incoming socket
made to verify that the remote node name
connection is compared to the comm.info
is in the netmap.cfg file. Also, checks the
record of the netmap.cfg file. These values
network map for all nodes that
must match for an Connect:Direct session
Connect:Direct will communicate with to
to be established. The comm.info record
validate the node name and the IP address.
can be the official network name, an alias
name listed in the appropriate file (for l—Checks the network map only for nodes
example, /etc/hosts, if the system is not that the local Connect:Direct will initiate
running NIS or DNS), or the IP address. For sessions with.
all connections, the remote node name
r—Checks the network map only for
must be in the netmap.cfg.
remote nodes that will communicate with
this node.
n—Will not validate any session
establishment requests in the network
map.
The default value is n.

outgoing.address If running in a high availability nnn.nnn.nnn.nnn (IPv4) or

environment, this parameter enables you nnnn:nnnn:nnnn:nnnn:nnnn:nnnn:nnnn:nn
to specify the virtual IP address for the nn (IPv6)
remote node to use for network map
For more information on specifying IP
checking and prevents the Process from
addresses and host names, see IP
failing when initiated from within a high
Addresses, Host Names, and Ports.
availability environment. Specify the IP
address for this value and network map
checking verifies the address instead of the
value set in comm.info in the SNODE
network map record.
pacing.send.delay The time to wait between send operations The format is nnn.
to the remote node. The decimal number is
No limit exists for the size of this value.
the number of milliseconds between the
end of one packet and the beginning of the The default is 0, which indicates no pacing
next packet. Time-based pacing does not of this type.
contribute to network traffic.
The value for this parameter has no effect
on LU6.2 connections.

pacing.send.count The number of send operations to perform No limit exists for the size of this value.
before automatically waiting for a pacing
The default is 0, which indicates no pacing
response from the remote node. The value
of this type.
for this parameter has no effect on LU6.2
connections.

110 IBM Connect:Direct for UNIX: Documentation

Parameter Description Value
proxy.attempt Enables the ID subparameter of snodeid y|n
to contain a proxy, or dummy user ID to be
y—Specifies that the remote users can
used for translation to a local user ID on
specify a dummy user ID in snodeid
the remote system. Using a dummy user ID
parameter.
improves security because neither the local
system nor the remote system requires a n—Specifies that the remote users cannot
valid user ID from the other side. specify dummy user ID in snodeid
parameter.
The default is n.

The following code illustrates the logic

used to perform a security check for the
user ID:

if (snodeid is coded with ID and PSWD)

attempt OS validation
if (OS validation succeeds)
security OK
else if (proxy.attempt=yes)
if (ID@PNODE proxy found)
security OK
else
security check fails
else
security check fails
else if (snodeid is coded with ID only)
if (proxy.attempt=yes)
if (ID@PNODE proxy found)
security OK
else
security check fails
else
security check fails
else if (snodeid is not coded)
if (submitter&;PNODE proxy found)
security OK
else
security check fails

The information is needed to monitor The format is nnnn.

connection requests from the CLI using
rpc.pmgr.port Where nnnn is a decimal number between
TCP/IP. This port identifies the
1024 and 65535.
communication port for the PMGR RPC
server which uses the TLI/XTI interface to The default value is 1367.
communicate with CLI. This parameter is
only applicable for HPUXIT and SOLARIS
platforms. It is a mandatory parameter for
HPUXIT and SOLARIS-based deployments.

Note: The Connect:Direct server must be

restarted for changes in parameter value to
come into effect.

Chapter 3. Administration Guide 111

Parameter Description Value
The maximum time to wait for remote run 0–10000
steps to complete. Remote run steps
runstep.max.time.to include remote run task, run job, or submit The value is in seconds.
. statements. This wait time is different from The default value is 0.
wait the wait time specified by the
tcp.max.time.to.wait parameter.
Using runstep.max.time.to.wait
prevents a Process from failing when a
remote step takes longer to complete than
specified in tcp.max.time.to.wait.
sess.total The maximum number of concurrent 0–999
connections between all nodes and the
A 1–3 digit number.
local node.
The default is 255.
The sum of api.max.connects and
sess.total cannot exceed the number of
file descriptors available. This value is
system dependent.
You must define enough file descriptors to
handle the number of concurrent
Connect:Direct sessions allowed, which
can be as many as 999.

sess.pnode.max The maximum concurrent connections, 0–999

where the local node is the initiator of the
The default is 255.
session. Number of PNODE sessions
cannot exceed the total number of
sessions.
If sess.pnode.max is larger than
sess.total, the value of
sess.pnode.max is silently rounded
down to the value of sess.total.

sess.snode.max The maximum concurrent connections, 0–999

where the local node is the secondary node
The default is 255.
in a session.
Number of SNODE sessions cannot exceed
the total number of sessions. If
sess.snode.max is larger than
sess.total, then it is silently changed to
the value of sess.total.

sess.default The default session class for starting 1–50

session managers. A Process executes on
The default is 1.
the specified class or any higher session
class.
tcp.api.bufsize The buffer size for transmitting data to and This value has no limit. The default is
from an Connect:Direct CLI/API. 32768 bytes.

112 IBM Connect:Direct for UNIX: Documentation

Parameter Description Value
tcp.api The information needed to monitor host name/IP address;nnnn
connection requests from the CLI or API
host name—is the name of the
using TCP/IP. The host is the host name or
Connect:Direct host computer.
IP address where Connect:Direct is
running. The port identifies the IP address—is the IP address of a machine
communications port for Connect:Direct. running Connect:Direct:
Multiple host name/IP addresses and port
nnn.nnn.nnn.nnn (IPv4) or
combinations can be specified when they
nnnn:nnnn:nnnn:nnnn:nnnn:nnnn:nnnn:nn
are separated by a comma. This parameter
nn (IPv6)
is required.
port—identifies the communications port
for Connect:Direct. The format is nnnn,
where nnnn is a decimal number. A semi-
colon separates the host name/IP address
from the port:
msdallas-dt;1363
You can specify multiple address/host
name and port combinations (separated
with a comma):
10.23.107.5;1363,
fe00:0:0:2014::7;1363, msdallas-
dt;1363
For more information on specifying IP
addresses and host names, see IP
Addresses, Host Names, and Ports.

This is the maximum time a CMGR waits 0–86399 (23 hours, 59 minutes, and 59
before exiting when it has not received a seconds)
tcp.api.inactivity. command from a client program.
timeout The value is in seconds. The default is 0,
which indicates no timeout occurs.

tcp.max.time.to.wait The maximum time the local node waits for 0–10000
a message from the remote node when
The value is in seconds. The default value
using TCP/IP. When the time expires, the
is 180.
Process is moved to the Timer queue and
Connect:Direct attempts to re-establish a
session with the remote node. When set to
0, wait time is unlimited unless limited by
the operating system.

TCP/IP Default Record

The tcp.ip.default record defines default information to use when the remote node is specified by IP
address. The tcp.ip.default record parameters are described in the following table:

Parameter Description Value

conn.retry.stwait The time to wait between retries The maximum value is limited to the
immediately after a connection failure highest value in the clock format,
occurs. The format is hh.mm.ss, where hh 23.59.59.
specifies hours, mm specifies minutes,
The default is 00.00.30, which is 30
and ss specifies seconds.
seconds.

Chapter 3. Administration Guide 113

Parameter Description Value
conn.retry.stattempts The number of times to attempt 0–9999
connection after a connection failure
The default is 6.
occurs.
conn.retry.ltwait The time to wait between long-term retry 0–23.59.59
attempts after all short-term retry
The default is 00.10.00, or 10
attempts are used. The format is
minutes.
hh.mm.ss, where hh specifies hours, mm
specifies minutes, and ss specifies
seconds.
conn.retry.ltattempts The number of times to attempt a 0–9999
connection after all short-term retry
The default is 6.
attempts are used.
comm.bufsize The buffer size for transmitting data to and The value for TCP/IP has no limit (up
from a remote node. to 2,147,483,623).
For LU6.2, the maximum is 32000.
The default is 65536 bytes.

Action to take after the specified short and hold | delete

conn.retry.exhaust.
long-term retries have been used.
action hold—Places Processes in the Hold
queue in Held in Error status, after
all retry attempts are used. This is
the default value.
delete—Causes the Processes to be
deleted from the TCQ.

tcp.max.time.to.wait The maximum time the local node waits 0–10,000

for a message from the remote node when
The value in seconds.
using TCP/IP. When the timer expires, the
Process is moved to the Timer queue and The default value is 180.
IBM Connect:Direct attempts to re-
When set to 0, wait time is unlimited
establish a session with the remote node.
unless limited by the operating
system.

The maximum time to wait for remote run 0–10000

steps to complete. Remote run steps
runstep.max.time.to. The value in seconds. The default
include remote run task, run job, or submit
wait value is 0.
statements. This wait time is different
from the wait time specified by the
tcp.max.time.to.wait parameter. Using
runstep.max.time.to.wait prevents a
Process from failing when a remote step
takes longer to complete than specified in
tcp.max.time.to.wait.
contact.name The name of the administrator or operator. Name
contact.phone The phone number of the IBM Phone number
Connect:Direct administrator or operator.
descrip Comments to include as part of the record. An unlimited string

114 IBM Connect:Direct for UNIX: Documentation

Parameter Description Value
sess.total The maximum number of concurrent 0–999
connections between all nodes and the
A 1–3 digit number. The default is
local node.
255.
The sum of api.max.connects and
sess.total cannot exceed the number of
file descriptors available. This value is
system dependent.

sess.pnode.max The maximum concurrent connections, 0–999

where the local node is the initiator of the
The default is 255.
session.
sess.snode.max The maximum concurrent connections, 0–999
where the local node is the secondary
The default is 255.
node in a session.
sess.default The default session class for starting 1–50
session managers. A Process executes on
The default is 1.
the specified class or any higher session
class. The value for this parameter
overrides the equivalent value in the
local.node record.
pacing.send.delay How long to wait between send operations nnn
to the remote node. The decimal number
The size of this number has no limit.
is the number of milliseconds between the
The default is 0, which indicates no
end of one packet and the beginning of the
pacing of this type.
next packet. Time-based pacing does not
contribute to network traffic.
The value for this parameter has no effect
on LU6.2 connections.

pacing.send.count The number of send operations to perform No limit exists for the size of this
before automatically waiting for a pacing value.
response from the remote node.
The default is 0, which indicates no
The value for this parameter has no effect pacing of this type.
on LU6.2 connections.

Chapter 3. Administration Guide 115

Remote Node Connection Record
The remote node connection record contains information you can use to define default values for a
generic remote node connection or customize to for a particular new remote node. Following are the
remote node connection parameters.

Parameter Description Value

alternate.comminfo Provides support for establishing netmap- host name/IP address or *
checked sessions with systems with
host name—Host name associated with the
multiple IP addresses, such as IBM
IP address, for example:
Connect:Direct/Plex z/OS. Use this
parameter to list all IP addresses or host :alternate.comminfo=hops (where hops is a
names that are part of the multiple IP machine on the local domain)
address environment.
:alternate.comminfo=hops.csg.stercomm.c
For IBM Connect:Direct/Plex, this list om (fully-qualified host name)
should include the address of each IBM
IP address——the IP address of a machine
Connect:Direct/Server with a different IP
running IBM Connect:Direct in IPv4 or IPv6
address from the IBM Connect:Direct/Plex
format:
Manager.If the IP address of the initiating
node does not match the IP address nnn.nnn.nnn.nnn (IPv4) or
specified on the comm.info parameter, the nnnn:nnnn:nnnn:nnnn:nnnn:nnnn:nnnn:nn
alternate.comminfo parameter is checked nn (IPv6)
for other valid IP addresses.
For example:
For more information on specifying IP
:alternate.comminfo=10.23.107.5
addresses and host names, see IP
Addresses, Host Names, and Ports. :alternate.comminfo=fe00:0:0:2014::7
Specify multiple addresses/host names by
separating them with a comma (,). A space
can be added after the comma for
readability. For example:
10.23.107.5, fe00:0:0:2014::7, msdallas-
dt
*—Accepts any IP address. This turns off IP
address validation.
Note: Partial pattern matches are not
supported, such as: *.mydomain.com,
myplex??.mydomain.com.

116 IBM Connect:Direct for UNIX: Documentation

Parameter Description Value
alt.comm.outbound Alternate communication address Fully-qualified host name/IP address;nnnn
(communication path) used for outbound
The host name/IP address and port are
Processes. This parameter provides the
separated by a semi-colon (;). A comma
alternate addresses for a remote node that
separates the list of alternate
has multiple NIC cards. When the local
communication paths, and the list is
node is the PNODE, the alternate
processed from the top down. For
addresses are tried if an initial attempt to
example:
the primary address (specified in the
comm.info parameter) fails. After a salmon;9400, 10.20.40.65;9500
connection has been established, if the
For more information on specifying IP
connection is subsequently lost, attempts
addresses and host names, see IP
to reestablish the connection through the
Addresses, Host Names, and Ports.
retry mechanism use the same address as
the initial connection.
When the local node is the SNODE, the
alternate addresses are used in the
Netmap check.

comm.bufsize The buffer size for transmitting data to and The value for TCP/IP has no limit (up to
from a remote node on TCP/IP 2,147,483,623).
connections.
For LU6.2, the maximum is 32000.
The default is 65536 bytes.

comm.info The information needed to initiate For TCP/IP connections, specify the host
connection requests to remote nodes using name or the IP address and port number.
TCP/IP or LU6.2. This information refers to
The default port is 1364.
the network card that the local IBM
Connect:Direct node uses to initiate For LU6.2 connections, specify a profile
outbound requests. This value is required. name, up to 8 characters.
• For TCP/IP connections, specify the host For more information on specifying IP
name or the IP address and port number. addresses and host names, see IP
If specifying IP address and port, Addresses, Host Names, and Ports.
separate parameters with a semicolon
(;).

comm.transport The transport protocol for the remote tcp | lu62 |blklu62
node.
tcp—TCP/IP connections
blklu62—Other LU6.2 connections

conn.retry.stwait Time to wait between retries immediately The maximum value is limited to the
after a connection failure occurs. The highest value in the clock format, 23.59.59.
format is hh.mm.ss, where hh specifies
The default is 00.00.30, which is 30
hours, mm specifies minutes, and ss
seconds.
specifies seconds.
conn.retry.stattempt Number of times to attempt connection 0–9999
s after a connection failure occurs.
The default is 3.

Chapter 3. Administration Guide 117

Parameter Description Value
conn.retry.ltwait Time to wait between long-term retry 0–23.59.59
attempts after all short-term retry
The default is 00.10.00, or 10 minutes.
attempts are used. The format is
hh.mm.ss, where hh specifies hours, mm
specifies minutes, and ss specifies
seconds.
conn.retry.ltattempt Number of times to attempt a connection 0–9999
s after all short-term retry attempts are
The default is 6.
used.
Action to take after the specified short and hold | delete
conn.retry.exhaust.
long-term retries have been used.
action hold—Places Processes in the Hold queue
in Held in Error status, after all retry
attempts are used. This is the default
value.
delete—Causes the Processes to be
deleted from the TCQ.

contact.name The name of the IBM Connect:Direct Name

administrator or operator.
contact.phone The phone number of the IBM Phone number
Connect:Direct administrator or operator.
descrip Comments to include as part of the record. An unlimited string
pacing.send.count The number of send operations to perform No limit exists for the size of this value.
before automatically waiting for a pacing
The default is 0, which indicates no pacing
response from the remote node. The value
of this type.
for this parameter has no effect on LU6.2
connections.
pacing.send.delay The time to wait between send operations nnn
to the remote node. The decimal number is
The size of this number has no limit. The
the number of milliseconds between the
default is 0, which indicates no pacing of
end of one packet and the beginning of the
this type.
next packet. Time-based pacing does not
contribute to network traffic.
The value for this parameter has no effect
on LU6.2 connections.

The maximum time to wait for remote run 0–10000

steps to complete. Remote run steps
runstep.max.time.to. include remote run task, run job, or submit The default value is 0.
wait statements. This wait time is different from
the wait time specified by the
tcp.max.time.to.wait parameter. Using
runstep.max.time.to.wait prevents a
Process from failing when a remote step
takes longer to complete than specified in
tcp.max.time.to.wait. The value is in
seconds.

118 IBM Connect:Direct for UNIX: Documentation

Parameter Description Value
sess.total The maximum number of concurrent 0–999
connections between all nodes and the
A 1–3 digit number.
local node.
The default is 255.
The sum of api.max.connects and
sess.total cannot exceed the number of file
descriptors available. This value is system
dependent.

sess.pnode.max The maximum concurrent connections, 0–999

where the local node is the initiator of the
The default is 255.
session. Number of PNODE sessions
cannot exceed the total number of
sessions.
If sess.pnode.max is larger than sess.total,
the value of sess.pnode.max is silently
rounded down to the value of sess.total.

sess.snode.max The maximum concurrent connections, 0–999

where the local node is the secondary node
The default is 255.
in a session.
Number of SNODE sessions cannot exceed
the total number of sessions. If
sess.snode.max is larger than sess.total,
then it is silently changed to the value of
sess.total.

tcp.crc Turn on or off the CRC function for TCP/IP y|n

Processes on the remote node.
The default is n.

Maintaining access information files

You can control access to IBM Connect:Direct through the following components:
• User authorization information file which contains local and remote user information records
• Strong access control file
• Program directory to limit access
• IBM Connect:Direct’s ability to detect shadow passwords
• Security exit

User Authorization Information File

In order for users to have access to IBM Connect:Direct and use IBM Connect:Direct commands and
statements, you need to define a record for each user ID in the user authorization information file, called
userfile.cfg. The user ID is the key to the local user information record. It must be a valid user ID on the
local system and must be unique. To disable access to the software for a local user, delete or comment
out the local user information record.
You can create a generic user ID by specifying an asterisk (*) as the user ID. If a user does not have a
specific local user information record, the user authorizations will default to those specified in this generic
record. If no generic local user information record is defined and no specific local user information record
is defined for the user, the user cannot use IBM Connect:Direct.
IBM Connect:Direct may optionally use remote user information records to translate remote user IDs to
valid local user IDs where IBM Connect:Direct is installed. If an snodeid parameter is not coded on the

Chapter 3. Administration Guide 119

 incoming Process, IBM Connect:Direct uses this proxy relationship to determine the rights of remote
users to issue IBM Connect:Direct commands and statements.
Connect:Direct for UNIX uses the asterisk (*) character to establish generic mappings that facilitate
mapping remote user IDs to local user IDs. The asterisk matches the node name or the host name. For
example, you can specify *@node name to map the remote user ID to all user IDs at one node name,
specify id@* to map to a specific user ID at all node names, or specify *@* to match all users at all node
names.

Sample Mapping of Remote User IDs to Local User IDs

The following table displays sample remote user ID mappings to local user IDs using the special
characters:

Remote User ID at Remote Node is Local User ID Result of Mapping

Name mapped
to
user @ * = test02 Remote user ID “user” on all
remote nodes is mapped to
local user ID test02.
* @ mvs.node3 = labs3 All remote user IDs on
remote node mvs.node3 are
mapped to local user ID
labs3.
* @ * = vip01 All remote user IDs on all
remote nodes are mapped to
local user ID vip01.

You can generate all the records through the script-based customization procedure or generate only one
or two records and use a text editor to generate additional records. After customization, you may want to
modify some of the parameters. Use cdcust to create a new user file or a text editor to modify the file as
necessary.

Sample User Authorization File

The following sample displays a user authorization file. In the sample, SAM1 is the remote user ID,
MVS.SAM1.NODE is the remote node name, and sam is the local UNIX user ID.

[email protected]:\
:local.id=sam:\
:pstmt.upload=y:\
:pstmt.upload_dir=/home/qatest/username/ndm/uploaddir:\
:pstmt.download=y:\
:pstmt.download_dir=/home/qatest/username/ndm/downloaddir:\
:pstmt.run_dir=/home/qatest/username/ndm/rundir:\
:pstmt.submit_dir=/home/qatest/username/ndm/submitdir:\
:descrip=:
sam:\
:admin.auth=y:\
:pstmt.copy.ulimit=y:\
:pstmt.upload=y:\
:pstmt.upload_dir=/home/qatest/username/ndm/uploaddir:\
:pstmt.download=y:\
:pstmt.download_dir=/home/qatest/username/ndm/downloaddir:\
:pstmt.run_dir=/home/qatest/username/ndm/rundir:\
:pstmt.submit_dir=/home/qatest/username/ndm/submitdir:\
:name=:\
:phone=:\
:descrip=:\
:cmd.s+conf=n:

120 IBM Connect:Direct for UNIX: Documentation

 Local User Information Record Format
The local user record, userid, defines the default values for each user ID. Most of the parameters in the
local user information record can take the following values:
• y—Indicates that a user can perform the function. In the case of process and select statistics
commands, the user can affect Processes and view statistics owned by this user ID
• n—Indicates that a user cannot perform the function.
• a—Indicates that a user can issue commands for Processes owned by all users and generate statistics
records for all users.
If the same parameter is specified in the remote user information record and the local user information
record, the parameter in remote user information record takes precedence unless it is a null value. When
a null value is specified in the remote record, the local user record takes precedence.
The following table defines the local user information parameters. The default values are underlined.

Parameter Description Value

admin.auth Determines if the user has administrative y|n
authority. If set to y, the user can perform
y—User has administrative authority.
all of the commands by default, but the
specific command parameters override the n—User does not have administrative
default. If set to n, the specific command authority.
parameters must be granted individually.
The default is n.

client.cert_auth Determines if the user can perform y|n

certificate authentication for client API
connections.
y—Enables client certificate authentication
for the user
n—Disables client certificate authentication
for the user

client.source_ip Use this parameter to list all of the IP A comma-separated list of client IP
addresses and/or host names that are valid addresses or host names associated with
for this user's API connection. If you client IP addresses.
specify values for this field, the IP address
The IP address of the client connection for
of this user's API connection is validated
this user must match the address
with the client.source_ip list. If the IP
configured in this field.
address does not match the one specified
on the list, the connection is rejected. For example: nnn.nnn.nnn.nnn, localhost

cmd.chgproc Determines if the user can issue the y|n|a

change process command.
y—Allows the user to issue the command.
A “y” value enables a user to issue the
n—Prevents the user from issuing the
command to targets owned by that user.
command. The default is n.
Whereas, “a” allows a user to issue the
command to targets owned by all users. a—Allows the user to issue the command
against targets owned by all users.

Chapter 3. Administration Guide 121

Parameter Description Value
cmd.delproc Determines if the user can issue the delete y|n|a
process command.
y—Allows the user to issue the command.
A “y” value enables a user to issue the
n—Prevents the user from issuing the
command to targets owned by that user.
command. The default is n.
Whereas, “a” allows a user to issue the
command to targets owned by all users. a—Allows the user to issue the command
against targets owned by all users.

cmd.flsproc Determines if the user can issue the flush y|n|a

process command.
y—Allows the user to issue the command.
A “y” value enables a user to issue the
n—Prevents the user from issuing the
command to targets owned by that user.
command. The default is n.
Whereas, “a” allows a user to issue the
command to targets owned by all users. a—Allows the user to issue the command
against targets owned by all users.

cmd.selproc Determines if the user can issue the select y|n|a

process command.
y—Allows the user to issue the command.
A “y” value enables a user to issue the
n—Prevents the user from issuing the
command to targets owned by that user.
command. The default is n.
Whereas, “a” allows a user to issue the
command to targets owned by all users. a—Allows the user to issue the command
against targets owned by all users.

cmd.viewproc Determines if the user can issue the view y|n|a

process command.
y—Allows the user to issue the command.
A “y” value enables a user to issue the
n—Prevents the user from issuing the
command to targets owned by that user.
command. The default is n.
Whereas, “a” allows a user to issue the
command to targets owned by all users. a—Allows the user to issue the command
against targets owned by all users.

cmd.selstats Determines if the user can issue the select y|n|a

statistics command.
y—Allows the user to issue the command.
A “y” value enables a user to issue the
n—Prevents the user from issuing the
command to targets owned by that user.
command. The default is n.
Whereas, “a” allows a user to issue the
command to targets owned by all users. a—Allows the user to issue the command
against targets owned by all users.

cmd.stopndm Determines if the user can issue the stop y|n

command.
y—Allows the user to issue the command.
n—Prevents the user from issuing the
command. The default is n.

cmd.s+conf Determines if the user can issue y|n

commands from network clients, such as
y—Allows the user to issue commands. The
IBM Control Center or Java API, to
default is y.
configure Connect:Direct Secure Plus.
n—Prevents the user from issuing
Note: This parameter has no effect on local
commands.
tools, such as spadmin.sh and spcli.sh.

122 IBM Connect:Direct for UNIX: Documentation

Parameter Description Value
cmd.submit Determines if the user can issue the submit y | n
process command.
y—Allows the user to issue the command.
n—Prevents the user from issuing the
command. The default is n.

cmd.trace Determines if the user can issue the trace y|n

command.
y—Allows the user to issue the command.
n—Prevents the user from issuing the
command. The default is n.

pstmt.crc Enables the user to override the initial y|n

settings to use the keyword CRC in a
y—Allows the user to issue the command.
Process statement.
n—Prevents the user from issuing the
command. The default is n.

descrip Permits the administrator to add Unlimited text string

descriptive notes to the record.
name The name of the user. User name
phone The phone number of the user. user phone number
pstmt.copy Determines if the user can issue the copy y|n
statement.
y—Allows the user to issue the command.
n—Prevents the user from issuing the
command. The default is n.

pstmt.copy.ulimit The action taken when the limit on a user y | n | nnnnnnnn | nnnnnnnnK | nnnnnnnM |
output file size is exceeded during a copy nnnnG
operation. The value for this parameter
y—Honors the user file size limit. If this
overrides the equivalent value for the ulimit
limit is exceeded during a copy operation,
parameter in the initialization parameters
the operation fails.
file.
n—Ignores the limit. The default is n.
nnnnnnnn, nnnnnnnnK, nnnnnnnM, or
nnnnG—Establishes a default output file
size limit for all copy operations. K denotes
1024 bytes. M denotes 1048576 bytes. G
denotes 1073741824 bytes. The
maximum value you can specify is 1 TB.

pstmt.upload Determines if the user can send files from y|n

this local node. If a file open exit is in use,
y—Allows the user to send files. The default
this parameter is passed to the exit, but it
is y.
is not enforced.
n—Prevents the user from sending files.

Chapter 3. Administration Guide 123

Parameter Description Value
pstmt.upload_dir The directory from which the user can send Directory path name
files. If a value is set for this parameter,
then files can only be sent from this
directory or subdirectories. If a file open
exit is in use, this parameter is passed to
the exit, but it is not enforced. If this
parameter is defined, file names in Copy
statements must be relative to this
directory. Absolute path names can be
used, but the path must coincide with this
specification.
pstmt.download Determines if the user can receive files to y|n
this local node. If a file open exit is in use,
y—Allows the user to receive files. The
this parameter is passed to the exit, but it
default is y.
is not enforced.
n—Prevents the user from receiving files.

pstmt.download_dir The directory to which the user can receive Directory path name
files. If a value is set for this parameter,
then files can only be received to this
directory or subdirectories. Otherwise, they
can be received to any directory. If a file
open exit is in use, this parameter is
passed to the exit, but it is not enforced.
pstmt.run_dir The directory where IBM Connect:Direct is Directory path name
installed that contains the programs and
scripts the user executes with run job and
run task statements. Any attempt to
execute a program or script outside the
specified directory fails.
The UNIX Restricted Shell provides
enhanced security by restricting the user to
the commands contained in the
pstmt.run_dir. If the user does not specify
pstmt.run_dir, the commands are started
with the Bourne shell.
To restrict the use of special characters in
the run directory, be sure to configure Y for
the restrict:cmd initialization parameter.
For more information on specifying the
restrict:cmd initialization parameter, see
Restrict Record.

pstmt.runjob Specifies whether the user can issue the y|n

run job statement.
y—Allows the user to issue the statement.
n—Prevents the user from issuing the
statement. The default is n.

124 IBM Connect:Direct for UNIX: Documentation

Parameter Description Value
pstmt.runtask Specifies whether the user can issue the y|n
run task statement.
y—Allows the user to issue the statement.
n—Prevents the user from issuing the
statement. The default is n.

pstmt.submit Specifies whether the user can issue the y|n

submit statement.
y—Allows the user to issue the statement.
n—Prevents the user from issuing the
statement. The default is n.

pstmt.submit_dir The directory from which the user can Directory path name
submit Processes. This is for submits
within a Process.
snode.ovrd Specifies whether the user can code the y|n
snodeid parameter on the submit
y—Allows the user to code the snodeid
command and process and submit
parameter
statements.
n—Prevents the user from coding the
snodeid parameter. The default is n.

pstmt.crc Gives the user the authority to specify the y|n

use of CRC checking in a Process
y—Allows a user to specify CRC checking
statement.
on a Process statement.
Setting this parameter to y enables the
n—Prevents a user from specifying
user to override the initial settings in the
CRCchecking on a Process statement. The
initialization parameters or network map
default is n.
settings files.

Remote User Information Record

The remote user information record contains a remote user ID and a remote node name that become the
key to the record. The local.id parameter identifies a local user information record for this user. You must
create a local user information record for the remote user.
Note: To prevent the remote user from using IBM Connect:Direct, delete or comment out the remote user
information, unless the remote user specifies an SNODEID parameter in the Process.
The remote user information record is remote userid@remote node name. It specifies the user and
remote node name pair defined as a remote user. This value becomes the key to the record and must be
unique. Create a remote user information record for each user on a remote node that will communicate
with this local node.
Following are the parameters for the remote user information record:

Parameter Description Value

local.id The local user ID to use for security Local user ID
checking on behalf of the remote user.
The local.id parameter must identify a
local user information record.

Chapter 3. Administration Guide 125

 Parameter Description Value
pstmt.copy Determines if the user can issue the y|n
copy statement.
y—Allows a user to issue the
statement.
n—Prevents a user from issuing the
statement. The default is n.

pstmt.upload Determines if the user can send files y|n

from this local node. If a file open exit is
y—Allows a user to send files. The
in use, this parameter is passed to the
default is y.
exit, but it is not enforced.
n—Prevents a user from sending
files.

pstmt.upload_dir The directory from which the user can Directory path name
send files. If a value is set for this
parameter, then files can only be sent
from this directory or subdirectories. If a
file open exit is in use, this parameter is
passed to the exit, but it is not enforced.
If this parameter is defined, file names
in Copy statements must be relative to
this directory. Absolute path names can
be used, but the path must coincide with
this specification.
pstmt.download Determines if the user can receive files y|n
to this local node. If a file open exit is in
y—Allows a user to receive files. The
use, this parameter is passed to the exit,
default is y.
but it is not enforced.
n—Prevents a user from receiving
files.

pstmt.download_dir The directory to which the user can Directory path name
receive files. If a value is set for this
parameter, then files can only be
received to that directory or
subdirectories. Otherwise, they can be
received to any directory. If a file open
exit is in use, this parameter is passed to
the exit, but it is not enforced.
pstmt.run_dir The directory that contains the programs Directory path name
and scripts the user can execute with
run job and run task statements. Any
attempt to execute a program or script
outside the specified directory fails.
To restrict the use of special characters
in the run directory, be sure to configure
Y for the restrict:cmd initialization
parameter. For more information on
specifying the restrict:cmd initialization
parameter, see Restrict Record.

126 IBM Connect:Direct for UNIX: Documentation

 Parameter Description Value
pstmt.submit_dir The directory from which the user can Directory path name
submit Processes. This is for submits
within a Process.
pstmt.runjob Specifies whether the user can issue the y | n
run job statement.
y—Allows a user to issue the
statement.
n—Prevents a user from issuing the
statement. The default is n.

pstmt.runtask Specifies whether the user can issue the y | n

run task statement.
y—Allows a user to issue the
statement.
n—Prevents a user from issuing the
statement. The default is n.

pstmt.submit Specifies whether the user can issue the y | n

submit statement.
y—Allows a user to issue the
statement.
n—Prevents a user from issuing the
statement. The default is n.

descrip Permits you to add descriptive notes to Text string

the record.

Strong Access Control File

To provide a method of preventing an ordinary user from gaining root access through IBM Connect:Direct,
a strong access control file called sysacl.cfg is created at installation in the d_dir/ndm/SACL/ directory. By
default, an ordinary user cannot access the root through Connect:Direct for UNIX. If you want to give an
ordinary root user access through Connect:Direct for UNIX, you must access and update the sysacl.cfg
file.
Note: Even if you do not want to limit root access through Connect:Direct for UNIX, the sysacl.cfg file
must exist. If the file is deleted or corrupted, all users are denied access to Connect:Direct for UNIX.
The file layout of the sysacl.cfg file is identical to the user portion of the userfile.cfg file. Setting a value in
the sysacl.cfg file for a user overrides the value for that user in the userfile.cfg file.
The root:deny.access parameter, which is specified in the sysacl.cfg file, allows, denies, or limits root
access to IBM Connect:Direct. This parameter is required. The following values can be specified for the
root:deny.access parameter:

Parameter Description Value

deny.access Allows, denies, or limits root access to y | n | d
IBM Connect:Direct
y—No Processes can acquire root authority
n—PNODE Processes can acquire root
authority, but SNODE Processes can not.
This is the default value.
d—Any Process can acquire root authority

Chapter 3. Administration Guide 127

 If a user is denied access because the root:deny.access parameter is defined in the sysacl.cfg file for that
user, a message is logged, and the session is terminated. If a user is running a limited ID, an informational
message is logged.

Automatic Detection of Shadow Passwords

Because shadow password files are available on some versions of the UNIX operating system,
Connect:Direct for UNIX detects the use of shadow passwords automatically, if available.

Limiting Access to the Program Directory

The program directory provides enhanced security for the run task and run job process statements by
limiting access to specified scripts and commands. Any attempt to execute a program or script outside
the specified directory fails. The program directory is identified with the pstmt.run_dir parameter. If the
program directory is specified, the UNIX restricted shell is invoked, providing enhanced security. If the
program directory is not specified, the regular (Bourne) shell is invoked for executing commands with no
restrictions.
The restricted shell is very similar to the regular (Bourne) shell, but it restricts the user from performing
the following functions:
• Changing the directory (cd)
• Changing PATH or SHELL environment variables
• Using command names containing a slash (/) character
• Redirecting output (> and >>)
Additional information about the restricted shell can be found in the appropriate UNIX manual pages or
UNIX security text books.
The restricted shell is started using only the environment variables HOME, IFS, PATH, and LOGNAME,
which are defined as follows:

HOME=run_dir
IFS=whitespace characters (tab, space, and newline)
PATH=/usr/rbin and run_dir
LOGNAME=user's UNIX ID

Because environment variables are not inherited from the parent Process, no data can be passed to the
script or command through shell environment variables. The restricted shell restricts access to specified
scripts and commands, but it does not restrict what the scripts and commands can do. For example, a
shell script being executed within the run_dir directory can change the value of PATH and execute
command names containing a slash (/) character. For this reason, it is important that the system
administrator controls which scripts and commands the user has access to and does not give the user
write privileges to the run_dir directory or any of the files in the run_dir directory.

Security Exit
The Security Exit in the initialization parameters file, initparm.cfg, provides an interface to password
support programs.
This exit generates and verifies passtickets and it also supports other password support programs. An
example of other programs is PASSTICKET, part of the RACF security system available on MVS hosts and
also supported by IBM on UNIX AIX and OS/2 computers using the NETSP product.
For more information on the Security Exit, see User Exit Record.

Maintaining client and server authentication key files

IBM Connect:Direct client/server security depends on a key, similar to a password, in a IBM
Connect:Direct server and an identical key in each API that communicates with that server. The keys are

128 IBM Connect:Direct for UNIX: Documentation

 defined and coordinated by the system administrator. You can edit both key files with any text editor
installed on your system.
The client key file is called keys.client on the node on which the API resides. The server key file is
keys.server on the node on which the server resides. The key files are located in the directory d_dir/
security.
CAUTION: To mitigate brute force attacks to break the keys.client and keys.server
authentication keys, IBM strongly recommends that customers use authentication key values with
a minimum length of 15 characters.

Key File Format

A record in a key file can contain up to four keys that match entries in another API or server key file. The
key file can contain as many key file records as necessary. The format of a key file entry is illustrated in
the following sample:

hostname MRLN SIMP key [key [key [key] ] ]

Key File Parameters

The following table describes the available key file parameters:

Parameter Description Value

hostname The host name of the server with which you want to 1—16 characters and must be
communicate or the host name of the API you will unique within its key file.
allow to communicate with your server. The
hostname is followed by one or more space
characters. If you replace the host name with an
asterisk (*) character in the server configuration file,
the server accepts a connection from any API with a
matching key. You can use only one asterisk per file.
Always place the entry with the asterisk after
entries with specific host names.
MRLN SIMP A required character string, separated from the Character string
other fields by one or more spaces.
key The security key. Separate the key from SIMP by Up to 22 characters long
one or more spaces. including A to Z, a to z, 0 to 9,
period (.), and
slash (/).
Note: Key values longer than 22
characters do not generate an
error; however, only the last 22
characters entered are used.
Any characters prior to the last
22 are ignored.

Sample Client Authentication Key File

The following figure illustrates API key lists in the Clients column and server key lists in the Servers
column.
• API A contains key11, key21, key31, and key41. Key11 enables API A to communicate with Server A
because Server A also contains the key11 entry. You must ensure that API1 is the host name on which
API A resides and that Server1 is the host name on which Server A resides.

Chapter 3. Administration Guide 129

 • API D contains key14, key24, and key34. Key14 enables API D to communicate with Server A because
Server A also contains the key14 entry. You must ensure that API4 is the host name on which API D
resides and that Server1 is the host name on which Server A resides.
• API C can communicate with Server A and Server B through matching keys. API C also can
communicate with Server C and Server D only through the * MRLN SIMP keyany line.

Authentication Process
The IBM Connect:Direct authentication process determines if the user is authorized to access the system.
The goal of IBM Connect:Direct security is to reliably determine the identity of each user without requiring
logon repetition. In addition, the security design ensures that all requests originate from the IBM
Connect:Direct API, to ensure that the authentication process is not bypassed by an unauthorized user.
The following figure displays the components that perform authentication:

130 IBM Connect:Direct for UNIX: Documentation

 Server Authentication Parameters
The server authentication parameters are specified in initparm.cfg. You must have ownership and
permissions to modify these files. Ownership is established during the installation procedure.
Additionally, the directory containing the keys.server file must have UNIX permission 0700, and
keys.server must have UNIX permission 0600. These files cannot be owned by root.
The following server authentication parameters are used by the CMGR during the authentication
procedure:

Parameter Description
server.program The server program to use during the
authentication procedure.
server.keyfile The key file to use during the authentication
procedure.

Client Authentication Parameters

The client authentication parameters are specified in ndmapi.cfg. You must have ownership and
permissions to modify these files. Ownership is established during the installation procedure.
Additionally, the directory containing the keys.client file must have UNIX permission 0700, and keys.client
must have UNIX permission 0600.
The following client authentication parameters are used by the CLI/API during the authentication
procedure:

Parameter Description
client.program The client program to use during the authentication
procedure.
client.keyfile The key file to use during the authentication
procedure.

Firewall Navigation
Firewall navigation enables controlled access to an IBM Connect:Direct system running behind a packet-
filtering firewall without compromising your security policies or those of your trading partners. You control
this access by assigning a specific TCP source port number or a range of source port numbers with a
specific destination address (or addresses) for IBM Connect:Direct sessions.
Before you configure source ports in the IBM Connect:Direct initialization parameters, you need to review
all information regarding firewall navigation and rules, especially if you are implementing firewalls.

Implement Firewall Navigation

To implement firewall navigation in IBM Connect:Direct:

Procedure
1. Coordinate IP address and associated source port assignment with your local firewall administrator
before updating the firewall navigation record in the initialization parameters file.
2. Add the following parameters to the IBM Connect:Direct initialization parameters file as needed, based
on whether you are using TCP:
• tcp.src.ports
• tcp.src.ports.list.iterations

Chapter 3. Administration Guide 131

 • udp.src.ports
• udp.src.ports.list.iterations
3. Coordinate the specified port numbers with the firewall administrator at the remote site.

Firewall Rules
Firewall rules need to be created on the local firewall to allow the local IBM Connect:Direct node to
communicate with the remote IBM Connect:Direct node. A typical packet-filtering firewall rule specifies
that the local firewall is open in one direction (inbound or outbound) to packets from a particular protocol
with particular local addresses, local ports, remote addresses, and remote ports. Firewall Navigation
differs between TCP; as a result, firewall rules for TCP should be configured differently.

TCP Firewall Navigation Rules

In the following table, the TCP rules are presented in two sections: the first section applies to rules that
are required when the local node is acting as a PNODE; the second section applies to rules that are
required when the local node is acting as an SNODE. A typical node acts as a PNODE on some occasions
and an SNODE on other occasions; therefore, its firewall will require both sets of rules.

TCP PNODE Rules

Rule Name Rule Direction Local Ports Remote Ports
PNODE session Outbound Local C:D's source ports Remote C:D's listening
port
TCP SNODE Rules
Rule Name Rule Direction Local Ports Remote Ports
SNODE session Inbound Local C:D's listening port Remote C:D's source
ports

TCP Firewall Configuration Example

The IBM Connect:Direct administrator configures the local node to listen on port 2264, and the following
initialization parameter settings are used to configure the local node's source ports:
• tcp.src.ports = (333.333.333.333, 2000–2200)
• tcp.src.ports.list.iterations = 1
This configuration specifies to use a source port in the range 2000–2200 when communicating with the
remote node's address 333.333.333.333 and to search the port range one time for an available port. The
local node will act as both a PNODE and an SNODE when communicating with the remote node.
Based on this scenario, the firewall rules for the local node are the following:

Rule Name Rule Direction Local Ports Remote Ports

PNODE session request Outbound 2000–2200 3364
SNODE session Inbound 2264 3000–3300

Session Establishment
Session establishment for TCP affects how you set up firewall rules and configure the firewall navigation
initialization parameters in IBM Connect:Direct.

TCP Session Establishment

An IBM Connect:Direct TCP client contacts an IBM Connect:Direct TCP server on its listening port. The
IBM Connect:Direct client scans the list of ports (specified using the tcp.src.ports initialization

132 IBM Connect:Direct for UNIX: Documentation

 parameter) and looks for a port to bind to. The number of times IBM Connect:Direct scans the list is
specified using the tcp.src.ports.list.iterations initialization parameter. If IBM Connect:Direct finds an
available port, communication with the remote node proceeds.

Specifying connection information

IBM Connect:Direct accepts both Internet Protocol version 4 (IPv4) and Internet Protocol version 6 (IPv6)
versions of the Internet Protocol as well as host names. You can enter IP addresses/host names and ports
in several ways, depending on the field you are specifying:
• Address or host name only
• Port number only
• Address/host name with a port number
• Multiple address/host name and port combinations
When specifying IP addresses/host names and ports for IBM Connect:Direct, use the following guidelines.

IP Addresses
IBM Connect:Direct accepts both IPv4 and IPv6 addresses. Wherever an IP address is specified in IBM
Connect:Direct, you can use either IPv4 or an IPv6 addresses.

IPv4 Addresses
IPv4 supports 232 addresses written as 4 groups of dot-separated 3 decimal numbers (0 through 9), for
example, 10.23.107.5.

IPv6 Addresses
IPv6 supports 2128 addresses written as 8 groups of colon-separated 4 hexadecimal digits, for example,
1001:0dc8:0:0:0:ff10:143e:57ab. The following guidelines apply to IPv6 addresses:
• If a four-digit group contains zeros (0000), the zeros may be omitted and replaced with two colons (::),
for example:

2001:0db8:85a3:0000:1319:8a2e:0370:1337
can be shortened as
2001:0db8:85a3::1319:8a2e:0370:1337

• Any number of successive 0000 groups may be replaced with two colons (::), but only one set of double
colons (::) can be used in an address, for example:

001:0db8:0000:0000:0000:0000:1319:58ab
Can be shortened as:
2001:0db8:0000:0000::1319:58ab

• Leading zeros in a four-zero group can be left out (0000 can be shortened to 0), for example:

2001:0db8:0000:0000:0000:0000:1319:58ab
Can be shortened as:
2001:0db8:0:0:0:0:1319:58ab

• You can write a sequence of 4 bytes that occur at the end of an IPv6 address in decimal format using
dots as separators, for example:

::ffff:102:304
Can be written as:
::ffff:1.2.3.4

Chapter 3. Administration Guide 133

 This notation is useful for compatibility addresses.

Host Names
When you specify a host name, rather than an IP address, IBM Connect:Direct gets the IP address from
the operating system. The first IP address returned by the operating system is used regardless of whether
it is in IPv4 or IPv6 format.
A host name (net, host, gateway, or domain name) is a text string of up to 24 characters comprised of the
alphabet (A–Z), digits (0–9), minus sign (-), and period (.), for example, msdallas-dt.
The following guidelines also apply:
• No blank or space characters are permitted as part of the name.
• Periods are allowed only when they are used to delimit components of domain-style names.
• Host names are not case sensitive.
• The first and last character must be a letter or digit.
• Single-character names or nicknames are not allowed.

Port Numbers
Port numbers can be appended to the end of IP/host addresses when they are preceded by a semi-colon
(;), for example, 10.23.107.5;1364. This convention is specific to IBM Connect:Direct and is not an
industry standard.
A port number must be in the range of 0 through 65535. Port numbers lower than 1024 are designated as
reserved and should not be used. The following examples show port numbers appended to IP/host
addresses using these conventions:

10.23.107.5;1364
fe00:0:0:2014::7;1364
msdallas-dt;1364

Multiple Addresses, Host Names, and Ports

You can specify multiple IPv4 and IPv6 addresses and host names by separating them with a comma (,). A
space can be added after the comma for readability, for example:

10.23.107.5, fe00:0:0:2014::7, msdallas-dt

You can also specify a port number for each address or host name. The port is separated from its
corresponding address/host name with a semi-colon (;), and each address/host name and port
combination is separated by a comma (,). A space may be added after the comma for readability. The
following example shows multiple address/host name and port combinations:

10.23.107.5;1364, fe00:0:0:2014::7;1364, msdallas-dt;1364

Multiple address/host names (and combinations with port numbers) are limited to 1024 characters.

About Using Masks for IP Address Ranges

When you specify a value for the tcp.src.ports parameter in the initialization parameters file, you can use
masks to specify the upper boundary of a range of IP addresses that will use a specific port, multiple
ports, or a range of ports. IBM Connect:Direct supports masks for both IPv4 and IPv6 addresses as shown
in the following sample entry from the initparms.cfg file:

134 IBM Connect:Direct for UNIX: Documentation

 tcp.src.ports=(199.2.4.*, 1000), (fd00:0:0:2015:*::*, 2000-3000), (199.2.4.0/
255.255.255.0, 4000-5000), (fd00:0:0:2015::0/48, 6000, 7000)

These sample addresses specify the following information:

(199.2.4.*, 1000)—Any IPv4 address that falls in the range from 199.2.4.0 through 199.2.4.255 will
use only port 1000.
(fd00:0:0:2015:*::*, 2000-3000)—Any IPv6 address that falls in the range from
fd00:0:0:2015:0:0:0:0 through fd00:0:0:2015:ffff:ffff:ffff:ffff will use a port in the range of 2000 through
3000.
(199.2.4.0/255.255.255.0, 4000-5000)—Any IPv4 address that falls in the range from 199.2.4.0
through 199.2.255.255 will use a port in the range of 4000 through 5000.
(fd00:0:0:2015::0/48, 6000, 7000)—Any IPv6 address that falls in the range from
fd00:0:0:2015:0:0:0:0 through fd00:0:0:ffff:ffff:ffff:ffff:ffff will use port 6000 or port 7000.
As shown in the sample entry above, the wildcard character (*) is supported to define an IP address
pattern. You can specify up to 255 unique IP address patterns or up to 1024 characters in length, each
with its own list of valid source ports. If the wildcard character is used, the optional mask is not valid.

Using IBM Connect:Direct in a test mode

You can enable a test mode for production instances of IBM Connect:Direct to perform the following
functions:
• Test new applications and customer connections
• Prevent future production work from executing until testing is complete after you have terminated all
active production work using the Flush Process command
• Resume regular production work after testing
• Control individual file transfers by application
• Enable and disable individual nodes and applications
While testing is being conducted, only Processes, particularly file transfers, involved with the testing
activity are executed. No production data is transferred to applications being tested while at the same
time no test data is transferred to production applications.

Processing Flow of the Test Mode

You enable the testing mode using the quiesce.resume initialization parameter and specify which IBM
Connect:Direct Processes to run and not run by storing your preferences as text records in a parameter
table named NDMPXTBL. A sample parameters file, NDMPXTBL.sample, is located in the /ndm/src
directory. After you have updated the file for your testing environment, place it in the installation ndm/cfg/
<nodename> directory. If you enable the quiesce.resume parameter, you must have an NDMPXTBL table
to operate IBM Connect:Direct in a test mode.
You can specify the following criteria that are used to find matches for one or more Processes to include
(using the “I” command code) or exclude (“X” command code) from execution:
• A partial or full Process name
• A partial or full remote node name
• A partial or full IBM Connect:Direct submitter ID and submitter node combination
In addition to telling IBM Connect:Direct which Processes to run, you tell the system what to do with the
Processes which do not get executed. You can specify the following dispositions for Processes not
permitted to run:
• Place the Process in the Hold queue

Chapter 3. Administration Guide 135

 • Place the Process in the Timer queue for session retry
• Flush the Process from the queue
For more information on how the testing mode can be used, see Sample Test Scenarios.
When the testing mode is enabled, IBM Connect:Direct performs a syntax check on the parameter table
and fails initialization if the table is invalid. If the table is valid, IBM Connect:Direct scans it looking for a
pattern that matches the Process that is about to execute. If a match is found, the Process is permitted to
execute if the “I” (Include) command code is in effect. If command code “X” (Exclude) is in effect, the
process is not permitted to execute. If a match is not found in the table, the opposite processing occurs
from the case where a match is found, that is, if no match is found and command code “I” is in effect, the
Process is not permitted to execute, whereas if command code “X” is in effect, the Process is permitted to
execute.
If a Process is not permitted to execute, the disposition specified in the NDMPXTBL parameter table to
either hold, retry, or flush the Process is implemented and a non-zero return code is returned. When a
Process is prevented from executing in testing mode, appropriate messages are issued and can be viewed
in the statistics log.
For Processes initiated on remote nodes, the testing mode functions in the same manner as it does for
Processes submitted on the local IBM Connect:Direct node except that the remote node is the PNODE
(Process owner) for that Process, and the local node is the SNODE (secondary node). The NDMPXTBL
Parameter Table is searched for a matching entry, and the remotely-initiated Process is either permitted
to execute or is excluded from execution. Because the local node is the SNODE for this type of transfer, it
cannot enforce the Process disposition setting in the NDMPXTBL parameter table. The remote PNODE
determines how the Process is handled. Typically, the remote node places the Process in the Hold queue
with a status of “HE” (Held in Error).

Preparing the NDMPXTBL Parameter Table

You can use any text editor to modify the sample NDMPXTBL parameter table supplied with IBM
Connect:Direct. When you update the parameter table, name it NDMPXTBL and save it to the Server
directory of the installation. The parameter table file can be created or updated while the server is active,
and any changes made to the file take effect for sessions that begin after the changes are made. Similarly,
the quiesce.resume initialization parameter can be modified while the server is active. For more
information on the quiesce.resume initialization parameter, see Quiesce/Resume Record.
Note: If you enable the quiesce.resume initialization parameter, you must have an NDMPXTBL parameter
table.

NDMPXTBL Parameter Table

Each table entry or record consists of a single-character command code in column one. Most command
codes have a parameter which begins in column two and varies according to the command code function.

Command Code Description Subparameters/Examples

* Comment line. * Only run the following Processes.
E Enables execution of Processes based The second column in this entry must
on table entries. Either “E” or “D” must contain one of the following values
be the first non-comment entry in the which indicates the disposition of a
table. PNODE Process if it is not allowed to
run.
H—Places the Process in the Hold queue
R—Places the Process in the Timer
queue in session retry
F—Flushes the Process from the queue

136 IBM Connect:Direct for UNIX: Documentation

Command Code Description Subparameters/Examples
D Disables the execution of all Processes The parameter for command code “E”
regardless of the contents of the can also be specified in column two.
parameter table and fails Process This is a convenience to make it easier
execution with a non-zero (error) return to change from “E” to “D” and vice versa
code and message LPRX003E. Either “E” without having to change column two to
or “D” must be the first non-comment a blank for command code “D.”
entry in the table
P Matches Processes based on a full or PCOPY—Matches a single Process
partial Process name. Supports the wild
PACH*—Matches all Processes
card trailing asterisk (*). Can be used to
beginning with “ACH”
enable or disable Process execution for
a particular application by using naming P*—Matches all Processes
conventions to match an application.
N Matches Processes based on a full or NCD.NODE1—Matches a single remote
partial remote node name. Supports the node name
wild card trailing asterisk (*).
NCD.NODEA*—Matches all remote node
names beginning with “CD.NODEA” N*—
Matches all remote node names

S Matches Processes based on a full or SACTQ0ACD@TPM002—Matches a

wild card IBM Connect:Direct submitter specific ID and node combination.
ID and submitter node combination. The
S*@TPM002—Matches all IDs from node
format is <id>@<node>.
TPM002
SACTQ0ACD@*—Matches ID ACTQ0ACD
from all nodes
S*@*—Matches all IDs from any node.
This is another way to match all
Processes.

I Includes Processes for execution that ER

match the patterns in the table which
I
follow this command code. Either “I” or
“X” must be the second non-comment NCD.BOSTON
entry in the table. Processes which do
Includes Processes for execution on the
not match a pattern in the table are not
CD.BOSTON node only. Processes
executed.
destined for all other remote nodes are
Note: To choose which command code placed in the Timer queue in session
to use to select Processes, determine retry
which group is smaller and use the
corresponding command Code. For
example, if the number of Processes to
be executed is smaller than the number
of Processes to exclude from execution,
specify “I” as the command code and
add patterns to match that group of
Processes.

Chapter 3. Administration Guide 137

 Command Code Description Subparameters/Examples
X Excludes from execution those EH
Processes that match the patterns in the
X
table which follow this command code.
Either “X” or “I” must be the second SDALLASOPS@*
non-comment entry in the table.
Excludes Processes for execution
Processes which do not match a pattern
submitted by the ID DALLASOPS from
in the table are executed.
any node

L Last entry in table.

Sample Test Scenarios

The following examples show different applications of the test mode using the NDMPXTBL parameter
table to define which IBM Connect:Direct Processes to run and not run.

Specifying Which Processes Run

In this example, IBM Connect:Direct executes all Processes that start with ACH or are named DITEST01
or DITEST02. All other Processes are placed in the Hold queue.

* Enable processing. Only permit processes matching one of the patterns

* to execute. Hold processes that don't execute.
EH
I
PACH*
PDITEST01
PDITEST02
L

Specifying Which Processes to Exclude

In this example, IBM Connect:Direct does not execute any Process that starts with ACH or is named
DITEST01 or DITEST02. All other Processes are executed.

* Exclude matching processes. Permit all others to execute.

EH
X
PACH*
PDITEST01
PDITEST02
L

Permitting Process Execution by Secondary Node and Submitter User ID/Node

In this example, IBM Connect:Direct executes all Processes that match one of the following criteria:
• The specific secondary node (SNODE) name is DI.NODE1
• An SNODE whose name starts with DI0017
• Any IBM Connect:Direct submitter ID from node DI0049
• The specific IBM Connect:Direct submitter ID ACHAPP from any node
All Processes not matching one of the above criteria are flushed from the queue.

138 IBM Connect:Direct for UNIX: Documentation

 * Only permit matching processes to execute. Flush those that do not.
EF
I
NDI.NODE1
NDI0017*
S*@DI0049
SACHAPP@*
L

Stopping the Test Mode

In this example, no Processes will be executed, and a non-zero return code will be displayed, which
signifies an error along with message ID LPRX003E. The remainder of the table is ignored (including the
“F” code to flush Processes from the queue), and all Processes are placed in the Hold queue.
To resume testing, change the “D” command code to an “E.”

* Execute no processes at all. Put them in the hold queue and return.
DF
I
PACH*
PDITEST01
PDITEST02
L

Chapter 3. Administration Guide 139

140 IBM Connect:Direct for UNIX: Documentation
Chapter 4. User Guide
The User Guide contains all the information you need in order to use Connect:Direct for UNIXto configure
and queue processes, use various system utilities, and create custom programs and user exits.

Controlling and Monitoring Processes

Use the Command Line Interface (CLI) to submit IBM Connect:Direct Processes and commands from a
native command line environment. You can also use the Connect:Direct Browser User Interface to
perform some of these tasks.

Starting the CLI

Procedure
1. If you have not defined the NDMAPICFG environment variable, type the following command for the
appropriate shell, where d_dir is the path to the IBM Connect:Direct subdirectory.
In the C shell:

% setenv NDMAPICFG d_dir/ndm/cfg/cliapi/ndmapi.cfg

In the Bourne or Korn shell:

$ NDMAPICFG=d_dir/ndm/cfg/cliapi/ndmapi.cfg
$ export NDMAPICFG

2. Type the following command to invoke IBM Connect:Direct CLI. Type options as required:

$ direct [-P string -s -t n -e nn -n name -p nnnnn -x -r -h -z]

Stopping the CLI

Procedure
• Stop the CLI operation by typing Control-D or quit at the prompt.

CLI Commands
Refer to the following table for a description of the command options and sample command entries:

© Copyright IBM Corp. 1993, 2018 141

 Option Description Value Sample Command
Entry
-P Identifies the custom string to use at text string $ direct -PNewPrompt
the command line prompt.
Up to 32 characters. $ direct -P”Test CD on
If the prompt string includes spaces Medea”
or special characters, enclose it in
single or double quotation marks.
The prompt string can also be
specified in the ndmapi.cfg file. If a
prompt string is specified on the
command line and in the ndmapi.cfg
file, -P takes precedence.
When the default prompt (“Direct”)
is overridden, the new prompt string
is shown at the command line
prompt and in the welcome banner
display.

-s Suppresses standard output. Use none $ direct -s

this option to view only the
completion status of a command.
-t n Enables the CLI/API trace option. 1|2|4 $ direct -t 4
The level number, n, identifies the
Specify one of the
level of detail in the trace output.
following level numbers:
1—Provides function entry
and function exit. This is
the default.
2—Provides function entry
and exits and basic
diagnostic information,
such as displaying values
of internal data structures
at key points in the
execution flow.
4—Enables a full trace. All
diagnostic information is
displayed.

142 IBM Connect:Direct for UNIX: Documentation

 Option Description Value Sample Command
Entry
-e nn Defines the error level above which 0 | 4 | 8 | 16 $ direct -e 16
the CLI automatically exits. If the
Valid values in the error
returned error code is greater than
level code are:
the error level specified, the CLI
automatically exits. 0—Indicates successful
completion.
Use this command within shell
scripts. 4—Indicates warning.
This parameter prevents unwanted 8—Indicates error.
execution of commands following a
16—Indicates catastrophic
command that generates an error
error.
above the specified level.
When the CLI terminates, it returns
a UNIX exit code that can be tested
by the shell.

-n name Identifies the host name of the IBM Connect:Direct host $ direct -n hostname
computer where the IBM name
Connect:Direct server (PMGR) is
running.
Note: Invoking direct with -p or -n
overrides the settings in the
ndmapi.cfg file.

-p nnnnn Identifies the communications port 1024–65535. The format $ direct -p 2222
number for the IBM Connect:Direct is nnnnn.
node.
Note: Invoking direct with -p or -n
overrides the settings in the
ndmapi.cfg file.

-x Displays command input on none $ direct -x

standard out. Use this command
when debugging scripts.
-r Makes the Process number available none $direct -r | grep
to user-written shell scripts. The CLI “_CDPNUM_”
displays a special string, _CDPNUM_
followed by a space, followed by the
Process number.
-h Displays command usage none $ direct -h
information if a IBM Connect:Direct
command is typed incorrectly.
-z Appends a newline character after a none $ direct -z
prompt.

CLI Job Control

IBM Connect:Direct enables you to switch the CLI Process between the foreground and the background in
shells that support job control. This capability enables you to edit the text of saved Processes, issue UNIX
commands, and resolve Process errors without exiting and reentering the CLI. Use the following
commands to switch the CLI Process:

Chapter 4. User Guide 143

 • Press the suspend character (Control-Z) to stop or suspend the CLI Process.
• Issue the fg command to move the CLI Process to the foreground.
Note: If you experience problems with job control, contact your system administrator for suggestions on
additional UNIX commands to use.

CLI History Commands

IBM Connect:Direct enables you to use the history commands available with UNIX. History commands do
not need the semicolon (;) at the end of the command. The following table lists the available history
commands:

Command Description
!! Repeat the last command one time.
!#n Set the number of commands to store in the history
buffer. The default history buffer size is 50
commands.
!n Repeat command number <n> in the history buffer.
!<string> Repeat command beginning with the string
<string>.
!? List the contents of the history buffer.

Overview of IBM Connect:Direct Commands

You control and monitor IBM Connect:Direct Processes using the following commands:
Note: The CMGR currently limits the size of a Process file to 60K bytes.

Command Abbreviation Description

submit sub Makes Processes available for execution.
change process cha pro Changes the status and modifies specific characteristics, of a
nonexecuting Process in the TCQ.
delete process del pro Removes a nonexecuting Process from the TCQ.
flush process flush pro Removes an executing Process from the TCQ.
stop stop Stops Connect:Direct for UNIX and returns control to the
operating system.
select process sel pro Monitors both executing Processes and Processes waiting for
execution. You can specify the search criteria and the form in
which the information is presented.
select statistics sel stat Retrieves information from the statistics file. You can specify the
search criteria and the form in which the information is presented.
view process view pro View a Process in the TCQ where the local node is the Pnode. View
process can only display Processes running on the local node
since only the Pnode has the information required to display a
Process.

144 IBM Connect:Direct for UNIX: Documentation

Abbreviations for Common IBM Connect:Direct Commands
The following table lists valid abbreviations for commonly used parameters for IBM Connect:Direct
commands:

Parameter Abbreviation
detail det
quit q
recids rec
release rel
pname pnam, pna
pnumber pnum
sunday sun
monday mon
tuesday tue
wednesday wed
thursday thu
friday fri
saturday sat
today tod
tomorrow tom

Restricting the Scripts and UNIX Commands Users Can Execute

System administrators and other network operations staff can restrict the scripts and UNIX commands
that you can execute with the run task and run job Process statements. System administrators and other
network operations staff can enforce the following limits on the capabilities you have with IBM
Connect:Direct:
• The capability to send or receive files; you may be limited either to sending files only or to receiving files
only.
• The locations to or from which you can send or receive files; you may be limited to specific local or
remote nodes.
Check with the system administrator for a list of specific restrictions for your user ID.

IBM Connect:Direct Command Syntax

Use the same command syntax for commands typed at the CLI prompt or used as the command text
parameter for an ndmapi_sendcmd() function. Refer to “Writing User Exits” on page 210, for details on
function calls. The following conventions are used when typing commands:
• When selecting a password or user ID, do not use IBM Connect:Direct keywords.
• Be aware that user names and file names are case sensitive.
• Type an individual command keyword in uppercase, lowercase, or mixed-case characters.
• Terminate all commands with a semicolon (;).

Chapter 4. User Guide 145

 • When typing commands, type the entire command name or type the first three characters or abbreviate
specific parameters. Refer to “Abbreviations for Common IBM Connect:Direct Commands” on page
145for a list of abbreviations.
• Do not abbreviate Process statements and parameters.
• File names, group names, user IDs, and passwords are variable length strings and can be any length.
• A IBM Connect:Direct node name is 1–16 characters long. The name of a record in the netmap
describing a remote node is typically the remote IBM Connect:Direct node name, but can be any string
1–256 characters long. You can also specify a remote node name as an IP address or hostname and a
port number or port name.

“Generic” Parameter Value

When the word generic is specified as a parameter value in a syntax definition, provide a string that can
include the asterisk (*) and question mark (?) characters. These characters provide a pattern matching or
wildcard facility for parameter values. The asterisk matches zero or more characters, and the question
mark matches any single character. The following sample illustrates the use of the asterisk and question
mark characters:

PNAME = A?PROD5*

The generic Process name specified in the previous sample shows a specification that matches all
Processes beginning with the letter A, followed by any single character in position two with the string
PROD5 in positions three through seven. The asterisk takes the place of zero or more characters
beginning in position eight.

“List” Parameter Value

When (list) is a parameter value, you can specify multiple parameter values by enclosing the group in
parentheses and separating each value with a comma. A list can also include generic values. The
following command illustrates a list:

(pnumber1, pnumber2, pnumber3)

Submitting a Process
The submit command makes Processes available for execution and enables the software to interpret the
Process statements contained in the specified files.
Parameters specified in the submit command override the same parameters specified on the Process
statement. There are no required parameters. However, if you do not specify a file name for the file
parameter, the text of the IBM Connect:Direct Process must follow the submit command. Following are
the parameters for the submit command:

Parameter Description Values

file The name of the Process file. The file name file name including the path name
can include a path name indicating the
location of the Process.
This parameter must be the first parameter.

146 IBM Connect:Direct for UNIX: Documentation

Parameter Description Values
class The node-to-node session on which a 1|n
Process can execute. A Process can execute
A numeric value from 1 to the value of
on the class specified or any higher session
maximum concurrent local node connections
class. The default class is specified as the
(sess.pnode.max). The default value is 1. The
sess.default parameter of the local.node
value cannot be greater than the maximum
record in the initialization parameters file.
number of local sessions with primary control.

crc Determines if crc checking is performed. This on | off

parameter overrides settings in the
on—Turns on crc checking.
initialization parameter, the network map,
and the Process. off—Turns off crc checking. The default is off.
Note: The user must be assigned authority to
change the crc settings in the user authority
file.

hold Determines if the Process is placed in the yes | no | call

Hold queue.
yes—Specifies the Process is placed in the Hold
When a Process is submitted with retain=yes queue in HI status until it is released by a
or retain=call, IBM Connect:Direct ignores change process command. A Process submitted
the hold parameter. with hold=yes is placed on the Hold queue even
if you specify a start time.
no—Specifies that the Process executes as soon
as resources are available. This is the default.
call—Specifies that the Process is held until a
connection is established between the remote
node and the local node. At that time, the
Process is released for execution.

maxdelay How long the submit command waits for the unlimited | hh:mm:ss | 0
submitted Process to complete execution.
unlimited—Waits until the Process completes
This parameter is useful when the command
execution.
is issued by a shell script. When this
parameter is specified, the script waits until hh:mm:ss—Waits for an interval no longer than
the Process completes before it continues the specified hours, minutes, and seconds.
execution. The return code of the Process is
0—Waits until the Process completes execution.
stored in the $? variable if you are using the
If you specify maxdelay=0, you get the same
Bourne or Korn shell and in $status variable
results as when you specify
if you are using the C shell, which the shell
maxdelay=unlimited.
script can use to test the results of Process
execution. If you do not specify maxdelay, no
delay occurs.
If the time interval expires, the submit
command returns a warning status code and
message ID to the issuing Process or CLI/
API. The Process is not affected by the time
interval expiration and executes normally.

newname A new Process name that overrides the name A name up to 256 characters long
in the submitted Process.

Chapter 4. User Guide 147

Parameter Description Values
notify The user e-mail to receive Process username@hostname or user@localhost
completion messages. This parameter uses
the rmail utility available in the UNIX System
V mail facility to deliver the completion
messages.
Note: IBM Connect:Direct does not validate
the e-mail address or user ID supplied to the
notify parameter. Invalid e-mail addresses
and failed E-mail attempts are handled
according to the local mail facilities
configuration.

pacct A string containing information about the “pnode accounting data” up to 256 characters
PNODE. Enclose the string in double
quotation marks.
pnodeid Security user IDs and passwords at the id , pswd
PNODE. The pnodeid subparameters can
id—Specifies a user ID on the PNODE.
contain 1–64 alphanumeric characters.
pswd—Specifies a user password on the PNODE.
If you specify pnodeid, you must also specify id.
Identify the ID first and the pswd last.

prty The priority of the Process in the 1–15, where fifteen is the highest priority. The
Transmission Control Queue (TCQ). A default is 10.
Process with a higher priority is selected for
execution before a Process with a lower
priority. The prty value does not affect the
priority during transmission.

148 IBM Connect:Direct for UNIX: Documentation

Parameter Description Values
retain Determines if IBM Connect:Direct retains a yes | no | initial
copy of the Process in the TCQ. IBM
yes—Specifies that the system retains the
Connect:Direct assigns a Process number to
Process in the Hold queue in HR status after
the Process when it is placed in the retain
execution.
queue. When the Process is run, the Process
number assigned to the retain Process is no—Specifies that the system deletes the
incremented by one. For example, if the Process from the TCQ after execution. This is
Process is assigned the Process number of the default.
1445 in the retain queue, the Process
initial—Specifies that the system retains the
number is 1446 when the Process is
Process in the Hold queue in HR status for
executed.
automatic execution every time the Process
If you specify a start time and set Manager initializes.
retain=yes, the Process remains in the Timer
queue in HR status and is submitted at the
appropriate interval. For example, when
startt=(Monday,2:00), the Process runs
each Monday at 2:00 AM. When
startt=(,1:00), the Process runs daily at 1:00
AM. IBM Connect:Direct does not provide a
way to run a Process hourly. To do this, you
must use the UNIX cron utility.
If no start time is identified, you must issue a
change process command to release the
Process for execution.
Do not code the startt parameter when you
specify retain=initial.

sacct Specifies accounting data for the SNODE. “snode accounting data” up to 256 characters.
Setting this value in the submit statement Enclose the string in double quotation marks.
overrides any accounting data specified in
Process.
snode Identifies the name of the secondary node. name | host name | nnn.nnn.nnn.nnn or
Setting this value overrides the snode value nnnn:nnnn:nnnn:nnnn:nnnn:nnnn:nnnn:nnnn[;p
in the Process statement. The snode ort name | nnnnn]]
parameter is required either on the submit
name—Specifies the node name of the remote
command or Process statement.
node. The secondary node name corresponds to
an entry in the network map file.
host name—Specifies the name of the host
computer where the remote IBM Connect:Direct
node is running.
nnn.nnn.nnn.nnn or
nnnn:nnnn:nnnn:nnnn:nnnn:nnnn:nnnn:nnnn —
Specifies the IP address of the remote node in
IPv4 or IPv6 format: nnn.nnn.nnn.nnn (IPv4) or
nnnn:nnnn:nnnn:nnnn:nnnn:nnnn:nnnn:nnnn
(IPv6).
[;port number |nnnnn]—Identifies the
communications port. You can only use this
parameter with the host name or IP address
parameters. The nnnnn value is a decimal
number from 1,024–65,535.

Chapter 4. User Guide 149

Parameter Description Values
snodeid Specifies security user IDs and security id [,pswd [,newpswd]]
passwords on the SNODE. The snodeid
id—Specifies a user ID on the SNODE.
subparameters can contain one or more
alphanumeric characters. pswd—Specifies a user password on the SNODE.
If you specify id, you do not have to specify
If IBM Connect:Direct finds that a Process
pswd. This capability enables the id parameter
has no snodeid parameter or defines a
to contain a dummy ID to be used for
snodeid parameter and the initialization
translation to a local ID on the remote system.
parameter proxy.attempt is set to y, then
any password specified on the snodeid newpswd—Specifies a new password value. On
parameter is ignored. A proxy user record is a certain platforms, the user password changes to
remote user record in the userfile.cfg, which the new value on the SNODE if the user ID and
corresponds to the user name specified on old password are correct (refer to
the snodeid parameter. If no proxy user documentation on the specific platform). If the
record exists, the snodeid parameter must SNODE is a UNIX node, the password does not
contain a valid user name and password for a change.
UNIX user who has a corresponding local
If you specify pswd, you must also specify id. If
user record in the userfile.cfg file.
you specify newpswd, you must also specify
When proxy.attempt=n and no snodeid is pswd. Type the values in the order of id, pswd,
defined, IBM Connect:Direct uses the and newpswd.
submitting ID and node to find a Remote
User Information record in the User
Authorization Information file. If IBM
Connect:Direct cannot find a match, then
that user cannot send or receive files.
If the initialization parameters file parameter
proxy.attempt is set to y, users are not
required to specify a password for the
snodeid parameter. This capability enables
the id subparameter to contain a dummy
user ID to be used for translation to a local
user ID on the remote system. The use of a
dummy user ID offers improved security
because neither the sender nor the receiver
are required to use an actual user ID.
Reserved keywords cannot be used in the
snodeid field.

150 IBM Connect:Direct for UNIX: Documentation

Parameter Description Values
startt Identifies the date, day, and time to start the [date | day | daily] [,hh:mm:ss [am | pm]]
Process. IBM Connect:Direct places the
date—Specifies the day (dd), month (mm), and
Process in the Timer queue in WS (Waiting
year (yy), which you can code as mm/dd/yyyy or
for Start Time) status. The date, day, and
mm-dd-yyyy. If you only specify date, the time
time are positional parameters. If you do not
defaults to 00:00:00, which indicates midnight.
specify date or day, a comma must precede
The current date is the default.
time.
day—Specifies the day of the week. Values are
Do not code the startt parameter when you
today, tomorrow, yesterday, monday, tuesday,
specify retain=initial.
wednesday, thursday, friday, saturday, and
sunday.
hh:mm:ss [am | pm]—Specifies the time of day
in hours (hh), minutes (mm), and seconds (ss).
You can specify the hour in either 12- or 24-
hour format. If you use 12-hour format, then
you must specify am or pm. The default is the
24-hour format. The default value is 00:00:00,
which indicates midnight.
If you specify only the day value, the time
defaults to 00:00:00. This means that if you
submit a Process on Monday, with monday as
the only startt parameter, the Process does not
run until the following Monday at midnight.
daily - Schedules the process for daily execution
at the specified time. If the specified time has
already elapsed on the day the command is
submitted, the process will be scheduled for the
next day. If you leave this parameter blank, the
process will be scheduled for daily execution.
The only difference between the daily
specification and leaving the parameter blank is
that if the specified time has already elapsed on
the day the command is submitted, the process
will be submitted immediately, and then daily at
the specified time thereafter.

&symbolic Specifies a symbolic parameter assigned a variable string 1

name 1 value. The value is substituted within the
variable string 2
Process when the symbolic parameter is
&symbolic
encountered. variable string n
name 2
The value for the symbolic parameter must The symbolic name cannot exceed 32
&symbolic
be in double quotation marks if it is a characters.
name n
keyword or contains special characters. If
you want to reserve the double quotation
marks when the symbolic name is resolved in
the Process, enclose the double-quoted
string in single quotes, for example:
&filename = “‘filename with spaces'”
The symbolic name itself must not be a
subset of any other symbolic name. (You
cannot have, for example, a symbolic name
called &param and another symbolic name
called &parameter in the same Process.)

Chapter 4. User Guide 151

Parameter Description Values
tracel Specifies the level of trace to perform for a level = 0 |1 | 2 | 4
Process. Tracing by Process can be turned on
snode | pnode
in the submit command or as part of the
Process definition. file=name
If you identify the snode or pnode level—Specifies the level of detail displayed in
immediately after the trace level definition, the trace output. The default is 4.
the trace level is turned on for all Processes
0—Terminates the trace.
submitted to and from the node identified.
1—The basic level that provides function entry
and function exit.
2—includes level 1 plus function arguments.
4—Enables a full trace. Basic diagnostic
information, such as values of internal data
structures at key points in the execution flow,
are displayed.
snode—Specifies to trace only the SNODE
SMGR.
pnode—Specifies to trace only the PNODE
SMGR.
file—Specifies the name of a file where the trace
output is directed. If you do not specify a file
name, the file is created in the IBM
Connect:Direct working directory with the file
name CMGR.TRC. The length of the name value
is unlimited.

Example - Submit a Process That Runs Every Week

The following command submits the Process named payroll:

submit file=payroll retain=yes startt=monday pacct=“1959,dept-27";

Because retain=yes is specified in this sample, the Process is retained in the TCQ after execution. The
Process starts next Monday at 00:00:00 and runs every Monday thereafter. Process accounting data is
specified for the PNODE.

Example - Submit a Process with a Start Time Specified

The following command submits the Process named copyfil:

submit file=copyfil snode=vmcent startt=(01/01/2008, 11:45:00 am);

Because startt is specified, the Process executes on the first day of January 2008 at 11:45 a.m.

Example - Submit a Process with No File Value

The following command submits a Process without a file parameter value, but with the Process
statements typed at the CLI command prompt:

Direct> sub do_copy process snode=node1

step01 copy from (
file=data.data
pnode
)
to (
file=b
snode

152 IBM Connect:Direct for UNIX: Documentation

 )
pend ;
Process Submitted, Process Number = 5

Example - Submit a Process and Turn On Tracing

The following command submits the Process named copy.cdp:

submit file=copy.cdp tracel=4 pnode;

Because tracel is specified and the pnode parameter is included, an SMGR and COMM full trace is
performed on the Process. Trace information is written to the default file SMGR.TRC.

Changing Process Parameters

The change process command modifies specified parameters for a nonexecuting Process.
You specify the Processes to be changed by Process name, Process number, secondary node name, and
submitter.
You can change the class, destination node, and priority. You can place a Process on the Hold queue or
release a Process from the Hold queue by issuing a change process command with either the release or
hold=no parameter.
If you submit a Process with a startt parameter, IBM Connect:Direct places the Process on the Timer
queue. If a Process fails, you can move it to the Hold queue by specifying the change process command
with hold=yes. IBM Connect:Direct then places the Process in the Hold queue in HO status. You can
release the Process for execution at a later time.
You can set tracing for an existing Process by setting the tracel parameter to 1, 2, or 4. You can turn off
tracing for a Process by setting trace1 to 0.
Specify at least one of the following search criteria parameters:

Parameter Description Value

pname Locate the Process to be changed name | generic | (list)
by Process name.
name—Specifies the Process name, up to 8
The Process name is limited to 8 alphanumeric characters.
characters on Connect:Direct for
generic—Specifies a nonspecific value for the
Microsoft Windows and
Process name. This generic value, containing
Connect:Direct for z/OS.
pattern-matching characters, evaluates to a list
of zero or more pname strings.
list—Specifies a list of Process names. Enclose
the list in parentheses, and separate each
value with a comma.

pnumber Locate the Process to be changed number from 1–99,999 | (list)

by Process number. IBM
number—Specifies the Process number.
Connect:Direct assigns the
Process number when the list—Specifies a list of Process numbers.
Process is submitted. Enclose the list in parentheses, and separate
each value with a comma.

Chapter 4. User Guide 153

 Parameter Description Value
snode Locate the Process to be changed remote node specification | generic | (list)
by the secondary node name.
remote node specification—Identifies a specific
This parameter can be used to
remote node name.
specify a specific remote node, a
generic value for matching generic—Specifies a nonspecific value for the
remote node names (using remote node name. This generic value,
pattern matching), or a list of containing pattern-matching characters,
multiple remote node names. evaluates to a list of zero or more remote node
names.
The secondary node name
typically contains the 1–16 list—Specifies a list of remote node
character remote IBM specifications. Enclose the list in parentheses,
Connect:Direct node name, but and separate each value with a comma.
can be any string up to 256
alphanumeric characters long.
You can also specify a remote
node name as an IP address or
hostname and a port number.

submitter Locate the Processes to be (node specification, userid) | generic | (list)

changed by the node
node specification, userid—Specifies the node
specification (the IBM
specification (the IBM Connect:Direct node
Connect:Direct node name) and
name) and user ID.
user ID of the Process owner. The
character length of this generic—Specifies a nonspecific value for node
parameter is unlimited. specification and user ID. This generic value,
containing pattern-matching characters,
evaluates to a list of zero or more node
specifications and user IDs.
list—Specifies a list of node specification and
user ID pairs. Enclose the list in parentheses,
and separate each value with a comma.

The optional parameters for the change process command are the following:

Parameter Description Value

class Changes the node-to-node session The default is 1.
on which a Process can execute. A
Process can execute on the class
specified or any higher session
class. The default class is specified
as the sess.default parameter of
the local.node record in the
initialization parameters file.

154 IBM Connect:Direct for UNIX: Documentation

 Parameter Description Value
hold Moves the Process to the Hold or yes | no | call
Wait queue.
yes—Places the Process in the Hold queue in
HO status until it is released by another
change process command.
no—Places the Process in the Wait queue in
WC (Waiting for Connection) status; the
Process executes as soon as resources are
available. This is the default.
call—Places the Process in the Hold queue in
HC (Hold for Call) status until the remote
node (SNODE) connects to the local node
(PNODE) or another Process is submitted. At
that time, IBM Connect:Direct releases the
Process for execution

newsnode Specifies a new remote node name new remote node specification
to assign to the Process.
prty Changes the priority of the Process 1–15, where 15 is the highest priority. If you
on the TCQ. IBM Connect:Direct do not specify prty, the default is 10.
uses the prty parameter for
Process selection. A Process with a
higher priority is selected for
execution before a Process with a
lower priority. The prty value does
not affect the priority during
transmission.
release Releases the Process from a held none
state. This parameter is equivalent
to hold=no.
tracel Changes the level of trace to level = 0 | 1 | 2 | 4
perform for a Process.
level—Specifies the level of detail displayed in
If you identify the SNODE or the trace output. The default is 4.
PNODE immediately after the trace
0—Terminates the trace.
level definition, the trace level is
1—Is the basic level that provides function
turned on for all Processes
entry and function exit.
submitted to and from the node
2 —Includes level 1 plus function arguments.
identified.
4—Enables a full trace. Basic diagnostic
information, such as values of internal data
structures at key points in the execution flow,
are displayed.

The following command changes the remote node name for the Process named cdproc to a new remote
node, paris:

change process pname=cdproc newsnode=paris;

Deleting a Process from the TCQ

The delete process command removes a nonexecuting Process from the TCQ.

Chapter 4. User Guide 155

 You select the Process to delete by Process name, Process number, secondary node name, submitter, or
any combination of the search criteria parameters. Specify at least one of the following search criteria
parameters:

Parameter Description Value

pname Identify the Process to delete by name | generic | (list)
Process name.
name—Specifies the Process name up to 8
The Process name is limited to 8 alphanumeric characters long.
characters on Connect:Direct for
generic—Specifies a nonspecific value for the Process
Microsoft Windows and for z/OS.
name. This generic value, containing pattern-
matching characters, evaluates to a list of zero or
more pname strings.
list—Specifies a list of Process names. Enclose the list
in parentheses, and separate each value with a
comma.

pnumber Identify the Process to delete by number | (list)

Process number. IBM
number—Specifies the Process number.
Connect:Direct assigns the
Process number when the list—Specifies a list of Process numbers. Enclose the
Process is submitted. Valid list in parentheses, and separate each value with a
Process numbers range from 1– comma (,).
99,999.
snode Identify the Process to delete by remote node specification | generic | (list)
the secondary node name. This
remote node specification—Identifies a specific
parameter can be used to specify
remote node name.
a specific remote node, a generic
value for matching remote node generic—Specifies a nonspecific value for the remote
names (using pattern matching), node name. This generic value, containing pattern-
or a list of multiple remote node matching characters, evaluates to a list of zero or
names. more remote node names.
The secondary node name list—Specifies a list of remote node specifications.
typically contains the 1–16 Enclose the list in parentheses, and separate each
character remote IBM value with a comma.
Connect:Direct node name, but
can be any string up to 256
alphanumeric characters long.
You can also specify a remote
node name as an IP address or
hostname and a port number.

submitter Identify Processes to delete by (node specification, userid) | generic | (list)

the node specification and user
node specification, userid—Specifies the node
ID of the Process owner. The
specification and user ID.
character length of this
parameter is unlimited. generic—Specifies a nonspecific value for node
specification and user ID. This generic value,
containing pattern-matching characters, evaluates to
a list of zero or more node specifications and user IDs.
list—Specifies a list of node specification and user ID
pairs. Enclose the list in parentheses, and separate
each value with a comma.

The following command deletes all nonexecuting Processes submitted by user ID cduser on node dallas:

156 IBM Connect:Direct for UNIX: Documentation

 delete process submitter=(dallas, cduser);

Removing a Process from the Execution Queue

The flush process command removes Processes from the Execution queue. You select the Process to
remove by Process name, Process number, secondary node name, submitter, or any combination of the
search criteria parameters. Specify at least one of the following search criteria parameters:

Parameter Description Value

pname Locate the Process to remove name | generic | (list)
by Process name.
name—Specifies the Process name, up to 8
The Process name is limited alphanumeric characters.
to 8 characters on
generic—Specifies a nonspecific value for the Process
Connect:Direct for Microsoft
name. This generic value, containing pattern-matching
Windows and Connect:Direct
characters, evaluates to a list of zero or more pname
for z/OS.
strings.
list—Specifies a list of Process names. Enclose the list in
parentheses, and separate each value with a comma.

pnumber Locate the Process to remove number from 1–99,999 | (list)

by Process number. IBM
number—Specifies the Process number.
Connect:Direct assigns the
Process number when the list—Specifies a list of Process numbers. Enclose the list
Process is submitted. in parentheses, and separate each value with a comma.

snode Locate the Process to remove remote node specification | generic | (list)
by the secondary node name.
remote node specification—Identifies a specific remote
This parameter can be used
node name.
to specify a specific remote
node, a generic value for generic—Specifies a nonspecific value for the remote
matching remote node node name. This generic value, containing pattern-
names (using pattern matching characters, evaluates to a list of zero or more
matching), or a list of remote node names.
multiple remote node names.
list—Specifies a list of remote node specifications.
The secondary node name Enclose the list in parentheses, and separate each value
typically contains the 1–16 with a comma.
character remote IBM
Connect:Direct node name,
but can be any string up to
256 alphanumeric characters
long. You can also specify a
remote node name as an IP
address or hostname and a
port number.

Chapter 4. User Guide 157

 Parameter Description Value
submitter Locate the Processes to (node specification, userid) | generic | (list)
remove by the node
node specification, userid—Specifies the node
specification (the IBM
specification (the IBM Connect:Direct node name) and
Connect:Direct node name)
user ID.
and user ID of the Process
owner. generic—Specifies a nonspecific value for node
specification and user ID. This generic value, containing
pattern-matching characters, evaluates to a list of zero
or more node specifications and user IDs.
list—Specifies a list of node specification and user ID
pairs. Enclose the list in parentheses, and separate each
value with a comma.

The flush process command has the following optional parameters:

Parameter Description Value

force Forcibly terminates an executing yes | no
Process or terminates a Process in an
yes—Specifies to forcibly and immediately
orderly fashion as the step
terminate the Process. The SMGR also terminates
completes. This parameter is useful
immediately.
if a Process is in the executing state
and waiting for unavailable no—Specifies to terminate the Process in an
resources. orderly fashion as the step completes. The SMGR
closes the statistics file and then terminates. This
is the default.

hold Places the terminated Process in the yes | no

Hold queue where it can be released
yes—Specifies to place the Process in the Hold
for re-execution.
queue in HS status after the Process is terminated.
no—Specifies to delete the Process from the TCQ
after the Process is terminated. This is the default.

The following command flushes all executing Processes named “Rome” from the Execution queue:

flush process pname=rome force=yes;

The following command flushes all executing Processes on node alma submitted by user ID jones:

flush process submitter=(alma, jones);

Stopping IBM Connect:Direct

The stop command initiates an orderly IBM Connect:Direct shutdown sequence or forcibly terminates the
software. After you run the stop command, no new Processes are allowed to run and no new connections
with remote systems are established. Commands can be issued and users can sign on until the server
terminates.
You can specify the force, immediate, quiesce, or step parameters with the stop command.
Note: The force parameter is required when running IBM Connect:Direct with the LU6.2 feature on any
supported platform other than AIX.
Following are the parameters for the stop command:

158 IBM Connect:Direct for UNIX: Documentation

 Parameter Description
force Forcibly terminates IBM Connect:Direct and
returns control to the operating system.
immediate Begins an immediate, but orderly shutdown of all
activity and terminates IBM Connect:Direct. The
software terminates connections, writes statistics
records, closes files, and shuts down.
quiesce Runs all executing Processes to completion before
shutting down IBM Connect:Direct. No new
Processes are started. This is the default value.
step Shuts down IBM Connect:Direct after all currently
executing Process steps are complete. The
software writes statistics records, closes files, and
shuts down. All active Processes are retained in the
TCQ. Processes restart when the software is re-
initialized.

The following command forcibly terminates IBM Connect:Direct and returns control to the operating
system:

stop force;

Viewing a Process in the TCQ

The view process command is used to view Processes in the TCQ when the local node is the PNODE. You
can search by Process name, Process number, queue, secondary node, status, owner of the Process, or
any combination of the search criteria parameters.
You also can specify more than one Process in the search criteria.
There are no required parameters for this command. If you do not specify an optional parameter, IBM
Connect:Direct selects all Processes executing or waiting for execution. Following are the optional
parameters for the view process command:

Parameter Description Value

pname Locate the Process to view by name | generic | (list)
Process name.
name—Specifies the Process name, up to 8
The Process name is limited to 8 alphanumeric characters.
characters on Connect:Direct for
generic—Specifies a nonspecific value for the
Microsoft Windows and
Process name. This generic value, containing
Connect:Direct for z/OS.
pattern-matching characters, evaluates to a list of
zero or more pname strings.
list—Specifies a list of Process names. Enclose the
list in parentheses, and separate each value with a
comma.

pnumber Locate the Process to view by number from 1–99,999 | (list)

Process number. IBM
number—Specifies the Process number.
Connect:Direct assigns the
Process number when the list—Specifies a list of Process numbers. Enclose the
Process is submitted. list in parentheses, and separate each value with a
comma.

Chapter 4. User Guide 159

 Parameter Description Value
queue Specifies the Processes to be all | exec | hold | wait | timer
viewed by the specified queue
all—Selects Processes from all queues. This is the
names.
default.
exec—Selects Processes from the Execution queue.
hold—Selects Processes from the Hold queue.
timer—Selects Processes from the Timer queue.
wait—Selects Processes from the Wait queue.

snode View the Process by the remote node specification | generic | (list)
secondary node name. This
remote node specification—Identifies a specific
parameter can be used to specify
remote node name.
a specific remote node, a generic
value for matching remote node generic—Specifies a nonspecific value for the remote
names (using pattern matching), node name. This generic value, containing pattern-
or a list of multiple remote node matching characters, evaluates to a list of zero or
names. more remote node names.
The secondary node name list—Specifies a list of remote node specifications.
typically contains the 1–16 Enclose the list in parentheses, and separate each
character remote IBM value with a comma.
Connect:Direct node name, but
can be any string up to 256
alphanumeric characters long.
You can also specify a remote
node name as an IP address or
hostname and a port number.

160 IBM Connect:Direct for UNIX: Documentation

Parameter Description Value
status Specifies the Processes to be EX | HC | HE | HI | HO | HR | HS | PE | WC | WR | WS |
viewed by Process status. If you (list)
do not specify a status value,
EX (Execution)—Specifies to select Processes from
information is generated for all
the Execution queue.
status values.
HC (Held for Call)—Specifies to select Processes
submitted with hold=call.
HE (Held due to Error)—Specifies to select Processes
held due to a connection error.
HI (Held Initially)—Specifies to select Processes
submitted with hold=yes.
HO (Held by Operator)—Specifies to select Processes
held by a change process command issued with
hold=yes.
HR (Held Retain)—Specifies to select Processes
submitted with retain=yes or retain=initial.
HS (Held Due to Execution Suspension)—Specifies to
select Processes suspended by a flush process
command issued with hold=yes.
PE (Pending Execution)—Specifies to select
Processes submitted with a maxdelay parameter
and assigned PE status by the Process Manager just
before a Session Manager is created to execute the
Process. After the Session Manager initializes, the
Process is placed on the Execution queue and the
status is changed to EX.
WC (Waiting for Connection)—Specifies to select
Processes that are ready for execution, but that all
available connections to the remote node are in use.
WR (Waiting for Restart)—Specifies to select
Processes that are waiting for restart after session
failure.
WS (Waiting for Start Time)—Specifies to select
Processes waiting for a start time. These Processes
are on the Timer Queue.
list—Specifies a list of status values. Enclose the list
in parentheses, and separate each value with a
comma.

Chapter 4. User Guide 161

 Parameter Description Value
submitter Locate the Processes to view by (node specification, userid) | generic | (list)
the node specification (the IBM
node specification, userid—Specifies the node
Connect:Direct node name) and
specification (the IBM Connect:Direct node name)
user ID of the Process owner. The
and user ID.
length of this parameter is
unlimited. generic—Specifies a nonspecific value for node
specification and user ID. This generic value,
containing pattern-matching characters, evaluates to
a list of zero or more node specifications and user
IDs.
list—Specifies a list of node specification and user ID
pairs. Enclose the list in parentheses, and separate
each value with a comma.

The following command displays the specified Process number:

view process pnumber=1;

Monitoring Process Status in the TCQ

The select process command displays information about Processes in the TCQ.
The search criteria provide flexibility in selecting Processes. You can search for a Process by Process
name, Process number, queue, secondary node, status, owner of the Process, or any combination of the
search criteria parameters.
You also can specify more than one Process in the search criteria. You can request either a detailed report
about the selected Process or a short report.
There are no required parameters for this command. If you do not specify an optional parameter, IBM
Connect:Direct selects all Processes executing or waiting for execution. Following are the optional
parameters for the select process command:

Parameter Description Value

pname Locate the Process to select by name | generic | (list)
Process name.
name—Specifies the Process name, up to 8
The Process name is limited to 8 alphanumeric characters.
characters on Connect:Direct for
generic—Specifies a nonspecific value for the
Microsoft Windows and
Process name. This generic value, containing
Connect:Direct for z/OS.
pattern-matching characters, evaluates to a list of
zero or more pname strings.
list—Specifies a list of Process names. Enclose the
list in parentheses, and separate each value with a
comma.

pnumber Locate the Process to select by number from 1–99,999 | (list)

Process number. IBM
number—Specifies the Process number.
Connect:Direct assigns the
Process number when the list—Specifies a list of Process numbers. Enclose the
Process is submitted. list in parentheses, and separate each value with a
comma.

162 IBM Connect:Direct for UNIX: Documentation

Parameter Description Value
queue Specifies the Processes to be all | exec | hold | wait | timer
selected by the specified queue
all—Selects Processes from all queues. this is the
names. The default is all.
default.
exec—Selects Processes from the Execution queue.
hold—Selects Processes from the Hold queue.
timer—Selects Processes from the Timer queue.
wait—Selects Processes from the Wait queue.

snode Locate the Process by the remote node specification | generic | (list)
secondary node name. This
remote node specification—Identifies a specific
parameter can be used to
remote node name.
specify a specific remote node, a
generic value for matching generic—Specifies a nonspecific value for the remote
remote node names (using node name. This generic value, containing pattern-
pattern matching), or a list of matching characters, evaluates to a list of zero or
multiple remote node names. more remote node names.
The secondary node name list—Specifies a list of remote node specifications.
typically contains the 1–16 Enclose the list in parentheses, and separate each
character remote IBM value with a comma.
Connect:Direct node name, but
can be any string up to 256
alphanumeric characters long.
You can also specify a remote
node name as an IP address or
hostname and a port number.

Chapter 4. User Guide 163

 Parameter Description Value
status Specifies the Processes to be EX | HC | HE | HI | HO | HR | HS | PE | WC | WR | WS |
selected by Process status. If (list)
you do not specify a status
EX (Execution)—Specifies to select Processes from
value, information is generated
the Execution queue.
for all status values.
HC (Held for Call)—Specifies to select Processes
submitted with hold=call.
HE (Held due to Error)—Specifies to select Processes
held due to a connection error.
HI (Held Initially)—Specifies to select Processes
submitted with hold=yes.
HO (Held by Operator)—Specifies to select Processes
held by a change process command issued with
hold=yes.
HR (Held Retain)—Specifies to select Processes
submitted with retain=yes or retain=initial.
HS (Held Due to Execution Suspension)—Specifies to
select Processes suspended by a flush process
command issued with hold=yes.
PE (Pending Execution)—Specifies to select
Processes submitted with a maxdelay parameter
and assigned PE status by the Process Manager just
before a Session Manager is created to execute the
Process. After the Session Manager initializes, the
Process is placed on the Execution queue and the
status is changed to EX.
WC (Waiting for Connection)—Specifies to select
Processes that are ready for execution, but that all
available connections to the remote node are in use.
WR (Waiting for Restart)—Specifies to select
Processes that are waiting for restart after session
failure.
WS (Waiting for Start Time)—Specifies to select
Processes waiting for a start time. These Processes
are on the Timer Queue.
list—Specifies a list of status values. Enclose the list
in parentheses, and separate each value with a
comma.

164 IBM Connect:Direct for UNIX: Documentation

 Parameter Description Value
submitter Locate the Processes to select (node specification, userid) | generic | (list)
by the node specification (the
node specification, userid—Specifies the node
IBM Connect:Direct node name)
specification (the IBM Connect:Direct node name)
and user ID of the Process
and user ID.
owner. The length of this
parameter is unlimited. generic—Specifies a nonspecific value for node
specification and user ID. This generic value,
containing pattern-matching characters, evaluates to
a list of zero or more node specifications and user
IDs.
list—Specifies a list of node specification and user ID
pairs. Enclose the list in parentheses, and separate
each value with a comma.

detail Specifies the type of report yes | no

(short or detailed) that IBM
yes—Generates a detailed report.
Connect:Direct generates for the
selected Processes. no—Generates a short report. This is the default.

The following command displays a short report for the specified Process number:

select process pnumber=9 detail=no;

Output from the command is displayed in the following table:

===================================================================================
SELECT PROCESS
===================================================================================
PROCESS NAME NUMBER USER SUBMITTER NODE QUEUE STATUS
-----------------------------------------------------------------------------------
PR01 9 root cd.unix.pj EXEC EX
===================================================================================

The following command displays a detailed report for the specified Process number:

select process pnumber=9 detail=yes;

Output from the command is displayed in the following table:

===================================================================================
SELECT PROCESS
===================================================================================
Process Name => pr01 Class => 9
Process Number => 9 Priority => 8
Submitter Node => cd.unix.pj PNODE => cd.unix.pj
Submitter => sub1 SNODE => cd.unix.pj
Retain Process => no Header Type => p

Submit Time => 19:52:35 Schedule Time =>

Submit Date => 05/22/1996 Schedule Date =>

Queue => EXEC

Process Status => EX
Message Text =>
-----------------------------------------------------------------------------------

Determining the Outcome of a Process

The select statistics command is used to examine Process statistics from the Connect:Direct statistics
file. The type of information in the statistics report includes copy status and execution events.

Chapter 4. User Guide 165

 The search criteria provide flexibility in selecting information you want to display. The parameters used
with the select statistics command determine search criteria and the form in which the information is
presented. You can specify records to select by condition code, Process name, Process number,
identification type, category, secondary node, start time, stop time, and submitter node specification and
user ID.
There are no required parameters for this command. If you do not indicate a search requirement with an
optional parameter, Connect:Direct selects all statistics records; however, the volume of records can be
excessive. Following are parameters for the select statistics command:

Parameter Description Value

ccode Selects statistics records operator, nn
based on the completion
operator—Specifies the completion code operator.
code operator and return
Following are the valid completion code operators:
code values associated with
Step Termination. You must eq or = or == (equal) This is the default.
specify the return code.
ge or >= or => (greater than or equal)
gt or > (greater than)
le or <= or =< (less than or equal)
lt or < (less than)
ne or != (not equal)
The return code is the exit status of the UNIX command
or the Connect:Direct Process or command.
nn—Specifies the return code value associated with Step
Termination.

destfile Selects statistics based on a dest=/path/file name

destination file name. This
For example:
parameter can be
abbreviated as dest. sel stat dest=/sci/payroll/june.payroll;
This parameter can be used in combination with the
srcfile parameter to select statistics based on a source
file name and a destination file name, for example:
sel stat srcf=/sci/accounting/june.payroll dest=/sci/
payroll/june.payroll

pname Locate the statistics to select name | generic | (list)

by Process name.
name—Specifies the Process name, up to 8 alphanumeric
The Process name is limited characters.
to 8 characters on
generic—Specifies a nonspecific value for the Process
Connect:Direct for Microsoft
name. This generic value, containing pattern-matching
Windows and Connect:Direct
characters, evaluates to a list of zero or more pname
for z/OS.
strings.
list—Specifies a list of Process names. Enclose the list in
parentheses, and separate each value with a comma.

pnumber Locate the statistics to select number from 1–99,999 | (list)

by Process number.
number—Specifies the Process number.
Connect:Direct assigns the
Process number when the list—Specifies a list of Process numbers. Enclose the list
Process is submitted. in parentheses, and separate each value with a comma.

166 IBM Connect:Direct for UNIX: Documentation

Parameter Description Value
reccat Specifies whether the CAEV | CAPR | (CAEV, CAPR)
selection of statistics file
CAEV—Specifies that the selection of statistics file
records is based on events or
records is related to an event, such as a IBM
related to a Process.
Connect:Direct shutdown.
CAPR—Specifies that the selection of statistics file
records is related to one or more IBM Connect:Direct
Processes.

recids Specifies the statistics file record id | (list)

records to be selected by
record id—Selects statistics file records for the specified
record ID. This parameter
record ID.
identifies particular types of
statistics records, such as a list—Specifies a list of Process names. Enclose the list in
copy termination records or parentheses, and separate each value with a comma.
Connect:Direct initialization
Following are the valid record ID values:
event records.
APSM—License Management failure generated.
CHFA—Change Functional Authority command issued.
CHGP—The change process command issued.
CHPX—Change Proxy command issued.
CRHT—Copyright statement.
COAC—Listen connection enabled for either API or a
remote node.
CSPA—Connect:Direct Secure Plus failure generated.
CSPE—Strong Password Encryption event.
CSTP—Child Process stopped.
CTIM—Command Manager inactivity timer popped.
CTRC—Copy termination record.
CTRM—Child Process terminated.
CUKN—Child Process unknown status.
CXIT—Child Process exited.
DELP—The delete Process command issued.
DLFA—Delete Functional Authority command issued.
DLPX—Delete Proxy command issued.
FLSP—The flush Process command issued.
FMRV—Error occurred in function management.
information receive operation.
FMSD—Error occurred in function management.
information send operation.
GPRC—Error occurred while getting Process.

Chapter 4. User Guide 167

 Parameter Description Value

IFED—The if statement ended.

LIEX—License expired.
LIOK—Listen okay.
LSED—Local Process Step Ended.
LSST—The record ID of a step on the local node.
LWEX—License expires within 14 days.
NAUH—Node Authorization check issued.
NINF—IBM Connect:Direct information generated at
startup.
NMOP—Network map file opened.
NMPR—The network map is updated through
Connect:Direct Browser User Interface, Control Center
Console, or KQV Interface.
NUIC—Initialization complete.
NUIS—Initialization started.
NUTC—Termination completed.
NUTS—Termination started.
PERR—Process error.
PFLS—Process flushed.
PPER—Pipe Error.
PRED—Process ended.
PRIN—Process interrupted.
PSAV—Process saved.
PSED—Process Step Ended.
PSTR—Process started.
QCEX—A Process moved from another queue to the EXEC
queue.
QCWA—A Process moved from another queue to the
WAIT queue.
QCTI—A Process moved from another queue to the
TIMER queue.
QCHO—A Process moved from another queue to the
HOLD queue.
QERR—Test Mode error event.
RFIP—Refresh initparms command issued.

168 IBM Connect:Direct for UNIX: Documentation

Parameter Description Value

RJED—The run job ended.

RNCF—Remote node connection failed.
RSED—Remote Process Step Ended.
RSST—The record ID of a step on the remote node.
RTED—The run task ended.
RTRS—Run Task Restarted.
RTSY—Run task restarted. Re-syncing with run task that
was executing.
SBED—The submit ended.
SCNT—Max session count.
SCPA—Step end status.
SELM—Select message command issued.
SELP—The select Process command issued.
SELS—The select statistics command issued.
SEND—Session ended.
SERR—System error.
SFSZ—Size of the file submitted.
SGON—User signed on using KQV Interface or Command
Line Interface.
SHUD—Shutdown occurred.
SIGC—Signal caught.
SLFA—Select func. Authority command issued.
SLIP—Select initparms command issued.
SLNM—Select netmap command issued.
SLPX—Select proxy command issued.
SLSG—Select signature command issued.
SPAC—S+ cmd add key certificate.
SPAT—S+ cmd add trusted root certificate.
SPCL—S+ cmd add alias node.
SPCN—S+ cmd add node.
SPDN—S+ cmd delete node.

Chapter 4. User Guide 169

 Parameter Description Value

SPGC—S+ cmd select ciphersuites.

SPRK—S+ cmd rekey parmfile.
SPSC—S+ cmd select key certificate.
SPSN—S+ cmd select nodes.
SPST—S+ cmd select trusted root certificates.
SPSY—S+ cmd sync netmap.
SPUC—S+ cmd change key certificate.
SPUN—S+ cmd change node.
SPUT—S+ cmd change trusted root certificate.
SPVP—S+ cmd validate parmfile.
SSTR—Session start.
STOP—The stop command issued.
SUBP—The submit command issued.
SUBV—Validate Process command issued.
TRAC—The trace command issued.
TZDI—The time zone of the local node represented as the
difference in seconds between the time at the local node
and the Coordinated Universal Time.
UNKN—Unknown command issued.
USEC—Security check for user ID failed.
USMG—IBM Connect:Direct is shutting down.
VEWP—View Process command issued.
Logged messages may not have an explicitly defined
record id. These messages default the record id to the
first four characters of the message. Some examples are
listed below.
XCMM—Command manager (CMGR) messages.
XCPR—Copy receive.
XCPS—Copy send.
XIPT—Communication errors.
XLKL—Low-level TCQ record locking errors.
XMSG—Message sent to user exit.

170 IBM Connect:Direct for UNIX: Documentation

Parameter Description Value

XPAC—Process parsing message.

XPAE—Parsing error occurred when a Process or
command was submitted.
XPAM—Parsing error occurred when a Process or
command was submitted.
XPMC—Process manager (PMGR) connection error
messages.
XPML—PMGR statistics log error messages.
XPMP—PMGR error messages when checking permission
on the Connect:DirectSelect programs.
XPMR—PMGR RPC and miscellaneous error messages.
XPMT—PMGR termination error messages.
XRPM—Run task or run job error messages.
XRRF—Relative record file access error messages. File
structure is use for TCQ.
XSMG—Session manager (SMGR) error messages.
XSQF—File access error messages.
XSTA—User exit program started.
XTQG—A single TCQ error message group.
XTQZ—A single TCQ error message group.

snode Locate the statistics file remote node specification | generic | (list)
record by the secondary node
remote node specification—Identifies a specific remote
name. This parameter can be
node name.
used to specify a specific
remote node, a generic value generic—Specifies a nonspecific value for the remote
for matching remote node node name. This generic value, containing pattern-
names (using pattern matching characters, evaluates to a list of zero or more
matching), or a list of remote node names.
multiple remote node names.
list—Specifies a list of remote node specifications.
The secondary node name Enclose the list in parentheses, and separate each value
typically contains the 1–16 with a comma.
character remote
Connect:Direct node name,
but can be any string up to
256 alphanumeric characters
long. You can also specify a
remote node name as an IP
address or hostname and a
port number.

Chapter 4. User Guide 171

 Parameter Description Value
srcfile Selects statistics based on a srcf=/path/file name
source file name. This
For example:
parameter can be
abbreviated as srcf. sel stat srcf=/sci/accounting/june.payroll;
This parameter can be used in combination with the
destfile parameter to select statistics based on a source
file name and a destination file name, for example:
sel stat srcf=/sci/accounting/june.payroll dest=/sci/
payroll/june.payroll

startt Selects records produced [date | day] [, hh:mm:ss [am|pm]]

both at and since the
date—Specifies the day (dd), month (mm), and year (yy),
specified time. The date or
which you can code as mm/dd/yyyy or mm-dd-yyyy. If
day and time are positional.
you only specify date, the time defaults to 00:00:00. The
If you do not specify date or
current date is the default.
day, a comma must precede
time. day—Specifies the day of the week. Values are today,
monday, tuesday, wednesday, thursday, friday, saturday,
and sunday.
hh:mm:ss [am | pm]—Specifies the time of day in hours
(hh), minutes (mm), and seconds (ss). You can specify the
hour in either 12- or 24-hour format. If you use 12-hour
format, then you must specify am or pm. The default is
the 24-hour format. The default value is 00:00:00, which
indicates midnight. If you specify only the day value, the
time defaults to 00:00:00.

stopt Specifies that Connect:Direct [date | day] [, hh:mm:ss [am|pm]]

searches for statistics
date—Specifies the day (dd), month (mm), and year (yy),
records up to and including
which you can code as mm/dd/yyyy or mm-dd-yyyy. If
the designated date, day, and
you only specify date, the time defaults to 00:00:00. The
time positional parameters. If
current date is the default.
you do not specify date or
day, a comma must precede day—Specifies the day of the week. Values are today,
time. monday, tuesday, wednesday, thursday, friday, saturday,
and sunday.
hh:mm:ss [am | pm]—Specifies the time of day in hours
(hh), minutes (mm), and seconds (ss). You can specify the
hour in either 12- or 24-hour format. If you use 12-hour
format, then you must specify am or pm. The default is
the 24-hour format. The default value is 00:00:00, which
indicates midnight. If you specify only the day value, the
time defaults to 00:00:00.

172 IBM Connect:Direct for UNIX: Documentation

 Parameter Description Value
submitter Locate the statistics records (node specification, userid) | generic | (list)
to select by the node
node specification, userid—Specifies the node
specification (the
specification (the Connect:Direct node name) and user
Connect:Direct node name)
ID.
and user ID of the Process
owner. The character length generic—Specifies a nonspecific value for node
of the parameter is unlimited. specification and user ID. This generic value, containing
pattern-matching characters, evaluates to a list of zero or
more node specifications and user IDs.
list—Specifies a list of node specification and user ID
pairs. Enclose the list in parentheses, and separate each
value with a comma.

detail Specifies the type of report yes | no

(short or detailed) that
yes—Generates a detailed report.
Connect:Direct generates for
the selected Processes. no—Generates a short report. This is the default.

Generating a Detailed Output Report for a Process

You can use the select statistics command to generate a detailed report for a Process. The following
command generates a detailed report for Process number 9:

select statistics pnumber=9 detail=yes startt=(08/10/2008);

The report consists of all records from August 10, 2008.

A sample statistics output for two steps only is listed in the following section. Use the table of recids in
“Determining the Outcome of a Process” on page 165 to interpret the Record ID. The Record ID can
change for each Process step displayed. The completion code indicates whether the Process executed
successfully or produced an error condition.
To display the long text of the message, issue the ndmmsg command.

Generating a Summary Report for a Process

You can use the select statistics command to generate a summary report for a Process. The following
command generates summary statistics for Process number 9:

sel stat pnumber=9 detail=no startt=(08/10/2008);

The report consists of all records from August 10, 2008.

Sample output that describes all Process steps in summary form is displayed in the following table:

===================================================================================
SELECT STATISTICS
===================================================================================
P RECID LOG TIME PNAME PNUMBER STEPNAME CCOD FDBK MSGID
-----------------------------------------------------------------------------------
P PSTR 08/10/2008 09:10:39 PR01 9 0 XSMG200I
P IFED 08/10/2008 09:10:44 PR01 9 0 XSMG405I
P CTRC 08/10/2008 09:10:44 PR01 9 0 XSMG405I
P IFED 08/10/2008 09:10:45 PR01 9 4 XSMG400I
P RTED 08/10/2008 09:10:45 PR01 9 0 XSMG400I
P IFED 08/10/2008 09:10:45 PR01 9 4 XSMG400I
P CTRC 08/10/2008 09:10:45 PR01 9 0 XSMG405I
P CTRC 08/10/2008 09:10:45 PR01 9 8 XSMG405I

Chapter 4. User Guide 173

 P CTRC 08/10/2008 09:10:45 PR01 9 8 XSMG405I
===================================================================================

To avoid lengthy search times when issuing the select statistics command, archive or delete statistics
files regularly. Also, use the startt and stopt parameters to bracket the desired stats as closely as
possible. Execution of a Process generates multiple statistics records. IBM Connect:Direct closes the
current statistics file and creates a new statistics file every midnight. It can also close the current file
before midnight if the file size exceeds the value set for the file.size initialization parameter. The default
file size is 1 megabyte.
Statistics files are in the d_dir/work/cd_node directory. Names of the statistics file are in the format
Syyyymmdd.ext, where yyyy indicates year, mm indicates month, and dd indicates day. The extension
(ext) begins as 001. The extension is incremented by one each time a new statistics file is created in a
single day.

Running System Diagnostics

The diagnostic command, trace, enables you to run system diagnostics and troubleshoot operational
problems. Use the trace command with the appropriate parameter listed in the following table to enable
and disable runtime traces within the Process Manager, Command Manager, and Session Manager
components of the software. For Session Manager traces, you can run a trace for a specific node.
The Command Manager trace is turned on immediately for the client that issued the trace command. After
the trace command is issued, all clients that make connections are also traced. Session Manager traces go
into effect immediately.
The trace command has the following parameters:

Parameter Description Value

cmgr To trace the Command level=0 |1 | 2 | 4
Manager.
file=name
level—Specifies the level of detail displayed in the
trace output. The default is 4.
0—Terminates the trace.
1—Is the basic level that provides function entry and
function exit.
2—Includes level 1 plus function arguments.
4—Enables a full trace. Basic diagnostic information,
such as values of internal data structures at key points
in the execution flow, are displayed.
file—Specifies the name of a file where the trace output
is directed. If you do not specify a file name, the file is
created in the IBM Connect:Direct working directory
with the file name CMGR.TRC. The length of the name
value is unlimited.

174 IBM Connect:Direct for UNIX: Documentation

Parameter Description Value
comm To trace the data sent to and level=0 |1 | 2 | 4
received from a remote IBM
file=name
Connect:Direct system within
the Session Manager. You can level—Specifies the level of detail displayed in the
set this trace independently trace output. The default is 4.
from or in conjunction with the
0—Terminates the trace.
smgr trace.
1—Is the basic level that provides function entry and
If you run both the comm and function exit.
smgr traces, trace output for 2—Includes level 1 plus function arguments.
both traces is directed to the 4—Enables a full trace that provides basic diagnostic
file name of the trace last information, such as values of internal data structures
specified. at key points in the execution flow.
file—Specifies the name of a file where the trace output
is directed. If you do not specify a file name, the file is
created in the IBM Connect:Direct working directory
with the file name COMM.TRC. The length of the name
value is unlimited. The default file name is COMM.TRC.

pmgr To trace the Process Manager. level=0 |1 | 2 | 4

file=name
level—Specifies the level of detail displayed in the
trace output. The default is 4.
0—Terminates the trace.
1—Is the basic level that provides function entry and
function exit.
2—Includes level 1 plus function arguments.
4—Enables a full trace that provides basic diagnostic
information, such as values of internal data structures
at key points in the execution flow.
file—Specifies the name of a file where the trace output
is directed. If you do not specify a file name, the file is
created in the IBM Connect:Direct working directory
with the file name PMGR.TRC. The length of the name
value is unlimited.

Chapter 4. User Guide 175

 Parameter Description Value
smgr To run the trace for Session level=0 |1 | 2 | 4
Managers created after issuing
snode | pnode | tnode
the trace command. Currently
executing Session Managers file=name
are unaffected.
level—Specifies the level of detail displayed in the
If you run both the comm and trace output. The default is 4.
smgr traces, trace output for
0—Terminates the trace.
both traces is directed to the
1—Is the basic level that provides function entry and
file name of the trace last
function exit.
specified.
2—Includes level 1 plus function arguments.
4—Enables a full trace that provides basic diagnostic
information, such as values of internal data structures
at key points in the execution flow.
snode—Specifies to trace only the SNODE SMGR.
pnode—Specifies to trace only the PNODE SMGR.
tnode—Identifies the node on which to perform the
trace. If you want to gather trace information for more
than one node, identify more than one node in this
parameter.
file—Specifies the name of a file where the trace output
is directed. If you do not specify a file name, the file is
created in the IBM Connect:Direct working directory
with the file name SMGR.TRC. The length of the name
value is unlimited. The default file name is SMGR.TRC.

The following sample trace command performs a level 2 trace on the Session Manager for the node called
ath3500ry and writes the output to the file Smgp.trc:

trace smgr pnode tnode=ath3500ry level=2 file=Smgp.trc;

A partial sample trace output is illustrated in the following section. A trace identifies the Process ID and
the function, the month and day, and the time in microseconds. The first column contains the Process ID.
Column two indicates the month and day in the form of MM/DD. Column three indicates the time in the
form of HH:MM:SSSS. The last column indicates the function. An arrow pointing to the right indicates the
function was entered. An arrow pointing to the left indicates the function was exited. Some of the
functions are indented, which indicates nesting. An indented arrow indicates that the function was called
by the preceding function.

indicates that the function was called by the preceding function.

===================================================================================
498 05/18 15:13:0104 cm_sendcmd_1 entered.
498 05/18 15:13:0206 -> ndm_error_destroy
<- ndm_error_destroy: ok
498 05/18 15:13:0506 -> ndm_error_create
<- ndm_error_create: ok
498 05/18 15:13:0708 ndm_cmds_free entered.
ndm_cmds_free exited.
498 05/18 15:13:0801 ->ndm_parser_jdi
498 05/18 15:13:0806 -> ndm_error_create
<- ndm_error_create: ok
498 05/18 15:13:0916 ->Parser: SELPRO
498 05/18 15:13:0926 ->bldexp
<-bldexp: Null argument value,
don&apos;t add.
498 05/18 15:13:1116 ->bldexp
498 05/18 15:13:1136 -> ndm_crit_comp
498 05/18 15:13:1155 ->compile
<-compile
<- ndm_crit_comp: Handle

176 IBM Connect:Direct for UNIX: Documentation

 <-bldexp: ok
.
.
.
===================================================================================

Process Queuing
The TCQ controls Process execution as IBM Connect:Direct operates. After you submit a Process, it is
stored in the TCQ. The TCQ consists of four queues: Execution, Wait, Timer, and Hold.
After you submit a Process, you can monitor the status, modify specific characteristics, and stop
execution by using the appropriate commands. The commands listed in the following table allow you to
perform these tasks:

Command Definition
change process Change the status and modify specific
characteristics of a nonexecuting Process in the
TCQ.
delete process Remove a nonexecuting Process from the Wait,
Timer, and Hold queues.
flush process Remove an executing Process from the Execution
queue.
select process Monitor Processes in the TCQ, including those
Processes that are executing.
view process View Processes in the TCQ.

Scheduling IBM Connect:Direct Activity

IBM Connect:Direct places a Process in a queue based on the parameters that affect scheduling. You can
specify scheduling parameters in the Process statement or the submit command.
Scheduling parameters are listed in the following section:
• retain=yes|no|initial
• hold=yes|no|call
• startt=[([date|day] [, hh:mm:ss | [am | pm]])
The following table shows how scheduling parameters affect the logical queues.

Scheduling Parameter Queue Comments

None of the scheduling Wait The Process remains in the Wait queue until IBM
parameters specified Connect:Direct establishes a session with the remote
node. After a session is established, the Process moves
to the Execution queue.
retain=yes Hold A copy of the Process executes once, unless you specify
a startt parameter value. Specify a day or time or both for
the Process to start.
retain=no Wait (if no other The Process remains in the Wait queue until IBM
parameters are Connect:Direct establishes a session with the remote
specified) node. The default is no.
retain=initial Hold A copy of the Process remains in the Hold queue and
executes every time the Process Manager is initiated.

Chapter 4. User Guide 177

 Scheduling Parameter Queue Comments
retain=yes and hold=no Hold A copy of the Process remains in the Hold queue to be
or hold=call executed when released.
hold=yes Hold You can execute the Process by specifying the change
process command with the release parameter.
hold=no Wait (if no other The default for hold is no.
parameters are
specified)
hold=call Hold The Process remains in the queue until the remote node
starts a session with the local node or another Process
starts a session with that remote node.
startt Timer When the scheduled day or time occur, the Process is
moved to the Wait queue.

Each Process in the TCQ has an associated status value. Each status value has a unique meaning that is
affected by the logical queue in which the Process is placed. Status values for each queue are shown in
the tables in the following sections. You can use the select process command to examine that status of
Processes in the TCQ. For example, the following command displays all Processes in the TCQ with
execution status:

select process status=EX;

Progression of a Process Through the TCQ

This section describes each logical queue of the TCQ and the progression of a Process through these
queues. The following figure illustrates the four logical queues and their associated parameter values:

178 IBM Connect:Direct for UNIX: Documentation

The Execution Queue
Processes are placed in the Execution queue after IBM Connect:Direct connects to the remote node.
Processes normally come from the Wait queue, but also can be placed in the Execution queue by a submit
command with maxdelay=0 specified.

Processes in the Execution queue can be in execution (EX) status or pending execution (PE) status.
Processes with EX status are exchanging data between two IBM Connect:Direct nodes. Processes with PE
status are waiting for Process start messages to be exchanged between the local node and the remote
node. Processes usually have PE status assigned for a very short period of time.
After a Process successfully completes, it is automatically deleted from the Execution queue. A flush
process command with hold=yes moves a Process from the Execution queue and places it in the Hold
queue. When a session is interrupted, the Process moves from the Execution queue to the Timer queue if
retry values are specified. If connection is not made before the retry values are exhausted or if retry

Chapter 4. User Guide 179

 values are not specified, the action taken depends on the conn.retry.exhaust.action parameter. By
default, the Process moves to the Hold queue.
The following table shows the status values for the Execution queue:

Element Comment
PE Pending Execution is the initial queue status when
a Process is submitted with maxdelay=0.
EX Execution status indicates that the Process is
executing.

The Wait Queue

Processes in the Wait queue are waiting for a new or existing connection to become available between the
local node and the remote node.

Processes can come from the Hold queue or the Timer queue. Processes also can be placed in the Wait
queue by a submit command with no parameters specified, submit with retain=no, or submit with
hold=no.
After the connection is made, Processes automatically move to the Execution queue.
The following table shows the status values for the Wait queue:

Status Comment
WC This status indicates the Process is ready to
execute as soon as possible, but no session is
available. Other Processes may be executing with
the SNODE, and no other sessions are available.
This Process runs as soon as a new session is
created or an existing session becomes available.
WR This status indicates that the Process is in retry
status. The number of retries and intervals
between retries is specified in the network map.
WA This status indicates the initial queue status when
a Process is submitted without a hold or retain
value. This Process is ready to execute as soon as
possible.
WS This status indicates that the Process is waiting for
the PNODE to continue the session.

The Timer Queue

Processes are placed in the Timer queue by a submit command with the startt parameter specified.
Processes in the Wait for Start Time (WS) status are waiting for the start time to arrive before moving to
the Wait queue. Processes also are placed in the Timer queue in Retry (WC) status if one of the following
error conditions occur:

• If a file allocation error occurs when a Process is executing on either the local or the remote node, and
the file allocation error is identified as a condition to retry, the Process is placed in the Timer queue. The
Process is then retried using the short-term and long-term retry parameter definitions. This capability
enables a Process that was unable to execute because a file that it called was unavailable to be retried
at a later time.

180 IBM Connect:Direct for UNIX: Documentation

• If a connection error occurs while a Process is executing, the intelligent session retry facility places all
Processes scheduled for the node, including the executing Process, in the Timer queue. This capability
eliminates the overhead required to retry each of the Processes on the node even though the
connection is lost.
• If CRC checking is activated, a Process that generates a CRC error is placed in the Timer queue.
IBM Connect:Direct automatically tries to execute the Process again based on the number of times to
retry and the delay between retries as specified in the network map parameters.
Processes move from the Timer queue to the Wait queue. A change process command with hold=yes
specified moves the specified Process from the Timer queue to the Hold queue. The following table shows
the status values for the Timer queue:

Status Comment
WR This status indicates that the Process is in retry
status. The number of retries and intervals
between retries is specified in the network map.
WS This status indicates that the Process is waiting for
the PNODE to continue the session.
HR Held Retain indicates that the Process was
submitted with retain=yes or retain=initial
specified and has already executed. The Process
can be released later by a change process
command with release specified.
WC This status indicates the Process is ready to
execute as soon as possible, but no session is
available. Other Processes may be executing with
the SNODE, and no other sessions are available.
This Process runs as soon as a new session is
created or an existing session becomes available.

The Hold Queue

Processes in the Hold queue are waiting for operator intervention before they progress to the Wait queue.
This queue enables operators of the local node and remote node to coordinate and control Process
execution.
Processes are placed in the Hold queue by a submit command with retain=initial, retain=yes, or hold=yes
parameters specified. Processes submitted with hold=call also are placed in the Hold queue. Processes
are moved from the Timer queue to the Hold queue by a change process command with hold=yes
specified. Additionally, Processes are moved from the Execution queue to the Hold queue by a flush
process command with hold=yes specified.
Processes are moved from the Hold queue to the Execution queue by a change process command with
the release parameter specified.
The following table shows the status values for the Hold queue:

Status Comment
HC Held for Call indicates that the Process was
submitted with hold=call specified. A session
started from either node causes the Process to be
moved to the Wait queue in WC status. The Process
is placed in the Execution queue when the Process
is selected for execution.

Chapter 4. User Guide 181

 Status Comment
HI Held Initially indicates that the Process was
submitted with hold=yes specified. The Process
can be released later by a change process
command with release or hold=no specified.
HE Held due to error specifies that a session error or
other abnormal condition occurred.
HO Held by Operator indicates that a change process
hold=yes was specified.
HR Held Retain indicates that the Process was
submitted with retain=yes or retain=initial
specified and has already executed. The Process
can be released later by a change process
command with release specified.
HS Held for Suspension indicates that the operator
issued a flush process command with hold=yes
specified. The Process can be released later by a
change process command with release specified.

IBM Connect:Direct Utilities

IBM Connect:Direct translates data from one character set code to a different character set code, such as
from ASCII to EBCDIC, based on a character translation table in the d_dir/ndm/xlate directory. IBM
Connect:Direct provides a default character translation table for use during file transfer operations or you
can modify this table using the utility program called ndmxlt.

Creating a Translation Table

1. To create a translation table, either copy the file called /cd_dir/cdunix/ndm/src/def_send.sxlt or /
cd_dir/cdunix/ndm/src/def_recv.sxlt, where cd_dir is the directory where IBM Connect:Direct is
installed, and rename it or modify this file.
2. Use a text editor to add the new values to the table in the file you created.
3. Compile the updated file with the ndmxlt utility.
4. Replace the default translation table in the d_dir/ndm/xlate with the updated table. Each table is 256
bytes long.

Following is a sample translation table:

# This file contains an example of defining an ASCII-to-EBCDIC translation table and
# then changing it to translate lowercase to uppercase.
#
# Define the ASCII-to-EBCDIC table.
offset=0
00 01 02 03 04 05 06 07 08 05 15 0B 0C 0D 0E 0F
10 11 12 13 3C 15 16 17 18 19 1A 1B 1C 1D 1E 1F
40 5A 7F 7B 5B 6C 50 7D 4D 5D 5C 4E 6B 60 4B 61
F0 F1 F2 F3 F4 F5 F6 F7 F8 F9 7A 5E 4C 7E 6E 6F
7C C1 C2 C3 C4 C5 C6 C7 C8 C9 D1 D2 D3 D4 D5 D6
D7 D8 D9 E2 E3 E4 E5 E6 E7 E8 E9 AD E0 BD 5F 6D
79 81 82 83 84 85 86 87 88 89 91 92 93 94 95 96
97 98 99 A2 A3 A4 A5 A6 A7 A8 A9 C0 4F D0 A1 7F
80 81 82 83 84 85 86 87 88 89 8A 8B 8C 8D 8E 8F
90 91 92 93 94 95 96 97 98 99 9A 9B 9C 9D 9E 9F
A0 A1 A2 A3 A4 A5 A6 A7 A8 A9 AA AB AC AD AE AF
B0 B1 B2 B3 B4 B5 B6 B7 B8 B9 BA BB BC BD BE BF
C0 C1 C2 C3 C4 C5 C6 C7 C8 C9 CA CB CC CD CE CF
D0 D1 D2 D3 D4 D5 D6 D7 D8 D9 DA DB DC DD DE DF
E0 E1 E2 E3 E4 E5 E6 E7 E8 E9 EA EB EC ED EE EF
F0 F1 F2 F3 F4 F5 F6 F7 F8 F9 FA FB FC FD FE FF
#
# Change the lowercase characters to uppercase.

182 IBM Connect:Direct for UNIX: Documentation

 offset=61
C1 C2 C3 C4 C5 C6 C7 C8 C9 D1 D2 D3 D4 D5 D6 D7
D8 D9 E2 E3 E4 E5 E6 E7 E8 E9

Each byte stores the character value for the target character set. The source character set is used as an
index into the table. For example, an ASCII blank (Hex 20) would locate the byte at offset Hex 20 in the
translation table. If the byte at location Hex 20 contains Hex code 40, that would translate to an EBCDIC
code indicating a blank character.

Compiling a Translation Table Using the ndmxlt Utility

Before you begin

You can create or modify a translation table tailored to your requirements with the ndmxlt utility program.
To invoke the ndmxlt utility, type the following command at the UNIX prompt:

$ ndmxlt -ssourcefile -ooutputfile [ -rradix] [ -ffiller] -mxlatefile

The parameters for the ndmxlt command are listed in the following table:

Parameter Description Values

-ssourcefile The path and file name of the translation table Path and name of translation
source file. If no value is specified, input is read table
from STDIN.
-ooutputfile The path and file name of the translation table Path and name of translation
output file. output file
-rradix The radix or base of the source file input data. All x|d|o
numeric values whether from command line
x—Hexadecimal. This is the
options or input data are interpreted based on the
default.
radix setting.
d—Decimal
o—Octal
The default is x.

-ffiller A filler byte value. The entire table is initialized to Any keyboard character, number,
this value before the input data is scanned and or special character, plus control
applied to the table. characters entered using a
preceding slash.
For example, “\0” is null.

-m The path and file name of a model translation Path and file name of the model
table. If specified, the model table is read in and translation table
then the input data is scanned and applied to the
table. This capability permits creating a number of
different tables that are variations from a single
base table without having to specify all 256 bytes
of input data for each table.

Chapter 4. User Guide 183

Example—Creating a Translation Table

About this task

Perform the following steps to create a sample translation table that changes lowercase characters to
uppercase characters:

Procedure
1. Make a copy of the sample translation table located at cd_dir/ndm/src/def_send.sxlt.
2. Open the new translation table with a text editor.
3. Add the following lines to the bottom of the table. It should look like the table in “Creating a
Translation Table” on page 182when you have added this information.

#
# Change the lowercase characters to uppercase.
offset=61
C1 C2 C3 C4 C5 C6 C7 C8 C9 D1 D2 D3 D4 D5 D6 D7
D8 D9 E2 E3 E4 E5 E6 E7 E8 E9

4. Copy the modified file to cd_dir/ndm/src and name it UpperCaseEBC.sxlt.

5. Compile the new translation table using the following syntax:

ndmxlt -s../src/UpperCaseEBC.sxlt -oUpperCaseEBC.xlt

6. To use this translation table, add the following sysopts parameter to the copy statement:

copy from file=filename

to file=filename
sysopts=":xlate.tbl=pathname/UpperCaseEBC.xlt:"

Example—Modifying a Model Translation Table

About this task

Perform the following steps to modify a model translation table. This method, when implemented, reads
the model table and writes it to a new file. It then reads the input data and makes changes to the table
created.

Procedure
1. Create a file called FourLinesUpperCase.sxlt and add the following lines to the file:

#
# Change the lowercase characters to uppercase.
offset=61
C1 C2 C3 C4 C5 C6 C7 C8 C9 D1 D2 D3 D4 D5 D6 D7
D8 D9 E2 E3 E4 E5 E6 E7 E8 E9

2. Copy the modified file to cd_dir/ndm/src.

3. Type the following command to compile this file and create a translation table called
fourLineUpperCase.xlt:

ndmxlt -s../src/FourLineUpperCase.sxlt -oFourLineUpperCase.xlt -mdef_send.xlt

4. To use this translation table, add the following sysopts parameter to the copy statement:

copy from file=filename

to file=filename
sysopts=":xlate.tbl=pathname/FourLineUpperCase.xlt:"

184 IBM Connect:Direct for UNIX: Documentation

Using Translation During File Transfer Operations
Translation is specified in the copy statement of a IBM Connect:Direct Process. You can use the default
translation table or create a new table.
Translation is specified in the copy statement of a IBM Connect:Direct Process. You can use the default
translation table or create a new table.
To use the default translation table, type the following copy statement:

copy from file=abc

to file=xyz
sysopts=":xlate.tbl=yes:"

To specify a customized table for data translation, include the following sysopts subparameter in the copy
statement, where pathname/filename identifies the translation table:

copy from file=filename

to file=filename
sysopts=":xlate.tbl=pathname/filename:"

Refer to the UNIX section of the IBM Connect:Direct Processes Web site at https://www.ibm.com/
support/knowledgecenter/CD_PROC_LANG/com.ibm.help.cdprocoverview.doc/
cdprc_over_what_is_a_cd_process.html for additional details concerning translation table specification
with a copy statement.

Translation Table Error Messages

The following table displays the error messages that are generated by ndmxlt:

Diagnostic Number Description

XXLT001I Invalid directive

XXLT002I Input file open error

XXLT003I Model file open error

XXLT004I Invalid filler value

XXLT005I Invalid offset value

XXLT006I Invalid radix value

XXLT007I Invalid table value

XXLT008I Table data out of bounds

Accessing IBM Connect:Direct Messages

The IBM Connect:Direct message file contains records with text for all messages, including errors and
messages from IBM Connect:Direct servers other than the host server. You can add and delete message
records with a text editor. The message file resides in d_dir/ndm/cfg/cd_node/msgfile.cfg. You can display
message text with the ndmmsg command.

Chapter 4. User Guide 185

 Message File Content
The message file is structured much the same way as other IBM Connect:Direct configuration files. Each
record is a logical line in a text file that consists of one or more physical lines. Each record has a unique
name, a message ID, and fields that make up the message text.
The message record definitions provide for symbolic substitution, which permits including actual file
names or other variable information within the text to more specifically identify a problem. Symbolic
variables begin with the ampersand character (&).
The format of IBM Connect:Direct message IDs is listed in the following table:

XxxxnnnI

Where:

X Indicates IBM Connect:Direct

xxx is a 3-character IBM Connect:Direct component identifier
nnn is a 3-digit decimal number
I is the standard, though not required, suffix

Message File Record Format

The following example shows the format of the message file record. Each record can be up to 4K bytes
long. Optional parameters and values are in brackets.

message id [long.text detailed message explanation] [mod.name issuing module name] short.text
message summary

Following are the parameters for the message file record:

Parameter Description Values

long.text A string that explains the message in detail. A text string
mod.name The name of the source module issuing the Source module name
message ID.
short.text A summary of the message. This field is required. Summary message, up to 72
characters

The following example illustrates a sample message record for XCPS008I:

XCPS008I:\ :mod.name=NUSMCP00.C:\
:short.text=File is not VB datatype.:\
:long.text=File is not variable block. Change sysopts datatype to\
either binary or text to transfer this file.\
\nSYSTEM ACTION-> the copy step failed and CD processing\
continued with the next process step.\
\nRESPONSE-> change the sysopts datatype to either\
binary or text.:\

Displaying Message Text

Use the ndmmsg command to display text in the message file. You can display both short and long text.
The following command illustrates the format for ndmmsg:

ndmmsg -f msgfname [-l | -s] msgid1 [msgid2 [msgid3 [...]]]

Following are the parameters for the ndmmsg command. If you do not specify an l or s parameter, both
short and long text are displayed.

186 IBM Connect:Direct for UNIX: Documentation

 Parameter Description
-f Specifies the name of the message file.

-l Displays the long text of a message.

-s Displays the short text of a message.

Following is a sample ndmmsg command:

ndmmsg -f /usr/ndmunix/msgfile.cfg XCMG000I

Output from the command is displayed in the following example:

rc=&rc
fdbk=&fdbk
mod.name=NUCMRG00.C
func.name=ndmapi_sendcmd
short.text=CMGR RPC call returns NULL
long.text=The ndmapi_sendcmd RPC call made by the API to the CMGR returns a
NULL pointer.There is probably an RPC error.ndm.action=None
user.action=First, check if the ndmcmgr is still running; it could have
been killed accidently.If so, then abort the current CLI and restart the
CLI. If the same problem occurs again, try to increase the value of wait
time (if set) in the API configuration file (ndmapi.cfg).

Precompressing/Decompressing Files Using the Standalone Batch

Compression Utility
The Standalone Batch Compression Utility (cdsacomp) enables you to precompress files and then transfer
the precompressed files to remote IBM Connect:Direct nodes using IBM Connect:Direct Processes. You
have the following options for decompressing the files. A file can either be:
• Decompressed as it is received by the remote node (available on all IBM Connect:Direct platforms)
• Stored on the remote node and later decompressed offline using cdsacomp (available only on IBM
Connect:Direct and Connect:Direct for z/OS).
Because cdsacomp can be used offline, it allows you to allocate some of the overhead associated with
compression to non-peak times. For example, if you need to send the same file to several remote nodes,
use this utility so that the file is precompressed only one time. You can also use cdsacomp to determine
how much compression can be achieved for a file without having to transmit the file.
The cdsacomp utility is located in the IBM Connect:Direct /bin directory.

Special Considerations for Using the Standalone Batch Compression Utility

Consider the following when you are using cdsacomp to precompress files:
• If you precompress a file with the cdsacomp utility, then you cannot specify any compression options in
your IBM Connect:Direct Process when you copy that file.
• You cannot specify data transformations (xlate, codepage, strip blanks, and so on) when sending a
precompressed file with :precompress=yes: sysopts (for on-the-fly decompression). The following
transformation options are available:
– -x
– -p
– -s
– -a

Chapter 4. User Guide 187

 • If you precompress a file with the cdsacomp utility on a IBM Connect:Direct node, then you cannot
specify a checkpoint interval in your IBM Connect:Direct Process if you decompress the file as it is
received by the remote node.
• When you are copying a precompressed file to z/OS without :precomp=yes: (for deferred
decompression):
– The Copy operation must specify DCB information for the destination file. The physical block size of
the destination file on Connect:Direct for z/OS must match the logical block size of the
precompressed source file on Connect:Direct for UNIX.
– The logical block size of the source file defaults to 27920 unless overridden by the -b parameter.

Using the Standalone Batch Compression Utility

Before you begin

To invoke the standalone batch compression utility (cdsacomp), type the following command at a UNIX
prompt:

cdsacomp

Following are the parameters for the cdsacomp utility:

Parameter Description Values

-m Specify which mode to use: precompress or compress | decompress
decompress. This argument is required.
The default is compress.

-i Specify the input file to precompress or full or relative path of input file
decompress. This argument is required.
-o Specify the output file to save. If the output file full or relative path of output file
already exists, it is overwritten. This argument is
required.
-z Use this option with “-m compress” to override level, window, memory
default compression values. This argument is
level—Compression level. The
optional.
range is 1–9. The default is 1.
When decompressing, the values used during
1—Provides the least
compression are used.
compression, but is the fastest.
9—Provides the most
compression, but is the slowest.
window—The size of the
compression window and history
buffer. Increasing the window
increases the compression, but
uses more virtual memory. The
range is 9–15. The default is 13.
memory—The amount of virtual
memory to allocate. The range
is 1–9. The default is 4.
1—Uses the least virtual
memory.
9—Uses the most virtual
memory.

188 IBM Connect:Direct for UNIX: Documentation

Parameter Description Values
-x Use this option to translate the file. full path to translate table file |
relative path to translate table
If this parameter is not specified, the file is not
file
translated.
This parameter is mutually exclusive with -
codepage.

-p Use this option to specify codepages for file source codepage, destination
conversion. Default is no codepage translation. codepage
This parameter is mutually exclusive with -xlate.

-d Specify the datatype of the file. text | binary | VB

When you use “-m compress”, the datatype The default is text.
values result in the following:
• text
Strips newline characters from each record
Supports -s and -a parameters
Uses data attributes of blocksize=23040,
recfm=vb, lrecl=23036, dsorg=ps
• binary
Uses data attributes of blocksize=23040,
recfm=u, lrecl=0, dsorg=ps
Does not support -s and -a parameters
• VB
Does not support -x, -p, -s, and -a parameters
Uses data attributes of blocksize=23040,
recfm=vb, lrecl=23036, dsorg=ps
When you use “-m decompress”, the datatype
values result in the following:
• text
Inserts newline characters into each record
Supports the -s parameter
• binary
Does not support the -s parameter
• VB
Does not support -x, -p, and -s parameters

-b Specify the block size of the output file. nnnnn

This parameter is valid only when you specify The range is 4096–32760. The
“-m compress” for the compression option. default is 27920.

-s Use this option to strip trailing blanks. y|n

This parameter is valid only when you specify y—yes
“-d text” for the datatype of the file.
n—no
The default is y.

Chapter 4. User Guide 189

 Parameter Description Values
-a Use this option to replace zero-length records y|n
with a single, blank character.
y—yes
This parameter is valid only when you specify
n—no
the following: “-d text” and “-m compress”.
The default is y.
Specify n if the data is copied to
an i5OS or mainframe node.

-h Use this option to display online help for the No values are available for this
utility. parameter.

Example—Precompress a Text File

In this example, the source file is a text file named source.file which is precompressed into a destination
file named compressed.file. The file is translated using the default translation table, /home/cd/ndm/xlate/
def_send.xlt. Trailing blanks are stripped. Default settings for ZLIB tuning, checkpoint interval and block
size are used.

cdsacomp -m compress
-d text
-i source.file
-o compressed.file
-x /home/cd/ndm/xlate/def_send.xlt
-s y

Example—Precompress a Text File With Codepage Conversion

In this example, the source file is a text file named zzz.sac which is precompressed into a file named
zzz.txt. The file is converted from EBCDIC-US to ASCII using the codepage option. Default settings are
used for parameters that are not specified.

cdsacomp -m compress
-d text
-i zzz.txt
-o zzz.sac
-p EBCDIC-US,ASCII

Example—Precompress a Binary File

In this example, the source file is a binary file named source.file which is precompressed into a
destination file named compressed.file. Default settings are used for parameters that are not specified.

cdsacomp -m compress
-d binary
-infile source.file
-outfile compressed.file

Example—Decompress a Text File

In this example, the source file is a precompressed text file named compressed.file which is
decompressed into a destination file named dest.file. The file is translated using the default translation
table, /home/cd/ndm/xlate/def_recv.xlt. Default settings are used for parameters that are not specified.

cdsacomp -m decompress
-d text
-i compressed.file
-o dest.file
-x /home/cd/ndm/xlate/def_recv.xlt

190 IBM Connect:Direct for UNIX: Documentation

 Examples—csdacomp Command Help
Requesting a summary of cdsacomp command parameters and help options:

cdsacomp -h

Example—Decompress a File on the Remote Node During the Copy Step

The “precomp=yes” parameter is used when the file was compressed by the cdsacomp utility prior to this
Process. The file is transferred by this Process as a pre-compressed file. It is then decompressed by
special processing as it is received on the remote node.

sample process snode=cdunix1

step01 copy
from
(
file=/home/cd/upload/compressed.file
sysopts=”:precomp=yes:”
pnode
)
to
(
file=/home/cd/download/decompressed.file
snode
disp=rpl
)
pend;

Example—Send Precompressed File to z/OS and Storing It as Precompressed

The precompressed file is copied to the z/OS node with PNODE sysopts of “datatype=binary”. The
destination file is not decompressed. The DCB settings of the original precompressed file are preserved
on the z/OS node. The specified checkpoint interval will be used during the file transfer. The file can be
decompressed with the z/OS cdsacomp utility.

sample process snode=cdunix1

step01 copy
from
(
file=/home/cd/upload/compressed.file
sysopts=”:datatype=binary:”
pnode
)
chkpt=2M
to
(
file=upload.compressed.file
dcb=(blksize=27920, lrecl=0, dsorg=ps, recfm=u)
snode
disp=(new,catlg)
)

pend;

Validate Configuration Files

When you manually edit any of the five text-based IBM Connect:Direct configuration files, the
Configuration Checking Utility (cfgcheck) enables you to validate these files offline. The following files can
be validated using this utility: userfile.cfg, initparm.cfg, netmap.cfg, ndmapi.cfg, and sysacl.cfg.

Note: The Strong Access Control File (sysacl.cfg) will be validated only when the user running the
Configuration Checking Utility is a root user.
By default, cfgcheck is run with no arguments and attempts to find all five of the configuration files in the
current working directory. If all of the IBM Connect:Direct components are not installed, then some of the

Chapter 4. User Guide 191

 files will not be found. For example, if the Command Line Interface (CLI) is installed but the IBM
Connect:Direct server is not installed, only the ndmapi.cfg file will exist in the installation directory.
Therefore, only the ndmapi.cfg file will be validated. When cfgcheck is run with no arguments, the utility
will report that the other configuration files were not found.
Note: Before you can execute cfgcheck, you must set the NDMAPICFG environment variable. For more
information, see “Controlling and Monitoring Processes” on page 141.
To invoke cfgcheck, type the following command at the UNIX prompt:

$ cfgcheck -t -h -f filename.cfg

The cfgcheck command has the following arguments:

Argument Description
No arguments (default) When no arguments are specified and the cfgcheck
utility is run by a non-root user, it searches the
cfg/ directory for the following configuration
files: initparm.cfg, netmap.cfg, userfile.cfg, and
ndmapi.cfg. When a root user runs cfgcheck, the
utility also searches the SACL/ directory to
locate the sysacl.cfg file.
-h Prints the help screen and exits.

-t Turns on tracing and prints verbose debug

information.

-f filename.cfg Specifies a configuration file name to validate,

where filename is the name of one of the
configuration files. You can specify multiple -f
arguments. When the -f argument is used, cfgcheck
will not automatically search for other
configuration files from the file specified.

Configuration Reports
You can generate a report of your system information and IBM Connect:Direct configuration information
using the Configuration Reporting Utility (cdcustrpt). Configuration reports can be generated for the
following IBM Connect:Direct components:
• Base installation of IBM Connect:Direct
• Connect:Direct Secure Plus for UNIX
During the IBM Connect:Direct installation, cdcustrpt is installed in the <installation>/etc/ directory.

Generating a Configuration Report on the Base Installation

Before you begin

When you use cdcustrpt to generate a report on the base IBM Connect:Direct installation, it reports the
following types of system information:
• Name and other information of the operating system
• Space on file systems
• Virtual memory statistics
• Contents of the IBM Connect:Direct installation directory

192 IBM Connect:Direct for UNIX: Documentation

In addition to reporting system information, cdcustrpt invokes the Configuration Checking Utility
(cfgcheck) to validate the syntax of the five text-based configuration files (if they are available and if the
user has access to the files) and to report on the contents of the configuration files. For more information
on cfgcheck, see “Validate Configuration Files” on page 191.
In this procedure, default values are computed by the utility based on the location and name of the
installed IBM Connect:Direct and are provided in brackets “[ ]”. Press Enter to accept the default values.
To invoke cducustrpt and generate a report of the base installation:

Procedure
1. Type the following command at a UNIX prompt:

% cdcustrpt

2. Type the full path where IBM Connect:Direct is installed and press Enter.
3. Type the full path and name for the report that will be generated and press Enter.
The report is generated in the location you specified, and any error messages are displayed as shown
in the following example:

% cdcustrpt

Enter full path of Connect:Direct destination directory:[/sci/users/jbrown1/cd40]:

Enter full path and name for this support report file:[/sci/users/jbrown1/cd40/etc/
cd.support.rpt]:

ls: /sci/users/jbrown1/cd40/ndm/SACL: Permission denied

cdcustrpt ended

In this example, the user does not have root access, so the Strong Access Control File (sysacl.cfg) can
not be accessed. The following example shows an excerpt from a sample report:

Chapter 4. User Guide 193

 ###########################################################################
####### Connect:Direct for UNIX 4.0.00 configuration report #######
###########################################################################
Connect:Direct for UNIX Version 4000, Build 00, IBM/RS6000 AIX, Fix date:
01OCT2007

Install directory: /sci/users/jbrown1/cd40

Local Node name: jb_aix40

Report for: jbrown1

=========================================================
===== Begin: Environment and system information =====
=========================================================

System: AIX skyglass 3 5 00CE208E4C00

Disk usage:
Filesystem 512-blocks Free %Used Iused %Iused Mounted on

/dev/hd4 262144 64216 76% 2479 4% /

/dev/hd2 8126464 2708688 67% 37802 4% /usr

/dev/hd9var 262144 18448 93% 613 2% /var

/dev/hd3 786432 363600 54% 424 1% /tmp

/dev/fwdump 524288 507752 4% 17 1% /var/adm/ras/platform

/dev/hd1 262144 216520 18% 167 1% /localhome

/proc - - - - - /proc

/dev/hd10opt 524288 52168 91% 3688 6% /opt

/dev/fslv00 121634816 13629040 89% 264984 15% /sci

scidalnis01:/export/nis01 1677670392 512499192 70% 0 -1% /home/nis01

Memory statistics:
System Configuration: lcpu=4 mem=3824MB

kthr memory page faults cpu

----- ----------- ------------------------ ------------ -----------
r b avm fre re pi po fr sr cy in sy cs us sy id wa
1 1 400072 232777 0 0 0 0 0 0 4 1805 197 0 1 99 0

Generating a Configuration Report on Connect:Direct Secure Plus for UNIX

If cdcustrpt detects the Connect:Direct Secure Plus directory in the installation directory,
<installation>/ndm/secure+/, it invokes the Connect:Direct Secure Plus Command Line Utility (splicli.sh)
to report on Secure+ parameters. If Connect:Direct Secure Plus is detected, you are prompted to enter
the path to the Connect:Direct Secure Plus parameters file (the default location is provided in brackets
“[ ]”), for example:

Enter full path of Secure+ parmfile

directory: [/sci/users/jbrown1/cd40/ndm/secure+/nodes]:

The following example shows an excerpt from a sample report:

===== Begin: Secure+ parameters =====

========================================
All secure+ nodes in /data/cd4204sp/ndm/secure+/nodes:
************************************************************************************
* Secure+ Command Line Interface *
* IBM(R) Connect:Direct(R) Secure Plus v6.0.0 *
*----------------------------------------------------------------------------------*
* Licensed Materials - Property of IBM *
* (C) Copyright IBM Corp. 1999, 2018 All Rights Reserved. *

194 IBM Connect:Direct for UNIX: Documentation

 * US Government Users Restricted Rights - Use, duplication *
* or disclosure restricted by GSA ADP Schedule Contract *
* with IBM Corp. *
************************************************************************************

SPCLI> display all;

Name=.Client
BaseName=.Client
Type=R
Protocol=DefaultToLN
Override=Y
SecurityMode=DefaultToLN
AuthTimeout=120
KeyCertLabel=
ClientAuth=N
CertCommonName=
CipherSuites=()

Name=.Keystore
File=/data/cd4204sp/ndm/secure+/certificates/cdkeystore.kdb

Name=.Local
BaseName=cd4204sp
Type=L
Protocol=TLS1.2
Override=Y
SecurityMode=Disable
AuthTimeout=120
SeaEnable=N
SeaCertValDef=
KeyCertLabel=MYSHA2562048ID
EncryptData=Y
ClientAuth=N
CipherSuites=(TLS_RSA_WITH_AES_256_GCM_SHA384,
TLS_RSA_WITH_AES_256_CBC_SHA256,TLS_RSA_WITH_AES_256_CBC_SHA,
TLS_RSA_WITH_AES_128_GCM_SHA256,TLS_RSA_WITH_AES_128_CBC_SHA256,
TLS_RSA_WITH_AES_128_CBC_SHA,TLS_RSA_WITH_RC4_128_SHA,
TLS_RSA_WITH_3DES_EDE_CBC_SHA,TLS_RSA_WITH_NULL_SHA256,TLS_RSA_WITH_NULL_SHA)

2016/03/11 11:58:07 cdtest

Writing Custom Programs

The IBM Connect:Direct Application Programming Interface (API) allows you to write custom programs in
either C or C++ to use with IBM Connect:Direct. With the C functions or the C++ classes, you can create
programs to perform the following tasks:
• Establish a connection to the IBM Connect:Direct server
• Disconnect from the server
• Receive command responses from the server
• Send commands to the server
This topic describes the format of the IBM Connect:Direct API functions and classes and provides
samples of their use. Sample programs are provided that use the IBM Connect:Direct API functions and
classes to issue commands and receive responses from the IBM Connect:Direct server.

Compiling Custom Programs

After you write a custom program, you must compile it, using a C or C++ compiler. Refer to the following
information to determine what minimum C++ compiler version to use for each platform:

Platform C++ Compiler

AIX IBM XL C/C++ for AIX, V11.1

Sun Solaris Sun C++ 5.12

Chapter 4. User Guide 195

Platform C++ Compiler
HP-Itanium aCC: HP ANSI C++ B3910B A.06.07

Linux x86 g++ (GCC) 6.3.1

Linux S390 g++ (GCC) 4.4.7

Linux ppc64le g++ 4.8.5

Use the commands defined in the following table to compile a custom C++ program using the C++ API
calls:

Platfo C++ Compile Command

rm
AIX
64-bit /usr/vacpp/bin/xlC -q64 -qinline -I../include -+ -o sdksample sdksample.C ../lib/ndmapi64.a -lbsd -ldl
-lsrc -lpthreads
Sun
64-bit /opt/SUNWspro/bin/CC -m64 -DBSD_COMP -I../include -o sdksample sdksample.C ../lib/ndmapi64.a
-L/usr/ucblib/sparcv9 -L/usr/lib/sparcv9
-lsocket -lrpcsoc -lnsl -lelf -ldl
-R/usr/ucblib/sparcv9

HP-Itanium
64-bit /opt/aCC/bin/aCC +DD64 -I../include -o sdksample sdksample.C ../lib/ndmapi64.a -L/usr/lib/hpux64 -
lrpcsvc -lnsl -ldld -Wl,+s -lunwind
Linux x86
64-bit g++ -I../include -O -DLINUX -o sdksample sdksample.C ../lib/ndmapi64.a -ldl -lnss_nis -lstdc++ -ltirpc
-lnsl
Note: A 64-bit Linux OS installation is required to compile 64-bit binaries.

LinuxS390
64-bit g++ -I../include -O -DLINUX -o sdksample sdksample.C ../lib/ndmapi64.a -ldl -lnss_nis -lstdc++ -ltirpc
Note: A 64-bit Linux OS installation is required to compile 64-bit binaries.

Linux ppc64le
64-bit g++ -I../include -O -DLINUX -o sdksample sdksample.C ../lib/ndmapi64.a -ldl -lstdc++ -ltirpc -lnsl

To build a C++ program using the C API calls, such as the apicheck.C sample program, replace the
sdksample.C parameter with the name of the C++ program and rename the output file parameter, -o
sdksample, to the name of the output file you want to create such as apicheck.
Use the commands defined in the following table to compile a C program:

Platfo C Compile Command

rm
AIX

196 IBM Connect:Direct for UNIX: Documentation

Platfo C Compile Command
rm
64-bit /usr/vacpp/bin/xlc -q64 -I../include -+ -o apicheck apicheck.c ../lib/ndmapi64.a -lbsd -ldl -lsrc -lC -
lpthreads
Sun
64-bit /opt/SUNWspro/bin/cc -m64 -DBSD_COMP -I../include -o apicheck apicheck.c ../lib/ndmapi64.a
-L/usr/ucblib/sparcv9 -L/usr/lib/sparcv9
-lsocket -lCstd -lCrun -lrpcsoc -lnsl -lelf -ldl
-lCrun -R/usr/ucblib/sparcv9

HP-Itanium
64-bit /opt/ansic/bin/cc +DD64 -I../include -o apicheck apicheck.c ../lib/ndmapi64.a -L/usr/lib/hpux64 -
lrpcsvc -lnsl -ldld -Wl,+s -lcl -lstd_v2 -lCsup -lunwind
Linux x86
64-bit gcc -I../include -O -DLINUX -o apicheck apicheck.c ../lib/ndmapi64.a -ldl -lnss_nis -lstdc++ -ltirpc -
lnsl
Note: A 64-bit Linux OS installation is required to compile 64-bit binaries.

LinuxS390
64-bit gcc -I../include -O -DLINUX -o apicheck apicheck.c ../lib/ndmapi64.a -ldl -lnss_nis -lstdc++ -ltirpc
Note: A 64-bit Linux OS installation is required to compile 64-bit binaries.

Linux ppc64le
64-bit gcc -I../include -O -DLINUX -o apicheck apicheck.c ../lib/ndmapi64.a -ldl -lstdc++ -ltirpc -lnsl

Writing Custom C Programs

If you write a custom program using the C API calls, you must include the header file ndmapi.h and link it
with ndmapi.a. A sample program called apicheck.c is provided.
For Java programming, you can call the C API functions by using the JNI and the libndmapi shared
objects: libndmapi.sl for HP and libndmapi.so for the other supported platforms. Although the JNI is
supported, the IBM Connect:Direct Java Application Interface is recommended for Java programs that
invoke the services of IBM Connect:Direct.
Note: The environment variable NDMAPICFG must be set to the pathname of the client configuration file.
Refer to “Controlling and Monitoring Processes” on page 141 for instructions on setting the environment
variable.
Use the following IBM Connect:Direct API functions for C and C++ programs:

C++ Function C Function Description

ndmapi_connect() ndmapi_connect_c() Establishes a connection with the server. Specify the
node to connect to in the ndm_nodespec pointer or
in the CLI/API Configuration Information file. If the
call is successful, NDM_NO_ERROR is returned.
Control returns to the application when the
connection is established and is ready for the first
API request.

Chapter 4. User Guide 197

 C++ Function C Function Description
ndmapi_sendcmd() ndmapi_sendcmd_c() Sends commands to IBM Connect:Direct. You must
provide the command text. The resp_moreflag is a
pointer to the flag indicating that more responses
are pending for the executed command. Invoke
ndmapi_recvresp_c() for C programs or
ndmapi_recvresp() for C++ programs to retrieve the
extra responses. Only the select process and select
statistics commands require the use of
ndmapi_recvresp_c() for use with C and
ndmapi_recvresp() for use with C++.
ndmapi_recvresp() ndmapi_recvresp_c() Receives responses to commands sent to IBM
Connect:Direct. The contents of the response buffer
are returned.
ndmapi_disconnect() ndmapi_disconnect_c() Terminates the API connection.

Three types of IBM Connect:Direct command responses are returned by these functions.
• Informational responses return information about the submitted command.
• Data responses, stored in the resp_buffer, contain data records.
• Error responses return ERROR_H, a pointer to a linked list of all errors found. The ID field values are
fixed for use when debugging. The msgid, feedback, and rc fields are specified by IBM Connect:Direct
and are referred to in message text. The subst field points to a string that contains substitution variable
information to be inserted appropriately in the message text. The error control structure keeps track of
the current and total number of errors. You can move through the errors by using the next pointer in
error entry blocks.
The following code defines the ERROR_H structure:

#define NDM_ERR_ENT_T struct NDM_ERR_ENT_S

#define NDM_ERR_ENT_H NDM_ERR_ENT_T *
#define NDM_ERR_CTL_T struct NDM_ERR_CTL_S
#define ERROR_H NDM_ERR_CTL_T *
struct NDM_ERR_ENT_S
{
int32 id;
char msgid[MSGIDLEN];
int32 feedback;
int32 rc;
char *subst;
NDM_ERR_ENT_H next;
};
struct NDM_ERR_CTL_S
{
int32 id;
int32 cur_entry;
int32 num_entries;
NDM_ERR_ENT_H next;
};

Creating a Connection to IBM Connect:Direct Using ndmapi_connect() or

ndmapi_connect_c()
Use ndmapi_connect() or ndmapi_connect_c() to create a connection to IBM Connect:Direct so that an
application can send commands and receive responses from the commands. Control returns to the
application when the connection is established and IBM Connect:Direct is ready for the first API request
or when an error condition is set.
Following is the format for the ndmapi_connect() or ndmapi_connect_c() function:

int32 ndmapi_connect ERROR_H error, char * ndm_hostname, char * ndm_portname

198 IBM Connect:Direct for UNIX: Documentation

The following table describes the parameters for the ndmapi_connect() or ndmapi_connect_c() function:

Parameter Description Value

error A pointer to a IBM Connect:Direct-defined structure that Pointer
contains error information or status information.
ndm_hostname A pointer to the text specification of the IBM Connect:Direct host Null-terminated
to which the connection is made. If this parameter is not string
specified, the host name is determined by first checking the
environment variable TCPHOST. If no value is specified, the
tcp.host.name field in the CLI/API configuration file is checked.
If no value is specified, the gethostbyname() command is
invoked and the default value of ndmhost is used.
ndm_portname A pointer to the host port number. If this parameter is not Pointer
specified, the environment variable TCPPORT is checked. If no
value is specified, the value of the tcp.port in the CLI/API
configuration file is checked. If no value is specified, the default
value 1363 is used.

The ndmapi_connect() or ndmapi_connect_c() function has the following return codes:

Parameter Description
NDM_NO_ERROR A session was established with the server.

NDM_ERROR A session was not established with the server.

Consult the error structure for detailed error
status.

The following sample function illustrates the use of ndmapi_connect() to connect to the sun1 host:

rc=ndmapi_connect (error, "sun1", "3122");

Terminating a Connection Using ndmapi_disconnect() or

ndmapi_disconnect_c()
Use ndmapi_disconnect() or ndmapi_disconnect_c() to terminate a connection to IBM Connect:Direct
that was established by a call to ndmapi_connect() or ndmapi_connect_c(). The ndmapi_disconnect() or
ndmapi_disconnect_c()function call is the following:

void ndmapi_disconnect

There are no parameters and no return codes for ndmapi_disconnect() or ndmapi_disconnect_c().

Following is a sample ndmapi_disconnect() function:

ndmapi_disconnect ();

Receiving Responses Using ndmapi_recvresp() or ndmapi_recvresp_c()

Use ndmapi_recvresp() or ndmapi_recvresp_c() to receive responses that are associated with a previous
command sent from the application. Following is the format for ndmapi_recvresp() or
ndmapi_recvresp_c():

int32 ndmapi_recvresp ERROR_H error int32 * resp_length, char * resp_buffer,

int32 * resp_moreflag

Following are the parameters for ndmapi_recvresp() or ndmapi_recvresp_c():

Chapter 4. User Guide 199

 Parameter Description Value
error A pointer to a IBM Connect:Direct-defined Pointer
structure that contains error information or
status information.
resp_length A pointer to the length, in bytes, of the Pointer to number of bytes returned or
application buffer to receive the response. The 0 if you no longer want to receive
API sets this parameter to the number of bytes responses. Setting this field to zero
returned. purges all queued responses.
resp_buffer A pointer to the application buffer that receives A local buffer, with a size greater than
the command or submit response. This buffer or equal to that set by resp_length
should allocate 4096 bytes. and filled in by ndmapi_recvresp() or
ndmapi_recvresp_c().
The format of resp_buffer is a free-form text
record structure. Field names are four The CLI passes the resp_buffer to
characters long and all uppercase. The data AWK for parsing. Valid values include:
can be any length and can include blanks. The
ADMN—IBM Connect:Direct
structure is:
administrator name
field name=data | field name=data |...
ADPH—IBM Connect:Direct
For example: administrator phone number
SUBM = username | PNUM = 12 | PNAM = CCOD—Completion code
proc1 |...
CKPT—Checkpoint
CLAS—Class
CSDS—Copy step start timestamp
CSPE—Secure+ enabled indicator
CSPP—Secure+ protocol
CSPS—Secure+ cipher suite

200 IBM Connect:Direct for UNIX: Documentation

Parameter Description Value

DBLW—Destination file blocks

received
DBYW—Bytes written
DBYX—Bytes received
DCOD—Destination completion code
DDAY—Submit date
DDS1—Destination disposition 1
DDS2—Destination disposition 2
DDS3—Destination disposition 3
DESC—IBM Connect:Direct
administrator description
DFIL—Destination file
DLDR—Download directory restriction
DMSG—Destination message ID
DNVL—Destination number of
volumes
DRCW—Records written
DRUX—RUs received
DVCN—Destination file volume count
DVOL—Destination volume array
DVSQ—Destination file volume
sequence number
ECMP—Extended compression ON or
OFF
ECPR—Extended compression
percentage
ECTP—Extended compression type
ETMC—Ela[sed clock time
ETMK—Elapsed kernal time
ETMU—Elapsed user time
FROM—Copy sending node

Chapter 4. User Guide 201

 Parameter Description Value

ICRC—CRC indicator
LCCD—Local completion code
LCLP—Local IP address and port
number
LKFL—Link fail
LMSG—Local message ID
LNOD—Local node
MSGI—Message ID
MSGT—Message text
MSST—Short text
OCCD—Other completion code
OERR—Other node in error
OMSG—Other message ID
PACC—PNODE account
PCRC—CRC indicator
PFIL—Process file
PNAM—Process name
PNOD—PNODE
PNUM—Process number
PPMN—PDS member name
PRTY—Priority
QUEU—Queue
RECC—Record category
RECI—Record ID
RETA—Retain Process
RMTP—Remote IP address and port
number
RSTR—Process restarted
RUSZ—RU Size
SACC—SNODE account
SBID—Submitter node ID
SBLR—Source file blocks sent

202 IBM Connect:Direct for UNIX: Documentation

Parameter Description Value

SBND—Submitter node name

SBYR—Bytes read
SBYX—Bytes sent
SCMP—Standard compression
SCOD—Source completion code
SCPR—Standard compression
percentage
SDDY—Schedule date
SDS1—Source disposition 1
SDS2—Source disposition 1
SDS2—Source disposition 2
SDS3—Source disposition 3
SELA—Elapsed time of the event
SFIL—Source file
SFSZ—source file size
SMSG—Source message ID
SNAM—Step name
SNOD—SNODE
SNVL—Source number of volumes
SOPT—SYSOPTS record
SRCR—Records read
SRUX—RUs sent
SSTA—Start time of the event
STAR—Start log date/time for record
STAT—Process status
STDL—Copy termination record
(CTRC) log time
STIM—Schedule time
STOP—Stop time of the event
STPT—Stop time of the event (STOP
duplicate)
STRT—Start time of the event (SSTA
duplicate)

Chapter 4. User Guide 203

 Parameter Description Value

SUBM—Submitter ID
SUBN—Submitter node
SUMM—Summary output selector
SVCN—Source file volume count
SVOL—Source volume array
SVSQ—Source file volume sequence
number
TIME—Submit time
TZDI—Local time zone delta from GMT
XLAT—Translation
ZLVL—Zlib compress level
Zlib—memory level
Zlib—window size

resp_moreflag Indicates that more ndmapi_recvresp() or None

ndmapi_recvresp_c() calls must be issued for
more information. This flag occurs only on
select process and select statistics commands.

The ndmapi_recvresp() or ndmapi_recvresp_c() function has the folliowing return codes:

Return Code Description

NDM_NO_ERROR The function completed successfully.

NDM_ERROR An error occurred. Consult the error structure for

detailed error status.

TRUNCATED Data is truncated because the receiving buffer is

too small.

Following is a sample ndmapi_recvresp() function:

int32 rc, resp_length;

int32 resp_moreflag;
char resp_buffer[makbuf];

rc= ndmapi_recvresp (error,

&resp_length,
resp_buffer,
&resp_moreflag
);

Sending a Command to IBM Connect:Direct Using ndmapi_sendcmd() or

ndmapi_sendcmd_c()
Use ndmapi_sendcmd() or ndmapi_sendcmd_c() to allow a command to be sent to a IBM Connect:Direct
application. Following is the format of ndmapi_sendcmd() or ndmapi_sendcmd_c():

int32 rc, resp_moreflag;

struct sendcmd_data ret_data;
rc=ndmapi_sendcmd (error,
"select process pnumber=2,",

204 IBM Connect:Direct for UNIX: Documentation

 &resp_moreflag,
&ret_data
);

Following are the parameters for ndmapi_sendcmd() or ndmapi_sendcmd_c():

Parameter Description Value

error A pointer to a IBM Connect:Direct-defined structure that contains Pointer
error information or status information.
cmd_text A pointer to the null-terminated text string that specifies the Pointer to a text
command to send to IBM Connect:Direct. The command text must string
be followed by a semicolon and terminated with a null.
When you use the submit=filename command from the API,
ensure that you allocate enough storage for the Process text. The
text of the Process submitted is returned in the text string
associated with this parameter when the function completes. If
you do not allocate enough storage for the Process text, a core
dump can result.

resp_moreflag A pointer to the flag that indicates that more responses are Pointer to a flag
pending for the command just executed. Invoke
ndmapi_recvresp() or ndmapi_recvresp_c() to retrieve the extra
responses.
ret_data A pointer to a structure containing internal response information Pointer to a
for a command. The structure is: structure

struct sendcmd_data {
char * cmd_name;
ulong cmd_id;
long data1;
long data2;
long data3;
};

sendcmd_data Provides the caller with some information about the user request. Information
Because parsing of command text occurs at the CMGR, the End about the user
User Application (EUA) has no way to identify the command that request
was submitted, unless it generated the text.
cmd_name A pointer to a string with the name of the command submitted. The Pointer to name
CLI uses this pointer to display completion messages. This field of command
enables you to display unique completion messages without any
knowledge of a specific command in the EUA.

Chapter 4. User Guide 205

 Parameter Description Value
cmd_id A four-byte identifier of the command that was found in the Four-byte
command text. Following are the four-byte identifiers: identifier

/**************Command IDs*******************/
#define CHANGE_PROCESS 0x43484750 /* "CHGP" */
#define DELETE_PROCESS 0x44454c50 /* "DELP"*/
#define FLUSH_PROCESS 0x464c5350 /* "FLSP" */
#define SELECT_PROCESS 0x53454c50 /* "SELP"*/
#define SELECT_STATISTICS 0x53454c53 /* "SELS" */
#define SUBMIT 0x5355424d /* "SUBM" */
#define TRACE_API 0x41504920 /* "API " */
#define TRACE_CMGR 0x434d4752 /* "CMGR" */
#define TRACE_SMGR 0x534d4752 /* "SMGR" */
#define TRACE_PMGR 0x504d4752 /* "PMGR" */
#define TRACE_COM 0x434f4d4d /* "COMM"*/
#define TRACE 0x54524143 /* "TRAC" */
#define STOPNDM 0x53544F50 /* "STOP" */

The CLI uses these identifiers to ensure that rules are being
followed. For instance, if an ndmapi_sendcmd returns with the
resp_moreflag set and the cmd_id is not SELECT_STATISTICS or
SELECT_PROCESS, the CLI generates an error.

data1, data2, For future expansion. data1 is used with the submit command to
and data3 return the Process number. data2 is used with the submit
command to return the result of the Process (0, 4, 8, or 16)

The ndmapi_sendcmd_c() function call has the following return codes:

Return Code Description

NDM_NO_ERROR or Process Number The function completed successfully.

NDM_ERROR An error occurred. Consult the error structure for

detailed error status.

Following is a sample ndmapi_sendcmd() function:

int32 rc, resp_moreflag;

struct sendcmd_data ret_data;
rc=ndmapi_sendcmd (error,
"select process pnumber=2 ;",
&resp_moreflag,
&ret_data
);

Writing Custom C++ Programs

If you write a custom program using C++ API calls, you must include the class called
ConnectDirectSession. The calling program must instantiate ConnectDirectSession and call the send and
receive functions. A sample program called sdksample.C is provided. To write a custom C++ program,
create a ConnectDirectSession class. The class contains the ConnectDirectSession interface and a
constructor and destructor call to allocate and release the storage associated with the class. This class is
the interface to the IBM Connect:Direct methods and provides connection, command, data retrieval, and
error services. Each method returns either CD_SUCCESS or CD_FAILURE.

Note: The environment variable NDMAPICFG must be set to the pathname of the client configuration file.
Refer to “Starting the CLI” on page 141for instructions on setting the environment variable.

206 IBM Connect:Direct for UNIX: Documentation

To use the ConnectDirectSession class, your application must include the cdunxsdk.h header file provided
in the installation and must link with the ndmapi.a file. Following is a sample ConnectDirectSession class
program:

#include "cdunxsdk.h"
#include <iostream.h>
#include <string.h>
void getError(ConnectDirectSession& cdSess);
main()
{
ConnectDirectSession cdSess;
char processText[16384];
if (cdSess.SessionINF->Connect() == CD_SUCCESS)
{
strcpy(processText,"submit maxdelay=unlimited sdksample process snode=SNODENAME ");
strcat(processText,"copy00 copy from (file=sample.txt pnode)");
strcat(processText," to (file=sample.000 snode disp=rpl) ;");
if (cdSess.SessionINF->SendCommand(processText) == CD_SUCCESS)
{
printf("%s completed, pnumber = %ld.\n",
cdSess.SessionINF->GetCommandName(),
cdSess.SessionINF->GetProcessNumber());
sprintf(processText, "SELECT STATISTICS PNUMBER=%ld DETAIL=YES ;", cdSess.SessionINF-
>GetProcessNumber());
(cdSess.SessionINF->SendCommand(processText) == CD_SUCCESS)
{
}
else
{
getError(cdSess);
}
}
else
{
getError(cdSess);
}
cdSess.SessionINF->DisConnect();
}
else
{
getError(cdSess);
}
}
void getError(ConnectDirectSession& cdSess)
{
if (cdSess.SessionINF->GetFirstError())
{
printf("\nError Message: %s", cdSess.SessionINF->GetMsgID());
printf("\nError Feedback: %d", cdSess.SessionINF->GetFeedBackCode());
printf("\nError RC: %d", cdSess.SessionINF->GetReturnCode());
printf("\nError SUBST: %s\n", cdSess.SessionINF->GetSubstitute()); }
while(cdSess.SessionINF->GetNextError())
{
printf("\nError Message: %s", cdSess.SessionINF->GetMsgID());
printf("\nError Feedback: %d", cdSess.SessionINF->GetFeedBackCode());
printf("\nError RC: %d", cdSess.SessionINF->GetReturnCode());
printf("\nError SUBST: %s\n", cdSess.SessionINF->GetSubstitute());
}
}

The ConnectDirectSession class methods are described in the following table:

Method Description Parameter Return Values

Connect Provides a connection to the IBM void or a CD_SUCCESS or
Connect:Direct server. pointer to an CD_FAILURE
IP address
Connect() with a void parameter
and port.
connects to the hostname and port
specified in the client configuration
file.

DisConnect Disconnects the current session. void CD_SUCCESS or

CD_FAILURE

Chapter 4. User Guide 207

 Method Description Parameter Return Values
SendCommand Sends a IBM Connect:Direct command Pointer to a CD_SUCCESS or
to the server for processing. command text CD_FAILURE
buffer.
ReceiveResponse Receives the response from a void CD_SUCCESS or
previously issued command, such as CD_FAILURE
the select statistics command.
GetResponse Retrieves the response from the void Pointer to a response
ReceiveResponse call. buffer.
GetResponseLength Returns the length of the previously void Length of the response
received response buffer. buffer from the
previously issued call.
MoreData Returns a value indicating if void TRUE—If more data is
outstanding data from the previously outstanding.
issued send command call is available.
FALSE—If no data is
If the return value is TRUE, call
outstanding.
ReceiveResponse again to retrieve
more data.
GetCommandName Returns the command name of the void Pointer to a command
previously issued send command, name buffer.
such as the submit command.
GetProcessNumber Returns the Process number of a void Process number of a
previously issued submit command. submit command.
-1—If no submit
command can be
found.

GetProcessCount Returns the number of Processes void Process number of a

affected by the last send command submit command that
that issued a delete, change, or flush issued a delete, change
process. or flush process.
-1—If no submit
command can be
found.

GetCurrentError Moves the error data pointer to the void TRUE—If successful
current error in the list. FALSE—If no current
error exists.
GetNextError Moves the error data pointer to the void TRUE—If successful
next error in the list.
FALSE—If no more
errors are found.

GetPreviousError Moves the error data pointer to the void TRUE—If successful
previous error in the list.
FALSE—If no previous
error exists.

GetFirstError Moves the error data pointer to the void TRUE—If successful
first error in the list.
FALSE—If no error is
found.

208 IBM Connect:Direct for UNIX: Documentation

Method Description Parameter Return Values
GetLastError Moves the error data pointer to the void TRUE—If successful,
last error in the list. otherwise FALSE.
GetMsgID Retrieves the message of the current void Return Value: Pointer
error data block. to a message ID if data
block is value.
You must call one of the GetXXXXError
methods before calling this method in
order to retrieve the proper results.

GetFeedBackCode Returns the feedback code of the void Feedback code.

current error data block.
GetReturnCode Returns the IBM Connect:Direct return void One of the valid IBM
code. Connect:Direct return
code: 1,4,8,16.
GetStatus Returns the status. void IBM Connect:Direct
status code.
GetSubstitute Returns the current substitution buffer void Pointer to a
associated with the error. substitution buffer.
DisplayError Displays the current error chain to an Parameters: Return Value: Returns
output location. Pointer to a the highest error found
file I/O in the error chain or -1
structure. on error.

Following is the ConnectDirectSession class header:

#include <stdio.h>

// Error enumeration.
typedef enum CDErrorCode
{
CD_SUCCESS = 0,
CD_FAILURE = -1

} CDErrorCode;

// <<Interface>>
class CDSession
{
public:
// Communication methods...
virtual CDErrorCode Connect(void) = 0;
virtual CDErrorCode Connect(char *IpAddress, char *IpPort) = 0;
virtual CDErrorCode DisConnect(void) = 0;
virtual CDErrorCode SendCommand(char *CmdText) = 0;
virtual CDErrorCode ReceiveResponse(void) = 0;

// Methods for retrieving ReceiveResponse data...

virtual const char *GetResponse(void) = 0;
virtual int GetResponseLength(void) = 0;
virtual bool MoreData(void) = 0;

// Methods for retrieving SendCommand return data...

virtual const char *GetCommandName(void) = 0;
virtual long GetProcessNumber(void) = 0;
virtual long GetProcessCount(void) = 0;

// Methods to iterate over error collection ...

virtual bool GetCurrentError(void) = 0;
virtual bool GetNextError(void) = 0;
virtual bool GetPreviousError(void) = 0;
virtual bool GetFirstError(void) = 0;
virtual bool GetLastError(void) = 0;

// Methods to retrieve error data...

virtual const char *GetMsgID(void) = 0;

Chapter 4. User Guide 209

 virtual int GetFeedBackCode(void) = 0;
virtual int GetReturnCode(void) = 0;
virtual int GetStatus(void) = 0;
virtual const char *GetSubstitute(void) = 0;

// Method to display error collection...

virtual int DisplayError(FILE *Output) = 0;
};

class ConnectDirectSession
{
public:
// Interface classes
CDSession *SessionINF;

ConnectDirectSession();
~ConnectDirectSession();
};

Writing User Exits

The user exit API functions allow you to write custom programs to use with IBM Connect:Direct. The user
exit programs are used by IBM Connect:Direct to invoke user-specific logic at strategic points within IBM
Connect:Direct execution. User exit programs must be C or C++ language programs and cannot be shell
scripts. The PMGR invokes the Statistics user exit program when you start IBM Connect:Direct and the
exit runs as long as IBM Connect:Direct runs. The SMGR invokes the File Open and Security user exits for
each session and stops them when the particular session terminates.

Note: exit_skeleton.c and exit_skeleton.C contain working examples of all three exits and can be made
with the make_exit_c and make_exit_C make files.
The user exit programs are described in the following:

Program Description
File Open Exit IBM Connect:Direct sends a message to this user
exit program to open the source or destination file
during processing of the copy statement. The File
Open Exit opens the source file and identifies the
file descriptor. This exit can perform any sort of
processing to file names or directory names. It can
also redirect the open request to other files as
needed.
The File Open Exit program (named “exit_skeleton”
in this example) must be owned by root and the
setuid bit must be set. Use the following
commands:
% chown root exit_skeleton
% chmod u+s exit_skeleton

Security Exit The Security Exit enables you to implement your

own security system or provide access to a third-
party security system.

Statistics Exit The Statistics Exit is a notification to the user exit

program after any record is written to the statistics
file. Whenever a statistics record is written to the
statistics file, an exact copy is passed to this exit.

210 IBM Connect:Direct for UNIX: Documentation

User Exit Functions
A connection between the user exit and IBM Connect:Direct is established when the user exit program
calls the exit_child_init() or exit_child_init_c() function. The connection is terminated through a specially
designated stop message. The types of messages are defined in the include file user_exit.h. The following
functions facilitate communications between the user exit and IBM Connect:Direct:

C++ Function C Function Description

exit_child_init() exit_child_init_c() Use this function as the first line in a user exit program to
initialize communications between IBM Connect:Direct and
the user exit program.
recv_exit_msg() recv_exit_msg_c() Used by both IBM Connect:Direct and the user exit
program to receive a message from the other Process. The
receive exit messages wait for a response from the other
Process.
send_exit_file() send_exit_file_c() The user exit program uses this function when it has
opened a file for IBM Connect:Direct. This function uses
underlying UNIX methods to pass an open file descriptor.
from one Process to another.
send_exit_msg() send_exit_msg_c() Both IBM Connect:Direct and the user exit program use
this function to send a message to the other Process. Send
messages are followed with a receive message to get the
response from the other Process.

Initializing Communications with exit_child_init() or exit_child_init_c()

Use the exit_child_init() or exit_child_init_c() function as the first line of code of the user exit program to
initialize communications. This function performs a check to verify that each side is ready to
communicate. Following is the format of the exit_child_init() function:

int exit_child_init( char * logfile )

The exit_child_init() or exit_child_init_c() function has the following parameter:

Parameter Description Value

logfile The name of the log or trace file that is opened for use by the Name of log file or trace
user exit programs. Because the file open and security exit file
are started by SMGR, which is running as root, the exits also
run as root. Running the exits as root can cause problems
with file permissions of the log file, so logfile enables you to
easily change owner or permissions on the file. See the
sample exit in d_dir/ndm/src/exit_skeleton.c for more
details.

The exit_child_init() or exit_child_init_c() function have the following return codes. Return codes for the
function are defined in ndmapi.h.

Return Code Description

GOOD_RC Communications between IBM Connect:Direct and
the user exit program were successfully initialized.

ERROR_RC Communications between IBM Connect:Direct and

the user exit program could not be initialized.

Chapter 4. User Guide 211

 Waiting for a Message Using recv_exit_msg() or recv_exit_msg_c()
The recv_exit_msg() or recv_exit_msg_c() function waits until it receives a message from IBM
Connect:Direct. Control is suspended until a message is received or an error occurs. The recv_exit_msg()
has the following format:

int recv_exit_msg( int exit_flag )

int * msg_type,
char * recv_buf,
int * recv_buf_len

The recv_exit_msg() or recv_exit_msg_c() functions have the following parameters:

Parameter Description Value

exit_flag A flag to specify the recipient ID. The only valid value a user EXIT_PROGRAM
exit program can use is EXIT_PROGRAM.
msg_type A pointer to the name of the received message. Messages Pointer to message
are requests from IBM Connect:Direct and the associated
response from the user exit program.
recv_buf A pointer to the memory location of the message. Pointer to message
recv_buf_len The length in bytes of the message to be received. Length of message

The recv_exit_msg()or recv_exit_msg_c() functions have the following return codes. Return codes for the
function are defined in ndmapi.h.

Return Code Description

GOOD_RC The message was received successfully.

ERROR_RC An error occurred and the message was not

received successfully. Possible causes include:
IBM Connect:Direct terminated, an invalid value
used for the exit_flag parameter, or the receiving
buffer not large enough to hold the message
received.

Passing a File Descriptor Using send_exit_file() or send_exit_file_c()

Use the send_exit_file() or send_exit_file_c() function to pass a file descriptor from one Process to
another Process. Following is the format of send_exit_file():

int send_exit_file int exit_flag

int fd

Following are the parameters for send_exit_file() or send_exit_file_c():

Parameter Description Value

exit_flag A flag to specify the sender ID. The only valid value a user exit EXIT_PROGRAM
program can use is EXIT_PROGRAM.
fd The file descriptor of a file that the user exit program opened in File descriptor
the place of IBM Connect:Direct, similar to one returned by the
open(2) function.

The send_exit_file() or send_exit_file_c() function calls have the following return codes. Return codes for
the function are defined in ndmapi.h.

212 IBM Connect:Direct for UNIX: Documentation

 Header Header
GOOD_RC The file descriptor was received successfully.

ERROR_RC An error occurred and the file descriptor was not

sent successfully. Possible causes include: IBM
Connect:Direct terminated, an invalid value used
for the exit_flag or fd parameters, or the last
message sent was not send_exit_msg.

Sending a Message to IBM Connect:Direct Using send_exit_msg() or

send_exit_msg_c()
The send_exit_msg() or send_exit_msgc() function enables the user exit program to send a message to
IBM Connect:Direct. This function returns control to the caller immediately after the message is queued.
Following is the format of the send_exit_msg() function:

int send_exit_msg int exit_flag

int msg_type,
char * send_buf,
int send_buf_len

Following are the parameters for send_exit_msg() or send_exit_msg_c():

Parameter Description Value

exit_flag A flag to specify the sender ID. The only valid value a user EXIT_PROGRAM
exit program can use is EXIT_PROGRAM.
msg_type A message name. Messages are requests from IBM Pointer to message
Connect:Direct and the associated response from the user
exit program.
send_buf A pointer to the memory location of the message to be sent. Pointer to message
send_buf_len The length in bytes of the message to be sent. Length of message

Following are the return codes for send_exit_msg() or send_exit_msg_c(). Return codes for the function
are defined in ndmapi.h.

Return Code Description

GOOD_RC The message was sent successfully.

ERROR_RC An error occurred and the message was not sent

successfully. Possible causes include: IBM
Connect:Direct terminated or an invalid value is
used for the exit_flag or msg_type parameters.

Overview of User Exit Messages

IBM Connect:Direct sends and receives messages, using the send_exit_msg() and the recv_exit_msg()
functions for a C++ program or the send_exit_msg_c() and the recv_exit_msg_c() functions for a C
program. For the exact definition of the data sent in each message, see the files located in d_dir/ndm/
include/user_exit.h and d_dir/ndm/include/user_exit2.h.
Note: The copy control block is defined in user_exit2.h.

Chapter 4. User Guide 213

 Statistics Exit Message
The statistics exit has only one type of message, the STATISTICS_LOG_MSG.
IBM Connect:Direct sends a STATISTICS_LOG_MSG to the user exit program. Every time IBM
Connect:Direct writes a statistic record, this message provides an exact copy of the character string. The
STATISTICS_LOG_MSG contains the IBM Connect:Direct statistics record.

File Open Exit Messages

The file open exit has four types of messages:
• FILE_OPEN_OUTPUT_MSG
• FILE_OPEN_OUTPUT_REPLY_MSG
• FILE_OPEN_INPUT_MSG
• FILE_OPEN_INPUT_REPLY_MSG
The file open exit has the following limitations:
• The oflag parameter passed to the user exit is already calculated based on the file disposition, as
explicitly specified on the copy statement or using the default value. If the user exit changes the oflag to
truncate and the original disposition is mod meaning the copy will append to the end of file if the file
already exists, then the user exit causes the Process to behave differently from how the Process
language is documented.
• Do not change the file type specified by the Process. For example, if the Process specifies a regular file,
the user exit cannot open and return a file descriptor for a pipe. No facility is available to modify
contents of the copy control block and return it to IBM Connect:Direct.
• If the oflag specifies opening a file with write access and the user exit changes access to read-only, IBM
Connect:Direct will fail when it attempts to write to a read-only file.
• The upload and download parameters that restrict directory access are ignored for this user exit.

FILE_OPEN_OUTPUT_MSG
During the copy statement process, IBM Connect:Direct sends a FILE_OPEN_OUTPUT_MSG to the user
exit program to open the destination file. The FILE_OPEN_OUTPUT_MSG contains:

• The open function oflag parameter (for example, O_CREAT|O_RDWR|O_TRUNC)

• The open function mode parameter, which controls file permissions
• UNIX user ID that will own the file
• UNIX group ID that will own the file
• UNIX user name
• A copy of the IBM Connect:Direct copy control block
• A copy of the IBM Connect:Direct parsed sysopts structure (the copy control block contains the actual
raw version from the process)

FILE_OPEN_OUTPUT_REPLY_MSG
The user exit program sends a reply message to the IBM Connect:Direct FILE_OPEN_OUTPUT_MSG. The
FILE_OPEN_OUTPUT_REPLY_MSG contains:

• Status value of zero for successful or non zero for failure

• Status text message (if status value is failure, status text message is included in the error message)

214 IBM Connect:Direct for UNIX: Documentation

• Pipe pid (for pipe I/O, the UNIX process ID of the shell process that is performing the shell command for
pipe I/O)
• Actual file name opened (to be used in statistics log messages)
If the status value is zero for successful, the user exit program must immediately call send_exit_file() or
send_exit_file_c() to send the file descriptor of the opened file to IBM Connect:Direct.

FILE_OPEN_INPUT_MSG
During the copy statement Process, IBM Connect:Direct sends a FILE_OPEN_INPUT_MSG to the user exit
program to open the source file. The FILE_OPEN_INPUT_MSG contains:

• The open function oflag parameter (for example, O_RDONLY)

• The open function mode parameter, which controls file permissions
• UNIX user ID that will own the file
• UNIX group ID that will own the file
• UNIX user name
• A copy of the IBM Connect:Direct copy control block
• A copy of the IBM Connect:Direct parsed sysopts structure (the copy control block contains the actual
raw version from the Process)

FILE_OPEN_INPUT_REPLY_MSG
This message type is used when the user exit program sends a reply message to the IBM Connect:Direct
FILE_OPEN_INPUT_MSG. The FILE_OPEN_INPUT_REPLY_MSG contains:

• Status value of zero for success or non zero for failure

• Status text message (if status value is failure, status text message is included in the error message)
• Pipe pid (for pipe I/O, the UNIX process ID of the shell process that is performing the shell command for
pipe I/O)
• Actual file name opened (used in statistics log messages)

Security Exit Messages

The security exit contains four types of messages:
• GENERATE_MSG
• GENERATE_REPLY_MSG
• VALIDATE_MSG
• VALIDATE_REPLY_MSG
CAUTION: If the security exit is used, IBM Connect:Direct relies on it for user ID authentication. If
the security exit is not implemented correctly, security can be compromised.

GENERATE_MSG
IBM Connect:Direct sends a generate message to the user exit program at the start of a session to
establish a security environment. The PNODE sends the GENERATE_MSG to the security exit to determine
a user ID and security token to use for authentication on the SNODE. The GENERATE_MSG contains:

• Submitter ID
• PNODE ID

Chapter 4. User Guide 215

 • PNODE ID password, if user specified one
• SNODE ID
• SNODE ID password, if user specified one
• PNODE name
• SNODE name

GENERATE_REPLY_MSG
The user exit program sends a reply message to IBM Connect:Direct. The GENERATE_REPLY_MSG
contains:

• Status value of zero for success or non zero for failure

• Status text message (if status value is failure, status text message is included in the error message)
• ID to use for security context on the SNODE side (may or may not be the same ID as in the generate
message)
• Security token used in conjunction with ID for security context on the SNODE side

VALIDATE_MSG
IBM Connect:Direct sends a validate message to the user exit program. The SNODE sends the
VALIDATE_MSG to the security exit to validate the user ID and security token received from the PNODE.
The VALIDATE_MSG contains:

• Submitter ID
• PNODE ID
• PNODE ID password, if user specified one
• SNODE ID
• SNODE ID password, if user specified one
• PNODE name
• SNODE name
• ID to use with security token
• Security token (password, PASSTICKET, or other security token)

VALIDATE_REPLY_MSG
The user exit program sends a reply message to the IBM Connect:Direct VALIDATE_MSG. The
VALIDATE_REPLY_MSG contains:

• Status value of zero for success or non zero for failure

• Status text message (if status value is failure, status text message is included in the error message)
• ID used for security context
• Security token to use in conjunction with ID for security context

User Exit Stop Message

216 IBM Connect:Direct for UNIX: Documentation

 IBM Connect:Direct sends the stop message, STOP_MSG, when all useful work for the user exit is
complete and to notify the user exit to terminate. A user exit should terminate only when a stop message
is received or if one of the above listed user exit functions returns an error code.

Copy Control Block

The copy control block structure contains the fields, which control how IBM Connect:Direct Processes the
copy statement Process file.

Exit Log Files

If user exit programs are specified in the initparm.cfg, IBM Connect:Direct creates exit logs. Exit log files
are provided specifically for the user exit programs and are used for debug and trace type messages. The
user exit program is started with the log file already opened on STDOUT and STDERR. The exit log files
are:

• stat_exit.log
• file_exit.log
• security_exit.log
Note: You can access the log files through the normal printf() and fprintf (stderr,...) functions.
The log files are located in the installed (d_dir) working directory:
.../d_dir/work/cd_node

Chapter 4. User Guide 217

218 IBM Connect:Direct for UNIX: Documentation
Chapter 5. Using FASP with IBM Aspera High-Speed
Add-on for Connect:Direct for UNIX (V4.2.0.3 or
later)
IBM Aspera High-Speed Add-on for Connect:Direct for UNIX uses FASP (Fast and Secure Protocol)
network transport to transfer files over high bandwidth and high latency network connections.
At low latency it performs similarly to TCP/IP. However, as latency and packet loss increase, unlike TCP/IP,
its performance does not degrade, and FASP continues to take advantage of all the available bandwidth.
IBM Aspera High-Speed Add-on for Connect:Direct for UNIX (V4.2.0.4 or later) supports interoperability
with Connect:Direct for Microsoft Windows (V.4.7.0.4 or later) and Secure Proxy (V3.4.3.0 or later).
Note: Secure+ is used to secure FASP transfers exactly the same way it is used for TCP/IP transfers.
Related concepts
“Using Connect:Direct for UNIX with IBM Aspera High-Speed Add-on and Secure Proxy (V4.2.0.4 or
later)” on page 221
You can send files using IBM Aspera High-Speed Add-on through Secure Proxy using Connect:Direct for
UNIX.

Activating FASP
By default, IBM Aspera High-Speed Add-on for Connect:Direct is not enabled. To enable it, you must
download a license key and install Connect:Direct for UNIX V4.2.0.4 iFix 13 or later.

About this task

Procedure
1. Download the IBM Aspera High-Speed Add-on for Connect:Direct license key for your Connect:Direct
node from Passport Advantage.
2. Rename the file aspera-license.
3. Save the renamed file to the <cd_dir>/ndm/cfg/<nodename> directory.
4. Download and install Connect:Direct for UNIX V4.2.0, Fix Pack 3 (or later) from Fix Central.
Important: The Connect:Direct install package includes the IBM Aspera High-Speed Add-on for
Connect:Direct configuration file (aspera.conf). It contains the minimum necessary basic configuration
statements to use FASP on Connect:Direct. It is always installed even if you do not purchase IBM
Aspera High-Speed Add-on for Connect:Direct. Do NOT make any changes to this file.

Licensed bandwidth for FASP transactions

The bandwidth available to a file transfer is limited by, among other things, the bandwidths specified in
the sender’s and receiver’s Aspera license keys.
There are two types of available license keys:
• Datacenter licenses (available in 10gbps, 1gbps, 300mbps and 100mbps) - can send and receive files
using FASP when connected to a node that has an Endpoint or DataCenter license.
• Endpoint license - can send and receive files using FASP when connected to a node that has a
DataCenter license.
Note: Aspera FASP bandwidth setting should not exceed the network capability. As per the available
network bandwidth in your network, start with a reasonable setting e.g. 100 mbps. FASP bandwidth

© Copyright IBM Corp. 1993, 2018 219

 setting is likely to max out the resources especially CPU. FASP requires more CPU than normal TCP/IP
transfer and secure+ requires even more CPU than Non-Secure+ transfer. In case of high CPU usage
(reaching approx. 100%), either add more CPU resources or reduce the FASP bandwidth setting.
When both sender and receiver only have Endpoint licenses, file transfer over FASP is not supported.
When either the sender or receiver has an Endpoint license and the other has a Datacenter license, the
available bandwidth is limited to the value in the Datacenter license. When both sender and receiver have
Datacenter licenses, the bandwidth is limited to the smaller of the two values in the Datacenter licenses.

FASP Process Language

Once the FASP parameters for both trading partners have been configured, you can override the default
settings on a process by process basis to perform exception processing.

Optional Parameters
FASP Parameters:
• FASP (Yes | No)
• FASP POLICY (Values are the same as the FASP Local and Remote node record parameters)
• FASP.FILESIZE.THRESHOLD (Values are the same as the FASP Local and Remote node record
parameters)
• FASP.BANDWIDTH (Values are the same as the FASP Local and Remote node record parameters)
FASP Parameters are applicable in three different contexts:
• COPY statement - The four FASP parameters may be used individually or as a group within a COPY
statement. This will set FASP values for the duration of that COPY statement and will not have any effect
on statements within the submitted Process
• PROCESS statement - The four FASP parameters may be used individually or as a group at the end of a
PROCESS statement. This will set the FASP parameters for all of the COPY statements in the process
• SUBMIT command - The four FASP parameters may be set individually or as a group at the end of a
SUBMIT command. This will set the FASP parameters for all COPY statements in the process being
submitted These settings will set FASP information for their relevant part of the scope, potentially
overriding the Local Node settings, Remote Node settings and each other.

Examples
Copy statement example:

step01 copy
from
(
file = /tmp/exampleout
pnode
)
ckpt = 2M
compress extended
fasp=yes
fasp.policy=fixed
fasp.bandwidth=500M
fasp.filesize.threshold=10G
to
(
file = /tmp/examplein
snode
disp = rpl
)

Process statement example:

220 IBM Connect:Direct for UNIX: Documentation

 SAMPLE PROCESS SNODE=WINVM-470
fasp=yes
fasp.policy=fixed
fasp.bandwidth=500M
fasp.filesize.threshold=10G
step01 copy
from
(
file = /tmp/exampleout
pnode
)
ckpt = 2M
compress extended
to
(
file = /tmp/examplein
snode
disp = rpl
)
PEND

Hierarchy Settings
The system uses the following hierarchy to process overrides:
1. Remote node record overrides local node record.
2. Process parameters override remote node record.
3. Submit statement overrides the process parameters.
4. Each Copy statement overrides the effective settings of the session established by the node settings,
Process or Submit statements. The Copy statement override is effective only for the duration of the
Copy step.

Using Connect:Direct for UNIX with IBM Aspera High-Speed Add-

on and Secure Proxy (V4.2.0.4 or later)
You can send files using IBM Aspera High-Speed Add-on through Secure Proxy using Connect:Direct for
UNIX.
FASP is supported in Secure Proxy V3.4.3 or later. If you send a file from your local Connect:Direct for
UNIX node configured for FASP, it passes through your Secure Proxy instance using FASP, and is sent to
the remote node.
In addition to the FASP parameter values outlined in Configuring FASP, the following parameter should be
used when using Secure Proxy between Connect:Direct nodes:

fasp=(yes|no|ssp,yes|no|ssp)

The first parameter is the default for Connect:Direct as the PNODE. The second parameter is the default
for Connect:Direct as the SNODE.
This parameter can now be used in the netmap local node record and remote node trading partner record
in Connect:Direct for UNIX.
The following table shows results when Connect:Direct FASP protocol is used between two
Connect:Direct nodes with no Sterling Secure Proxy involved.

PNODE fasp= Protocol SNODE fasp=

N TCP N
N TCP Y
N TCP SSP

Chapter 5. Using FASP with IBM Aspera High-Speed Add-on for Connect:Direct for UNIX (V4.2.0.3 or later) 221
 Y TCP N
Y C:D FASP Y
Y TCP SSP
SSP TCP N
SSP TCP Y
SSP TCP SSP

The following table shows results when Connect:Direct FASP protocol is used with two Connect:Direct
nodes going through a single instance of Sterling Secure Proxy.

PNODE fasp= Protocol SSP Protocol SNODE fasp=

N TCP SSP TCP N
N TCP SSP TCP Y
N TCP SSP TCP SSP
Y TCP SSP TCP N
Y C:D FASP SSP C:D FASP Y
Y C:D FASP SSP TCP SSP
SSP TCP SSP TCP N
SSP TCP SSP C:D FASP Y
SSP TCP SSP TCP SSP

The following table shows results when Connect:Direct FASP protocol is used with two Connect:Direct
nodes going through two instances of Sterling Secure Proxy.

PNODE Protocol SSP Protocol SSP Protocol SNODE

fasp= fasp=
N TCP SSP TCP SSP TCP N
N TCP SSP TCP SSP TCP Y
N TCP SSP TCP SSP TCP SSP
Y TCP TCP TCP SSP TCP N
Y C:D FASP SSP C:D FASP SSP C:D FASP Y
Y C:D FASP SSP C:D FASP SSP TCP SSP
SSP TCP SSP TCP SSP TCP N
SSP TCP SSP C:D FASP SSP C:D FASP Y
SSP TCP SSP C:D FASP SSP TCP SSP

For more information on using Sterling Secure Proxy with FASP, see Using FASP with Sterling Secure Proxy
(V3.4.3 or later).

222 IBM Connect:Direct for UNIX: Documentation

Configuring FASP

About this task

FASP configuration settings are not added to the Connect:Direct configuration files during install. To
enable IBM Aspera High-Speed Add-on for Connect:Direct, you must manually configure the initparm.cfg
and netmap.cfg files to run FASP.

Procedure
1. Do one of the following steps:
• If you installed Connect:Direct for UNIX V4.2.0.4 as a new installation (you did not upgrade from a
previous version), go to Step 2. The initparm.cfg file is already configured for FASP listen ports.
• If you upgraded from a previous version of Connect:Direct for UNIX to V4.2.0.4, you must configure
the initparm.cfg file by specifying a FASP listen port or port ranges.
Format is listen.ports=(nnnnn, nnnnn-nnnnn).
Example:

# FASP listen ports

fasp:\
:listen.ports=(44001, 33002-33005):

Note: The number of concurrent FASP processes is limited to the number of ports designated in this
file. If you attempt to use more concurrent FASP processes than there are ports available fails, FASP
fails.
2. Configure the netmap.cfg file by specifying FASP values for the local node record. Use the following
chart.
Example:

local.node:\

…
:fasp=yes:\
:fasp.policy=fair:\
:fasp.bandwidth=500MB:\
:fasp.filesize.threshold=2GB:\

Parameter Value
fasp Optional. Default is no if the parameter is not
present. Enables FASP.
• If set to no, FASP is disabled.
• If set to yes, yes, FASP is enabled. This sets the
default for all Connect:Direct file transfers.
fasp=(pnode value, snode value), for example,
fasp=(yes, ssp)
• This setting can be overridden by the remote
node record or process parameters.
• The remote server must have FASP enabled.

fasp.filesize.threshhold Optional. Used to restrict small files from being

sent using FASP.
• If the file is greater than or equal to the stated
value, the Connect:Direct server sends the file
using FASP. Otherwise, it is sent using TCP/IP.

Chapter 5. Using FASP with IBM Aspera High-Speed Add-on for Connect:Direct for UNIX (V4.2.0.3 or later) 223
 Parameter Value

• Default is 1GB.
• You can use KB, MB, or GB designators. If no
designator is included, the system uses bits.
• This setting can be overridden by the remote
node record or process parameters.

fasp.bandwidth Optional. Default is as stipulated in the FASP

license key. Specifies how much bandwidth each
transfer can use.
• Default value can be changed, but cannot
exceed the bandwidth specified in the license
key.
• You can use KB, MB, or GB designators. If no
designator is included, the system uses bits per
second.
• This setting can be overridden by the remote
node record or process parameters, but cannot
exceed the bandwidth specified in the license
key.

fasp.policy Optional. Specifies the fairness of each transfer.

Default is fair.
• This setting can be overridden by the remote
node record or process parameters.
• Valid values are:
– Fixed - FASP attempts to transfer at the
specified target rate, regardless of the actual
network capacity. This policy transfers at a
constant rate and finishes in a guaranteed
amount of time. This policy typically occupies
a majority of the network's bandwidth, and is
not recommended in most file transfer
scenarios.
– Fair - FASP monitors the network and adjusts
the transfer rate to fully utilize the available
bandwidth up to the maximum rate. When
other types of traffic build up and congestion
occurs, FASP shares bandwidth with other
traffic fairly by transferring at an even rate.
This is the best option for most file transfer
scenarios.
– High - FASP monitors the network and
adjusts the transfer rate to fully utilize the
available bandwidth up to the maximum rate.
When congestion occurs, a FASP session
with high policy transfers at a rate twice of a
session with fair policy.
– Low - Similar to Fair mode, the Low (or
Trickle) policy uses the available bandwidth
up to the maximum rate as set in the Aspera

224 IBM Connect:Direct for UNIX: Documentation

 Parameter Value

license file. When congestion occurs, the

transfer rate is decreased all the way down
to the minimum rate as set in the Aspera
license file.

3. (Optional) Configure the netmap.cfg file by specifying FASP values for the remote node record. Use the
following chart. Configure the remote node if you need to override your local node settings. For
example, if you want to exclude a trading partner from using FASP. You can also configure the remote
node record later.
Example:

myRmtNodePartner:\

…
:fasp=yes:\
:fasp.policy=fair:\
:fasp.bandwidth=1GB:\
:fasp.filesize.threshold=1GB:\

Parameter Value
fasp Optional. Valid values are yes and no. Enables
FASP.
• If set to no, files sent to this remote node will
not use FASP.
• If set to yes, files sent to this remote node will
default to use FASP instead of TCP/IP.
• This setting can be overridden by the process
parameters.
• The remote server must have FASP enabled.

fasp.filesize.threshhold Optional. Used to restrict small files from being

sent using FASP.
• If the file is greater than or equal to the stated
value, the Connect:Direct server sends the file
using FASP. Otherwise, it is sent using TCP/IP.
• Default is 1GB.
• You can use KB, MB, or GB designators. If no
designator is included, the system uses bits.
• This setting can be overridden by the process
parameters.

fasp.bandwidth Optional. Default is as stipulated in the FASP

license key. Specifies how much bandwidth each
transfer can use.
• Default value can be changed, but cannot
exceed the bandwidth specified in the license
key.
• You can use KB, MB, or GB designators. If no
designator is included, the system uses bits per
second.

Chapter 5. Using FASP with IBM Aspera High-Speed Add-on for Connect:Direct for UNIX (V4.2.0.3 or later) 225
 Parameter Value

• This setting can be overridden by the process

parameters, but cannot exceed the bandwidth
specified in the license key.

fasp.policy Optional. Specifies the fairness of each transfer.

Default is fair.
• This setting can be overridden by the process
parameters.
• Valid values are:
– Fixed - FASP attempts to transfer at the
specified target rate, regardless of the actual
network capacity. This policy transfers at a
constant rate and finishes in a guaranteed
amount of time. This policy typically occupies
a majority of the network's bandwidth, and is
not recommended in most file transfer
scenarios.
– Fair - FASP monitors the network and adjusts
the transfer rate to fully utilize the available
bandwidth up to the maximum rate. When
other types of traffic build up and congestion
occurs, FASP shares bandwidth with other
traffic fairly by transferring at an even rate.
This is the best option for most file transfer
scenarios.
– High - FASP monitors the network and
adjusts the transfer rate to fully utilize the
available bandwidth up to the maximum rate.
When congestion occurs, a FASP session
with high policy transfers at a rate twice of a
session with fair policy.
– Low - Similar to Fair mode, the Low (or
Trickle) policy uses the available bandwidth
up to the maximum rate as set in the Aspera
license file. When congestion occurs, the
transfer rate is decreased all the way down
to the minimum rate as set in the Aspera
license file.

FASP Messages
Use the following table to obtain FASP error message information.
Note: Long text message files for these message IDs can be viewed using the Connect:Direct Requester
Message Lookup utility.

Non-Detailed Statistics Mode (Message ID only) Detailed Statistics Mode

FASP001E FASP001E: FASP server session creation failed.
FASP002E FASP002E: FASP client session creation failed.
FASP003E FASP003E: FASP could not be initialized.

226 IBM Connect:Direct for UNIX: Documentation

 Non-Detailed Statistics Mode (Message ID only) Detailed Statistics Mode
FASP004E FASP004E: Lock timeout.
FASP005E FASP005E: Memory allocation failure.
FASP006E FASP006E: Condition wait timed out.
FASP007E FASP007E: No FASP listen ports available.
FASP008E FASP008E: FASP disabled due to file size
&FILESIZE < threshold &THRESHOLD
FASP009E FASP009E: FASP session terminated unexpectedly.
FASP010E FASP010E: SNODE refused FASP, FASP disabled.
FASP011E FASP011E: FASP CRC verification failed.
FASP012E FASP012E: FASP disabled due to conflict with
UDT33.
FASP020E FASP020E: Session Manager received invalid FASP
control message.
FASP021E FASP021E: FASP control message fragmented or
invalid.
FASP022E FASP022E: Session Manager failed to receive FASP
control message.
FASP023E FASP023E: The FASP control message to send
exceeds the buffer size.
FASP024E FASP024E: Session Manager failed to send FASP
control message.
FASP030E FASP030E: FASP license file not found.
FASP031E FASP031E: FASP license file expired.
FASP032E FASP032E: FASP license in error.
FASP033E FASP033E: FASP license is malformed.
FASP034E FASP034E: FASP license is malformed.
FASP035E FASP035E: FASP License file at &LOCATION will
expire in &VALUE day(s).
FASP040E FASP040E: FASP initialization failed - remote
&TYPE &NODE. Error=&ERROR.
FASP041E FASP041E: FASP initialization failed - local &TYPE
&NODE. Error=&ERROR.
FASP042E FASP042E: FASP initialization failed.

Monitoring FASP transactions

You can view the Copy Termination Record (CTRC) for detailed statistics. For example, you can verify FASP
was used, what bandwidth was used, and which policy was used.
In the example below, note the following explanations:
• FASP=>Y indicates that FASP was used to transfer this file. FASP=>N would indicate TCP/IP was used.
• FSPL=>FAIR is the policy negotiated for this file transfer.

Chapter 5. Using FASP with IBM Aspera High-Speed Add-on for Connect:Direct for UNIX (V4.2.0.3 or later) 227
 • FSBW=>1000000000 is the bandwidth negotiated for this file transfer (in bits per second).
• FMBC =>2 is the high water mark for the number of FASP buffers used
• FBCS =>16777216 is the FASP buffer size
• FSTH =>1073741824 is filesize threshold
• FSLP =>23708 is listen port used for FASP
Example:

PROCESS RECORD Record Id => CTRC

Completion Code => 0
Message Id => SCPA000I
Short Text => Copy step successful.
Ckpt=>Y Lkfl=>N Rstr=>N Xlat=>N Scmp=>N Ecmp=>N CRC=>N
FASP=>Y FSPL=>FAIR FSBW=>10000000000 FMBC=>2 FBCS=>16777216 FSTH=>1073741824
FSLP=>23708

Limitations
The following features cannot be used with FASP and Connect:Direct for UNIX:
• Firewall navigation source ports should not be used with FASP
• Silent installation does not support the FASP configuration parameters

228 IBM Connect:Direct for UNIX: Documentation

Chapter 6. Using S3 object store providers with IBM
Connect:Direct for UNIX

IBM Connect:Direct for UNIX can be configured to extend support to S3 object storage providers including
AWS, Minio, Dell EMC ECS, and Red Hat Ceph to execute public and on-premise cloud-based operations.
Users can now continue using the benefits of Connect:Direct features like security, reliability, and point-
to-point file transfers optimized for high-volume delivery along with versatility that comes with a S3
storage backend.
Note that by default, Connect:Direct for Unix uses AWS S3 object store to transfer data between nodes
installed on an EC2 instance or On-prem nodes, using pre-defined AWS S3 buckets. For more information
on how to configure Connect:Direct to use other S3 object store providers see, “Setting up Connect:Direct
Node on S3 object store providers” on page 229.
The Linux platform supports managed file transfers between the node and the AWS S3 object store. It is
required to be installed on an EC2 instance in the same region as the source and destination S3 buckets.
The EC2 instance requires the minimum configuration for SUSE or Red Hat Linux specified in the table
above. To set up AWS account, EC2 instance, S3 bucket configuration and credentials contact your IT
Administrator.
A Connect:Direct for Unix node running this release could either be located on-premise or be running on
an EC2 instance on the cloud. The user can also configure both the Pnode and Snode on two EC2
instances on Cloud. An Amazon S3 object can serve as a source or as a destination to send and receive
files.
Note: Connect:Direct for UNIX supports only Amazon Web Services. It does not yet support MS Azure,
Google Cloud, and IBM SoftLayer.

Setting up Connect:Direct Node on S3 object store providers

Note that by default, Connect:Direct for Unix uses AWS S3 object store to transfer data between nodes
installed on a EC2 instance or On-premise nodes, using pre-defined AWS S3 buckets. The following
sections describe tasks required to activate Connect:Direct Node on AWS S3.
By default, cloud support for Connect:Direct is not enabled. To enable cloud support, create and manage
all related AWS services and complete the following tasks:
• Pre-requisites to activate Connect:Direct Unix on AWS
• Installing Connect:Direct Unix node on cloud
• Configuring Connect:Direct node for S3
IBM Connect:Direct for UNIX can also be configured to extend support to other S3 object store providers
such as Minio, Dell EMC ECS, and Red Hat Ceph to execute public and on-premise cloud-based
operations. The following parameters must be declared in Initparms, when installing Connect:Direct for
Unix, to extend support for other S3 object store providers:
• name
• s3.endpointUrl
• s3.endpointPort
• s3.profilePath
• s3.profileName
For more information see the section, Configuring the Connect:Direct Node for S3.
Pre-requisites to set-up Connect:Direct Unix on AWS

© Copyright IBM Corp. 1993, 2018 229

 Before you configure Connect:Direct node definitions necessary for using Connect:Direct for UNIX, you
must complete the following tasks:
1. Set up AWS accounts and credentials
2. Select and create an AMI instance, RedHat or SuSE
3. Create IAM user/roles
4. Create Security group. Port numbers which are specific to Connect:Direct should be added to the
security group
5. S3 Bucket Management
For more information see, https://aws.amazon.com/account.
Installing Connect:Direct Unix node on Cloud
No specific configuration is required to install Connect:Direct for Unix node on an EC2 instance. For
information to install Connect:Direct for UNIX see, “Installing Connect:Direct for UNIX” on page 16.
If you are upgrading from an old release of Connect:Direct for UNIX node note that:
• CD Unix, Linux platform, and JRE are now included in the base installation
• Initparms to be included during the S3 plugin configuration are updated during the upgrade process
Configuration considerations
• All values used to change the default S3 IO EXIT behavior should be provided through s3. variables
either by declaring them as defaults via. initparms.cfg file or by declaring specific values in
sysopts.
• An s3. variable is searched first in sysopts. If no value is retrieved from sysopts, the default value
declared in the initparm.cfg file is used.
• A parameter declared in sysopts overrides the initparm.cfg file parameter value
Configuring the Connect:Direct Node for S3
1. S3 configuration is added to the Initparms during installation-.

# S3 IO Exit parameters
file.ioexit:\
:name=s3:\
:library=/cdunix/ndm/lib/libcdjnibridge.so:\
:home.dir=/cdunix/ndm/ioexit-plugins/s3:\
:options=-Djava.class.path=/cdunix/ndm/ioexit-plugins/s3/
cd-s3-ioexit.jar com.aricent.ibm.mft.connectdirect.s3ioexit.S3IOExitFactory:

S3 configuration is added to the Initparms during installation.

• name – S3 object store plugin name
– To declare a new S3 provider, a new entry with a new scheme must be created such as:

# S3 IO Exit parameters
file.ioexit:\
:name=new:\...

– To define another S3 object store provider, declare the provider name in Initparms as a separate
entry.
Note: AWS is defined as the default S3 provider in Initparms.

230 IBM Connect:Direct for UNIX: Documentation

#AWS S3 provider
File.ioexit:\
name=s3:\
#Minio S3 provider
File.ioexit:\
name=m3:\

• library – Identifies the full path to libcdjnibridge.so shared library.

• home.dir – Identifies the full path to the S3 home directory.
• options – Identifies the JVM properties to use, class path and main class (S3IOExitFactory) to invoke.
Default values are set in the Initparms using the :option field. Default values for the following
parameters can be declared using the -D syntax in the :option= field.
Note: Parameter declaration names are case sensitive.

Parameter Description Example

s3.endPointUrl New endpoint URL. s3.endPointUrl=10.120.133.151
Default: None

s3.endPointPort Define Endpoint port as an integer. s3.endPointPort=9020

Default: None

s3.endPointSecure Exit will generate HTTP or HTTPS URI s3.endPointSecure=NO

depending on this parameter.
Default: YES

s3.profilePath Name of the credential file to use to s3.profilePath=’/home/some user/

retrieve profiles entries. Can be s3io/credentials’
included in quoted.
Default: None

s3.profileName Entry name in the credentials file. s3.profileName=new

Default: None Note: credential file should have one
entry for new profile.

[profile new]
aws_access_key_id = anaccesskey
aws_secret_access_key
=asecretaccesskey

Chapter 6. Using S3 object store providers with IBM Connect:Direct for UNIX 231
 Parameter Description Example

s3.virtualHostedUr Sets the URI style to virtual-hosted– s3.virtualHostedUri=YES

i style or path-style URLs to access a
bucket. Set the parameter to:
• YES to request a Virtual-hosted-style
URI
• NO to request a Path style URI
Default values:
Scheme name is S3: Virtual hosted
style
Other scheme name: Path style
see https://docs.aws.amazon.com/
AmazonS3/latest/dev/
VirtualHosting.html
Note: Virtual hosted style will be
effectively active only if endpoint is a
DNS name
Note: Scheme name S3 can refer to
another S3 provider than AWS S3
Note: Some S3 providers don't support
virtual hosted URI

s3.sseS3 Amazon S3 default encryption enables s3.sseS3=YES

users to set the default encryption
behavior for an S3 bucket. You can set
default encryption on a bucket such
that all new objects are encrypted
when they are stored in the bucket.
The objects are encrypted using
server-side encryption with either
Amazon S3-managed keys (SSE-S3) or
Customer Master Keys (CMKs) stored in
AWS Key Management Service (AWS
KMS).
Set the parameter to YES to request
server side encryption.
Default value is NO
For more information, see Bucket
Encryption

Example declaration

232 IBM Connect:Direct for UNIX: Documentation

" NEW IO Exit parameters file.ioexit:\
:name=new:\
:library=/cdunix/ndm/lib/libcdjnibridge.so:\
:home.dir=/cdunix/ndm/ioexit-plugins/s3:\
:options=-Xmx640m -Ds3.profileName=newentry
-Ds3.endPointUrl=10.120.133.151
-Ds3.endPointPort=9020
-Ds3.profilePath=’/home/some user/s3io/credentials’
-Djava.class.path=/cdunix/ndm/ioexit-plugins/s3/cd-s3
-ioexit.jar com.aricent.ibm.mft.connectdirect.s3ioexit.S3IOExitFactory:

The following parameters are used for tuning or diagnostics in rare situations -

s3ioexit.objectSize # Default max object size is 5TB, this is similar to

the
ulimit feature to restrict the file size that can be
uploaded.
s3ioexit.dwldRange # Defaults to 5MB, sets the S3 read buffer size.
s3ioexit.partSize # Since the part size is calculated dynamically, this
should be removed ( or for test only )
s3ioexit.trace_level # Allows more detailed trace logs than supported by
CDU.
cdioexit_trace_destination # Indicates trace to SMGR.TRC or external trace log
file,
needed for detail S3 traces that would overflow
SMGR.TRC
s3.executorMaxPool # Max number of threads for parts upload.
Default:1O, Max:20
s3.executorMaxRetries # Number of retries when an upload thread failed its
allocation (when a memory exception occurred)
Default:10, Min:1, Max:20

Note: To enable Multipart upload, set ckpt parameter value to 0. Checkpoint restart can be explicitly
configured within a copy step through the ckpt parameter. If it is not configured in the copy step, it
can be configured in the Initparms through the ckpt.interval parameter.
2. Alternatively, S3 configuration can also be added as values in sysopts using the :variable=value:
syntax.
S3 parameters set in sysopts will override default values or values set in initparms.cfg file for the
referenced entry in the copy step statement that is, s3:// for an S3 entry and ascheme:// for an
ascheme entry.
Using sysopts and S3 parameters can provide flexibility when managing more than one profile or more
than one S3 provider. The following example assumed that an s3 entry in initparms.cfg file is the
default one and copy step uses S3:// as the scheme name.
• sysopts=”:s3.profileName=anotherprofile:” will request to use this specific profile.
• sysopts=”:s3.sseS3=YES:” requests server side encryption for this S3 object.
• sysopts=”:s3.profileName=newentry:s3.endPointUrl=10.120.133.151:s3.endPoint
Port= 9020:s3.profilePath=’/home/some user/s3io/credentials’:” will point to
another S3 provider but default is on AWS.
Note: Parameter declaration names is not case sensitive. Also for sysopts, names are not case
sensitive.
3. AWS Credentials Management -
With AWS cloud support being extended on Connect:Direct for UNIX the user is required to manage
AWS credentials.

Chapter 6. Using S3 object store providers with IBM Connect:Direct for UNIX 233
 A simple method of associating credentials with a Connect:Direct user is to use the AWS CLI Configure
command, which places the credential in ~/.aws/credentials, for example, /home/ec2-user/.aws/
credentials.
The AWS credentials are only required to access S3 during a pnode or snode copy step. During the
copy step, the user is impersonated by the S3 IO Exit and the users home directory is used to access
AWS credentials.
On AWS and with the default s3 entry in initparms.cfg file that is, with no extra parameters,
Connect:Direct for UNIX uses the following default credential providers chain:
• Environment variables: AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY
• Java system properties: aws.accessKeyId and aws.secretKey
• The default credential profiles file path: ~/.aws/credentials
• Amazon ECS container credentials: loaded from the Amazon ECS when environment variable
AWS_CONTAINER_CREDENTIALS_RELATIVE_URI is set
• Instance profile credentials: used on EC2 instances and delivered through the Amazon EC2
metadata service. Instance profile credentials are used only when
AWS_CONTAINER_CREDENTIALS_RELATIVE_URI is not set
• Web Identity Token credentials from the environment or container
Note: The default credential providers chain implementation described above may not apply to other
S3 providers.
4. Functional User Authorities Configuration -
The user authorities file; userfile.cfg has been updated to support restricted S3 upload and download
directories. When defined, only the S3 bucket defined may be used to send files from (upload) or
receive files to (download).

cd-cloud-user:\
:admin.auth=n:\
:pstmt.copy.ulimit=n:\
:pstmt.upload=y:\
:pstmt.upload_dir=s3://uploadBucket:\
:pstmt.download=y:\
:pstmt.download_dir=s3://downloadBucket:\
:pstmt.run_dir=:\
:pstmt.submit_dir=:\
:name=:\
:phone=:\
:descrip=:

S3 File transfers are limited to user file data and are not supported by Run Task/Job or other areas that
specify a filename, for example, run_dir and submit_dir in the above example can only refer to
standard file system locations.

Using IBM Connect:Direct® for Unix with AWS S3

This section contains all the information you need in order to use IBM Connect:Direct® for UNIX to
configure processes for either uploading or downloading user files with Amazon S3.
• AWS S3 buckets
• Working with Traces

Using AWS S3 buckets

The copy step of the Connect:Direct Process statement supports uploading and downloading user files
using the AWS S3 Object Store. The Connect:Direct Unix node must be installed on an EC2 instance in the

234 IBM Connect:Direct for UNIX: Documentation

 same AWS region as the S3 bucket. The node installed on EC2 can be used as Pnode or Snode and either
can read and write user files using S3.
1. Changes in Process Language:
The Exits are specified in the FILE keyword of the Connect:Direct process language. The s3://myBucket
represents the S3 bucket to store sample.txt in.

sample PROCESS
SNODE=cd-ec2
SNODEID=(cd-proxy-user)

upld COPY
FROM (
FILE=sample.bin
)
CKPT=10M
TO (
FILE=s3://myBucket/sample.bin
DISP=RPL
)
PEND;

s3:// scheme refers to initparm.cfg entry with name=s3.

For multiple entries defined in initparm.cfg file, name=<scheme> identifies the new scheme to use in
process FILE= keyword. FILE=<scheme>:// points to this entry.
Since S3 interprets and handles only S3:// pattern, the <scheme>:// pattern is replaced with S3://
during run time.
The process displayed above uploads a file named sample.bin from an on-premise Pnode to an
Snode in the AWS cloud named cd-ec2. The file is stored in myBucket on S3. The AWS credentials
configured for the cd-proxy-user are used to access S3.
S3 checkpoint intervals are supported from 10M to 1G. If the value falls out of range, a warning is
logged in statistics.
User would need to consider bucket versioning on S3. When uploading a file to S3 the option to modify
file (MOD) is not supported. Only NEW and RPL options can be set by the user.
For NEW, if Bucket versioning is on, a new version of the file is created on S3.
For RPL, if Bucket versioning is on, the latest version of the file is replaced. If the file does not exist
then it'll be created.

Working with Traces

Enabling traces for Connect:Direct Unix running on AWS is similar to how it’s done in an on-premise
version. S3 traces are included when SMGR tracing is enabled

Limitations
When running Connect:Direct for UNIX with an S3 object store be aware of the following limitations:
• EC2 instance is static, not elastic.
• File transfers via cloud are not supported by Run Task/Job or other areas that specify a filename.
• The partSize is limited to 100 MB only. So, the user can configure partSize as any value ranging from 5
MB to 100 MB.
• Maximum file size which can be transferred to S3 is 5TB.
• The user should consider cost associated with the usage of cloud resources.

Chapter 6. Using S3 object store providers with IBM Connect:Direct for UNIX 235
 • S3 does not support the option MOD (modify) for files that are transferred via Connect:Direct. Only NEW
or RPL(replace) is supported. Wildcard Copy is not supported over cloud.
• If there are multiple versions of the same file present in S3 bucket then only the latest version can be
downloaded and not any previous version.
• Multipart download is not supported.
• To enable Multipart upload, set ckpt parameter value to 0. Checkpoint restart can be explicitly
configured within a copy step through the ckpt parameter. If it is not configured in the copy step, it can
be configured in the Initparms through the ckpt.interval parameter. For more information see,
Connect:Direct for UNIX Getting Started Guide

236 IBM Connect:Direct for UNIX: Documentation

Chapter 7. Introduction to Connect:Direct Secure
Plus for UNIX
The Connect:Direct Secure Plus for UNIX application provides enhanced security for IBM Connect:Direct
and is available as a separate component. It uses cryptography to secure data during transmission. You
select the security protocol to use with Connect:Direct Secure Plus.

Introduction to Connect:Direct Secure Plus for UNIX

The Connect:Direct Secure Plus for UNIX application provides enhanced security for IBM Connect:Direct
and is available as a separate component. It uses cryptography to secure data during transmission. You
select the security protocol to use with Connect:Direct Secure Plus.

Security Concepts
Cryptography is the science of keeping messages private. A cryptographic system uses encryption keys
between two trusted communication partners. These keys encrypt and decrypt information so that the
information is known only to those who have the keys.
There are two kinds of cryptographic systems: symmetric-key and asymmetric-key. Symmetric-key (or
secret-key) systems use the same secret key to encrypt and decrypt a message. Asymmetric-key (or
public-key) systems use one key (public) to encrypt a message and a different key (private) to decrypt it.
Symmetric-key systems are simpler and faster, but two parties must somehow exchange the key in a
secure way because if the secret key is discovered by outside parties, security is compromised.
Asymmetric-key systems, commonly known as public-key systems, avoid this problem because the public
key may be freely exchanged, but the private key is never transmitted.
Cryptography provides information security as follows:
• Authentication verifies that the entity on the other end of a communications link is the intended
recipient of a transmission.
• Non-repudiation provides undeniable proof of origin of transmitted data.
• Data integrity ensures that information is not altered during transmission.
• Data confidentiality ensures that data remains private during transmission.

Secure Plus UNIX Video Tutorials

You can view video tutorials about the installation, configuration, troubleshooting, and other technical
features of Connect:Direct Secure Plus for UNIX.
The Connect:Direct Secure Plus videos are useful for Connect:Direct administrators. These tutorials
provide a quicker way to access information and remove the need to reference the Connect:Direct Secure
Plus documentation library.
Click the link below to access the Connect:Direct Secure Plus for UNIX video channel to view tutorials
about the following topics:
• Installation
• Configuration
• Troubleshooting
The Connect:Direct Secure Plus UNIX video channel can be found at this link:Connect:Direct Secure Plus
for UNIX Video Channel.

© Copyright IBM Corp. 1993, 2018 237

Protocol Support
Before you configure Connect:Direct Secure Plus, you must determine the protocol that you and your
trading partners will use to secure communications sessions. For planning information, see Plan Your
Implementation of the SSL or TLS Protocol.

Transport Layer Security Protocol (TLS)

The TLS protocol use certificates to exchange a session key between the node that initiates the data
transfer process (the primary node, or PNODE) and the other node that is part of the communications
session (the secondary node, or SNODE). A certificate is an electronic document that associates a public
key with an individual or other entity. It enables you to verify the claim that a given public key belongs to a
given entity. Certificates can be self-issued (self-signed) or issued by a certificate authority (CA). See Self-
Signed and CA-Signed Certificates for details on the differences between self-signed and CA-issued
certificates.
When a CA receives an application for a certificate, the CA validates the applicant's identity, creates a
certificate, and then digitally signs the certificate, thus vouching for an entity's identity. A CA issues and
revokes CA-issued certificates.
Self-signed certificates are created and issued by the owner of the certificate, who must export the
certificate in order to create a trusted root file that includes this certificate and supply the trusted root file
to the partner in a connection.

TLS 1.3
TLS 1.3 adds new features for improved security. For more information, see RFC 8446, section 1.2 Major
Differences from TLS 1.2.

Deprecated Protocols
SSL3.0, TLS 1.0 and TLS 1.1 protocols are deprecated and should not be used. It is recommended that
trading partners using deprecated protocols migrate to TLS 1.3 or TLS 1.2.
If deprecated protocols are required, TLS 1.3 should not be enabled in the trading partner's configuration,
otherwise the handshake may fail. Deprecated protocols should be exclusively configured per node.
The Secure+ feature continues to support SSL 3.0, TLS 1.0 and TLS 1.1.

NIST SP800-131a and Suite B support

Connect:Direct supports a new standard from The National Institute of Standards and Technology (NIST),
SP800-131a to extend the current FIPS standards, as well as Suite B cryptographic algorithms as
specified by the National Institute of Standards and Technology (NIST).

The government of the Unites States of America produces technical advice on IT systems and security,
including data encryption and has issued Special Publication SP800-131a that requires agencies from the
Unites States of America to transition the currently-in-use cryptographic algorithms and key lengths to
new, higher levels to strengthen security.
Applications must use strengthened security by defining specific algorithms that can be used and what
their minimum strengths are. These standards specifies the cryptographic algorithms and key lengths that
are required in order to remain compliant with NIST security standards.
To comply with the new requirements, IBM products with cryptographic functionality must:
• Enable TLS 1.2 and be prepared to disable protocols less than TLS 1.2
• Cryptographic keys adhere to a minimum key strength of 112 bits
• Digital signatures are a minimum of SHA-2
The following is included in Secure Plus for NIST SP800-131a and Suite B support:

238 IBM Connect:Direct for UNIX: Documentation

 • Support TLS 1.1 and 1.2 with SHA-2 cipher suites
• Support for SP800-131a transition and strict modes
• Support for NSA Suite B 128 and 192 bit cipher suites and modes
• Support for IBM CMS Keystore
• Support migrating existing Secure+ certificates to the IBM CMS Keystore
• Support for JRE 1.7 SR1 iKeyman/iKeycmd utilities for certificate management.
For more information on NIST security standards, see http://csrc.nist.gov/publications/nistpubs/
800-131A/sp800-131A.pdf.
For more information on Suite B security standards, see http://www.nsa.gov/ia/programs/
suiteb_cryptography/index.shtml

Connect:Direct Secure Plus Tools

Connect:Direct Secure Plus consists of five components:
• Connect:Direct Secure Plus Administration Tool (Secure+ Admin Tool)
• Parameters file (Secure+ parameters file)
• Access file (Secure+ access file)
• Strong Password Encryption Parameters file
• Connect:Direct Secure Plus Command Line Interface (Secure+ CLI).
The following sections describe these components and their function within Connect:Direct Secure Plus.
Note: Only one instance of the Secure+ Admin Tool or the Secure+ CLI may be used at a time because
they access the same configuration file. Do not open these tools at the same time or multiple copies of the
same tool at the same time (two instances of Secure+ Admin Tool or two instances of Secure+ CLI). Only
the user who accessed the configuration file first will be able to save updates.

Secure+ Admin Tool

The Secure+ Admin Tool is a graphical user interface (GUI) that enables you to configure and maintain the
Sterling Connect:Direct Secure Plus environment. The Secure+ Admin Tool is the interface for creating
and maintaining the Secure+ parameters file; operating system utilities and editing tools cannot be used
to create or update this file.

Secure+ Parameters File

The Connect:Direct Secure Plus parameters file (Secure+ parameters file) contains information that
determines the protocol and encryption method used during encryption-enabled Connect:Direct Secure
Plus operations. To configure Connect:Direct Secure Plus, each site must have a Secure+ parameters file
that contains one local node record and at least one remote node record for each trading partner who
uses Connect:Direct Secure Plus to perform a secure connection. The local node record defines the most
commonly used security and protocol settings for the node at the site. The local node record can also be
used as a default for one or more remote node records. Each remote node record defines the specific
security and protocol settings used by a trading partner. You should create a remote node record in the
Secure+ parameters file for each Connect:Direct node that you communicate with even if the remote node
does not use Connect:Direct Secure Plus.
Note: The Secure+ parameters file is not dynamically updated. When multiple users update the Secure+
parameters file, each user must close and reopen the file to display new records added by all sources.
When you create the Secure+ parameters file, a record named .SEAServer is automatically added to the
file, which enables Connect:Direct to interface with Sterling External Authentication Server during TLS
session. External authentication is configured in this record and enabled/disabled in the local and remote
node records.

Chapter 7. Introduction to Connect:Direct Secure Plus for UNIX 239

 With v6.1, Connect:Direct Secure Plus support to cache certificate validation responses from External
Authentication Server when it interfaces External Authentication Server during a TLS session. This
minimizes the overhead associated with requesting certificate validation from External Authentication
Server, thus eliminating the need for Connect:Direct Secure Plus to query External Authentication Server
each time. External Authentication Server response caching feature is disabled by default. To enable it
see, “Update the Sterling External Authentication Server Record” on page 267 and “Configure External
Authentication in the .SEAServer Record” on page 253.
For additional security, the Secure+ parameters file is stored in an encrypted format. The information
used for encrypting and decrypting the Secure+ parameters file (and private keys) is stored in the Secure+
access file.

Secure+ Access File

The Connect:Direct Secure Plus access file (Secure+ access file) is generated automatically when you
create the Secure+ parameters file for the first time. You type a passphrase when you first initialize
Connect:Direct Secure Plus. This passphrase is used to generate the keys necessary to encrypt and
decrypt the entries in the Secure+ parameters file. The passphrase itself is not retained.
Your Connect:Direct Secure Plus administrator must secure the Secure+ access file (<cdinstall>/ndm/
secure+/nodes/.cdspacf).The administrator must have full create and update permissions to update this
file. The Connect:Direct server must have read authority. To maintain a secure Secure+ access file, the
general user community should not have access permission. This file can be secured with any available
file access restriction tool. Availability of the Secure+ access file to unauthorized personnel can
compromise the security of data exchange.

Strong Password Encryption Parameters File

Strong Password Encryption protects Connect:Direct passwords which may be specified in a
Connect:Direct Process by encrypting the Process when it is submitted and stored in the Connect:Direct
work area. Strong Password Encryption uses the AES 256 encryption algorithm. Strong Password
Encryption parameters are stored in the parameters file (<cdinstall>/ndm/secure+/nodes/.Password).
This feature is enabled by default. For more information on using this feature, refer to Configure Strong
Password Encryption.

Connect:Direct Secure Plus Command Line Interface

The Java-based Connect:Direct Secure Plus Command Line Interface (Secure+ CLI) is provided to enable
you to create customized scripts that automate implementing Connect:Direct Secure Plus. Sample UNIX
scripts are provided as models for your customized scripts. You can save these scripts with another name,
modify them to reflect your environment, and distribute them throughout your enterprise. For more
information about using the Secure+ CLI, commands and parameter descriptions, and the scripts, see
Automate Setup with the Secure+ CLI.

Before You Begin

Before you configure the IBM Connect:Direct environment for secure operations, ensure that you
complete the following tasks:
• Identifying Expert Security Administrator
• Assessing Security Requirements of Trading Partners
• Planning Your Implementation of IBM Connect:Direct
• Completing the Worksheets

Identifying Expert Security Administrator

The instructions and information provided to assist you in implementing IBM Connect:Direct assume that
you have an expert UNIX security administrator who is familiar with your company's security

240 IBM Connect:Direct for UNIX: Documentation

 environment. Identify who this individual is within your company and work with this individual as you plan
your Connect:Direct implementation.

Assessing Security Requirements of Trading Partners

Security planning is a collaborative effort between you and your trading partners. You must know the
expectations of your trading partners and plan your security implementation to meet those
requirements.Contact your trading partners to gather the information necessary to coordinate your
implementation of IBM Connect:Direct.

Planning Your Implementation of IBM Connect:Direct

Before you begin

After you have identified your security administrator and determined the security requirements of your
trading partners, review the following information:
• Plan Your Implementation of the SSL or TLS Protocol
• Set Up for the TLS or SSL Protocol

Completing the Worksheets

Before you begin

Before you configure IBM Connect:Direct, complete the worksheets in Configuration Worksheets. Use this
information to configure the local and remote nodes to use Connect:Direct.

Plan Your Implementation of the TLS Protocol

Before you configure Connect:Direct Secure Plus, review the following concepts, requirements, and terms
to ensure that you have all the resources and information necessary to implement the Transport Layer
Security (TLS) protocol.

Overview of the TLS Protocol

The TLS protocol provides three type of authentication:
• During the first type of authentication, called server authentication, the site initiating the session
(PNODE) requests a certificate from its trading partner (SNODE) during the initial handshake. The
SNODE returns its ID certificate (read from its KeyStore) and the PNODE authenticates it using one or
more trusted root certificates stored in its KeyStore. Root certificates are signed by a trusted source—
either a public certificate authority, such as Thawte, or by the trading partner acting as its own CA. If the
ID certificate from the SNODE cannot be validated using any root certificate found in the KeyStore, or if
the root certificate has expired, the PNODE terminates the session. IBM Connect:Direct writes entries to
the statistics logs of both nodes and the session is aborted.
• The second type of authentication, called client authentication, is optional. If this option is enabled in
the SNODE's IBM Connect:Direct parameters file definition for the PNODE, the SNODE will request a
certificate from the PNODE and authenticate it using the information in its KeyStore. If this
authentication fails, the SNODE terminates the session and IBM Connect:Direct writes information
about the failure to the statistics log of both nodes.
• The third type of authentication is also optional and consists of validating the certificate common name.
This authentication is enabled when the security administrator specifies the common name (CN)
expected to be contained in the ID certificate to be validated in its IBM Connect:Direct Parameters file.
– During the first type of authentication, the PNODE compares the common name it has specified for
the SNODE in its IBM Connect:Direct Parameters file with the common name contained in the
certificate sent by the SNODE. If the compare fails, that is, the information is not identical, the PNODE

Chapter 7. Introduction to Connect:Direct Secure Plus for UNIX 241

 terminates the session, and IBM Connect:Direct writes information about the failure to the statistics
logs of both nodes.
– During the second type of authentication, the SNODE compares the common name it has specified
for the PNODE in its IBM Connect:Direct Parameters file with the common name contained in the
certificate sent by the PNODE. If the compare fails, that is, the information is not identical, the SNODE
terminates the session, and IBM Connect:Direct writes information about the failure to the statistics
logs of both nodes.

Self-Signed and CA-Signed Certificates

Determining the type of certificate to use for secure communications sessions and the method to
generate the certificate is challenging. Self-signed certificates and digital certificates issued by certificate
authorities offer advantages and disadvantages. You may also be required to use both types of
certificates, depending on the security requirements of your trading partners. The following table
compares the advantages and disadvantages of self-signed and CA-signed certificates:

Type of Certificate Advantages Disadvantages

Self-signed certificate No cost Requires you to distribute your
certificate, minus the private key, to
each trading partner in a secure
manner
Easy to generate Difficult to maintain; anytime the
certificate is changed, it must be
distributed to all clients
Self-validated Not validated by a third-party entity
Efficient for small number of trading Inefficient for large number of trading
partners partners
CA-signed certificate Eliminates having to send your Trading partners must download
certificate to each trading partner digital CA-signed certificate used to
verify the digital signature of trading
partner public keys.
No changes are required on the trading Must be purchased from third-party
partner's system if you recreate the CA vendor
digitally-signed certificate using the
same CA

Terminology for TLS Certificates

The following defines the security terms associated with TLS certificates and communication sessions.
The terms are listed in alphabetical order.
CA-signed certificate
Digital document issued by a certificate authority that binds a public key to the identity of the
certificate owner, thereby enabling the certificate owner to be authenticated. An identity certificate
issued by a CA is digitally signed with the private key of the certificate authority.
Certificate (also known as digital certificate, public key certificate, digital ID, or identity certificate)
Signed certificate that is obtained from a certificate authority by generating a certificate signing
request (CSR). It typically contains: (1) distinguished name and public key of the server or client; (2)
common name and digital signature of the certificate authority; (3) period of validity (certificates
expire and must be renewed); and (4) administrative and extended information. The certificate
authority analyzes the CSR fields, validates the accuracy of the fields, generates a certificate, and
sends it to the requester.

242 IBM Connect:Direct for UNIX: Documentation

 A certificate can also be self-signed and generated by any one of many tools available, such as
OpenSSL. These tools can generate a digital certificate file and a private key file in PEM format, which
you can combine using any ASCII text editor to create a key certificate file.
Certificate authority (CA)
An organization that issues digitally-signed certificates. The certificate authority authenticates the
certificate owner's identity and the services that the owner is authorized to use, issues new
certificates, renews existing certificates, and revokes certificates belonging to users who are no longer
authorized to use them. The CA digital signature is assurance that anybody who trusts the CA can also
trust that the certificate it signs is an accurate representation of the certificate owner.
Certificate signing request (CSR)
Message sent from an applicant to a CA in order to apply for a digital identity certificate. Before
creating a CSR, the applicant first generates a key pair, keeping the private key secret. The CSR
contains information identifying the applicant (such as a directory name in the case of an X.509
certificate), and the public key chosen by the applicant. The CSR may be accompanied by other
credentials or proofs of identity required by the certificate authority, and the certificate authority may
contact the applicant for further information.
Cipher suite
A cryptographic key exchange algorithm that enables you to encrypt and decrypt files and messages
with the TLS protocol.
Client authentication
A level of authentication that requires the client to authenticate its identity to the server by sending its
certificate.
Key certificate file
File that contains the encrypted private key and the ID (public key) certificate. This file also contains
the certificate common name that can be used to provide additional client authentication.
Passphrase
Passphrase used to access the private key.
Private key
String of characters used as the private, “secret” part of a complementary public-private key pair. The
symmetric cipher of the private key is used to sign outgoing messages and decrypt data that is
encrypted with its complementary public key. Data that is encrypted with a public key can only be
decrypted using its complementary private key.
The private key is never transmitted and should never be shared with a trading partner.
Public key
String of characters used as the publicly distributed part of a complementary public-private key pair.
The asymmetric cipher of the public key is used to confirm signatures on incoming messages and
encrypt data for the session key that is exchanged between server and client during negotiation for a
TLS session. The public key is part of the ID (public key) certificate. This information is stored in the
key certificate file and read when authentication is performed.
Self-signed certificate
Digital document that is self-issued, that is, it is generated, digitally signed, and authenticated by its
owner. Its authenticity is not validated by the digital signature and trusted key of a third-party
certificate authority. To use self-signed certificates, you must exchange certificates with all your
trading partners.
Session key
Asymmetric cipher used by the client and server to encrypt data. It is generated by the SSL software.

Chapter 7. Introduction to Connect:Direct Secure Plus for UNIX 243

 Trusted root certificate file (also known as root certificate file
File that contains one or more trusted root certificates used to authenticate ID (public) certificates
sent by trading partners during the IBM Connect:Direct protocol handshake.

Set Up Connect:Direct Secure Plus

Before you can configure the node definitions that are necessary for using Connect:Direct Secure Plus,
you must complete the following tasks:
• Install Connect:Direct Secure Plus
• Starting the Secure+ Admin Tool
• Populating the Secure+ Parameters File

Install Connect:Direct Secure Plus

You can install Connect:Direct Secure Plus using the Connect:Direct installation script. For more
information on installing Connect:Direct Secure Plus, see the IBM Connect:Direct for UNIX Getting Started
Guide.
Note: After Connect:Direct Secure Plus is installed, the system administrator is responsible for securing
access to the Secure+ Admin Tool, Secure+ CLI, and Secure+ parameters files. The Connect:Direct Secure
Plus administrator and IBM Connect:Direct Server need full permission to the Connect:Direct Secure Plus
directory; no other users require access.

Starting the Secure+ Admin Tool

Before you begin

Use the Connect:Direct Secure Plus Administration Tool (Secure+ Admin Tool) or the Connect:Direct
Secure Plus Command Line Interface (Secure+ CLI) to set up and maintain a Connect:Direct Secure Plus
operation. This section provides instructions on using the Secure+ Admin Tool. Refer to Automate Setup
with the Secure+ CLI, for instructions on using the Secure+ CLI.
To start the Secure+ Admin Tool on a UNIX system, type the following command at the UNIX command
prompt from within the ndm/bin directory:

spadmin.sh

The Secure+ Admin Tool starts and opens the Secure+ parameters file for the associated IBM
Connect:Direct node.
Note: The Secure+ parameters file is not dynamically updated. When multiple users update the Secure+
parameters file, each user must close and reopen the file to display new records added by all sources.

Accessing Secure+ Admin Tool Help

Before you begin

Note: Secure+ Admin documents are available on the Knowledge Center. If you access the Secure+
Admin Tool Help from the Secure+ Admin Tool Help menu and the following error message displays:

java.lang.UnsupportedOperationException: The BROWSE action is not supported on the current

platform!

Be aware of the following limitation:

• This error is connected to launching of your web browser with java browse method.
• The BROWSE action is not supported on all LINUX desktops but works on gnome and KDE.

244 IBM Connect:Direct for UNIX: Documentation

Populating the Secure+ Parameters File
To communicate with a trading partner using Connect:Direct Secure Plus, you define a node record for
that partner in both the IBM Connect:Direct network map and the Connect:Direct Secure Plus parameters
file (Secure+ parameters file). To set up the Connect:Direct Secure Plus environment, you can populate
the Secure+ parameters file from entries defined in an existing network map.

About this task

When you populate the Secure+ parameters file from the network map, a record is automatically created
in the Secure+ parameters file for each node entry in the network map. Initially, the .Local node record is
disabled, and all other records are set to default to local.
Perform the following steps to populate the Secure+ parameters file with node entries defined in the IBM
Connect:Direct network map:

Procedure
1. From the Secure+ Admin Tool Main Window, click the Sync with Netmap option of the File menu
item.
The Available Netmaps dialog box is displayed.
2. Navigate to the netmap.cfg file located in the d_dir/ndm/cfg/node_name directory. Select the netmap
to open and click Sync. The Select Netmap Entries to Add dialog box is displayed.
3. Click Add All.
The Select Parameters File Entries to Delete dialog box is displayed.
4. Click Skip to close the Secure+ parameters file without deleting any entries.
The Secure+ parameters file is populated and the Secure+ Admin Tool Main Window displays remote
node records in the Secure+ parameters file including the records you added from the network map.

Node Configuration Overview

Before you begin using Connect:Direct Secure Plus, you must configure nodes for secure operations.
When you import the network map records into the Secure+ parameters file, Connect:Direct Secure Plus
parameters are disabled. To configure the nodes for Connect:Direct Secure Plus, complete the following
procedures:
• Import existing Certificates.
• Configure or create a new CMS Key Store through the Key Management menu on the Secure+ Admin
Tool.
• Configure the Connect:Direct Secure Plus .Local node record
Define the security options for the local node. Because TLS and SSL provide the strongest
authentication with easy-to-maintain keys, configure the local node for one of these protocols.
Determine which protocol is used by most trading partners and configure the local node with this
protocol.
• Disable remote nodes that do not use Connect:Direct Secure Plus
• Customize a remote node for the following configurations:
– To use a unique certificate file to authenticate a trading partner
– To use a different self-signed or CA-signed certificate for client or server authentication
– To identify a unique cipher suite used by a trading partner
– To activate common name validation
– To activate client authentication

Chapter 7. Introduction to Connect:Direct Secure Plus for UNIX 245

 – To enable FIPS 140-2 mode
– To activate external authentication
• Configure all remote nodes that use a protocol that is not defined in the local node
When you configure the local node, all remote nodes are automatically configured to the protocol
defined in the local node. If a trading partner uses a different protocol, you must turn on the protocol in
the remote node record. For example, if you activate the TLS protocol in the .Local node record and a
trading partner uses the SSL protocol, configure the SSL protocol in the remote node record for the
trading partner.

Import Existing Certificates

About this task

Before performing your .Local node configuration, you need to import existing certificates.
To import existing certificates:

Procedure
1. Import existing certificates, either keycerts or trusted root files from trading partners into the Key
Store. On the Secure+ Admin Tool main window, from the Key Management menu, select Configure
Key Store. The Key Store Manager window appears.
2. Verify the CMS Key Store path. If incorrect, click browseto locate the Key Store path. The Browse CMS
KeyStore File window appears.
3. The default Key Store name is: cdkeystore.kdb To locate the default Key Store path, navigate to the Key
Store file.

Windows path: <cdinstalldir>\Server\Secure+\Certificates\cdkeystore.kdb

Unix path: <cdinstalldir>/ndm/secure+/certificates/cdkeystore.kdb

4. Click Import. On the Import PEM KeyStore File window, navigate to and select the certificate file you
want to use and click OK.
5. If a key certificate file is being imported, the password must be entered. The KeyStore Password
window appears. Type your password and click OK.
6. The PEM Certificate Viewer displays to allow a review of the certificate file. Verify the certificate is valid
and click the Import button. Import Results window displays with status of imported certificate. Click
Close.
7. The certificate is imported and given a Label based on the certificate Common Name, (CN=). Note the
serial number to identify the correct certificate after import.
Note: A common name is used for Label and identification which means that multiple certificates can
have the same common name and therefore, can be overwritten depending on the setting of the
Default Mode. Additionally, the Default Mode of Import is Add or Replace Certificates.
8. Click OK to create the new CMS KeyStore file. Key Store Manager will display contents of the new
keystore.

Create CMS Key Store

About this task

Before performing your .Local node configuration, you may need to create a new CMS Key Store file.
To create a new CMS Key Store file:

246 IBM Connect:Direct for UNIX: Documentation

 Procedure
1. On the Key Store Manager window, click New. The Create new CMS KeyStore File dialog box appears.
2. Enter the Directory location (you can also Browse to the location desired), the KeyStore file name, and
the password for the new KeyStore file. You can also choose to Populate with standard certificate
authorities. This will import all standard public CA Root certificates into the new KeyStore file.
3. Click OK to create the new CMS KeyStore file. Key Store Manager will display contents of the new
keystore.
4. Click Import. On the Import PEM KeyStore File window, navigate to and select the certificate file you
want to use and click OK.
5. If a key certificate file is being imported, the password must be entered. The KeyStore Password
window appears. Type your password and click OK.
6. The PEM Certificate Viewer displays to allow a review of the certificate file. Verify the certificate is valid
and click the Import button. Import Results window displays with status of imported certificate. Click
Close.
7. The certificate is imported and given a Label based on the certificate Common Name, (CN=). Note the
serial number to identify the correct certificate after import.
Note: A common name is used for Label and identification therefore multiple certificates can have the
same common name and therefore, can be overwritten depending on the setting of the Default Mode.
Additionally, the Default Mode of Import is Add or Replace Certificates.

Configuring the Connect:Direct Secure Plus .Local Node Record

About this task

Before you can configure the .Local node record, you must either import your existing certificates or
create and configure a CMS Key Store. For additional information, see Import Existing Certificates or
Create CMS Key Store in the documentation library.
It is recommended that you configure the .Local node record with the protocol used by most of your
trading partners. Because remote node records can use the attributes defined in the .Local node record,
defining the .Local node record with the most commonly used protocol saves time. After you define the
protocol in the .Local node record, all remote nodes default to that protocol. Also, identify the trusted root
file to be used to authenticate trading partners.
To configure the local node, refer to the Local Node Security Feature Definition Worksheet that you
completed for the .Local node record security settings and complete the following procedure:

Procedure
1. From the Secure+ Admin Tool Main Window, double-click the .Local record. The Edit Record dialog box
displays the Security Options tab, the node name, and the type of node.
2. Set the Security Options for the local or remote node entry you are configuring and if necessary, modify
the time-out value in Authentication Timeout.
Refer to the following table for an explanation of the Security Options boxes:
Note: The SSL3.0, TLS 1.0 and TLS 1.1 protocols are deprecated and should not be used. It is
recommended that trading partners using deprecated protocols migrate to TLS 1.3 or TLS 1.2. If
deprecated protocols are required, TLS 1.3 should not be enabled in the trading partner's
configuration, otherwise the handshake may fail. Deprecated protocols should be exclusively
configured per node. The Secure+ feature continues to support SSL 3.0, TLS 1.0 and TLS 1.1.

Field Name Field Definition Valid Values

Node Name Specifies the node record name. .Local

This is not an editable field.

Chapter 7. Introduction to Connect:Direct Secure Plus for UNIX 247

 Field Name Field Definition Valid Values
Base Record Specifies the name of the base record. Name of the local Connect:Direct
If an alias record is selected, the base node.
record name is displayed in this box.

Type Specifies the current record type. Local for a local record and Remote
for a remote record.
This is not an editable field.

Disable Secure+ Disables Connect:Direct Secure Plus. Default value is Disable Secure+.
Note: If this option is selected,
override is enabled, and no remote
node definition exists for the remote
node in the Connect:Direct Secure
Plus parameters file, Connect:Direct
Secure Plus is bypassed.

Enable SSL 3.0 Enables SSL protocol to ensure that The default value is Disable Secure
Protocol data is securely transmitted. +.
The SSL3.0 is deprecated and should
not be used. It is recommended that
trading partners using deprecated
protocols migrate to TLS 1.3 or TLS 1.2.

Enable TLS 1.0 Enables TLS protocol to ensure that The default value is Disable Secure
Protocol data is securely transmitted. +.
TLS1.0 is deprecated and should not be
used. It is recommended that trading
partners using deprecated protocols
migrate to TLS 1.3 or TLS 1.2.

Enable TLS 1.1 Enables TLS protocol to ensure that The default value is Disable Secure
Protocol data is securely transmitted. +.
The TLS1.1 is deprecated and should
not be used. It is recommended that
trading partners using deprecated
protocols migrate to TLS 1.3 or TLS 1.2.

Enable TLS 1.2 Enables TLS protocol to ensure that The default value is Disable Secure
Protocol data is securely transmitted. +.
Enable TLS 1.3 Enables TLS protocol to ensure that The default value is Disable Secure
Protocol data is securely transmitted. +.
Disable Disables the ability to override values The default value is Disable.
in the .Local node record with values in
the remote node record.
FIPS 140-2 Enables FIPS 140-2 security. The default value is Disable.
SP800-131A Enables NIST SP800-131a security in The default value is Disable.
Transition transition mode.
SP800-131A Enables NIST SP800-131a security The default value is Disable.
mode.
Suite B 128 bit Enables Suite B 128 bit security. The default value is Disable.

248 IBM Connect:Direct for UNIX: Documentation

 Field Name Field Definition Valid Values
Suite B 192 bit Enables Suite B 192 bit security. The default value is Disable.

Node or Copy There are several types of overrides. The default value is No.
Statement Override For both PNODE and SNODE, this
parameter indicates whether Remote
Node record parameters will override
the .Local Node record parameters or
not.

If it is set to No, or if set to Yes and

there is no correlating Remote Node
record for a given session, then:
• For PNODE, this parameter indicates
whether process overrides, which
may optionally be specified in
Process, Submit, and Copy
statements, will be allowed.
• For SNODE, this parameter indicates
whether:
– The Secure+ protocol specified by
the PNODE will be allowed to
override that specified by the
SNODE.
– To allow unsecured incoming
sessions to proceed.

Authentication Specifies maximum time, in seconds, A numeric value equal to or greater

Timeout that the system waits to receive the than 0, ranging from 0 to 3600.
Connect:Direct Secure Plus blocks
The default is 120 seconds.
exchanged during the Connect:Direct
Secure Plus authentication process.
If you specify a value of 0,
Connect:Direct waits indefinitely to
receive the next message.
Specify a time to prevent malicious
entry from taking as much time as
necessary to attack the authentication
process.

3. Click the TLS Options tab. The TLS Options dialog box is displayed.
4. Select an existing Key Certificate from the key store. To select a Key Certificate from the keystore, click
Browse next to Key Certificate Label. The CMS KeyStore Certificate Viewer appears.
Note: You must add or import the key certificate into your key store prior to configuring your node. For
additional information, see Import Existing Certificates or Create CMS Key Store in the documentation
library. For additional information on how to use iKeyman, see http://www-01.ibm.com/support/
knowledgecenter/SSYKE2_6.0.0/com.ibm.java.security.component.60.doc/security-component/
ikeyman_overview.html?lang=en.
5. In the Key Certificates area, select the key certificate you want to use and click OK box.
6. Click the External Authentication tab. The External Authentication dialog box is displayed.
7. Choose one of the following options:

Chapter 7. Introduction to Connect:Direct Secure Plus for UNIX 249

 • To enable external authentication on the remote node, click Yes in the Enable External
Authentication box.
• To disable external authentication on the remote node, click No.
8. Type the Certificate Validation Definition character string defined in External Authentication Server.
9. Click OK to close the Edit Record dialog box and update the parameters file.

Customize Remote Node Records

After you configure the .Local node record, Connect:Direct Secure Plus enables the protocol and
parameters that you configured for the local node for all remote node records. If all trading partners use
the protocol and configuration defined in the .Local node record, you are now ready to begin using
Connect:Direct Secure Plus.
However, even when a trading partner uses the same protocol as the one defined in the .Local node
record, you may need to customize remote node records for the following configurations:
• Using a unique certificate file to authenticate a trading partner—During a TLS session, a certificate
enables the PNODE to authenticate the SNODE. You identified a certificate in the .Local node record. If
you want to use a unique certificate to authenticate a trading partner, you must identify this information
in the remote node record.
• Using a self-signed certificate file to authenticate a trading partner—During a TLS session, a certificate
enables the PNODE to authenticate the SNODE. If you want to use a self-signed certificate to
authenticate a trading partner, you must identify this information in the remote node record.
• —Client authentication requires that the SNODE validate the PNODE. If you want to enable client
authentication, activate this feature in the remote node record.
• Activating common name authentication—If you want another layer of security, you can activate the
ability to validate the certificate common name by specifying the common name expected to be in the
identity certificate received, either by the PNODE from the SNODE, or, when client authentication is
enabled, by the SNODE from the PNODE.
• Identifying the cipher suite used by a trading partner—When configuring the TLS protocol, you enable
cipher suites that are used to encrypt the transmitted data. When communicating with a trading partner,
you and the trading partner must use the same cipher suite to encrypt data. If the trading partner does
not enable a cipher suite that is enabled in your configuration, communication fails. If necessary, enable
cipher suites in the remote node record.

Configuring a Remote Node Record

About this task

Before you can configure the .Remote node record, you must either import your existing certificates or
create and configure a CMS Key Store. For additional information, see Import Existing Certificates or
Create CMS Key Store in the documentation library.
Configure the Remote node record with the protocol used by most of your trading partners. Because
remote node records can use the attributes defined in the Remote node record, defining the Remote node
record with the most commonly used protocol saves time. After you define the protocol in the Remote
node record, all remote nodes default to that protocol. Also, identify the trusted root file to be used to
authenticate trading partners.
To configure the local node, refer to the Local Node Security Feature Definition Worksheet that you
completed for the Remote node record security settings and complete the following procedure:

Procedure
1. From the Secure+ Admin Tool Main Window, double-click the .Remote record. The Edit Record dialog
box displays the Security Options tab, the node name, and the type of node.

250 IBM Connect:Direct for UNIX: Documentation

2. Set the Security Options for the local or remote node entry you are configuring and if necessary, modify
the time-out value in Authentication Timeout.
Refer to the following table for an explanation of the Security Options boxes:
Note: SSL3.0, TLS 1.0 and TLS 1.1 protocols are deprecated and should not be used. It is
recommended that trading partners using deprecated protocols migrate to TLS 1.3 or TLS 1.2. If
deprecated protocols are required, TLS 1.3 should not be enabled in the trading partner's
configuration, otherwise the handshake may fail. Deprecated protocols should be exclusively
configured per node. The Secure+ feature continues to support SSL 3.0, TLS 1.0 and TLS 1.1.

Field Name Field Definition Valid Values

Node Name Specifies the node record name. .Remote

This is not an editable field.

Base Record Specifies the name of the base record. Name of the local Connect:Direct
If an alias record is selected, the base node.
record name is displayed in this box.

Type Specifies the current record type. Local for a local record and Remote
for a remote record.
This is not an editable field.

Disable Secure+ Disables Connect:Direct Secure Plus. Default value is Disable Secure+.
Note: If this option is selected,
override is enabled, and no remote
node definition exists for the remote
node in the Connect:Direct Secure
Plus parameters file, Connect:Direct
Secure Plus is bypassed.

Enable SSL 3.0 Enables SSL protocol to ensure that The default value is Disable Secure
Protocol data is securely transmitted. +.
The SSL3.0 is deprecated and should
not be used. It is recommended that
trading partners using deprecated
protocols migrate to TLS 1.3 or TLS 1.2.

Enable TLS 1.0 Enables TLS protocol to ensure that The default value is Disable Secure
Protocol data is securely transmitted. +.
TLS1.0 is deprecated and should not be
used. It is recommended that trading
partners using deprecated protocols
migrate to TLS 1.3 or TLS 1.2.

Enable TLS 1.1 Enables TLS protocol to ensure that The default value is Disable Secure
Protocol data is securely transmitted. +.
The TLS1.1 is deprecated and should
not be used. It is recommended that
trading partners using deprecated
protocols migrate to TLS 1.3 or TLS 1.2.

Enable TLS 1.2 Enables TLS protocol to ensure that The default value is Disable Secure
Protocol data is securely transmitted. +.

Chapter 7. Introduction to Connect:Direct Secure Plus for UNIX 251

 Field Name Field Definition Valid Values
Enable TLS 1.3 Enables TLS protocol to ensure that The default value is Disable Secure
Protocol data is securely transmitted. +.
Disable Disables the ability to override values The default value is Disable.
in the .Remote node record with values
in the remote node record.
FIPS 140-2 Enables FIPS 140-2 security. The default value is Disable.
SP800-131A Enables NIST SP800-131a security in The default value is Disable.
Transition transition mode.
SP800-131A Enables NIST SP800-131a security The default value is Disable.
mode.
Suite B 128 bit Enables Suite B 128 bit security. The default value is Disable.
Suite B 192 bit Enables Suite B 192 bit security. The default value is Disable.

Node or Copy For PNODE, this parameter indicates The default value is No.
Statement Override whether process overrides, which may
optionally be specified in Process,
Submit, and Copy statements, will be
allowed.

For SNODE, this parameter indicates

whether the Secure+ protocol specified
by the PNODE will be allowed to
override that specified by the SNODE.

Authentication Specifies maximum time, in seconds, A numeric value equal to or greater

Timeout that the system waits to receive the than 0, ranging from 0 to 3600.
Connect:Direct Secure Plus blocks
The default is 120 seconds.
exchanged during the Connect:Direct
Secure Plus authentication process.
If you specify a value of 0,
Connect:Direct waits indefinitely to
receive the next message.
Specify a time to prevent malicious
entry from taking as much time as
necessary to attack the authentication
process.

3. Click the TLS Options tab. The TLS Options dialog box is displayed.
4. Select an existing Key Certificate from the key store. To select a Key Certificate from the keystore, click
Browse next to Key Certificate Label. The CMS KeyStore Certificate Viewer appears.
Note: You must add or import the key certificate into your key store prior to configuring your node. For
additional information, see Import Existing Certificates or Create CMS Key Store in the documentation
library. For additional information on how to use iKeyman, see http://www-01.ibm.com/support/
knowledgecenter/SSYKE2_6.0.0/com.ibm.java.security.component.60.doc/security-component/
ikeyman_overview.html?lang=en.
5. In the Key Certificates area, select the key certificate you want to use and click OK box.
6. Click the External Authentication tab. The External Authentication dialog box is displayed.
7. Choose one of the following options:

252 IBM Connect:Direct for UNIX: Documentation

 • To enable external authentication on the remote node, click Yes in the Enable External
Authentication box.
• To disable external authentication on the remote node, click No.
8. Type the Certificate Validation Definition character string defined in External Authentication Server.
9. Click OK to close the Edit Record dialog box and update the parameters file.

Validating the Configuration

Perform this procedure to ensure that the nodes have been properly configured. The validation process
checks each node to ensure that all necessary options have been defined and keys have been exchanged.
Perform the following steps to validate the Secure+ parameters file:

Procedure
1. From the Secure+ Admin Tool Main Menu, click Validate Secure+ from the File menu. The Secure+
Admin Tool - Validation Results window is displayed.
2. If the Secure+ parameters file is not correctly configured, warning and error messages are displayed.
3. Go back to the Secure+ parameters file and make changes to correct each error reported.
4. Read each warning message. If necessary, change the Secure+ parameters file to correct each
warning.
Warning messages do not always mean that the Secure+ parameters file is configured incorrectly.
Some warning messages are informational only.
5. Click Close to close the Validation Results window.

Configure External Authentication in the .SEAServer Record

About this task

At installation, a record named .SEAServer is created in the parameters file, which enables Connect:Direct
Secure Plus to interface with External Authentication Server during TLS sessions to validate certificates.
External Authentication Server properties are configured in this record and enabled/disabled in the local
and remote node records.
Complete the following procedure to configure the server properties that will allow Connect:Direct for
UNIX to interface with External Authentication Server:
Note: The values specified for this procedure must match the values specified in External Authentication
Server.

Procedure
1. Double-click the record called .SEAServer.
2. Type the Host Name for External Authentication Server.
3. Type the Port Number where External Authentication Server is listening. The default is 61366.
4. To enable caching SEAS certificate validation response, select Enable Caching.
When enabled, Connect:Direct Secure Plus can reuse previously fetched certificate validity responses
from External Authentication Server that is, cache the responses to ease the certificate validation
process when Connect:Direct interfaces with External Authentication Server during a TLS sessions.
5. Type the Cache Validity per certificate in hours. Default is 24 hours. Range: 1-720 hours.
6. Cache grace validity time per certificate when SEAS is unavailable in hours
Type the number of hours when the local cache entry of certificate expires and External Authentication
Server is unavailable such that Connect:Direct Secure Plus can accept it from its cache. Default is 0
hours which means cache grace validity time does not apply. Range: 0-720 hours.

Chapter 7. Introduction to Connect:Direct Secure Plus for UNIX 253

 Note: Cache grace validity time per certificate when SEAS is unavailable in hours should always be
greater than or equal to Cache Validity per certificate in hours.
7. Click OK to update the record.

Configure Strong Password Encryption

This feature uses strong encryption to encrypt all Connect:Direct Process data stored on disk in the
Connect:Direct work area while a Process is on the TCQ. This feature is enabled by default.

Disabling Strong Password Encryption

Complete the procedure below to disable Strong Password Encryption:

Procedure
1. From the Secure+ Admin Tool Main Menu screen, select Password Encryption from the Edit menu.
The Secure+ Admin Tool - Password Encryption window is displayed.
2. Click the No option for Enable Strong Password Encryption.
3. Click OK to disable Strong Password Encryption. The following message is displayed:

The IBM Connect:Direct Server must be restarted for the changes to Strong Password Encryption to
become effective.
4. Restart the IBM Connect:Direct Server.

Enabling Strong Password Encryption

Complete the procedure below to enable Strong Password Encryption:

Procedure
1. From the Secure+ Admin Tool Main Menu screen, select Password Encryption from the Edit menu.
The Secure+ Admin Tool - Password Encryption window is displayed.
2. Click the Yes option for Enable Strong Password Encryption.
3. Click OK to enable Strong Password Encryption. The following message is displayed:

The IBM Connect:Direct Server must be restarted for the changes to Strong Password Encryption to
become effective.
4. Restart the IBM Connect:Direct Server.

Resetting Passwords
If the Strong Password Encryption key stored in the .Password file is out of sync with the Strong Password
Encryption key used to encrypt the passwords, you must reset all Strong Password Encryption passwords.

About this task

The .Password file can get out of sync if one of the following occurs:
• You restore the .Password file from a backup—The .Password file is updated each time the IBM
Connect:Direct server is started, so the backup will probably not contain the current parameters.
• The .Password file is deleted—The .Password file is recreated as needed, so the Strong Password
Encryption key used to encrypt the passwords no longer exists.
• The .password file is corrupt—The Strong Password Encryption Key used to encrypt the passwords is not
accessible.
Complete the procedure below to reset the passwords:

254 IBM Connect:Direct for UNIX: Documentation

 Procedure
1. Stop the IBM Connect:Direct server.
2. Delete the <cdinstall>/ndm/secure+/nodes/.Password file.
3. Start the IBM Connect:Direct server.
4. Manually delete all Processes in the TCQ. Refer to the IBM Connect:Direct for UNIX User Guide for
command syntax and parameter descriptions for the delete Process and flush Process commands.

Decryption Failure
If the process KQV file fails decryption at startup or during runtime, the server places the Process in the
HOLD/Error queue to raise the visibility of the error.

Configure Certificate Authentication for Client API Connections

The API connection certificate authentication feature allows clients to connect to a Connect:Direct server
by using only an SSL Certificate with the Common Name (CN) specified as a user name.
If the intended client usage does not include submitting processes, then the user name does not have to
be a real UNIX system user name and only needs to be defined in the Connect:Direct UNIX user
authorization file. If process submission is intended, then the user specified in the CN must be a real UNIX
system user. You can configure this feature in the user authorization information file of a Connect:Direct
node. The API certificate authentication requires no user password to be presented.
This feature improves password management in large deployments of Connect:Direct, as it removes the
extra administrative steps that result from password usage.
Note:
This feature is specific only to API connections. These connections must also be AIJ-based. When you
use the authentication feature, ensure that the version of the AIJ is at least 1.1.00 Fix 000025. This
version of the AIJ contains updates that allow blank passwords to be used. This version contains the
updates that allow blank passwords the system uses the AIJ. These AIJ version requirements also apply
if you use the authentication feature in IBM Control Center. API connection certificate authentication is
not supported for the Direct.exe CLI, Connect:Direct Requester, or the Connect:Direct native C/C++/C#
non Java APIs.

Configuring API certificate authentication

Client Authentication must be enabled on the Connect:Direct Secure Plus. Client record. Client
authentication is not enabled by default in Connect:Direct Secure Plus. During an API connection, a peer
certificate is required from Control Center or the AIJ client. That certificate must contain a common name
field of an SSL certificate whose contents match a Connect:Direct local user record in the Connect:Direct
node. You also must use a blank password in order for Connect:Direct to trigger the API certificate
authentication process.
A new functional authorities configuration parameter is added to Connect:Direct for UNIX. The parameter
specifies whether a specific user can log in as a client via API certificate authentication, and it must be set
to Yes when you configure API certificate authentication.

Automate Setup with the Secure+ CLI

The Java-based Connect:Direct Command Line Interface (Secure+ CLI) and sample script enable you to
create customized script that automate creating an initial installation of IBM Connect:Direct, populating
the Secure+ parameters file, and managing node records. You can then distribute these scripts
throughout your enterprise to implement the IBM Connect:Direct application. Before you create the
scripts for distribution, consider creating an installation of Connect:Direct Secure Plus using the Secure+
Admin Tool and testing it to verify the results.

Chapter 7. Introduction to Connect:Direct Secure Plus for UNIX 255

Start and Set Up the Secure+ CLI
The following sections describe the commands and parameters used to start and set up the command
line environment.

Starting the Secure+ CLI

To start the Secure+ CLI:

Procedure
1. Go to d_dir/ndm/bin.
2. Type the following command:

spcli.sh
3. Press Enter.

Control the Display of Commands

Set the following parameters to define how error messages are captured:

Parameter Definition Values

-li Switch to enable the display of commands to the terminal. y|n
-lo Switch to enable the display of output and error messages to the y|n
terminal.
-le Switch to enable the display of errors to STDERR. y|n
-e Switch to tell the Secure+ CLI to exit when the return code is higher 0 | 4 | 8 | 16
than the specified number.
If you do not include this parameter, Secure+ CLI continues to run even
after an error has occurred.

-p The full path of the default Secure+ parameters file directory. The
Secure+ parameters file in this directory is opened automatically.
-h Switch to display the usage of the Secure+ CLl.

Control Help
The Help command determines what help information is displayed. You can list all Secure+ CLI
commands and display help for individual commands.

Command Description
help Displays all the Secure+ CLI commands.
help <command> Displays help for the specified command.

Specify Delimiter Characters

Define the following commands to determine how error messages are captured:

Command Definition Values

Set begdelim= Defines beginning and ending character to Any character
use to enclose keywords that use blanks and
enddelim= The default value is “ (double
other special characters.
quotes).

256 IBM Connect:Direct for UNIX: Documentation

Encrypt Passwords to Use with the Secure+ CLI
The Secure+ CLI displays passwords in plain text. If your company security policy mandates that you use
encrypted passwords, you can use the Local Connection Utility (LCU) to create an LCU file that contains
non-encrypted information used to encrypt the password and the encrypted password. For more
information on creating and using LCU files, see Encrypt Passwords for use with CLI.

Sample Script
The following script is provided as a model for creating custom scripts to define your IBM Connect:Direct
environment and automate the implementation of it. To prevent any loss of data, you cannot run the
script, but you can save it with a different name and modify it to suit your needs.
The sample script is available in Automation Script. The script is designed to assist you as follows:
spcust_sample1.sh
An example of configuring IBM Connect:Direct to use the TLS protocol with the Secure+ CLI. The
example demonstrates the configuration of Connect:Direct with the trusted root file, key certificates,
and ciphers.

Maintain the Secure+ Parameters File

The commands in the following table describe how to maintain the Secure+ parameters file from the
command line interface.

Command Description Parameter Values

Init Parmfile Creates the Secure+ localnode=Name of the local node local node name
parameters file. Must where the Secure+ parameters file will
be initialized before be created.
you can define nodes.
path=Location where the Secure+ directory location
parameters file will be created.
For example,
d_dir/ndm/secure+/
node

passphrase=Arbitrary set of characters a string at least 32

that encrypts the Secure+ parameters characters long
file.
Open Opens a Secure+ path=Location where the Secure+ directory location
Parmfile parameters file so parameters file will be created.
For example,
that you can
d_dir/ndm/secure+/
configure it.
node

Close Closes the Secure+ None None

Parmfile parameters file. After
this command is
issued, no more
updates can be
performed on the
Secure+ parameters
file.

Chapter 7. Introduction to Connect:Direct Secure Plus for UNIX 257

 Command Description Parameter Values
Refresh Refreshes the Secure None None
Parmfile + parameters file.
This will close the
current parameters
file and reopen it,
bringing in any
changes since last
opened.
Validate Validates the Secure+ None None
Parmfile parameters file and
ensures that it is a
valid file.
Rekey Recreates the Secure passphrase=Arbitrary set of characters passphrase, up to 32
Parmfile + parameters file if it that encrypts the Secure+ parameters characters long
becomes corrupted. file.
Sync Imports remote node path=Location and name of the location of network map
Netmap records defined in the network map file. file
IBM Connect:Direct
name=Name of the node in the node name or wildcard
network map.
network map. Use wildcard characters
Wildcard values are:
to resync more than one node at a
time. Asterisk (*)—any
number of characters.
Example: kps.* syncs up
all nodes with a name
that starts with kps.
Question mark (?)—a
single character.
Example: k?s.* syncs up
kas.* and kbs.*.

Display Information
The following commands are available to display information:

Command Description Parameter

display info Displays information about when the None
Secure+ parameters file was last
updated.
display all Displays all nodes in the Secure+ None
parameters file.
display localnode Displays the values defined in the .Local None
node record.

258 IBM Connect:Direct for UNIX: Documentation

Command Description Parameter
display remotenode Displays the values defined in remote node name or wildcard
node records.
name—The name of the node to
display information about.
Use wildcard characters to display
information about a group of
remote node records. The options
are:
Asterisk (*)—Indicates any number
of characters. For example, kps.*
displays all nodes with a name that
starts with kps.
Question mark (?)—Indicates a
single character. For example: k?s.*
displays kas.* and kbs.*.

display client Displays the values defined in None

the .Client node record.
display seaserver Displays the values defined in None
the .SEAServer record.
display protocols Displays supported security protocols None
which should be defined in a comma
separated list . Supported protocols
are: TLS1.2,TLS1.3
TLS1.0, TLS1.1, and SSL3.0 are
deprecated and should not be used. It
is recommended that trading partners
using deprecated protocols migrate to
TLS 1.3 or TLS 1.2.

display securitymodes Displays supported security modes for None

additional security. These modes are:
FIPS140-2 |
SP800-131A_TRANSITION |
SP800-131A_STRICT | SUITE_B-128 |
SUITE_B-192
display ciphersuites Displays all supported Cipher Suites for None
Secure+ which can be defined either as
a single cipher suite or in a comma
separated list.

Chapter 7. Introduction to Connect:Direct Secure Plus for UNIX 259

Manage CMS Keystore
The commands in the following table describe how to create and maintain the CMS keystore file from the
command line interface.

Command Description Parameter Values

create keystore Will create a new CMS File=While a default <path to CMS KeyStore file (*.kdb)>
Key Store file. keystore file is created
Default path is in:
at installation and can
be used, you may need d_dir/ndm/secure+/certificates/
to create a new CMS cdkeystore.kdb
KeyStore File.
Passphrase=The A string with a minimum of three
password for the new characters and a maximum of eighty
KeyStore file. characters.
*This password must be retained; it
will be required to administer the
Secure+ KeyStore.

PopulateRoots=Popula y|n
te with standard
certificate authorities.
This will import all
standard public CA
Root certificates into
the new KeyStore file.
update keystore Updates the CMS File=Path to existing <path to CMS KeyStore file (*.kdb)>
KeyStore CMS KeyStore and
Default path is in:
filename.
d_dir/ndm/secure+/certificates/
cdkeystore.kdb

Passphrase=The The retained password which was

password for the given at the creation of the keystore.
KeyStore file.
import keycert Imports existing File=Existing key Full path and filename to key
keycerts into the certificate file. certificate file to be imported.
keystore file.
*This file contains the
private key*

Passphrase=Password Pre-defined password of key certificate

of key certificate file to file.
be imported.
Label=(optional) Name A string of characters which can be an
of imported key alias name but if it is not defined, the
certificate file. Common Name of the certificate will
be the label used.
SyncNodes=Update y|n
node/certificate
references
ImportMode=Type of Add | Replace | AddOrReplace
import to be used.

260 IBM Connect:Direct for UNIX: Documentation

Command Description Parameter Values
import trustedcert Imports public File=Trusted public file Full path and filename to trusted
certificate files from from trading partner. certificate file to be imported.
trading partners.
ImportMode=Type of Add | Replace | AddOrReplace
import to be used.
delete keystoreentry Deletes certificates File=Can be either key Full path and filename to certificate
from CMS keystore. certificate file or file.
trusted public trading
partner file.
Label=Specified label Label which was defined at time of
of imported certificate import of the certificate file.
file.
DeleteChain=Defines y|n
whether to delete the
entire chain, if it exists.
SyncNodes=Reset y|n
node/certificate
references

Update the .Local Node Record

The update localnode command configures the protocol for the .Local node record. The command has
the following parameters:

Command Parameter Values

update localnode protocol=Specifies a comma delimited list Disable | TLS 1.2,TLS 1.3
of Protocols to use in the .Local node
(See Display Protocols)
record.
TLS1.0, TLS1.1, SSL3.0 are deprecated
and should not be used. It is
recommended that trading partners
using deprecated protocols migrate to
TLS 1.3 or TLS 1.2.

SecurityMode Disable | FIPS140-2 |

SP800-131A_TRANSITION |
SP800-131A_STRICT | SUITE_B-128 |
SUITE_B-192
(See Display SecurityModes)

override=Identifies if values in the remote y|n

node can override values defined in
the .Local node record.
AuthTimeout=Specifies the maximum time, 0–3600
in seconds, that the system waits to receive
The default is 120 seconds.
the IBM Connect:Direct control blocks
exchanged during the IBM Connect:Direct
authentication process.

Chapter 7. Introduction to Connect:Direct Secure Plus for UNIX 261

 Command Parameter Values
KeyCertLabel=Identifies the label of the keycert label | null
key certificate.
Note: If no keycert label is specified,
the following should be noted:
Pnode sessions will fail if the remote
node requires client authentication.
Snode sessions will fail.

EncryptData=If no is specified, Encrypt y|n

Only Control Block Information; data is
sent unencrypted. Default is Yes - data and
control block information are encrypted.
ClientAuth = Enables client authentication y|n
in a .Client node record.
CipherSuites= Specifies the cipher suites comma delimited list of cipher suites |
enabled. all | null
Note: Only certain cipher suites are all—Enables all ciphers.
supported in FIPS-mode. For a list of the
null—Clears any existing values from
FIPS-approved cipher suites, see Special
the node definition.
Considerations in the IBM Connect:Direct
for UNIX Release Notes.

SeaEnable=Enables certificate validation y|n

by Sterling External Authentication Server
SeaCertValDef=Character string defined in character string | null
Sterling External Authentication Server
null—Clears any existing values from
(SEAS).
the node definition.

Manage Remote Node Records

This section contains the commands and parameters used to create, update, display, and delete remote
node records.

Create a Remote Node Record

The create remotenode command creates a remote node record and configures the protocol settings.
The command has the following parameters:

Command Parameter Values

create remotenode model=Name of an existing node to use name of a valid remote node
as a model to copy from.
Name=Identifies name of the remote name
node record.
protocol=Specifies a comma delimited Disable | TLS 1.2,TLS 1.3 |DefaultToLN
list of Protocols to use in the remote
TLS1.0, TLS1.1, and SSL3.0 are
node record.
deprecated and should not be used. It is
recommended that trading partners
using deprecated protocols migrate to
TLS 1.3 or TLS 1.2.
(See Display Protocols)

262 IBM Connect:Direct for UNIX: Documentation

Command Parameter Values
SecurityMode Disable | FIPS140-2 |
SP800-131A_TRANSITION |
SP800-131A_STRICT | SUITE_B-128 |
SUITE_B-192 | DefaultToLN
(See Display SecurityModes)

override=Identifies if values in the copy y | n | DefaultToLN

statement can override values defined in
the remote node record.
AuthTimeout=Specifies the maximum 0–3600
time, in seconds, that the system waits to
The default is 120 seconds.
receive the IBM Connect:Direct control
blocks exchanged during then
Connect:Direct authentication process.
KeyCertLabel=Identifies the label of the keycert label | null
key certificate.
EncryptData=If no is specified, Encrypt y | n | DefaulttoLN
Only Control Block Information; data is
sent unencrypted. Default is Yes - data
and control block information are
encrypted.
ClientAuth = Enables client y | n | DefaultToLN
authentication with a remote trading
partner.
CertCommonName=The certificate name | null
common name defined in the certificate.
null—Clears any existing values from the
node definition.

CipherSuites= Specifies the cipher suites comma delimited list of cipher suites | All
enabled. | null
SeaCertValDef=Character string defined character string | null
in Sterling External Authentication Server
null—Clears any existing values from the
(SEAS).
node definition.

Chapter 7. Introduction to Connect:Direct Secure Plus for UNIX 263

 Update the Remote Node Record
The update remotenode command creates a remote node record and configures the protocol settings.
The command has the following parameters:

Command Parameter Values

update remotenode Name=Specifies name for the remote remote node name | wildcard
node record.
Use wildcard characters to update a
group of remote node records. The
options are:
Asterisk (*)—Any number of characters.
Example: kps.* displays remote nodes
with a name that starts with kps.
Question mark (?)—Single character.
Example: k?s.* displays kas.* and kbs.*.

protocol=Specifies a comma delimited list Disable |TLS 1.2,TLS 1.3 | DefaultToLN

of Protocols to use in the remote node
TLS1.0, TLS1.1, SSL3.0 are deprecated
record.
and should not be used. It is
recommended that trading partners using
depcrecated protocols migrate to TLS 1.3
or TLS 1.2.
(See Display Protocols)

SecurityMode Disable | FIPS140-2 |

SP800-131A_TRANSITION |
SP800-131A_STRICT | SUITE_B-128 |
SUITE_B-192 | DefaultToLN
override=Identifies if values in the copy y | n | DefaultToLN
statement can override values defined in
the remote node record.
AuthTimeout=Specifies the maximum 0–3600
time, in seconds, that the system waits to
The default is 120 seconds.
receive the Connect:Direct control blocks
exchanged during the Connect:Direct
authentication process.
KeyCertLabel=Identifies the label of the keycert label | null
key certificate.
EncryptData=If no is specified, Encrypt y | n | DefaulttoLN
Only Control Block Information; data is
sent unencrypted. Default is Yes - data
and control block information are
encrypted.
ClientAuth = Enables client authentication y | n | DefaultToLN
with a remote trading partner.
CertCommonName=The certificate name | null
common name defined in the certificate.
null—Clears any existing values from the
node definition.

264 IBM Connect:Direct for UNIX: Documentation

Command Parameter Values
CipherSuites= Specifies the cipher suites comma delimited list of cipher suites | All
enabled. | null
Note: Only certain cipher suites are
supported in FIPS-mode. For a list of the
FIPS-approved cipher suites, see Special
Considerations in the IBM Connect:Direct
for UNIX Release Notes.

SeaEnable=Enables certificate validation y | n | DefaultToLN

by Sterling External Authentication Server.
DefaultToLN—Defaults to the setting
specified in the .Local node record

SeaCertValDef=Character string defined in character string | null

Sterling External Authentication Server
null—Clears any existing values from the
(SEAS).
node definition.

Display a Remote Node Record

The display remotenode command displays information about one or more remote node records. The
command has the following parameter:

Command Parameter Values

display remotenode name=Name of the remote node node name | wildcard value
record to display information
To display information about more than one
about.
remote node record, use wildcard characters.
Use wildcard characters to display
information about a group of remote node
records. The options are:
Asterisk (*)—Any number of characters.
Example: kps.* displays remote nodes with a
name that starts with kps.
Question mark (?)—A single character.
Example: k?s.* displays kas.* and kbs.*.

Manage Remote Node Records

Create Alias
The create alias command will create an alias record for an existing node record in the Secure+ parmfile.
The command has the following parameter:

Chapter 7. Introduction to Connect:Direct Secure Plus for UNIX 265

 Command Parameter Value
create alias name=The alias name to be An alias name for an existing node name
used. record.
Important: Characters used in Netmap Node
Names (or Secure+ Node Names or Secure+
Alias Names) should be restricted to A-Z, a-z,
0-9 and @ # $ . _ - to ensure that the entries
can be properly managed by Control Center,
Sterling Connect:Direct Browser User
Interface, or IBM Sterling Connect:Direct
Application Interface for Java for Java (AIJ)
programs.

basename=The name of the The existing node name

existing node record.

Delete a Remote Node Record

The delete remotenode command deletes one or more remote node records. The command has the
following parameter:

Command Parameter Values

delete remotenode name=Name of the remote node remote node name | wildcard value
record to display information about.
To display information about more than one
Use wildcard characters to delete a remote node record, use wildcard
group of remote node records. characters.
Use wildcard characters to display
information about a group of remote node
records. The options are:
Asterisk (*)—Any number of characters.
Example: kps.* displays remote nodes with
a name that starts with kps.
Question mark (?)—A single character.
Example: k?s.* displays kas.* and kbs.*.

Update the .Client Node Record

The update client command creates a .Client node record and configures the protocol settings. The
command has the following parameters:

Command Parameter Values

update client protocol=Specifies a comma delimited list of Disable | TLS 1.2,TLS 1.3 |
Protocols to use in the .Client record DefaultToLN
TLS1.0, TLS1.1, and SSL3.0 are
deprecated and should not be used. It
is recommended that trading partners
using deprecated protocols migrate to
TLS 1.3 or TLS 1.2.
(See Display Protocols)

266 IBM Connect:Direct for UNIX: Documentation

 Command Parameter Values
SecurityMode Disable | FIPS140-2 |
SP800-131A_TRANSITION |
SP800-131A_STRICT | SUITE_B-128
| SUITE_B-192 | DefaultToLN
(See Display SecurityModes)

override=Enforces secure connection between y | n | DefaultToLN

a Connect:Direct client and the Connect:Direct
server
AuthTimeout=Specifies the maximum time, in 0–3600
seconds, that the system waits to receive the
The default is 120 seconds.
Connect:Direct control blocks exchanged
during the Connect:Direct authentication
process.
KeyCertLabel=Identifies the label of the key keycert label | null
certificate
EncryptData=If no is specified, Encrypt Only y | n | DefaulttoLN
Control Block Information; data is sent
unencrypted. Default is Yes - data and control
block information are encrypted.
CipherSuites= Specifies the cipher suites comma delimited list of cipher suites |
enabled. All | null

Maintain the Sterling External Authentication Server Record

This section contains the commands and parameters used to update and display the .SEAServer record.

Update the Sterling External Authentication Server Record

The update seaserver command configures properties for Sterling External Authentication Server (SEAS)
in the .SEAServer record that is created at installation. The command has the following parameters:

Command Parameter Values

update seaserver Protocol=Specifies a comma delimited list Disable | TLS1.2,TLS 1.3 DefaultToLN
of Protocols to use in the .SEAServer
TLS1.0, TLS1.1, and SSL3.0 are
record.
deprecated and should not be used. It
is recommended that trading partners
using deprecated protocols migrate to
TLS 1.3 or TLS 1.2.
(See Display Protocols)

SeaHost=External authentication host host name | null

name defined in SEAS.
null—Clears any existing values from
the node definition

AuthTimeout=Specifies the maximum 0–3600

time, in seconds, that the system waits to
The default is 120 seconds.
receive the Connect:Direct control blocks
exchanged during the Connect:Direct
authentication process.

Chapter 7. Introduction to Connect:Direct Secure Plus for UNIX 267

 Command Parameter Values
SeaPort=External authentication server port number | 61366
port number (listening) defined in SEAS.
SeaCacheEnable=Enable caching External Y|N
Authentication Server certificate validation
The default is N.
response.
SeaCacheValidityTime=Time duration The default is 24 hours.
during which the local cache entry is valid
Range: 1 to 720 hours
for certificates
SeaGraceValidityTime=Number of hours The default is 0 hours which means
when the local cache entry of certificate cache grace validity time does not
expires and External Authentication apply.
Server is unavailable such that
Range: 0 to 720 hours
Connect:Direct Secure Plus can accept it
from its cache.

Display the Sterling External Authentication Record

The display SEAServer command displays information about the .SEAServer record. This command has
no parameters.

Strong Password Encryption

This section contains the commands and parameters used to update and display the .Password file.

Update the .Password File

The update password command enables or disables Strong Password Encryption. The update goes into
effect after you start the IBM Connect:Direct Server. The command has one parameter, SpeEnable, which
can be set to Y or N to enable or disable Strong Password Encryption. Following is an example:

Update Password
SpeEnable=<Y>
;

If you enable or disable Strong Password Encryption, the server displays the following warning:

SPCG741W=The IBM Connect:Direct Server must be restarted for the changes to Strong Password
Encryption to become effective.

268 IBM Connect:Direct for UNIX: Documentation

 Display the .Password File
The Display Password command displays the Strong Password Encryption setting and .Password history.

Displaying the IBM Connect:Direct Node Information

After you set up node records in Connect:Direct Secure Plus, you can view all of the nodes and their
attributes from the Secure+ Admin Tool Main Menu Window. To display a Connect:Direct Secure Plus
node record, open it by double-clicking the node record name.

Node List Field Descriptions

Below is a description of all the fields displayed in the Node Name List:

Field Name Field Definition Values

Node Name Displays the node record name. .Local | remote node name
| .client
Type Displays the current record type. L|R
L—Local record
R—Remote record

Connect:Direct Displays the status of IBM Connect:Direct. N | TLS | SSL | *

Secure Plus
N—Disabled
TLS—TLS protocol
SSL—SSL is deprecated and
should not be used. It is
recommended that trading
partners using deprecated
protocols migrate to TLS
1.3 or TLS1.2.
*—Default to local node

Override Displays the status of override. Enable override in the Y|N|*

local node to allow remote node records to override the
Y—Enabled
settings in the local node record.
N—Disabled
*—Default to local node

CipherSuites Displays the TLS or SSL cipher suites that are enabled for Varies, based on the cipher
the node record. suites enabled.
ClientAuth Displays the status of client authentication. If the TLS Y|N|*
protocol is used, enabling client authentication means
Y—enabled
the SNODE verifies the identity of the PNODE.
N—Disabled
*—Default to local node

LimExpr Identifies if the Limited Export version is being used by a Y|N|*

remote node.
Y—Enabled
N—Disabled
*—Default to local node

Chapter 7. Introduction to Connect:Direct Secure Plus for UNIX 269

 Field Name Field Definition Values
AutoUpdate Indicates if the option to automatically update key Y|N|*
values during communication is enabled.
Y—enabled
N—disable
*—default to local node

Base Record Displays the name of the base record for the alias There are no parameter
records. values.

Viewing Node Record Change History

Perform the following steps to view the history of changes to a Connect:Direct Secure Plus node record.

Procedure
1. From the Secure+ Admin Tool Main Window, double-click the node record name.
2. Click the Security Options tab.
The history of changes is displayed in the Update History field.

Viewing Information about the Secure+ Parameters File

Perform the following steps to view information about the Secure+ parameters file:

Procedure
1. Open the Secure+ Admin Tool.
2. On the File menu option of the Secure+ Admin Tool Main Window, click Info. The File Information
dialog box is displayed.
Refer to the following table for an explanation of the fields.

Field Name Field Definition

Current File Displays the name of the Secure+ parameters file
opened.
Number of Records Lists the number of nodes defined in the Secure+
parameters file.
Number of Updates Displays how many times the Secure+
parameters file has been updated.
Last 3 Updates Displays the name of the last three nodes
updated.
3. Click OK to close the File Information dialog box.

Modify a Connect:Direct Secure Plus Configuration

After using Connect:Direct Secure Plus, it may be necessary to modify a configuration. This section
provides the following procedures for modifying Connect:Direct Secure Plus information:
• Disabling Connect:Direct Secure Plus
• Deleting a Connect:Direct Secure Plus remote node record
• Resecuring the Secure+ parameters file and Secure+ access file
• Changing the cipher suites

270 IBM Connect:Direct for UNIX: Documentation

Disabling Connect:Direct Secure Plus
You can use this procedure to disable all nodes in a configuration or one remote node. Perform the
following steps to disable Connect:Direct Secure Plus:

Procedure
1. Do one of the following:
• To disable all nodes in a configuration, open the local node record.
• To disable one node, open the remote node record for that node.
2. Click the Security Options tab.
3. Click the Disable Secure+.
4. Click OK to update the node record.
Note: In order to continue IBM Connect:Direct operations with IBM Connect:Direct disabled, both
trading partners must disable Connect:Direct Secure Plus.

Deleting a Remote Node Record

If a remote node record is no longer defined in the network map, you can remove it from the Secure+
parameters file. The following procedure deletes nodes that are defined in the IBM Connect:Direct
parameters file but not in the selected network map:

Procedure
1. From the Secure+ Admin Tool Main Menu Window, click the Sync with Netmap of the File menu.
2. Click the network map to use from the pull down list.
3. Click OK.
4. Click Skip to move through the Select Netmap Entries to the Add dialog box.
5. Do one of the following to delete node records:
• To delete selected node records, highlight the remote nodes to delete and click Delete Selection.
• To delete all remote node records that are not found in the network map, click Delete All.
Note: Do not delete the remote node record that is named for the IBM Connect:Direct node. It is the
base record for the .Local node record. You cannot delete the .Local node record.

Resecuring the Secure+ Parameters File and Secure+ Access file

Routinely, or if your Secure+ access file is compromised, perform the following steps to resecure
Connect:Direct Secure Plus:

Procedure
1. From the Secure+ Admin Tool Main Window, click Rekey Secure+ from the File menu. The Rekey
Secure+ dialog box is displayed.
2. Type an alphanumeric string at least 32 characters long in the Passphrase field. Connect:Direct
Secure Plus uses the passphrase to re-encrypt the Secure+ parameters file the and Secure+ access
files. You do not have to remember this passphrase value.
3. Click OK to accept the new passphrase. The Connect:Direct Secure Plus decrypts and re-encrypts the
Secure+ parameters file and Secure+ access file.

CAUTION: Do not type a new passphrase if an error occurs. If an error occurs while you are
resecuring the files, restore the node records from the ACFSave directory. This directory is
created after the Rekey Secure+ feature is executed.

Chapter 7. Introduction to Connect:Direct Secure Plus for UNIX 271

Connect:Direct Secure Plus Statistics Record Information
IBM Connect:Direct logs statistics for IBM Connect:Direct Process activity. IBM Connect:Direct statistics
includeConnect:Direct Secure Plus information for a Process.
Fields are included in Connect:Direct Process statistics records to provide Connect:Direct Secure Plus
information about the Process. Connect:Direct Secure Plus information is included in the Process
statistics information only when you attach to aConnect:Direct Secure Plus server. For information on
viewing statistics, refer to the Sterling Connect:Direct Browser User Interface User Guide. When you use
the select statistics function to view information about a IBM Connect:Direct Process, statistics
information about a particular Process is displayed. If Connect:Direct Secure Plus is
enabled,Connect:Direct Secure Plus fields are also displayed.
The Connect:Direct Secure Plus fields and values available using the select statistics function are shown
in the following table:

Field Name Field Description Values

Connect:Direct Secure Specifies whether Connect:Direct Y|N
Plus Enabled Secure Plus is enabled.
Connect:Direct Secure Specifies which protocol is enabled. TLS 1.2 | TLS 1.3
Plus Protocol
SSL 3.0, TLS 1.0, and TLS 1.1 protocols are
deprecated and should not be used. It is
recommended that trading partners using
deprecated protocols migrate to TLS 1.3 or
TLS1.2.

Cipher Suite Displays the cipher suite used during cipher suite name
a session.
For example:
TLS_ECDHE_RSA_WITH_AES_128_GCM_SH
A256

PNode Cipher List Specifies the encryption algorithms IDEACBC128 | TDESCBC112 | DESCBC56
available for the PNODE during the
session.
PNode Cipher Specifies the preferred data Y | N | algorithm name
encryption as specified in the Secure
+ parameters file of the PNODE.
SNode Cipher List Specifies the encryption algorithms IDEACBC128 | TDESCBC112 | DESCBC56
available for the SNODE during the
session as specified in the Secure+
parameters file of the SNODE.
SNode Cipher Specifies the preferred data Y | N | algorithm name
encryption algorithm as defined in
the Secure+ parameters file of the
SNODE.
Control Block Cipher Specifies the algorithm used for IDEACBC128 | TDESCBC112 | DESCBC56
encrypting control blocks. This value
is determined during authentication
when the PNODE and SNODE are
merged.
Copy Data Cipher Specifies the encryption method IDEACBC128 | TDESCBC112 | DESCBC56
used for encrypting data. The value
is determined after the values in the
SNODE and the PNODE are merged.

272 IBM Connect:Direct for UNIX: Documentation

Field Name Field Description Values
PNODE Signature Indicates whether digital signatures Y|N
Enabled are enabled for the PNODE. This
value is obtained from the Secure+
parameters file settings. If the COPY
statement overrides the Secure+
parameters file, the value from the
COPY statement is used.
SNODE Signature Indicates whether digital signatures Y|N
Enabled are enabled for the SNODE. This
value is obtained from the Secure+
parameters file settings.
Signature Enabled Identifies the digital signature value Y|N
used for a copy operation.
In the Session Start record, this
value is the result of the merged
value between the PNODE and
SNODE. In the Copy Termination
record, if the COPY statement
overrides the Secure+ parameters
file value, the merged value depends
on the value supplied in the COPY
statement.
(The unprocessed value from the
COPY statement is recorded in the
Signature Enabled field of the
PNODE).

Current Signature Indicates whether the current digital Y | N

Verified signature was verified.
Previous Signature Indicates whether the previous Y|N
Verified digital signature was verified.

IBM Connect:Direct CLI Select Statistics Detail

When you use the IBM Connect:Direct CLI select statistics function to view the information about a
Connect:Direct Process, you see statistics information about a particular Process. Connect:Direct Secure
Plus fields are shown in bold in the following samples. The Connect:Direct field names, descriptions, and
valid values are shown in Connect:Direct Secure Plus Statistics Record Information. For more information
on Connect:Direct certificate auditing, see Secure+ Parameters File Auditing.

Chapter 7. Introduction to Connect:Direct Secure Plus for UNIX 273

Session Start (SSTR) Record
The following sample Session Start Record (SSTR) displays the output of an SSL session:

Record Id => SSTR

Process Name => Stat Log Time => 15:23:21

Process Number => 0 Stat Log Date => 10/16/2004

Submitter Id =>

Start Time => 15:23:20 Start Date => 10/16/2004

Stop Time => 15:23:21 Stop Date => 10/16/2004

SNODE => JKTIB8100

Completion Code => 0

Message Id => LSMI004I

Message Text => PNODE session started - remote node &NODE

Secure+ Protocol => SSL 3.0

SSL Cipher Suites => ssl_RSA_WITH_RC4_128_MD5

---------------------------------------------------------------------

274 IBM Connect:Direct for UNIX: Documentation

Copy Termination (CTRC) Record
The Copy Termination Record (CTRC) sample below uses the SSL protocol:

Record Id => CTRC

Process Name => XX Stat Log Time => 15:26:32

Process Number => 195 Stat Log Date => 10/16/2004

Submitter Id => user1

Start Time => 15:23:47 Start Date => 10/16/2004

Stop Time => 15:26:32 Stop Date => 10/16/2004

SNODE => DLAS8100

Completion Code => 0

Message Id => SCPA000I

Message Text => Copy operation successful.

COPY DETAILS: Ckpt=> Y Lkfl=> N Rstr=> N XLat=> N Scmp=> N Ecmp=> N

From node => S

Src File => D:\long path

Dest File => D:\long path

Src CCode => 0 Dest CCode => 0

Src Msgid => SCPA000I Dest Msgid => SCPA000I

Bytes Read => 23592960 Bytes Written => 23592960

Records Read => 1024 Records Written => 1024

Bytes Sent => 23791420 Bytes Received => 23791420

RUs Sent => 30721 RUs Received => 30721

Secure+ Protocol =>SSL 3.0

SSL Cipher Suites =>SSL_RSA_WITH_RC4_128_MD5

---------------------------------------------------------------------

Chapter 7. Introduction to Connect:Direct Secure Plus for UNIX 275

Secure+ Parameters File Auditing
IBM Connect:Direct provides auditing of Secure+ parameters files and certificates for archival purposes.
The Connect:Direct Secure Plus Administration Tool (Secure+ Admin Tool) and the Connect:Direct Secure
Plus Command Line Interface (Secure+ CLI) log changes made to the Connect:Direct Secure Plus
parameters file (Secure+ parameters file). The following events are logged:
• Application Startup
• Init Parmfile
• Open Parmfile
• Sync Netmap
• Rekey Parmfile
• Create Node
• Update Node
• Delete Node
The Secure+ parameters file logging feature has the following operational characteristics:
• The logging feature is always enabled and cannot be disabled.
• If errors occur when the log is being updated, the application terminates.
• Each log entry contains a timestamp, user ID, and a description of the action/event.
• When an existing node is updated, any changed fields are reported.
• When a node is created or deleted, the values of all non-empty fields are reported.
• Any commands that modify a node are logged.
Note: The certificates used by Connect:Direct Secure Plus are individual files that can be stored anywhere
on the system. As a result, the logging feature cannot detect when existing certificate files are modified.
Connect:Direct Secure Plus only stores the certificate path name and detects changes to this field only.

Access Secure+ Parameters File Audit Logs

The Secure+ parameters file audit logs are stored in a dedicated directory, ...\secure+\log. The log file
naming convention is SP[YYYY][MM][DD].001 (using local time), and the contents of a log file are limited
to a single calendar date. You can view these log files using any text editor. Log files are not deleted by
IBM Connect:Direct.

Secure+ Parameters File Audit Log Entries

Each audit log has the following header:

[YYYYMMDD][HH:MM:SS:mmm][userid]

When a parameter file is created or opened, an ID is generated that associates the change with the node
being updated as shown in the following:

[YYYYMMDD][HH:MM:SS:mmm][userid][ParmFileID]

The following fields may appear in a create, update, or delete audit record.

Field Name Description

Name Name of the node
BaseRecord Name of the base record
Type Record type of local, remote, or alias

276 IBM Connect:Direct for UNIX: Documentation

 Field Name Description
Protocol Enables Connect:Direct Secure Plus protocol
Override Enables overriding the current node
AuthTimeOut Authentication timeout
SslTlsTrustedRootCertFile Pathname to trusted roots file
SslTlsCertFile Pathname to key certificate file
SslTlsCertPassphrase Key certificate passphrase (masked)
SslTlsEnableClientAuth Enable client authentication
SslTlsCertCommonName Common name of the remote certificate to verify
SslTlsEnableCipher List of SSL/TLS cipher suites
SslTlsSeaEnable Enable external authentication
SslTlsSeaCacheEnable Enable caching External Authentication Server
certificate validation response.
SeaCacheValidityTime Time duration during which the local cache entry is
valid for certificates
SeaGraceValidityTime Number of hours when the local cache entry of
certificate expires and External Authentication
Server is unavailable such that Connect:Direct
Secure Plus can accept it from its cache.
SeaCertValDef External authentication validation definition
SeaHost External authentication host name
SeaPort External authentication port number

Secure+ Parameters File Audit Log Error Reporting

Errors are reported for the following logging functions: open log, write log, and lock log. If an error occurs
during one of these functions, an error message is displayed, and the application is terminated. The lock
function times out after 30 seconds. Typically, Secure+ Admin Tool or the Secure+ CLI hold the lock for
less than one second per update.

IBM Connect:Direct Secure Plus Certificate Auditing

In a TLS session, audit information about the identity certificate and its signing certificate is logged in the
statistics log in the Session Start (SSTR) and Copy Termination (CTRC) records. The audit information is
included in the response data from a select statistics command in the SSTR and CTRC records. In a TLS
session, the PNODE (client) always logs the audit information. The SNODE (server) only logs the
information when client authentication is enabled. For logging to occur, the session handshake must
succeed and progress to the point of logging the SSTR and CTRC records.

Certificate Audit Log Entries

The audit consists of the subject name and serial number of the identity and its signing certificate. The
identity certificate also contains an issuer attribute, which is identical to the signing certificate subject
name. Although many signing certificates may exist between the identity and final root certificate, the
audit includes only the last two certificates in a chain: an intermediate certificate and an end certificate.
In the SSTR and CTRC records, the CERT contains the common name and serial number of the key
certificate, and the CERI contains the common name of the issuer and the serial number of an
intermediate or root CA. They may also contain the certificate serial number, for example:

Chapter 7. Introduction to Connect:Direct Secure Plus for UNIX 277

CERT=(/C=US/ST=MA/L=Marshfield/O=test.org/OU=Dev/CN=Test ID/SN=99c0ce01382e6c83)|
CERI=(/C=US/ST=MA/L=Marshfield/O=test.org/CN=root CA/SN=da870666bbfb5538)

Connect:Direct Secure Plus certificate audits may contain the following fields:

Field Name Abbreviation Max Lengths (RFC 2459)

Common Name CN 64
Country C 2
Locality L 128
State ST 128
Organization O 64
Organization Unit OU 64
Email Address emailAddress 128
Serial Number SN 128 (estimated)

Access Certificate Audit Logs

Certificate audit information located in the SSTR and CTRC records cannot be accessed directly using
Connect:Direct Requester or Sterling Connect:Direct Browser User Interface. To access certificate
information, you can issue a query directly to the database or use an SDK-based or JAI-based program to
issue a Select Statistics command. The response to the Select Statistics command contains the
AuditInfo field of the statistics records, including the SSTR and CTRC records. This field contains
certificate audit information.
The following example was generated using a database query. The certificate audit information is
highlighted in bold.

'2007-05-21 14:50:27', 2, 'SSTR', 'CAEV', '', 0, '2007-05-21 14:50:26', '2007-05-21 14:50:27', '', '', 'JLYON-
XP.4400', 0, 'MSGI=LSMI004I|SBST=(&NODE=JLYON-XP.4400)|PNOD=JLYON-XP.4400|CSPE=Y|CSPP=TLSv1|
CSPS=TLS_RSA_WITH_AES_256_CBC_SHA|
CERT=(/C=US/ST=MA/L=Marshfield/O=test.org/OU=Dev/
CN=Example Test ID/SN=a9febbeb4f59d446)|
CERI=(/C=US/ST=MA/L=Marshfield/O=test.org/OU=Dev/CN=Example
IntermediateCA/SN=a69634a8a7830268)|STSD=2|TZDI=-14400|'
'2007-05-21 14:50:28', 2, 'CTRC', 'CAPR', 'SAMPLE', 1, '2007-05-21 14:50:27', '2007-05-21 14:50:28',
'JLYON-XP.4400', 'jlyon', 'JLYON-XP.4400', 0, 'MSGI=SCPA000I|LCCD=0|LMSG=SCPA000I|OCCD=0|
OMSG=SCPA000I|PNAM=SAMPLE|PNUM=1|
SNAM=STEP1|SBND=JLYON-XP.4400|SBID=jlyon|PNOD=JLYON-XP.4400|SNOD=JLYON-XP.4400|LNOD=P|
FROM=P|XLAT=N|ECZI=N|ECMP=N|SCMP=N|OERR=N|CKPT=Y|LKFL=N|RSTR=N|
RUSZ=65535|PACC=|SACC=|PPMN=|SFIL=C:\Program Files\Sterling Commerce\Connect Direct
v4.4.00\Server\Process\Sample.html|SDS1= |SDS2= |SDS3= |SFSZ=0|SBYR=861|SRCR=1|SBYX=863|
SRUX=1|SNVL=-1|SVOL=|DFIL=C:\Program Files\Sterling Commerce\Connect Direct v4.4.00\Server\Process
\Verify.html|PPMN=|DDS1=R|DDS2= |DDS3= |DBYW=861|DRCW=1|DBYX=863|DRUX=1|DNVL=0|DVOL=|
CSPE=Y|CSPP=TLSv1|CSPS=
TLS_RSA_WITH_AES_256_CBC_SHA|CERT=(/C=US/ST=MA/L=Marshfield/O=test.org/OU=Dev/
CN=Example Test ID/SN=a9febbeb4f59d446)|CERI=(/C=US/ST=MA/L=Marshfield/O=test.org/OU=Dev/
CN=Example Intermediate CA/SN=a69634a8a7830268)
|PCRC=N|ETMC=60|ETMK=10|ETMU=0|STSD=2|TZDI=-14400|'

278 IBM Connect:Direct for UNIX: Documentation

 Certificate Audit Log Error Reporting
If an error occurs when the subject name is extracted from the identity (CERT) or issuer's (CERI)
certificates, the following message ID is logged:

CERT=(MSGI=CSPA310E)|CERI=(MSGI=CSPA310E)

Only the message ID is displayed with the CERT or CERI tokens; the standard IBM Connect:Direct error
function is not used. After the error occurs, the session continues.

Connect:Direct Secure Plus Troubleshooting

Use the following table to help troubleshoot problems with Connect:Direct Secure Plus:

Problem Possible Cause Solution

Connect:Direct Secure Plus The Connect:Direct network Verify that the network map entries for
features are enabled in the maps do not contain entries for both the PNODE and the SNODE exist.
Secure+ parameters file, but the PNODE and SNODE.
the statistics record indicates
that these functions are
disabled.
Running a Process with a Unique public/private key pairs Change the .Local node record to
remote node fails with an are generated for the remote Enable Override=Y.
authentication error. node record and the .Local
node record is set to Enable
Override=N.
The ENCRYPT.DATA The algorithm name used in the Verify that the algorithm name in the
parameter, specified from the COPY statement is not in the COPY statement is in the supported
COPY statement causes the supported algorithm list for algorithm list for both nodes.
copy step to fail with error both nodes.
message CSPA080E.
Connect:Direct Secure Plus is Remote node records do not • A remote node record must exist for
installed, but error message exist. every node in the netmap. Use the
CSPA001E occurs on Sync with Netmap feature to create
transfers not using any missing nodes.
Connect:Direct Secure Plus.
• Disable Connect:Direct Secure Plus
by clicking Disable Secure+ in
the .Local node record.

Signature verification fails Configuration settings missing • If this is a non-Secure node, make
with error message or incorrect. sure the remote node record has
CSPA002E. Disable Connect:Direct Secure Plus
selected.
• Check the Connect:Direct Secure
Plus settings for the node.

Signature verification fails • Configuration settings • Execute standard operating

with error message missing or incorrect. procedure for investigating security
CSPA003E, CSPA004E, or violation.
• A security attack in progress.
CSPA005E.

Chapter 7. Introduction to Connect:Direct Secure Plus for UNIX 279

 Problem Possible Cause Solution
Signature verification fails Expired Signature Previous Key If Auto Update is disabled, check the
with error message Pair. Date exceeded or keys expiration date for the signature key
CSPA007E. have been changed. pair for both nodes. Check the update
history log on both nodes for the last
change to the record. Verify that the
signature public key is correct for both
nodes.
Running a Process with a Authentication Previous Key If Auto Update is disabled, check the
remote node fails with an Pair Expiration Date exceeded authentication previous key pair
authentication error, or keys have been changed. expiration date for both nodes. Check
CSPA008E. the update history log on both nodes
for the last change to the record. Verify
the authentication public key is correct
for both nodes.
Strong authentication fails • The time allowed for strong • Increase the timeout value.
with the error, CSPA010E. authentication expired. • Execute standard operating
• A security attack in progress. procedure for investigating security
violation.

Connect:Direct Secure Plus An illegal attempt to override • Turn on Enable Override in the
session fails with the error, Connect:Direct Secure Plus remote node record to allow the
CSPA011E. parameters. COPY statement to override the node
settings.
• Check the COPY statement and
remove the override statements.

Connect:Direct Secure Plus Connect:Direct Secure Plus Check the remote node definition
session fails with the error, cannot read the remote node settings.
CSPA014E. definition.
Connect:Direct Secure Plus Connect:Direct Secure Plus is Make sure Connect:Direct Secure Plus
session fails with the error, not enabled in the local node is enabled for the local node.
CSPA016E. definition.
Connect:Direct Secure Plus Error generating digital • Resubmit the Process.
session fails with the error, signature.
• Call IBM Customer Support.
CSPA019E.
Connect:Direct Secure Plus The COPY statement requested Remove the SECURE= parameter from
session fails with the error, Connect:Direct Secure Plus the COPY statement.
CSPA077E. parameters but Connect:Direct
Secure Plus is not configured.
Connect:Direct Secure Plus Invalid encryption algorithm Change the ENC.DATA parameter and
session fails with the error, identified in COPY statement. specify one of the following values: Y,
CSPA079E. N, IDEACBC128, TDESCBC112, or
DESCBC56 and resubmit the Process.
Connect:Direct Secure Plus No common algorithms are Verify the algorithm list for both nodes
session fails with the error, available for both nodes. contains at least one common
CSPA080E. algorithm name.
Connect:Direct Secure Plus Session attempted but remote Make sure both nodes are defined.
session fails with the error, node is not configured.
CSPA091E.

280 IBM Connect:Direct for UNIX: Documentation

Problem Possible Cause Solution
Connect:Direct Secure Plus Both nodes are not configured Check the protocol setting at both sites
session fails with the error, for the same protocol. and verify that the same protocol is
CSPA200E. configured at each site.
Connect:Direct Secure Plus TLS protocol handshake failed. Edit the cipher suite list and add a
session fails with the error, cipher suite used by the trading
CSPA202E. partner.
Connect:Direct Secure Plus The TLS protocol could not Make sure the certificate information is
session fails with the error, validate the server's certificate. typed into the node record.
CSPA203E or CSPA204E.
Connect:Direct Secure Plus A trading partner is not using Make sure that both ends of the
session fails with the error, TCP/IP for communication. communication use TCP/IP.
CSPA205E.
Connect:Direct Secure Plus The TLS protocol could not Make sure the certificate information is
session fails with the error, validate the server's certificate. entered into the node record.
CSPA206E.
Connect:Direct Secure Plus The common name in the Make sure the certificate common
session fails with the error, certificate received does not name is spelled correctly and uses the
CSPA208E. match the Connect:Direct same case as that in the certificate.
Secure Plus configuration.
Connect:Direct Secure Plus The certificate has expired or is Obtain a new certificate and
session fails with the error, invalid. reconfigure the node record.
CSPA209E.
Connect:Direct Secure Plus The COPY statement attempts • The system continues to operate.
session fails with the error, to override settings in the TLS
• If desired, change the Process
CSPA210E. protocol.
statement and remove the COPY
override options.

Connect:Direct Secure Plus The remote trading partner Notify the trading partner that a
session fails with the error, failed to send a certificate. certificate is required.
CSPA211E.
Connect:Direct Secure Plus The trusted root certificate Check the local node configuration and
session fails with the error, could not be loaded. make sure the location of the trusted
CSPA280E. root certificate is correctly identified.
Connect:Direct Secure Plus The trusted root certificate is Check the local node configuration and
session fails with the error, empty. make sure the location of the trusted
CSPA281E. root certificate is correctly identified.
Connect:Direct Secure Plus The user certificate file cannot Check the local node configuration and
session fails with the error, be loaded. make sure the location of the user
CSPA282E. certificate file is correctly identified.
Connect:Direct Secure Plus The Secure+ parameters files Run the Secure+ Admin Tool to
session fails with the error, have not been initialized. initialize the Secure+ parameters files.
CSPA303E.
Connect:Direct Secure Plus The SSL library failed during the Examine all related errors to determine
session fails with the error, handshake. the cause of the failure.
CSPA309E.

Chapter 7. Introduction to Connect:Direct Secure Plus for UNIX 281

 Problem Possible Cause Solution
Connect:Direct Secure Plus Certificate validation failed. Verify that the root certificate is
session fails with the error, properly configured. An alternate
CSPA311E. certificate may be required.

Configuration Worksheets
Use the worksheets in this topic to record the configuration information for Connect:Direct Secure Plus.
• The Local Node Security Feature Definition Worksheet is a record of the security functions defined for
the local IBM Connect:Direct node.
• The Remote Node Security Feature Definition Worksheet is a record of the security functions defined for
remote nodes. For each trading partner, define a remote node record. Make a copy of the blank Remote
Node Security Feature Definition Worksheet for each remote node that you are configuring for
Connect:Direct Secure Plus operations.

Local Node Security Feature Definition Worksheet

Record the security feature definition for the IBM Connect:Direct .Local node record on this worksheet.
Local Node Name: ______________________________________
Configured Security Functions
Enable TLS protocol: Yes _______ No _______
Enable SSL protocol: Yes _______ No _______
Authorization Timeout: ________________
Trusted Root Certificate File __________________________________________________
location:
Key Cert File: __________________________________________________
Certificate Passphrase: __________________________________________________
Cipher Suite(s) Enabled: __________________________________________________
External Authentication
Enable External Authentication Yes _______ No _______
Certificate Validation Definition __________________________________________________________
_
Enable FIPS 140-2 mode Yes _______ No _______

Remote Node Security Feature Definition Worksheet

Make a copy of this worksheet for each remote node defined in the IBM Connect:Direct parameters file
that you are configuring for IBM Connect:Direct operations. Record the security feature definitions for a
remote node record on this worksheet.
Remote Node Name: _____________________________
Security Options
Protocol defined in the .Local node record: <protocol> _______
Is the remote node using the protocol defined in the .Local Yes _______ No _______
node record?

282 IBM Connect:Direct for UNIX: Documentation

If you answered No to the question above, identify the protocol to use for the Remote Node:

Note: If you do not enable the override option, IBM Connect:Direct generates an error message.

Enable TLS protocol: Yes _______ No _______

Enable SSL protocol: Yes _______ No _______
If you want to use the same protocol defined in the local node, select Default to Local Node.
Enable Override: Yes _______ No _______

Note: The COPY statement cannot override settings in SSL-enabled or TLS-enabled remote nodes.

Authorization Timeout: _________________

TLS or SSL Protocol Functions
Trusted Root Certificate File _____________________________________
location:
Certificate File: _____________________________________
Certificate Passphrase: _____________________________________
Cipher Suite(s) Enabled: __________________________________________________________
_
Enable Client Authentication: Yes _______ No _______ Default to local node
_____
Certificate Common Name: _____________________________________

Note: If you want to add a second level of security, enable client authentication for the remote node and type
the certificate common name.

External Authentication
Enable External Authentication Yes _______ No _______ Default to local node
_____
Certificate Validation Definition __________________________________________________________
_
Enable FIPS 140-2 mode Yes _______ No _______

Certificate Files
The TLS security protocol use a secure server RSA X.509V3 certificate to authenticate your site to any
client that accesses the server and provides a way for the client to initiate a secure session. You obtain a
certificate from a certificate authority or you can create a self-signed certificate. When you obtain a
certificate file, a trusted root certificate file and key file are created. This topic describes the layout of the
trusted root certificate file and the key certificate file.
Connect:Direct Secure Plus uses two certificate files to initiate TLS session: a trusted root certificate file
and a key certificate file.
When you obtain a root certificate from a certificate authority, you receive a trusted root certificate file. To
configure Connect:Direct Secure Plus, add the name and location of the trusted root certificate file to the
node record using the Secure+ Admin Tool.
A sample trusted root certificate file called trusted.txt is installed in the Connect:Direct Secure Plus
\certificates directory when you install Connect:Direct Secure Plus. Use any text editor to add or delete
certificate information to this file. In simple configurations, only one trusted root certificate file is used. In

Chapter 7. Introduction to Connect:Direct Secure Plus for UNIX 283

 more sophisticated configurations, you may associate individual trusted root files with one or more node
records.
When you use a certificate signing request (CSR) tool you do not need to change the contents of the key
certificate file.
If you set up your own PKI infrastructure, you may chain more than two certificates, including a CA root
certificate, one or more intermediate CA certificates, and an identity certificate. You can create chained
certificates using one of the following methods:
• Using the Local Key Certificate File—In a chain of two certificates, the local key certificate file contains a
private key and an identity certificate. In a longer chain, the key certificate file contains the private key
and the identity key, followed by the intermediate CA certificates.
• Using the Remote Trusted File— In a chain of two certificates, the remote trusted file contains the CA
root certificate. In a longer chain, the remote trusted file contains the CA root certificate and all the
intermediate CA certificates.

Formats
The formats discussed in this section apply to the certificate files used with Connect:Direct Secure Plus.
The formats are illustrated in the sample certificate files below.

General Object Format

All objects are formatted in the Privacy Enhanced Mail (PEM) style, beginning with a line in the format.
Below is a sample object format:

-----BEGIN <object>-----

and end with:

-----END <object>-----

In this sample, <object> is a placeholder for the name of the object type: CERTIFICATE or ENCRYPTED
PRIVATE KEY.

Certificate Format
A certificate is encoded as a general object with the identifier string CERTIFICATE or X.509 CERTIFICATE.
The base64 data encodes a Bit Error Rate (BER)-encoded X.509 certificate. This is the same format used
for PEM. Anyone who provides or understands PEM-format certificates can accommodate the certificate
format. For example, VeriSign commonly fulfills certificate requests with certificates in this format, SSLeay
supports them, and SSL servers understand them. Both Netscape and Microsoft support this format for
importing root CA certificates.

Private Key Format

A private key is encoded as a general object with the identifier string ENCRYPTED PRIVATE KEY. The
base64 data encodes a BER-encoded PKCS#8 Private Key object. The passphrase associated with the
Private Key is required for Connect:Direct Secure Plus and is stored in the Secure+ parameters file.
Additional encryption is used to prevent the passphrase from being discovered.

284 IBM Connect:Direct for UNIX: Documentation

Sample Certificate Files
In the sample user certificate below, a private key is followed by the server certificate, which is followed
by the root certificate.

-----BEGIN ENCRYPTED PRIVATE KEY-----

MIICCDAaBgkqhkiG9w0BBQMwDQQIIfYyAEFKaEECAQUEggHozdmgGz7zbC1mcJ2r

IGpupStY5rLqqQ5gwLn45UWgzy6DM96CQg6+Dyn0N9d1M5lIg2wlnUwE8vI=

-----END ENCRYPTED PRIVATE KEY-----

User/Server Certificate

-----BEGIN CERTIFICATE-----

MIICUDCCAdoCBDaM1tYwDQYJKoZIhvcNAQEEBQAwgY8xCzAJBgNVBAYTAlVTMRMw

iKlsPBRbNdq5cNIuIfPS8emrYMs=

-----END CERTIFICATE-----

// Final Root Certificate (optional)

-----BEGIN CERTIFICATE-----

MIICUDCCAdoCBDaM1tYwDQYJKoZIhvcNAQEEBQAwgY8xCzAJBgNVBAYTAlVTMRMw

iKlsPBRbNdq5cNIuIfPS8emrYMs=

-----END CERTIFICATE-----

In the sample root certificate below, the trusted.txt file contains a list of trusted root certificates.

Chapter 7. Introduction to Connect:Direct Secure Plus for UNIX 285

 RSA Commercial CA - exp. Dec 31, 2003

-----BEGIN CERTIFICATE-----

MIICUDCCAdoCBDaM1tYwDQYJKoZIhvcNAQEEBQAwgY8xCzAJBgNVBAYTAlVTMRMw

iKlsPBRbNdq5cNIuIfPS8emrYMs=

-----END CERTIFICATE-----

RSA Commercial CA - exp. Dec 31, 2010

-----BEGIN CERTIFICATE-----

MIICUDCCAdoCBDaM1tYwDQYJKoZIhvcNAQEEBQAwgY8xCzAJBgNVBAYTAlVTMRMw

iKlsPBRbNdq5cNIuIfPS8emrYMs=

-----END CERTIFICATE-----

Model Automation Scripts

The following scripts are provided as models for creating custom scripts to define your Connect:Direct
Secure Plus environment and automate the implementation of it. To prevent any loss of data, you cannot
run the scripts, but you can save them with a different name and modify them to suit your needs.

Configure Connect:Direct Secure Plus to Use the TLS Protocol

The spcust_sample1 script demonstrates using the Secure+ CLI to configure Connect:Direct Secure Plus
to use the TLS protocol with the trusted root file, key certificates, and ciphers.

#! /bin/sh
#
#############################################################################
# Licensed Materials - Property of IBM
#
# Connect:Direct for UNIX
#
# (C) Copyright IBM Corp. 1992, 2014 All Rights Reserved.
#
# US Government Users Restricted Rights - Use, duplication or disclosure
# restricted by GSA ADP Schedule Contract with IBM Corp.
#############################################################################
#
# spcust_sample1.sh contains an example of configuring
# Secure+ to use SSL or TLS protocols with the Secure+ CLI.

286 IBM Connect:Direct for UNIX: Documentation

# The example demonstrates the configuration of Secure+
# with the trusted root and key certificates and ciphers
#
#
# Variables
#
# The return code.
# spcli.sh returns the highest return code of the commands
# it executed. Possible return codes and their meanings are
# 0 success
# 4 warning
# 8 error
# 16 fatal error
RC=0
#
#
# Functions
#
#
# Custom initialization logic written by customer.
#
initCustom()
{
# Customer adds custom initialization code here.
echo "Init custom..."
# rm -rf /sci/users/jlyon/cd42/ndm/secure+/nodes
}
#
# Invoke CLI to configure Secure+.
#
invokeCLI()
{
/sci/users/jlyon/cd42/ndm/bin/spcli.sh -e 8 -li y << EOF
;
display info
;
;
; -- Synch with netmap
;
sync netmap
path=/sci/users/jlyon/cd42/ndm/cfg/<node name>/netmap.cfg
name=*
;
;
; -- Import KeyCert
;
Import KeyCert
File=<path to Key Certificate file>
Passphrase=<KeyStore passphrase>
Label=<optional, destination name of key certificate>
ImportMode=<Add | Replace | AddOrReplace>
;
;
; -- Import TrustedCert
;
Import TrustedCert
File=<path to Trusted Certificate file>
ImportMode=<Add | Replace | AddOrReplace>
;
;
; -- Update LocalNode
;
Update LocalNode
Protocol=<Comma delimited list of Protocols, see Display Protocols>
SecurityMode=<One Security Mode, see Display SecurityModes>
Override=<y | n>
AuthTimeout=<nnn seconds>
KeyCertLabel=<label of key certificate | null>
EncryptData=<y | n>
ClientAuth=<y | n>
CipherSuites=<Comma delimited list of Ciphersuites | All | null>
SeaEnable=<y | n>
SeaCertValDef=<external authentication server certificate validation definition | null>
;
;
; -- Display localnode
;
display localnode
;
;
; -- Validate parmfile
;

Chapter 7. Introduction to Connect:Direct Secure Plus for UNIX 287

 validate parmfile
;
EOF
return $?
}
#
# Custom termination logic written by customer.
#
terminateCustom()
{
# Customer adds custom termination code here.
# For example, E-mail standard out log for review.
# Send error messages to system monitoring facility.
echo "$RC"
echo "Custom Terminating ... "
}
#
# Main script
#
echo
echo "This script has been prevented from running because it will alter the configuration"
echo "of Secure+. Before removing this warning and its exit call, please modify the script"
echo "so that it carries out only desired modifications to the configuration of Secure+."
echo
exit
initCustom
invokeCLI
RC=$?
terminateCustom
exit $RC

Encrypt Passwords for use with CLI

The Secure+ CLI displays passwords in plain text. If you need to encrypt passwords for use with the
Secure+ CLI, use the Local Connection Utility (LCU) to create an LCU file that contains non-encrypted
information used to encrypt the password and the encrypted password, such as a keycert passphrase.
You can then refer to this file when prompted for passwords.

288 IBM Connect:Direct for UNIX: Documentation

Chapter 8. About SMF
The Service Management Facility (SMF) is a core component of the Predictive Self-Healing set of
technologies introduced in Solaris 10. With SMF, system administrators use simple command line utilities
to identify, observe, and manage services provided by the system, and the system itself.
This document describes how to place IBM Connect:Direct under the control of SMF.

Place IBM Connect:Direct under Solaris Service Management

Facility Control
This procedure uses the following sample names and files to describe how to putIBM Connect:Direct
under the control of SMF. Modify the names and files in the table for your implementation.

Note: You need either root access or a user ID with role-based access control (RBAC) authorization to
add and modify SMF services. For additional information, see Implementing Solaris Role-Based Access
Control with SMF for Connect:Direct.

Sample Name File

Service Name connect-direct
Service Manifest /var/svc/manifest/network/connect-direct.xml
Fault Managed Resource Identifier (FMRI) svc:/network/connect-direct:default
Run Script /lib/svc/method/connect-direct
Log File /var/svc/log/network-connect-direct:default.log

Installing and Configuring the SMF Script

Procedure
1. Stop IBM Connect:Direct using the Command Line Interface (CLI). For information, refer to IBM
Connect:Direct for UNIX User Guide.
2. As root, copy the following Bourne shell script file to /lib/svc/method/connect-direct.

© Copyright IBM Corp. 1993, 2018 289

 #!/sbin/sh
#
# /lib/svc/method/connect-direct
#
# For Solaris SMF. This file goes in /lib/svc/method/
# Please set the top three variables before using this script.
# Notes®:The CDunix Admin ID is needed below because SMF scripts are run as root at
# system boot and shutdown. And since the root ID is not in the Connect:Direct
# userfile.cfg, the root ID does not have permission to "stop" C:D.
# We don't want to put the root ID in the userfile.cfg just to get around this.
# So we su to the CDunix Admin ID that installed Connect:Direct, (or su to an
# ID with permissions to stop Connect:Direct). Then issue the Direct CLI
# command to stop the Connect:Direct service.
# Also, a "stop force;" is given in the Connect:Direct CLI in order to have
# Connect:Direct do an immediate clean stop. A simple "stop;" would wait for
# currently running Connect:Direct jobs to complete. However, the OS is not
# going to wait for C:D to complete long running jobs. Instead, after a few
# moments the OS would finally kill the cdpmgr, which is generally not what we
# want. However, using a "stop force;" the cdpmgr will take a checkpoint of
# job progress and cleanly shut down. Then after Connect:Direct restarts it
# will pick up from that last checkpoint.
# For further questions about this script, contact IBM Customer Support.
. /lib/svc/share/smf_include.sh
# Installation path
CDUNIX_HOME=/opt/cdunix
# Name of this Connect:Direct instance.
CDUNIX_NODE_NAME=chicago_CD
# The ID that installed Connect:Direct or an ID with authority to issue
# the "stop" command.
CDUNIX_ADMIN=jsmith

290 IBM Connect:Direct for UNIX: Documentation

 # Do not change the remainder of this file unless you require different behavior.
startup()
{
INITPARM_CONF=${CDUNIX_HOME}/ndm/cfg/${CDUNIX_NODE_NAME}/initparm.cfg
[ ! -f ${INITPARM_CONF} ] && exit $SMF_EXIT_ERR_CONFIG
[ ! -x ${CDUNIX_HOME}/ndm/bin/cdpmgr ] && exit $SMF_EXIT_ERR_PERM
exec ${CDUNIX_HOME}/ndm/bin/cdpmgr -i ${INITPARM_CONF} 2>&1
}
shutdown()
{
[ ! -f ${CDUNIX_HOME}/ndm/cfg/cliapi/ndmapi.cfg ] && \
exit $SMF_EXIT_ERR_CONFIG
# Don't exec this. C:D may already be down. If so, CLI returns 8
# and SMF will then put us in "maintenance" mode.
su ${CDUNIX_ADMIN} -c \
"NDMAPICFG=${CDUNIX_HOME}/ndm/cfg/cliapi/ndmapi.cfg; \
export NDMAPICFG; \
echo 'stop force;' | ${CDUNIX_HOME}/ndm/bin/direct" 2>&1
}
case "$1" in
start)
startup
;;
stop)
shutdown
exit 0
;;
refresh|restart)
shutdown

startup
;;
*)
echo "Usage: $0 {start|stop|restart}"
exit 1
;;
esac

3. To match your installation, edit the following shell variables: CDUNIX-HOME, CDUNIX_NODE_NAME,
and CDUNIX_ADMIN.

Chapter 8. About SMF 291

 4. Verify that the owner and permissions of this script file match those of the other scripts in the /lib/svc/
method directory.
5. To test the /lib/svc/method/connect-direct script:
a) Change to the /lib/svc/method/ directory.
b) As root, start the IBM Connect:Direct service by typing the following command:./connect-
direct start
c) Verify that the IBM Connect:Direct service is running.
d) As root, stop the IBM Connect:Direct service by typing the following command:./connect-direct
stop
e) Verify that the IBM Connect:Direct service stopped.
6. As root, copy the SMF Service Manifest in the following sample to /var/svc/manifest/application/
connect-direct.xml.

292 IBM Connect:Direct for UNIX: Documentation

<?xml version="1.0"?>
<!DOCTYPE service_bundle SYSTEM "/usr/share/lib/xml/dtd/service_bundle.dtd.1">
<!--
Example SMF Service manifest for Connect:Direct for UNIX on Solaris.
-->
<service_bundle type='manifest' name='Connect:Direct'>
<service
name='application/connect-direct'
type='service'
version='1'>
<!--
If we have multiple instances of application/connect-direct provided
by different licensed implementations, we keep dependencies
and methods within the instance.
-->
<instance name='default' enabled='false'>
<!--
Wait for network interfaces to be initialized.
-->
<dependency name='network'
grouping='require_all'
restart_on='error'
type='service'>
<service_fmri value='svc:/milestone/network:default'/>
</dependency>
<!--
Wait for all local filesystems to be mounted.
-->
<dependency name='filesystem-local'
grouping='require_all'
restart_on='none'
type='service'>
<service_fmri
value='svc:/system/filesystem/local:default'/>
</dependency>
<!--
Wait for automounting to be available, as we may be
transfering data from home directories or other remote
filesystems.
-->
<dependency name='autofs'
grouping='optional_all' restart_on='error'
type='service'>
<service_fmri
value='svc:/system/filesystem/autofs:default'/>
</dependency>
<exec_method
type='method'
name='start'
exec='/lib/svc/method/connect-direct start'
timeout_seconds='30' >
<method_context>
<method_credential user='root' group='root' />
</method_context>
</exec_method>
<exec_method
type='method'
name='stop'
exec='/lib/svc/method/connect-direct stop'
timeout_seconds='30' >
<method_context>
<method_credential user='root' group='root' />
</method_context>
</exec_method>

Chapter 8. About SMF 293

 <exec_method
type='method'
name='refresh'
exec='/lib/svc/method/connect-direct restart'
timeout_seconds='45' >
<method_context>
<method_credential user='root' group='root' />
</method_context>
</exec_method>
<property_group name='cdpmgr' type='application'>
<stability value='Evolving' />
</property_group>
<property_group name='startd' type='framework'>
<propval name='ignore_error'
type='astring'
value='core,signal' />
</property_group>
<property_group name='general' type='framework'>
<propval name='action_authorization' type='astring'
value='solaris.smf.manage.connect-direct' />
<propval name='value_authorization' type='astring'
value='solaris.smf.manage.connect-direct' />
</property_group>
</instance>
<stability value='Evolving' />
<template>
<common_name>
<loctext xml:lang='C'>
Connect Direct for UNIX
</loctext>
</common_name>
<documentation>
<doc_link name='ibm.com'
uri='http://www.ibm.com/
support/knowledgecenter/en/SS4PJT/landing/cd_welcome.html'/>
</documentation>
</template>
</service>
</service_bundle>

7. Verify that the owner and permissions of the manifest of the connect-direct.xml file match those of the
other xml files in the /var/svc/manifest/application/ directory.
8. Verify that the Connect:Direct FTP+ service stopped.

Controlling IBM Connect:Direct Using the SMF Script

To place the IBM Connect:Direct service under the control of SMF:

Procedure
1. As root, import the file by typing the following command:
/usr/sbin/svccfg import /var/svc/manifest/application/connect-direct.xml
2. As root, start the IBM Connect:Direct service under SMF control by typing the following command:
svcadm enable connect-direct
Verify the IBM Connect:Direct service is running.
3. To verify IBM Connect:Direct restarts under the control of SMF, type the following command:
svcs -p connect-direct
Observe the Process number in use.
4. Stop the IBM Connect:Direct service by using the Command Line Interface (CLI) method. For
additional information, refer to IBM Connect:Direct User's Guide.
IBM Connect:Direct stops, and immediately restarts under SMF control.
5. To confirm IBM Connect:Direct is under the control of SMF, type the following command:
svcs -p connect-direct

294 IBM Connect:Direct for UNIX: Documentation

 The system generates a Process number different from that observed in step 3.

Implementing Solaris Role-Based Access Control with SMF for IBM

Connect:Direct
Implementing role-based access control (RBAC) is optional. After you place under the control of SMF, only
the root ID or a user ID with RBAC authorization for SMF is authorized to issue the SMF commands to stop
and start IBM Connect:Direct. To authorize additional specific user IDs to stop and start IBM
Connect:Direct, you must implement basic RBAC to grant authority to the user.

Before you begin

Many solutions exist for setting up RBAC on Solaris. If you frequently add users to or remove users from
administration, consider creating role accounts and profiles. For additional RBAC information, see the
Solaris System Administration Guide: Basic Administration and Solaris System Administration Guide:
Advanced Administration. Consider using the following procedure if you enable only a few users.

Procedure
1. Open the file: /etc/security/auth_attr.
2. Add the following line anywhere in the file:
solaris.smf.manage.connect-direct:::Manage Connect Direct Service States::
The corresponding FMRI manifest entry copied to connect-direct.xml eliminates the need to edit the
connect-direct.xml manifest file.
3. As root, type the following command, substituting the user ID you want to authorize for userID:
usermod -A solaris.smf.manage.connect-direct userID
4. If this message appears: usermod: ERROR: userID is not a local user, then do the following:
Open the file: /etc/user_attr.
Add the following line anywhere in the file, substituting the user ID you want to authorize for userID:
userID::::type=normal;auths=solaris.smf.manage.connect-direct
5. If an entry for your user ID already exists in the /etc/user_attr file, merge the entries. You only merge
the auths portion, which is a comma-delimited list of entries found in /etc/security/auth_attr.

Results
The user ID is authorized to control only and can issue commands, including the following:
• svcadm enable connect-direct
• svcadm disable connect-direct
• svcadm refresh connect-direct

Starting and Stopping IBM Connect:Direct under SMF Control

After the IBM Connect:Direct service is under the control of SMF, the service starts when you boot the
Solaris system, and stops when you shut down the Solaris system. Examples are provided of basic SMF
commands to control the IBM Connect:Direct service. For simplicity, the examples use the FMRI shortcut
name connect-direct in place of the full FMRI instance name, svc:application/connect-direct.

Before you begin

If you add service manifest to control IBM Connect:Direct at a later time, use the full FMRI name to avoid
ambiguity. The example commands assume that only one FMRI exists for IBM Connect:Direct on this
system, so the shortcut name is used.

Chapter 8. About SMF 295

 Note: The stop commands issued from the IBM Connect:Direct CLI stop the IBM Connect:Direct service;
however, SMF immediately restarts it. This behavior gives the impression that the stop commands
function improperly. To eliminate confusion when you stop the service, advise IBM Connect:Direct users
of the following SMF control commands: Starting the Connect:Direct Service, and Stopping the
Connect:Direct Service.

Starting the Connect:Direct FTP+ Service

To start the service, as root type the following command:

Before you begin

/usr/sbin/svcadm enable connect-direct
Service starts running, and restarts when the Solaris system boots.

Stopping the IBM Connect:Direct Service

To stop the service, as root type the following command:

Before you begin

/usr/sbin/svcadm disable connect-direct
The service stops, and remains disabled when the Solaris system boots.
After you disable the service, you can stop and start IBM Connect:Direct using the same method used
before IBM Connect:Direct was placed under the control of SMF.

Correcting Errors in the Script or FMRI File

If you modify the SMF script or the FMRI file and errors result, SMF places IBM Connect:Direct into a
maintenance state. Correct the affected script or FMRI file.

Before you begin

To signal to the assigned restarter that the service is repaired, as root type the following command:
/usr/sbin/svcadm clear connect-direct

Removing IBM Connect:Direct from SMF Control

To remove IBM Connect:Direct from SMF control, stop IBM Connect:Direct using the svcadm disable
method:

Procedure
1. As root, type the following command:

/usr/sbin/svccfg delete svc:application/connect-direct:default

2. Delete the following files:

• /var/svc/manifest/network/connect-direct.xml
• /lib/svc/method/connect-direct
For additional information, see Managing Services in the Solaris System Administration Guide:Basic
Administration.

296 IBM Connect:Direct for UNIX: Documentation

Notices
This information was developed for products and services offered in the US. This material might be
available from IBM in other languages. However, you may be required to own a copy of the product or
product version in that language in order to access it.
IBM may not offer the products, services, or features discussed in this document in other countries.
Consult your local IBM representative for information on the products and services currently available in
your area. Any reference to an IBM product, program, or service is not intended to state or imply that only
that IBM product, program, or service may be used. Any functionally equivalent product, program, or
service that does not infringe any IBM intellectual property right may be used instead. However, it is the
user's responsibility to evaluate and verify the operation of any non-IBM product, program, or service.
IBM may have patents or pending patent applications covering subject matter described in this
document. The furnishing of this document does not grant you any license to these patents. You can send
license inquiries, in writing, to:

IBM Director of Licensing

IBM Corporation
North Castle Drive, MD-NC119
Armonk, NY 10504-1785
US

For license inquiries regarding double-byte character set (DBCS) information, contact the IBM Intellectual
Property Department in your country or send inquiries, in writing, to:

Intellectual Property Licensing

Legal and Intellectual Property Law
IBM Japan Ltd.
19-21, Nihonbashi-Hakozakicho, Chuo-ku
Tokyo 103-8510, Japan

INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS PUBLICATION "AS IS"

WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO,
THE IMPLIED WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A
PARTICULAR PURPOSE. Some jurisdictions do not allow disclaimer of express or implied warranties in
certain transactions, therefore, this statement may not apply to you.
This information could include technical inaccuracies or typographical errors. Changes are periodically
made to the information herein; these changes will be incorporated in new editions of the publication.
IBM may make improvements and/or changes in the product(s) and/or the program(s) described in this
publication at any time without notice.
Any references in this information to non-IBM websites are provided for convenience only and do not in
any manner serve as an endorsement of those websites. The materials at those websites are not part of
the materials for this IBM product and use of those websites is at your own risk.
IBM may use or distribute any of the information you provide in any way it believes appropriate without
incurring any obligation to you.
Licensees of this program who wish to have information about it for the purpose of enabling: (i) the
exchange of information between independently created programs and other programs (including this
one) and (ii) the mutual use of the information which has been exchanged, should contact:

IBM Director of Licensing

IBM Corporation
North Castle Drive, MD-NC119
Armonk, NY 10504-1785
US

© Copyright IBM Corp. 1993, 2018 297

 Such information may be available, subject to appropriate terms and conditions, including in some cases,
payment of a fee.
The licensed program described in this document and all licensed material available for it are provided by
IBM under terms of the IBM Customer Agreement, IBM International Program License Agreement or any
equivalent agreement between us.
The performance data and client examples cited are presented for illustrative purposes only. Actual
performance results may vary depending on specific configurations and operating conditions.
Information concerning non-IBM products was obtained from the suppliers of those products, their
published announcements or other publicly available sources. IBM has not tested those products and
cannot confirm the accuracy of performance, compatibility or any other claims related to non-
IBMproducts. Questions on the capabilities of non-IBM products should be addressed to the suppliers of
those products.
Statements regarding IBM's future direction or intent are subject to change or withdrawal without notice,
and represent goals and objectives only.
All IBM prices shown are IBM's suggested retail prices, are current and are subject to change without
notice. Dealer prices may vary.
This information is for planning purposes only. The information herein is subject to change before the
products described become available.
This information contains examples of data and reports used in daily business operations. To illustrate
them as completely as possible, the examples include the names of individuals, companies, brands, and
products. All of these names are fictitious and any similarity to actual people or business enterprises is
entirely coincidental.
COPYRIGHT LICENSE:
This information contains sample application programs in source language, which illustrate programming
techniques on various operating platforms. You may copy, modify, and distribute these sample programs
in any form without payment to IBM, for the purposes of developing, using, marketing or distributing
application programs conforming to the application programming interface for the operating platform for
which the sample programs are written. These examples have not been thoroughly tested under all
conditions. IBM, therefore, cannot guarantee or imply reliability, serviceability, or function of these
programs. The sample programs are provided "AS IS", without warranty of any kind. IBM shall not be
liable for any damages arising out of your use of the sample programs.
Each copy or any portion of these sample programs or any derivative work must include a copyright notice
as shown in the next column.
© 2015.
Portions of this code are derived from IBM Corp. Sample Programs.
© Copyright IBM Corp. 2015.

Trademarks
IBM, the IBM logo, and ibm.com are trademarks or registered trademarks of International Business
Machines Corp., registered in many jurisdictions worldwide. Other product and service names might be
trademarks of IBM or other companies. A current list of IBM trademarks is available on the web at
"Copyright and trademark information" at www.ibm.com/legal/copytrade.shtml.
Adobe, the Adobe logo, PostScript, and the PostScript logo are either registered trademarks or
trademarks of Adobe Systems Incorporated in the United States, and/or other countries.
IT Infrastructure Library is a registered trademark of the Central Computer and Telecommunications
Agency which is now part of the Office of Government Commerce.
Intel, Intel logo, Intel Inside, Intel Inside logo, Intel Centrino, Intel Centrino logo, Celeron, Intel Xeon,
Intel SpeedStep, Itanium, and Pentium are trademarks or registered trademarks of Intel Corporation or
its subsidiaries in the United States and other countries.

298 Notices
 Linux is a registered trademark of Linus Torvalds in the United States, other countries, or both.
Microsoft, Windows, Windows NT, and the Windows logo are trademarks of Microsoft Corporation in the
United States, other countries, or both.
ITIL is a registered trademark, and a registered community trademark of the Office of Government
Commerce, and is registered in the U.S. Patent and Trademark Office.
UNIX is a registered trademark of The Open Group in the United States and other countries.
Java and all Java-based trademarks and logos are trademarks or registered trademarks of Oracle and/or
its affiliates.
Cell Broadband Engine is a trademark of Sony Computer Entertainment, Inc. in the United States, other
countries, or both and is used under license therefrom.
Linear Tape-Open, LTO, the LTO Logo, Ultrium and the Ultrium Logo are trademarks of HP, IBM Corp. and
Quantum in the U.S. and other countries.
Connect Control Center®, Connect:Direct®, Connect:Enterprise®, Gentran®, Gentran®:Basic®,
Gentran:Control®, Gentran:Director®, Gentran:Plus®, Gentran:Realtime®, Gentran:Server®,
Gentran:Viewpoint®, Commerce™, Information Broker®, and Integrator® are trademarks, Inc., an IBM
Company.
Other company, product, and service names may be trademarks or service marks of others.

Terms and conditions for product documentation

Permissions for the use of these publications are granted subject to the following terms and conditions.

Applicability
These terms and conditions are in addition to any terms of use for the IBM website.

Personal use
You may reproduce these publications for your personal, noncommercial use provided that all proprietary
notices are preserved. You may not distribute, display or make derivative work of these publications, or
any portion thereof, without the express consent of IBM.

Commercial use
You may reproduce, distribute and display these publications solely within your enterprise provided that
all proprietary notices are preserved. You may not make derivative works of these publications, or
reproduce, distribute or display these publications or any portion thereof outside your enterprise, without
the express consent of IBM.

Rights
Except as expressly granted in this permission, no other permissions, licenses or rights are granted, either
express or implied, to the publications or any information, data, software or other intellectual property
contained therein.
IBM reserves the right to withdraw the permissions granted herein whenever, in its discretion, the use of
the publications is detrimental to its interest or, as determined by IBM, the above instructions are not
being properly followed.
You may not download, export or re-export this information except in full compliance with all applicable
laws and regulations, including all United States export laws and regulations.
IBM MAKES NO GUARANTEE ABOUT THE CONTENT OF THESE PUBLICATIONS. THE PUBLICATIONS ARE
PROVIDED "AS-IS" AND WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED,

Notices 299
 INCLUDING BUT NOT LIMITED TO IMPLIED WARRANTIES OF MERCHANTABILITY, NON-INFRINGEMENT,
AND FITNESS FOR A PARTICULAR PURPOSE.

300 IBM Connect:Direct for UNIX: Documentation

IBM®

Part Number:
Product Number: 5655-X01

(1P) P/N: