Sterling Connect:Direct for UNIX 4.2.0
Documentation
Version 4.2.0
IBM
Sterling Connect:Direct for UNIX 4.2.0
Documentation
Version 4.2.0
IBM
This edition applies to Version 5 Release 2 of IBM Sterling Connect:Direct and to all subsequent releases and
modifications until otherwise indicated in new editions.
© Copyright IBM Corporation 1993, 2016.
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...... 4
Supported Interfaces............ 6
Support Requests Resolved for This Release .... 6
Known Restrictions............ 22
Upgrade Considerations .......... 23
Upgrading Sterling Connect:Direct File Agent on
AIX ................. 24
Special Considerations........... 24
Special Considerations for Using Sterling File
Accelerator (UDT) ........... 24
Special Considerations for Connectivity with the
HP NonStop Kernel Operating System .... 25
Special Considerations for Using Sterling
Connect:Direct for UNIX in FIPS 140-2 Mode .. 25
Sterling Connect:Direct for UNIX Guidelines ... 26
Password Storage ............ 26
Libraries to Install ............ 26
Chapter 2. Sterling Connect:Direct for
UNIX Overview ........... 29
Sterling Connect:Direct for UNIX Overview ... 29
Process Manager ........... 29
Command Manager .......... 30
Session Manager............ 30
User Authorization ........... 30
Process Restart ............ 31
Archive Statistics Files .......... 32
Sample Processes, Shell Scripts, and API
Programs .............. 32
Sterling Connect:Direct for UNIX Configuration
Files ................ 33
Sterling Connect:Direct for UNIX Directory
Structure .............. 34
Installing Sterling Connect:Direct for UNIX .... 34
Preparing to Install Sterling Connect:Direct for
UNIX in a Cluster Environment ...... 35
Conventions to Observe When Installing Sterling
Connect:Direct for UNIX ......... 38
Worksheet Instructions ......... 38
Installing Sterling Connect:Direct ...... 45
Customizing Sterling Connect:Direct for UNIX . 46
Setting Up the Sterling Connect:Direct for UNIX
Server ............... 47
Setting Up the Sterling Connect:Direct for UNIX
Client ............... 49
Installing Sterling Connect:Direct File Agent .. 51
Installing Sterling Connect:Direct Secure Plus .. 52
SNA Support for Sterling Connect:Direct for
UNIX ............... 54
Defining High-Availability Settings in the
Configuration Files ........... 54
Setting Up Additional Configuration
Requirements for IBM HACMP....... 55
Setting Up Additional Configuration
Requirements for Hewlett-Packard
MC/ServiceGuard ........... 56
Verifying the Installation ......... 56
Sterling Connect:Direct File Agent Overview ... 57
Sterling Connect:Direct File Agent Operation .. 59
Sterling Connect:Direct File Agent Logging
Capabilities ............. 59
Sterling Connect:Direct File Agent Configuration
Interface and Help ........... 60
Planning the Sterling Connect:Direct File Agent
Configuration ............ 60
IBM Sterling Connect:Direct Worksheet .... 60
IBM Sterling Connect:Direct File Agent
Configuration Examples ......... 62
About SNA LU6.2 Connections ........ 64
AIX SNA Server Configuration ....... 66
HP SNAplus2 Configuration Requirements ... 68
SNAP-IX SNA Gateway Support Configuration
Requirements............. 69
Brixton 4.1 SNA for Sun Solaris Requirements .. 71
Configuring SunLink SNA 9.1 Support for Sun
Solaris ............... 75
Sample z/OS Definitions for an LU6.2
Connection ............. 76
Special Considerations When Configuring LU6.2 80
Setting Up Sterling Connect:Direct for UNIX Manual
Pages ................ 82
Accessing Sterling Connect:Direct Manual Pages 82
Chapter 3. Administration Guide.... 85
Maintaining configuration files ........ 85
Modifying configuration files ....... 86
Maintaining the initialization parameters file ... 86
Contents of the initialization parameters file .. 87
Updating records ........... 88
Firewall navigation record ........ 98
Maintaining the client configuration file ..... 99
Contents of the client configuration file.... 100
Maintaining the network map file ...... 101
Contents of the network map file...... 101
Local node connection record ....... 102
TCP/IP Default Record ......... 107
Remote Node Connection Record...... 109
Maintaining access information files ...... 112
User Authorization Information File ..... 112
Strong Access Control File ........ 120
Automatic Detection of Shadow Passwords .. 121
Limiting Access to the Program Directory ... 121
Security Exit............. 122
Maintaining client and server authentication key
files ................ 122
Key File Format ........... 122
Key File Parameters .......... 122
Sample Client Authentication Key File .... 123
© Copyright IBM Corp. 1993, 2016 iii
Authentication Process ......... 123
Firewall Navigation .......... 125
Firewall Configuration Examples ...... 126
Session Establishment ......... 128
Specifying connection information ...... 128
IP Addresses ............ 128
Host Names ............. 129
Port Numbers ............ 130
Multiple Addresses, Host Names, and Ports .. 130
About Using Masks for IP Address Ranges .. 130
Using Sterling Connect:Direct in a test mode ... 131
Processing Flow of the Test Mode ..... 131
Preparing the NDMPXTBL Parameter Table .. 132
Sample Test Scenarios ......... 134
Chapter 4. User Guide ....... 137
Controlling and Monitoring Processes ..... 137
Starting the CLI ........... 137
Stopping the CLI ........... 137
CLI Commands ........... 137
CLI Job Control ........... 139
CLI History Commands ......... 140
Overview of Sterling Connect:Direct Commands 140
Submitting a Process .......... 142
Changing Process Parameters ....... 149
Deleting a Process from the TCQ ...... 151
Removing a Process from the Execution Queue 153
Stopping Sterling Connect:Direct ...... 154
Viewing a Process in the TCQ ....... 155
Monitoring Process Status in the TCQ .... 158
Determining the Outcome of a Process .... 162
Generating a Detailed Output Report for a
Process .............. 170
Generating a Summary Report for a Process .. 170
Running System Diagnostics ....... 171
Process Queuing ............ 174
Scheduling Sterling Connect:Direct Activity .. 174
Progression of a Process Through the TCQ .. 175
Sterling Connect:Direct Utilities ....... 179
Creating a Translation Table ....... 179
Compiling a Translation Table Using the ndmxlt
Utility ............... 180
Example—Creating a Translation Table .... 181
Example—Modifying a Model Translation Table 182
Using Translation During File Transfer
Operations ............. 182
Translation Table Error Messages ...... 182
Accessing Sterling Connect:Direct Messages .. 183
Precompressing/Decompressing Files Using the
Standalone Batch Compression Utility .... 184
Validate Configuration Files ....... 189
Configuration Reports ......... 190
Writing Custom Programs ......... 194
Compiling Custom Programs ....... 194
Writing Custom C Programs ....... 196
Writing Custom C++ Programs ...... 205
Writing User Exits ............ 209
User Exit Functions .......... 210
Overview of User Exit Messages ...... 213
Exit Log Files ............ 216
Chapter 5. Using FASP with IBM
Aspera High-Speed Add-on for
Sterling Connect:Direct for UNIX
(V4.2.0.3 or later) .......... 219
Activating FASP ............ 219
Licensed bandwidth for FASP transactions ... 219
FASP Process Language .......... 220
Using Sterling Connect:Direct for UNIX with IBM
Aspera High-Speed Add-on and Sterling Secure
Proxy (V4.2.0.4 or later) .......... 221
Configuring FASP ............ 223
FASP Messages............. 227
Monitoring FASP transactions ........ 228
Limitations .............. 229
Chapter 6. Introduction to Sterling
Connect:Direct Secure Plus for UNIX . 231
Introduction to Sterling Connect:Direct Secure Plus
for UNIX ............... 231
Security Concepts ........... 231
Security Features ........... 231
Secure Plus UNIX Video Tutorials ..... 232
Protocol Support ........... 232
Sterling Connect:Direct Secure Plus Tools ... 233
Before You Begin ........... 235
Plan Your Implementation of the SSL or TLS
Protocol ............... 236
Overview of the TLS Protocol and the SSL
Protocol .............. 236
Self-Signed and CA-Signed Certificates .... 237
Set Up Sterling Connect:Direct Secure Plus ... 239
Install Sterling Connect:Direct Secure Plus... 240
Starting the Secure+ Admin Tool ...... 240
Populating the Secure+ Parameters File.... 241
Node Configuration Overview ....... 241
Import Existing Certificates........ 242
Create CMS Key Store ......... 243
Configuring the Sterling Connect:Direct Secure
Plus .Local Node Record ........ 244
Customize Remote Node Records ..... 246
Configuring a Remote Node Record ..... 246
Validating the Configuration ....... 248
Configure Strong Password Encryption.... 249
Automate Setup with the Secure+ CLI ..... 250
Start and Set Up the Secure+ CLI...... 250
Encrypt Passwords to Use with the Secure+ CLI 251
Sample Script ............ 251
Maintain the Secure+ Parameters File .... 252
Manage CMS Keystore ......... 254
Update the .Local Node Record ...... 255
Manage Remote Node Records ...... 256
Update the .Client Node Record ...... 260
Maintain the Sterling External Authentication
Server Record ............ 261
Strong Password Encryption ....... 261
Displaying the Sterling Connect:Direct Node
Information .............. 262
Node List Field Descriptions ....... 262
Viewing Node Record Change History .... 263
iv Sterling Connect:Direct for UNIX 4.2.0: Documentation
Viewing Information about the Secure+
Parameters File............ 263
Modify a Sterling Connect:Direct Secure Plus
Configuration ............ 263
Sterling Connect:Direct Secure Plus Statistics
Record Information ........... 265
Sterling Connect:Direct CLI Select Statistics
Detail ............... 266
Session Start (SSTR) Record ....... 266
Copy Termination (CTRC) Record ..... 267
Secure+ Parameters File Auditing ...... 267
Access Secure+ Parameters File Audit Logs .. 268
Secure+ Parameters File Audit Log Entries .. 268
Sterling Connect:Direct Secure Plus Certificate
Auditing .............. 269
Sterling Connect:Direct Secure Plus
Troubleshooting ............ 271
Configuration Worksheets ......... 274
Local Node Security Feature Definition
Worksheet ............. 274
Remote Node Security Feature Definition
Worksheet ............. 274
Certificate Files............. 275
Formats .............. 276
Sample Certificate Files ......... 277
Model Automation Scripts ......... 278
Configure Sterling Connect:Direct Secure Plus to
Use the SSL or TLS Protocol ....... 278
Encrypt Passwords for use with CLI...... 280
Chapter 7. About SMF........ 281
Place Sterling Connect:Direct under Solaris Service
Management Facility Control ........ 281
Installing and Configuring the SMF Script.... 281
Controlling Sterling Connect:Direct Using the SMF
Script ................ 286
Implementing Solaris Role-Based Access Control
with SMF for Sterling Connect:Direct ..... 287
Starting and Stopping Sterling Connect:Direct
under SMF Control ........... 288
Starting the Sterling Connect:Direct FTP+
Service .............. 288
Stopping the Sterling Connect:Direct Service .. 288
Correcting Errors in the Script or FMRI File ... 288
Removing Sterling Connect:Direct from SMF
Control ............... 289
Notices .............. 291
Trademarks .............. 293
Terms and conditions for product documentation 294
Contents v
vi Sterling Connect:Direct for UNIX 4.2.0: Documentation
Chapter 1. Release Notes
The IBM
®
Sterling Connect:Direct
®
for UNIX Release Notes document supplements
Sterling 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
Sterling Connect:Direct for UNIX.
New Features and Enhancements
Sterling Connect:Direct for UNIX 4.2 and its related software have the following
features and enhancements:
Fix Pack 4 (V4.2.0.4 iFix 013)
New Feature or Enhancement
Sterling Connect:Direct for UNIX now offers high-speed bridging support through Sterling
Secure Proxy which allows IBM High-Speed Add-on for Connect:Direct to be used between
nodes with native FASP support (Linux, AIX, and Windows) and nodes without native
FASP support (currently z/OS and zLinux). When using Sterling Secure Proxy between
Connect:Direct nodes, IBM High-Speed Add-on for Connect:Direct can be used on the
external leg of a transmission while the internal leg uses TCP/IP. This offers multiple
implementation options to deploy IBM High-Speed Add-on for Connect:Direct to your
enterprise allowing Connect:Direct for Unix, Windows, zLinux, and z/OS to all gain the
performance benefits of FASP. This new feature includes some changes in the FASP
parameter options. See Using FASP with IBM Aspera High-Speed Add-on for Sterling
Connect:Direct for UNIX for more information.
Adds support for SHA2 Private Key encryption.
Fix Pack 4 (V4.2.0.4)
New Feature or Enhancement
IBM
®
Aspera
®
High Speed Add-on for Sterling Connect:Direct
®
uses FASP(TM) (Fast and
Secure Protocol) network transport to transfer files over high bandwidth and high latency
network connections. FASP support has been added for interoperability with Sterling
Connect:Direct for Microsoft Windows (V4.7.0.4 or later) and Sterling Secure Proxy
(V3.4.3.0 or later).
Fix Pack 3 (V4.2.0.3)
© Copyright IBM Corp. 1993, 2016 1
New Feature or Enhancement
Support for FASP (Fast and Secure Protocol) has been added. FASP is supported on Linux
and AIX platforms only. See the Sterling Connect:Direct for UNIX Hardware and Software
Requirements for specific information regrading support for FASP.
FASP requires a license key for use. Download the license key from Passport Advantage
when you download the fix pack.
Note: If you previously downloaded a licence key for UNIX V4.2.0, Fix Pack 2, you must
download the new license key for Fix Pack 3 to continue using FASP. Your old license key
will not work with the new fix pack.
Important: If you are installing Sterling Connect:Direct for UNIX V4.2.0.3 using the Silent
Install method, you must also update the options file with the following parameter to
support FASP: cdai_asperaLicenseFile=<path to aspera license>
Base Release (V4.2.0)
New Feature or Enhancement
Addition of NIST SP800-131a and Suite B support for Sterling Connect:Direct Unix and
Windows platforms
Support for TLS 1.1/1.2 for Sterling Connect:Direct Unix and Windows platforms.
Support for zFBA parameter to enhance performance of large file transfers between z/OS
and AIX.
Provides silent installation capability for Sterling Connect:Direct for UNIX. For more
information, refer to the IBM Sterling Connect:Direct Enterprise Deployment Guide.
Adds support for block mode file transfer. In this mode, Sterling Connect:Direct uses the
file block as the data unit to improve performance. Sterling Connect:Direct for UNIX
supports block mode file transfer when the following conditions exist:
v Remote node supports block mode (Sterling Connect:Direct for z/OS
®
only)
v Source and destination files have like characteristics
v Files are supported file types
The ndm.env_vars:sanitize initialization parameter adds a user option to prevent the
cdpmgr from sanitizing inherited environment variables. Valid values are y (yes) and n
(no). Default value is y.
Attention: The initialization parameter is added for convenience. IBM recommends
coding run task steps that do not rely on inherited environment variables.
Provides new copy step sysopt, RECDL, to specify a non-standard record delimiter for
source and destination text files. The RECDL sysopt is specified as x<hex value of record
delimiter>. For example, if the source file is EBCDIC and uses the EBCDIC NL (new line
character) as the record delimiter, the source file sysopts would include :RECDL=x15:.
Provides new fsync.after.receive initialization parameter that calls the fsync function to
flush all data to disk before you close the file. Files that are written and closed by Sterling
Connect:Direct on an NFS destination might not be immediately ready for processing
because of NFS-delayed writes. The fsync.after.receive initialization parameter is part of the
copy.parms record of the initparm.cfg file. Valid values are y (yes) to call fsync before you
close a data file that was received, and n (no). Default value is n.
2 Sterling Connect:Direct for UNIX 4.2.0: Documentation
New Feature or Enhancement
Provides outgoing Process netmap checking capability. The netmap.check parameter values
now include the following settings:
v Y - Checks the network map for all nodes that Sterling Connect:Direct communicates
with to validate the node name and IP address.
Attention: This is an expanded definition to the previous meaning of Y for this
parameter.
v L - Checks the network map only for nodes that the local Sterling Connect:Direct
initiates sessions with to validate the node name and IP address.
v R - Checks the network map only for remote nodes that communicate with the local
node to validate the node name and IP address.
v N - Does not validate any session establishment requests in the network map.
Provides new daily keyword that, when specified with an elapsed time in the startt
parameter of a submit command, schedules the Process for the next day at the specified
time.
Applied removal of STS support for Sterling Connect:Direct for Unix and Windows.
Provides for automated deployment of Sterling Connect:Direct for UNIX across the
enterprise with enterprise deployment tools such as IBM Tivoli
®
Endpoint Manager. For
more information, refer to the IBM Sterling Connect:Direct Enterprise Deployment Guide.
Features removed from this release
v Removed support for Sterling Certificate Wizard. You should start using IBM
iKeyman instead, which is located in the bin directory of the JRE bundled with
Sterling Connect:Direct for UNIX. For information on how to use iKeyman, see
iKeyman Overview.
v The Station-to-Station (STS) protocol is a cryptographic key agreement scheme
based on classic Diffie- Hellman that provides mutual key and entity
authentication. IBM is ending support for the STS (Station-to-Station) protocol in
the Connect:Direct family of products beginning with version 5.2 for z/OS and
Distributed Platforms. This corresponds to Connect:Direct Windows 4.7,
Connect:Direct Unix 4.2, and Connect:Direct i5/OS 3.8.
Why is STS being removed?
As computing power increases many security standards are moving towards
stronger encryption. STS does not support the strongest encryption algorithms.
The closed nature of the standard prevents the addition of stronger encryption,
and puts IBM at risk if any vulnerabilities are found in the future. In a risk
situation, IBM would be unable to take corrective action and still support STS.
What are the alternatives?
The Connect:Direct family currently supports several alternatives to STS. In
addition, Connect:Direct 5.2 (this release) brings new support for TLS 1.1/1.2,
FIPS suite B, and several other major encryption and security features.
If you require the STS protocol, you must remain on the most recent release
according to the following table. End of support has not been determined for
these versions and customers will be given with a minimum one year notice.
Operating System Last Version with STS Support
z/OS 5.1.1
Windows 4.6.1
UNIX 4.1
i5/OS 3.7
Chapter 1. Release Notes 3
Hardware and Software Requirements
IBM
®
Sterling Connect:Direct
®
for UNIX and its related software require the
following hardware and software: It supports systems running in 32- or 64-bit
mode.
Component
or
Functionality Hardware Software RAM (min.)
Disk Space
(min.)
Sterling
Connect:Direct
for UNIX
with TCP/IP,
Sterling File
Accelerator,
or (V4.2.0, Fix
Pack 3 and
higher) FASP
connectivity
HP PA-RISC HP-UX version 11iv2
September 2004 Update or
higher or 11iv3
Note: Not supported with
FASP.
2 GB 50 MB
HP Integrity
system with
Intel Itanium
processor
HP-UX version 11iv2
September 2004 Update or
higher or 11iv3
Note: Not supported with
FASP.
2 GB 50 MB
IBM System
pSeries
AIX versions 6.1 and 7.1. 2 GB 50 MB
Sun SPARC
system
Solaris version 10, update to
level 11 (Jan 2013) or higher,
and Solaris 11.
Note: Not supported with
FASP.
2 GB 50 MB
Intel and
AMD
x86/x86-64
Solaris version 10, update to
level 10 (Aug 2011) or
higher, and Solaris 11.
Note: Not supported with
FASP.
2 GB 50 MB
Any point release of Red
Hat Enterprise Linux
version 5, 6, or (V4.2.0, Fix
Pack 3 or later) 7.
2 GB 50 MB
SuSE SLES version 10 SP4
or greater (
Note: Not supported with
FASP.
2 GB 50 MB
SuSE SLES version 11 2 GB 50 MB
SuSE SLES version 12
(Sterling Connect:Direct
®
for
UNIX V4.2.0.2 or later)
2 GB 50 MB
4 Sterling Connect:Direct for UNIX 4.2.0: Documentation
Component
or
Functionality Hardware Software RAM (min.)
Disk Space
(min.)
Linux zSeries Any point release of Red
Hat Enterprise Linux
version 5, 6, or (V4.2.0, Fix
Pack 3 or later) 7.
2 GB 50 MB
SuSE SLES version 10 SP4
or greater
Note: Not supported with
FASP.
2 GB 50 MB
SuSE SLES version 11
Note: Not supported with
FASP.
2 GB 50 MB
SuSE SLES version 12
(Sterling Connect:Direct
®
for
UNIX V4.2.0.2 and higher)
Note: Not supported with
FASP.
2 GB 50 MB
Sterling
Connect:Direct
File Agent
Same as
requirements
for Sterling
Connect:Direct
for UNIX
Same as requirements for
Sterling Connect:Direct for
UNIX
Java
™
Standard Edition 6,
installed with Sterling
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
7 before you install Sterling
Connect:Direct File Agent.
2 GB 275 MB
Sterling
Connect:Direct
Secure Plus
Same as
requirements
for Sterling
Connect:Direct
for UNIX.
Same as requirements for
Sterling Connect:Direct
Secure Plus.
Java Standard Edition 7,
installed with Sterling
Connect:Direct Secure Plus.
2 GB 70 MB
High-
Availability
support
HP PA-RISC HP MC/Service Guard
IBM System
pSeries
IBM HACMP
™
Sun SPARC
system
SunCluster 2.2, 3.0 or 3.2
SNA
connectivity
IBM System
pSeries
Install and configure
Communications Server for
AIX
®
V6.
HP PA-RISC For HP-UX 11i, you must
install and configure both of
the following
v SNAplus2 Link version
R7
v SNAplus2API version R7
Chapter 1. Release Notes 5
Component
or
Functionality Hardware Software RAM (min.)
Disk Space
(min.)
Sun SPARC
systems
Install and configure
SNAP-IX Gateware software
DATA Connection Limited
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:
v 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.
v 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.
v 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.
Supported Interfaces
Sterling Connect:Direct for UNIX supports the following interfaces:
v Ethernet
v SDLC
v X.25 (QLLC)
Support Requests Resolved for This Release
Version 4.2.0.3
APAR IT04683
In some circumstances, CDU will mistake a new incoming process for a
restarted process, generating an XSMG251I message and process failure.
APAR IT05409
In some circumstances, CDU will inappropriately synchronize a new
incoming run task process with a previously interrupted run task process,
and immediately return the status of the interrupted process with an
XSMG417I message instead of running the new task.
APAR IT04686
When C:D is doing work, temporary files are created in the {C:D UNIX
6 Sterling Connect:Direct for UNIX 4.2.0: Documentation
installation directory}/work/{C:D UNIX node name} directory. After
certain error scenarios, some of these temporary files are not removed.
APAR IT06191
CVE-2014-8730, a Transport Layer Security (TLS) padding vulnerability via
a POODLE (Padding Oracle On Downgraded Legacy Encryption) like
attack, affects Sterling Connect:Direct for UNIX.
APAR IT06994
FASP transfers use port 33001 on the snode side, no matter which fasp
record listen ports are configured in the snode initparm.cfg file.
APAR IT06869
A client which has submitted a maxdelay process that lasts longer than one
minute may get an error return code with message XCMM044I returned
after exactly one minute.
APAR IT02062
The first several characters of the file name specification are cut off when
received by 64 bit File Open Exits on Linux or Solaris x86 platforms.
Important: All File Open Exits, including 32 bit versions, must be
recompiled after applying this fix.
RTC456414
Added a PMR Stamper and Data Collector utility, which automates
gathering diagnostic information about Connect:Direct for UNIX and
optionally sends it to IBM Support. Execute "{C:D UNIX installation
directory}/etc/CD_Data_Collector --help" to see usage details.
APAR IT07136
Automated upgrade to C:D UNIX 4.2.0 from versions previous to 4.2.0 fails
with error message CDAI015E.
APAR IT03077
An upgrade command performed by the automated installation script
(cdinstall_a) will fail if pre-existing configuration files don't pass the
configuration check, or if the sample.cd process fails to complete
successfully, even when the configuration errors or sample.cd operation
failure is considered tolerable. Fix adds a variable to cdinstall_a called
cdai_verifyUpgrade. This variable allows users to choose whether to verify
an upgrade or not. Valid values are "y" (the default) and "n".
APAR IT07339
A wildcard copy with the source specification on AIX may occasionally fail
to find any files matching the wildcard pattern when matching files in fact
exist.
APAR IT07359
CDU 4.2.0 automated installation script (cdinstall_a) doesn't process the
cdai_localCertFile parameter or other certificates located in the deployment
directory.
APAR IT03078
The automated installation script, cdinstall_a, doesn't provide an option to
deploy a custom keystore file or a custom label for the deployed keycert
file.
Chapter 1. Release Notes 7
Fix adds and describes three new optional variables, cdai_keystoreFile,
cdai_keystorePassword, and cdai_localCertLabel, that allow users to deploy
a custom keystore file and specify the keycert label to be used in basic
Secure+ configurations.
If cdai_keystoreFile and cdai_keystorePassword are specified, then the
automated installation will use this file as the keystore file. If they are not
specified, then the automated installation procedure will use the default
keystore file that is created during the installation. In either case, the
keystore file will be customized by adding the certificate portion of the
deployed keycert file and any other deployed certificates to it.
If cdai_localCertLabel is specified, the specification will be used to label the
keycert for use in basic Secure+ configurations. If it is not specified, a
default label will be used.
APAR IT02518
An XPAE003I message is generated for a select statistics command issued
with a destfile or srcfile parameter value enclosed in double quotes, which
are required if the value contains spaces, equal signs or other reserved
characters.
APAR IT03227
The fsync.after.receive initparm option, used to make sure files written and
closed by C:D on an NFS destination are immediately ready for processing,
doesn't detect when the NFS resource is out of space. Note, the fix for this
issue changes the fsync.after.receive default value to "Y".
APAR IT07855
When a very old version of Global Security Kit Version 8 (GSKit 8) is
installed globally on a system, C:D UNIX 4.2.0 installations may fail,
producing a Java core dump and reporting that "The Initialize Secure+
operation failed." If upgrading from a previous version of C:D UNIX, the
Java core dump will be followed by a message reporting that "The ReKey
Parmfile Secure+ operation failed."
APAR IT07894
Connect:Direct for UNIX Secure+ Option uses IBM Java Runtime, which is
vulnerable to the following issues:
v CVE-2014-3065: IBM Java SDK contains a vulnerability in which the
default configuration for the shared classes feature potentially allows
arbitrary code to be injected into the shared classes cache, which may
subsequently be executed by other local users.
v CVE-2014-6468: An unspecified vulnerability related to the Hotspot
component has complete confidentiality impact, complete integrity
impact, and complete availability impact.
APAR IT07931
Connect:Direct for UNIX Secure+ Option uses GSKit, which is vulnerable
to the following issues:
v CVE-2015-0138: A vulnerability in various IBM SSL/TLS
implementations could allow a remote attacker to downgrade the
security of certain SSL/TLS connections. An IBM SSL/TLS client
implementation could accept the use of an RSA temporary key in a
non-export RSA key exchange ciphersuite. This could allow a remote
attacker using man-in-the-middle techniques to facilitate brute-force
decryption of TLS/SSL traffic between vulnerable clients and servers.
This vulnerability is also known as the FREAK attack.
8 Sterling Connect:Direct for UNIX 4.2.0: Documentation
v CVE-2015-0159: An unspecified error in GSKit usage of OpenSSL crypto
function related to the production of incorrect results on some platforms
by Bignum squaring (BN_sqr) has an unknown attack vector and impact
in some ECC operations.
APAR IT08220
In the copy termination statistics record, process name, process number
and snode name fields are duplicated.
APAR IT08276
CBC ciphers are vulnerable to CVE-2011-3389 (BEAST Attack). Previous
recommendation to mitigate CVE-2011-3389 was to not use CBC ciphers.
RC4 ciphers are vulnerable to CVE-2015-2808 (Bar Mitzvah Attack).
Current recommendation to mitigate CVE-2015-2808 is to discontinue use
of RC4 ciphers. However, the remaining available ciphers are generally
CBC ciphers. Accordingly, code is fixed to mitigate CVE-2011-3389.
Note: Connect:Direct for UNIX by default disables the RC4 stream cipher.
If you enabled the RC4 stream cipher you are exposed to the RC4 "Bar
Mitzvah" Attack for SSL/TLS. IBM recommends that you review your
entire environment to identify other areas where you have enabled the RC4
stream cipher and take appropriate mitigation and remediation actions.
APAR IT08514
After upgrading to C:D UNIX 4.2.0 from a previous version, some clients,
such as Sterling Control Center or Sterling Connect:Direct Browser, may
generate errors processing a select statistics command. Possible errors
include "CCTR035E Failed to connect to server" or "KQVString.parse()
detected data problem...."
APAR IT08958
After a system reboot, cdpmgr may fail to start, reporting XPMD006I
message.
APAR IT08954
CDU nodes configured to run behind a load balancer will have the same
node name. When these nodes act as pnodes and initiate processes to the
same snode at the same time, it's possible that the snode will not be able to
distinguish between the processes, generating XLKL004I messages and
possibly corrupting the TCQ. Fix adds a new parameter to the ndm.node
initparm record called instance.id. The parameter value is initialized with a
universally unique identifier (UUID).
APAR IT08385
cdver executed without argument may not display the product version.
Issue may also manifest during installation or upgrade procedures as
"unary operator expected" errors.
APAR IT09564
Connect:Direct for UNIX Secure+ and File Agent Options use IBM Java
Runtime, which is vulnerable to the following issue on HP-UX and Solaris
platforms:
CVE-2015-0383: An unspecified vulnerability in Oracle Java SE and JRockit
related to the Hotspot component has no confidentiality impact, partial
integrity impact, and complete availability impact.
APAR IT09904
cdpmgr may occasionally crash. When this happens on AIX 6.1, if cdpmgr
was configured with the SUID bit turned off, a core dump will be
Chapter 1. Release Notes 9
generated and the errpt command will show cdpmgr crashed with a signal
4 or sometimes signal 11. The crash is more likely when cdpmgr is idle. A
possible symptom of the issue is the Session Count statistics records
(RECI=SCNT) logged with either negative or unrealistically large positive
values indicated.
APAR IT10090
Connect:Direct for UNIX did not report snodeid value utilized.
APAR IT10120
A process copy step sending to an invalid destination, such as a
nonexistent path, will log an XCPS003I on the source side and then
XIPT016I and go into TIMER/RETRY. On the destination side, an
XCPR010I is logged and then "SMGR terminated by signal 11".
APAR IT10377
Connect:Direct for UNIX Secure+ will fail to send data when the
negotiated RU size is less than 16K on systems that use the SSL BEAST
mitigation. The error is "The SSL library failed, reason=SSL_write failed
Message ID CSPA309E". The issue occurs between nodes where an older
version of Secure+ is used, that does not support buffer sizes larger than
16K for SSL sessions.
APAR IT10717
Connect:Direct API commands over a secure connection fail after
upgrading the JRE in Connect:Direct Browser, Sterling Control Center or
other application using the Application Interface for Java (AIJ).
APAR IT04205
On occasion, the statistics archive utility won't run on a day when it
should run, causing two days worth of statistics log files to be contained in
the archive file when it runs the next day.
APAR IT10817
Copy receive performance from C:D Z/OS can be degraded when the
UNIX destination file sysopts includes "datatype=binary", and the Z/OS
source file record format is VB or FB.
APAR IT06148
A fresh C:D install will include the unused "syslog.logd" initparm.
APAR IT06145
Under specific stress situations, "direct" will trigger a segmentation fault.
Version 4.2.0.2
APAR IT02517
cdpmgr fails to start, reporting "Secure+ library installation corrupted",
after upgrading from a previous CDU version without Secure+ installed.
APAR IT03451
Simple clicking OK button in CD Secure+ Admin tool, without changing
any value is updating the node's record file.
APAR IT03523
On some Linux systems, CDU 4.2.0 may fail to start, reporting an
exception that indicates "libgsk8cms.so: cannot open shared object file: No
such file or directory".
APAR IT03815
An interrupted snode process goes into WAIT/WS state until pnode
10 Sterling Connect:Direct for UNIX 4.2.0: Documentation
resumes the process. If pnode never resumes the process, the snode process
will remain in the TCQ in WAIT/WS indefinitely.
Fix adds a new parameter to the tcq record of the initparm.cfg,
ckpt.max.age. This parameter specifies the number of days that an snode
process will remain in WAIT/WS state waiting for the pnode to resume the
process before it is automatically deleted. The default value is 8.
APAR IT04106
If a connection attempt to a remote node failed for some reason, the
session start statistics record (SSTR) would log a completion code (CC) of
0, improperly indicating that the session attempt succeeded.
APAR IT04446
Added millisecond time resolution to some of the existing time stamps
saved in statistics logs, such as "Stat log record time" (STAR), "Start time of
event" (STRT) and "Stop time of the event" (STPT). The CLI will only
display the added resolution for select statistics with detail=yes. API clients
can choose whether or not to display the added resolution.
APAR IT05619
The SSLv3 protocol contains a number of weaknesses including POODLE
(Padding Oracle On Downgraded Legacy Encryption, CVE-2014-3566). IBM
Sterling Connect:Direct (CD) for UNIX is therefore also vulnerable when
the SSLv3 protocol is used. When CD for UNIX is operating as the SSL
server (snode in CD terms) and is configured for TLS connections, and a
CD operating as the SSL client (pnode in CD terms) attempts an SSLv3
connection, it's possible that CD for UNIX will allow the connection to be
made and negotiated to SSLv3. Fix prevents the possible negotiation to
SSLv3 when TLS is configured.
Note: SSLv3 is an obsolete and insecure protocol. IBM recommends to use
the TLS protocol instead. To fully disable SSLv3 and use TLS instead,
ensure that all secure connections are configured to 'Enable TLS Protocol'
and 'Disable Override'.
Version 4.2.0.1
APAR IT01935
Vulnerability related to Record Processing in TLS 1.0 and later which can
result in high CPU Utilization that requires a system reboot to resolve.
RTC423150
Inappropriate CSPA204E written to statistics when Sterling Contol Center
Secure Connection settings are changed.
APAR IT01701
z/OS file allocation attributes specified in a type defaults file (typekey)
may not be honored. Copy step may also fail with errors similar to
SVSJ032I.
Version 4.2.0.0
APAR IC93901
XUTL003I error generated when non default CLI configuration file name is
used.
APAR IC93913
Automated install fails with CDAI019E message when the target
installation directory already exists. Solution adds installation variable
Chapter 1. Release Notes 11
named cdai_ignoreExistingInstallDir (--ignoreExistingInstallDir from the
command line) with a default value of "n". Setting the variable to "y"
causes cdinstall_a to ignore an existing target installation directory and
proceeds with the installation. Use this variable with caution when
engaging in automated deployment across multiple systems.
APAR IC94090
DBCS converted data received from a FB record format source file is
corrupted.
APAR IC94423
Copy step sending a file to a new data set on Connect:Direct for z/OS fails
and reports SVSH018I message when the block size for the new file is
specified as or defaulted to zero.
APAR IC94780
Copy step receiving a file in binary mode from Connect:Direct for z/OS
may fail and report XCPR001I message.
APAR IC94963
Copy step sending a zero byte source file to a z/OS destination file with
VB record format fails and reports various error messages, including
SVSJ013I and SVS5018I.
APAR IC95144
Connect:Direct for UNIX configured to use PAM authentication fails to
reject a user with an invalid account, for example, an account with an
expired password.
APAR IC95766
Session establishment and run task processing may slow down with high
session concurrency, particularly running on AIX with system auditing
turned on.
APAR IC95823
spadmin.sh or spcli.sh can fail to execute, reporting java error
StringIndexOutOfBoundsException.
APAR IC95830
Copy to Connect:Direct for z/OS with disp=old specification may result in
altered destination file allocation DCB specifications. Copy step may also
fail with errors similar to SVSJ032I.
APAR IC96647
cfgcheck doesn't generate a warning when a configuration file contains
duplicate record names.
APAR IC93810
cfgcheck reports XRIA002I for validly configured initparm.cfg records
ndm.env_vars and secure+ and the copy.parms record parameter
fsync.after.receive.
APAR IC97377
Copy step sending a file to a new data set on Connect:Direct for z/OS fails
and reports SVSH018I message when the record format for the new file is
specified as Fixed Block (FB) and no other DCB attributes are specified.
APAR IC98425
Automated installation script, cdinstall_a, hangs if the trace command line
option is specified as yes and there is no options file specified.
12 Sterling Connect:Direct for UNIX 4.2.0: Documentation
APAR IC98685
Excessive statistics generated causing performance degradation when the
sess.default value for a remote node is set to some value greater than one,
and multiple processes get queued up for that remote node.
APAR IC98932
Auditing processes on AIX 6.1 and greater may consume significant CPU
resources during and after a Connect:Direct for UNIX high load scenario.
APAR IC99214
Multiple concurrent API connections submitting processes for execution
may occasionally confuse two C:D processes, such that the one process is
submitted twice, running once with the correct process name and number,
and again with an incorrect process name and number, and the other
process not running at all. Alternatively, the issue might manifest as
occasional XSQF009I and XSMG405I event messages with fdbk=2 referring
to temporary files in the Connect:Direct for UNIX work directory.
APAR IC99434
IBM Sterling Connect:Direct for UNIX is affected by a vulnerability in the
IBM Runtime Environment, Java(TM) Technology Edition (CVE-2013-1500).
APAR IC99558
Automated install script cdinstall_a will fail reporting CDAI025E if the
default umask setting for the adminUserid is more restrictive than 22.
Solution adds installation variable named cdai_allowUmaskReset (--
allowUmaskReset from the command line) with a default value of "y".
Variable has no effect if the default umask of the adminUserid is 22 or ess.
If the default umask of the adminUserid is greater than 22, "y" causes
cdinstall_a to reset the umask of the adminUserid to 22. Setting the
variable to "n" in that case causes cdinstall_a to proceed with the more
restrictive than recommended umask setting.
Note: If the installation procedure proceeds with a umask setting that is
more restrictive than the recommended value, some users may not have
the necessary permissions to use Connect:Direct for UNIX.
APAR IC99599
cdcust may generate a false warning that Connect:Direct configurations
requiring root authority were not completed when run on a system with
SELinux ACL implemented.
APAR IT00471
On some Linux systems, run task steps will generate system log messages
indicating ndmsmgr attempted an unknown command via ioctl32.
APAR IT01040
Processes may fail reporting XSQF009I, "Get step return code file failed"
when a step return code file with the same name exists. Step return code
files are temporary files used by Connect:Direct to capture state
information of a running process. Compounding the problem, the error for
this scenario does not get propagated to the PRED statistic record, causing
a client that submitted the process programmatically and waited on the
result to conclude the process succeeded.
Version 4.1.0.4
APAR IC92400
Run task steps that rely on a LANG environment variable setting other
than the system default value and execute incorrectly.
Chapter 1. Release Notes 13
APAR IC84762
comm.bufsize value defaults to 4096 when it's not specified in either the
remote node record or the local.node record of the netmap.cfg file.
Documented default is 65536.
APAR IC85214
If multiple comm.info fields are defined in a netmap entry (valid for some
SNA connections), cdpmgr will leak memory whenever the netmap entry
is referenced.
APAR IC85987
cdpmgr server is killed when command logging is turned on and a client,
such as Sterling Control Center, attempts to import a large Secure+ trusted
certificates file.
APAR IC86449
On AIX 6.1 and above, a copy step that overwrites a local file to which the
local user has no update permission is successful.
APAR IC86456
Improper upgrade procedure resulting in mismatched Secure+ libraries
causes cdpmgr to hang on start up.
APAR IC87996
The Partitioned Data Set (PDS) member name, key word PPMN, is listed
twice in the Copy Termination Record (record id CTRC) that is logged to
statistics when copying a file to or from a zSeries PDS member.
APAR IC86881
Secure cdpmgr initialization procedure to sanitize inherited environment
variables, added for APAR IC82150, may prevent run task steps that
depend on one or more of the inherited environment variables from
working properly.
APAR IC89092
Upgrading to 4.1.0 from a release previous to 4.1.0 configured with Secure+
generates some inappropriate messages indicating that the initialize
Secure+ operation failed
APAR IC88093
Certain business scenarios may require the need to specify a nonstandard
record delimiter for UNIX text files. Added new copy step sysopt called
RECDL.
APAR IC89513
On some Solaris systems, CLI may fail to connect, reporting XSEC016I
message. ndmauthc or ndmauths may also generate a core file when this
happens.
APAR IC89667
Secure+ SSL connection initiated to Sterling Connect:Direct for z/OS uses a
16k buffer even when both sides have larger buffer sizes specified.
APAR IC91661
Custom program using the Sterling Connect:Direct for UNIX API may
generate XCMG000I errors when submitting a command. Server may show
an XSEC012I error concurrently.
APAR IC91973
Greater than two gig file transfers fail with XSQF006I on Linux systems
with kernel version 3.x.
14 Sterling Connect:Direct for UNIX 4.2.0: Documentation
Version 4.1.0.3
QC19725
Process with snodeid override specified submitted on Sterling
Connect:Direct for UNIX node via a submit statement within another
Sterling Connect:Direct Process may fail to pass snode security.
QC19758
Sterling Connect:Direct for HP NonStop reports an invalid feedback code
in the completion status for a run task step submitted to Sterling
Connect:Direct for UNIX.
QC19832
On AIX systems, temporary work files are created in /tmp instead of
{install dir}/work/{node name} directory for Processes submitted by a user
without write permission in the {install dir}/work/{node name} directory.
QC19857
View Process command may hang and generate many XUPC023I errors
when viewing a submitted Process that includes a submit step with an
snodeid or pnodeid override.
QC20035
An LCCA082I error is generated after cdpmgr has been started by root and
a Secure+ configuration command is issued from a KQV client, like
Sterling Control Center.
QC20041
Possible denial of service if attacker can play back multiple simulated
sessions that include large malformed session control packets that generate
lots of errors.
QC20043
Stack overflow vulnerability in ndmauthc. An attacker could exploit the
vulnerability to execute commands with Sterling Connect:Direct for UNIX
installer authority.
QC20044
Stack overflow vulnerability in modules that read the initparm.cfg file, like
cdpmgr and ndmsmgr.
QC20157
Null pointer dereference vulnerability in ndmsmgr for Secure+
connections. Vulnerability could enable denial of service attack.
QC20158
ndmsmgr segmentation violation during Secure+ connection attempt using
a malicious certificate with an inordinately long subject. Possible denial of
service.
QC20403
Potential for XPMR018I error when client such as Sterling Control Center
attempts to update the initparm.cfg file.
QC20473
Some records on z/OS VB destination file are not filled to LRECL
specification when sending a UNIX file with datatype=binary and
codepage conversion specified.
QC20638
ndmcmgr aborts with signal 11 when Sterling Control Center attempts to
add a local user.
Chapter 1. Release Notes 15
RTC 103045
When Secure+ is installed on a node for the first time, it must be
initialized. The initialization procedure requires the Sterling Connect:Direct
node name, but it is not offered by default.
RTC 140646
Clients like Sterling Control Center or Sterling Connect:Direct Browser
User Interface are able to set an invalid tcp.api value in the local.node
netmap entry causing future api connections to be rejected.
APAR IC82150
Improved safe initialization procedures for suid files ndmauthc, ndmauths,
and cdpmgr.
APAR IC81358
Statistics archive files may be owned by root.
RTC 315406
cdinstall indication of disk space requirement to install File Agent is too
low
APAR IC83460
When SSL/TLS is enabled, updating the .SEAServer entry in Secure+
would fail even when External Authentication is disabled: "Error: The
.SEAServer host name must be specified."
APAR IC83593
On exit, cdcust may give an inappropriate warning about incomplete root
authority configurations.
APAR IC84027
spcli may display resolved symbolic link values for pathnames entered
with symbolic links specified.
APAR IC84003
When Sterling Connect:Direct for UNIX receives a redirect message,
SCPA007I, from Sterling Connect:Direct for z/OS Plex environment,
Sterling Connect:Direct for UNIX inappropriately records a nonzero
completion code. Plex redirection is a normal operational flow.
Version 4.1.0.2
QC19065
XSMG605I error when copy step to i5/OS node fails and connection is via
Secure+ STS with digital signatures enabled.
QC19079
XSMG271I error on restarted wildcard copy step when local user on
sending node is other than the Sterling Connect:Direct installer.
QC19299
SVSJ032I error sending a binary file to a z/OS destination file with V or
VB record format.
QC19324
Scheduled Process fails with XSQF009I error if cdpmgr is recycled before
the scheduled Process start time.
QC19414
cdcust option to run "Configurations requiring root privilege" is ineffective
when root user is configured with a nologin shell.
16 Sterling Connect:Direct for UNIX 4.2.0: Documentation
QC19435
Files written and closed by Sterling Connect:Direct on NFS destination may
not be immediately ready for processing due to NFS delayed writes.
QC19633
cdinstall fails to detect and provide notice when the installed Sterling
Connect:Direct version is newer than the installing version.
Version 4.1.0.1
QC18587
Null pointer dereference vulnerability in ndmsmgr.
QC18588
Stack overflow exploit potential in ndmsmgr.
QC18972
Added "daily" keyword that when specified in the startt parameter with an
elapsed time will schedule the Process for the next day at the specified
time.
QC18999
XIPT011I error when Sterling Control Center attempts to import a large
(greater than 16k) trusted certificate file.
QC19021
Trailing blanks are not stripped from first record of a text file received with
strip.blanks=yes and codepage conversion.
QC19050
Added functionality to allow server connections to strongly secure
sensitive information in session overhead and leave data which may not be
sensitive unencrypted to enhance performance. Documentation for this
feature and how to use it is available on our IBMconref="../common/
product_names.dita#variables/SterlingCommerce-l"> Support Center
website.
Version 4.1.0.0
1351573
Copy step fails to checkpoint and restarts from beginning after Process is
suspended (flush/hold) and restarted.
1365363
TCP comm errors (XIPT errors) are not returned in a select statistics by
pnumber response.
1369148
Customer client applications coded with the Sterling Connect:Direct API
would core dump after successive connection failures.
1370676
Wildcard send gets file read permission error when user should have read
access via supplementary group permissions.
1370745
"Bytes Read" counter may be incorrect in the Copy Termination Record
(CTRC) of select statistics output when sending a text file with
strip.blanks=yes.
Chapter 1. Release Notes 17
1370775
CTRC stat record does not reflect XSQF006I generated when small text file
received on filesystem that is at full capacity.
1370824
ndmsmgr persisting and using high percentage of CPU in some cases after
pnode=snode Process is completed.
1371040
Proxy record that begins with the '#' character causes XSMG242I error for
incoming Processes.
1371229
Select statistics command response time improvement.
1371264
Message SVSG005I missing from msgfile.cfg.
1371409
Add methods GetProcessRC and GetProcessMsgID to the C++ sdk API for
Process submitted with maxdelay=unlimited.
1371934
XCPS009I error when LRECL specification exactly equal actual text file
record length.
1372112
Flush Process ineffective when run task step is running on remote node.
Restriction: Processes running a run task step on a remote node can now
be flushed; however, the Process will not be flushed on the remote node
side. The task will continue to completion and then the remote node
Process will fail with a communication error.
1372125
XUPC035I errors on view Process command when Process specifies sysopts
string with embedded quotes.
1372165
XSMG240I error after successful step completion.
1372245
XSMG015I Process error on HP-UX systems configured with long node
names.
1372292
Netmap record names longer than 16 characters cause configuration
problems in spadmin and spcli.
1372394
Default session class specified in adjacent node record fails to override
session class defined in local node record.
1372833
18 Sterling Connect:Direct for UNIX 4.2.0: Documentation
PRED record message id short text shows generic Process completed
message, not specific text of PRED record message id.
1372865
Wildcard copy fails to send file that user has read access to via Access
Control List.
QC13457
Netmap not checked for outgoing Processes.
QC13793
Potential for small cdpmgr memory leak when select Process detail
command is processed.
QC13827
Ndmcmgr memory leak causes File Agent to generate a
NullPointerException after repeatedly submitting Processes.
QC14076
cfgcheck '-f' parameter does not restrict check to named file only.
QC14185
Allow underscore characters in hostnames.
QC14341
Sterling Control Center update of local.node record removes tcp.api value.
QC14470
Wild card copy step would inappropriately report success when some but
not all matching files were not readable by the user. Added new error
message XSMG277I to indicate this condition.
QC14572
After upgrading node with Secure+ option, connections may fail with
CSPA016E or CSPA317E errors.
QC14577
XPAE003I syntax error submitting Process coded with several symbolics
defined with long symbolic names and values.
QC14599
Install on AIX 5.3 with Service Pack 10 applied fails indicating
unsupported pthreads library version.
QC14670
MBCS002E error receiving file using codepage conversion and
strip.blanks=yes.
QC14782
XUPC028I error when a view Process command is attempted on a Process
with a run task/job step that includes '|' and '=' characters.
QC14860
Potential for client application using API to dump core after
ndmapi_sendcmd function call.
QC15020
Expired passwords pass security check on shadow password security
enabled systems.
Chapter 1. Release Notes 19
QC15507
While processing a large number of Sterling Connect:Direct Processes, a
'select process pnumber=*' command will intermittently return a truncated
list of Processes.
QC15570
When Sterling Connect:Direct for UNIX is at maximum API capacity (as
specified by api.max.connects), a Java API call to instantiate (create and
connect) to a new node will complete successfully, but subsequent execute
commands will fail with the messages "Error: Connection Exception!" and
"Unexpected IOException in CommunicationBuffer::Receive()" or "Error:
Connection Exception! End of file in CommunicationBuffer::Receive()".
QC15647
XAPI006I errors with Substitution="Specified file could not be opened",
with api submit "submit file=filename;" with no space between end of
command text and ';'.
QC15740
Change Process command issued for large amount of Processes on TCQ
takes a long time to complete and generates many XLKL004I errors.
QC16086
Select Process command while many Processes are in tcq causes CLI to exit
with XCMG000I error.
QC16177
CLI abruptly exits with various error indications (depending on operating
system) when a select statistics command is issued with a stopt parameter
value previous to any existing statistics. Current statistics shows an
ndmcmgr terminating with signal SEGV.
QC16235
cfgcheck doesn't indicate line number of errors reported.
QC16242
Sessions fail with CSPA311E and CSPA309E when Secure+ configured with
certificates using SHA-2 based signatures.
QC16338
CSPE003E error generated when attempting to submit a Process. Preceded
by CSPE008E error with fdbk=9 on cdpmgr startup.
QC16418
When a KQV client (Sterling Connect:Direct Browser User Interface,
Sterling Connect:Direct File Agent, etc.) submits a Process, the submitted
time reported to the KQV client is the UNIX Epoch, 31 Dec 1969.
QC16538
The XSEC007I message generated when a CLI connection fails due to
improper directory permissions of the security subdirectory has misleading
text.
QC16620
Apparent hang in spadmin on HP platforms when DISPLAY is directed to
Attachmate Reflection X server.
QC16622
No statistic record logged when a non-executing Process is deleted from
the TCQ by user.
20 Sterling Connect:Direct for UNIX 4.2.0: Documentation
QC16726
CSPE007E, error=Lock Failed, when a submit within Process step is run on
snode with local snode authority other than the Sterling Connect:Direct
installer ID.
QC16794
If a wildcard copy step ends with an error condition code, subsequent
successful wildcard copy steps will erroneously report step failure.
QC16797
Processes submitted from Sterling Connect:Direct Requester fail to retry
connections specified in alt.comm.outbound.
QC16938
No statistic record logged when Secure+ is installed, and a Secure+ session
attempt fails due to a Secure+ library load attempt failure.
QC17049
XXDR012I message referring to Key=SER generated for incoming
connections from i5/OS.
QC17370
ndmsmgr executable may hang and burn CPU when non-Sterling
Connect:Direct component (possibly a denial of service attack contrivance)
sends a buffer to the server port attempting to emulate a Sterling
Connect:Direct component.
QC17371
ndmumgr is vulnerable to a stack overflow exploit which could allow a
non-root user root authority.
QC17372
ndmumgr can be exploited by a non root user to create a root owned file.
QC17439
tcp.max.time.to.wait parameter is not honored for initial connection
attempt.
QC17694
XUPC035I and XUPC066I messages missing from msgfile.cfg.
QC17727
SPAdmin/SPCli execution fails with error opening audit log.
QC17761
XCPS009I error generated due to inappropriate record length check by
Sterling Connect:Direct for UNIX when sending a file.
QC17763
Select statistics command specified with startt=(day of the week) fails with
"XPAS009I - STARTT has a future date."
QC18309
If Sterling Connect:Direct File Agent 1.3 has been previously applied to a
Sterling Connect:Direct for UNIX installation, a cdinstall operation in
upgrade mode fails when upgrade attempted for File Agent.
QC18378
Trace cmgr command only effects ndmcmgr of client that issued the
command and new ndmcmgrs started after the command is issued.
Ndmcmgrs that are running at the time the command is issued are not
affected.
Chapter 1. Release Notes 21
QC18772
On some systems, such as RHEL 6, Sterling Connect:Direct API client
connect fails with XAPI005I and XSEC015I. Server statistics show XIPT016I.
Known Restrictions
Sterling Connect:Direct for UNIX has the following restrictions when using
third-party hardware or software:
v An issue occurs with GSKit-Crypto Solaris x86 32-bit binaries; these will not load
in FIPS mode on the Intel chipset (the problem does not occur on AMD
chipsets).
v Changes to the SPCli will break customer scripts.
v There is no GUI support for creating ECDSA signed certificates.
v UDT
– Under conditions of high CPU usage, a Sterling Connect:Direct Process
running over UDT may be interrupted by a lost connection. If the connection
is lost, the Process is retried. The frequency of connections lost due to high
CPU usage can be reduced by restricting the number of concurrent UDT
sessions through netmap session limits.
– All UDT SNODE connections must be defined in your netmap so that the
node name can be used to specify the SNODE in a Process statement. You
cannot use an IP address and port number to specify the SNODE in a Process
statement if you want to connect to a remote node using UDT.
– UDT is not supported in a load balancing environment.
– UDT is not supported with FASP.
v 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.
v If you use the Hummingbird Exceed terminal emulator to access a Solaris
workstation, you may not have all of the fonts needed to use Sterling
Connect:Direct Secure Plus. 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 Sterling
Connect:Direct from performing a core dump if it is unable to locate a font.
v Sterling Connect:Direct Secure Plus 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 Sterling Connect:Direct. If you do not have
access to X Windows, you can use the Sterling Connect:Direct Secure Plus
Command Line Interface (Secure+ CLI).
v Sterling Connect:Direct Secure Plus does not support server gated crypto (SGC)
certificates.
v The Secure+ CLI does not support using $HOME or the tilde (~) to specify the
path to your home directory.
22 Sterling Connect:Direct for UNIX 4.2.0: Documentation
v Sterling Connect:Direct Secure Plus supports FIPS mode on the following
platforms:
– Sun Solaris 10 (SPARC)
– IBM AIX 5L 5.3
– HP-UX 11iv2 (HP Integrity)
– HP-UX 11iv2 (PA_RISC)
v 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);
v 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 Sterling 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.
v Sterling Connect:Direct Browser User Interface is not supported running on HP
Integrity systems with Intel Itanium processors.
v 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 effect installation or
functionality of Sterling Connect:Direct File Agent on Linux.
Upgrade Considerations
If you are upgrading from an existing version of Sterling Connect:Direct for UNIX,
observe the following guidelines:
v 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.
v 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*.???
Chapter 1. Release Notes 23
The following variable definitions apply:
– root_password - Root user's password
– cddir - Directory in which Sterling Connect:Direct for UNIX is installed
– node - Your Sterling Connect:Direct node name
– user_who_starts_cdpmgr - User name of the user who will start the cdpmgr
daemon
v If you are upgrading a collection of Sterling 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.
Upgrading Sterling 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.
v Although Sterling Connect:Direct for UNIX Process names can be up to 255
characters long, some Sterling Connect:Direct platforms, such as Sterling
Connect:Direct for z/OS limit Process names to eight characters. Processes
running between UNIX and platforms that limit Process names to eight
characters can have unpredictable results if longer names are specified.
v If you install Sterling Connect:Direct for UNIX on an HP Integrity system, you
cannot use the Sterling Connect:Direct Secure Plus parameter file generated on a
PA-RISC computer. You must create a new parameter file.
v The Sterling Connect:Direct Secure Plus initparms record and the user authority
that have been added to Sterling Connect:Direct for UNIX version 4.1.00 support
remote configuration of Sterling Connect:Direct Secure Plus. These configuration
options are needed when using the Central Management feature available in
Sterling Control Center 5.0 and later.
v If you are using a certificate that was created with an older version of Sterling
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 Using Sterling File Accelerator
(UDT)
If you plan to use UDT for file transfers on high-speed networks with latency, refer
to the following table for performance differences between TCP and UDT:
Bandwidth Latency Results
45 Mbps All latencies TCP is equal to UDT
24 Sterling Connect:Direct for UNIX 4.2.0: Documentation
Bandwidth Latency Results
155 Mbps Less than 20 ms TCP outperforms UDT
Greater than 20 ms UDT outperforms TCP
1 Gbps Less than 10 ms TCP outperforms UDT
Greater than 10 ms UDT outperforms TCP
For more information, see Determining When to Use UDT (Sterling File
Accelerator) white paper available with the Sterling Connect:Direct for UNIX
product documentation on the IBM Support portal.
Special Considerations for Connectivity with the HP NonStop
Kernel Operating System
This version of Sterling Connect:Direct for UNIX offers connectivity to Sterling
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:
v 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.
v 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.
v 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 Sterling
Connect:Direct Processes Web site.
Special Considerations for Using Sterling Connect:Direct for
UNIX in FIPS 140-2 Mode
This version of Sterling Connect:Direct Secure Plus for UNIX offers a FIPS mode of
operation. Refer to the following note when configuring it:
Note: Upon initialization, a message is written in statistics which indicates that
FIPS mode is enabled:
Strong Password Encryption enabled, FIPS mode enabled.
However, this message applies to strong password encryption only. FIPS mode is
not used in transfers with trading partners until it is specified in the Secure+ parm
file.
Chapter 1. Release Notes 25
Sterling Connect:Direct for UNIX Guidelines
Before you install Sterling Connect:Direct for UNIX, read all the information in this
section and follow the guidelines.
v Print and Review IBM Sterling Connect:Direct for UNIX Implementation Guide.
v To install Sterling Connect:Direct Secure Plus at the same time that you install
Sterling Connect:Direct for UNIX, following the instructions in IBM Sterling
Connect:Direct for UNIX Getting Started Guide.
v When you upgrade from a previous version, the parameters file is converted
and can be used with the new version.
Password Storage
Sterling Connect:Direct for UNIX enables you to use any of the following for
password storage:
v /etc/passwd file
v /etc/shadow file when supported by the operating system
v HP-UX trusted security
v Network Information Service (NIS), formerly known as Yellow Pages
v Digital UNIX Enhanced Security
v Pluggable Authentication Modules (PAM)
Libraries to Install
Ensure that you have the following libraries installed:
UNIX Platform Software Library
Intel and AMD
x86/x86-64, Linux
zSeries
All supported Linux
Intel and AMD
x86/x86-64
Red Hat Enterprise
Linux version 6
For Red Hat Enterprise Linux version 6, the
following libraries need to be installed:
v libXtst-1.0.99.2-3.el6.i686
v libXmu-1.0.5-1.el6.i686
v libXt-1.0.7-1.el6.i686
v libXft-2.1.13-4.1.el6.i686
v libX11-1.3-2.el6.i686 (32-bit only)
v libXi-1.3-3.el6.i686
v libXext-1.1-3.el6.i686
v libXau-1.0.5-1.el6.i686
v libXrender-0.9.5-1.el6.i686
Linux zSeries Red Hat Advanced
Server
IBM System
pSeries
AIX IBM C Set ++ Runtime Libraries for AIX version
8 or later
These libraries can be accessed at:
http://www.ibm.com/developerworks/aix
Note: After you install these libraries, rerun the
Sterling Connect:Direct for UNIX installation
program.
26 Sterling Connect:Direct for UNIX 4.2.0: Documentation
UNIX Platform Software Library
Solaris 11, SPARC
and x86
librpcsoc.so.1
Note: This library can be acquired by installing
the compatibility/ucb package.
Chapter 1. Release Notes 27
28 Sterling Connect:Direct for UNIX 4.2.0: Documentation
Chapter 2. Sterling Connect:Direct for UNIX Overview
IBM Sterling 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. Sterling
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.
Sterling Connect:Direct for UNIX is based on client-server architecture. The Sterling
Connect:Direct for UNIX server components interact with the user interfaces (API,
CLI, IBM Sterling Connect:Direct Browser User Interface, and IBM Sterling Control
Center) to enable you to submit, execute, and monitor Sterling Connect:Direct for
UNIX statements and commands.
Sterling Connect:Direct for UNIX Overview
IBM Sterling 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. Sterling
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.
Sterling Connect:Direct for UNIX is based on client-server architecture. The Sterling
Connect:Direct for UNIX server components interact with the user interfaces (API,
CLI, IBM Sterling Connect:Direct Browser User Interface, and IBM Sterling Control
Center) to enable you to submit, execute, and monitor Sterling Connect:Direct for
UNIX statements and commands.
Process Manager
The Process Manager (PMGR) is the daemon that initializes the Sterling
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:
v Initializes Sterling Connect:Direct for UNIX
v Accepts connection requests from Sterling Connect:Direct for UNIX client APIs
and remote nodes
v Creates Command Manager and Session Manager child Processes to
communicate with APIs and remote nodes
v Accepts requests from Command Managers and Session Managers when
centralized Sterling Connect:Direct for UNIX functions are required
v Stops Sterling Connect:Direct for UNIX
Command Manager
© Copyright IBM Corp. 1993, 2016 29
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 Sterling Connect:Direct for UNIX operation. You must
define enough file descriptors to handle the number of concurrent Sterling
Connect:Direct for UNIX sessions allowed, which can be as many as 999.
The CMGR provides the following functions:
v Executes commands sent by the API and sends the results back to the API
v Carries out the Sterling Connect:Direct for UNIX authentication procedure, in
conjunction with the API, to determine access to Sterling Connect:Direct for
UNIX
v Interacts with the PMGR when executing commands
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:
v Performs the necessary Sterling Connect:Direct for UNIX work
v Acts as a primary node (PNODE) and initiates Process execution
v 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
Sterling Connect:Direct for UNIX can authorize local and remote users to perform
certain Sterling Connect:Direct for UNIX tasks. In order to use Sterling
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 Sterling Connect:Direct for UNIX, a second access file called the Strong
Access Control (SACL) file is created when you install Sterling Connect:Direct for
UNIX and is named sysacl.cfg. The root:deny.access parameter, which is specified
30 Sterling Connect:Direct for UNIX 4.2.0: Documentation
in the sysacl.cfg file, allows, denies, or limits root access to Sterling Connect:Direct
for UNIX. If the SACL file is deleted or corrupted, access to Sterling 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
Sterling Connect:Direct for UNIX facilities are available to enable Process recovery:
v 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.
v 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.
v 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.
v Run Task restart—If a Process is interrupted when a run task on an SNODE step
is executing, Sterling 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.
– 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, Sterling 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 Sterling
Connect:Direct for UNIX cold restart, Sterling 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 Sterling Connect:Direct for UNIX
runs behind a connection load balancer.
v Interruption of Process activity when the SNODE is a Sterling Connect:Direct for
UNIX node—When the SNODE is a Sterling 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.
Chapter 2. Sterling Connect:Direct for UNIX Overview 31
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
Sterling Connect:Direct for UNIX provides a utility to archive and purge statistics
files. When you configure Sterling 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
Sterling Connect:Direct for UNIX provides sample Processes and shell scripts in
d_dir/ndm/src, where d_dir indicates the destination directory of the Sterling
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
rtunx.cd
run task
rjunx.cd
run job
32 Sterling Connect:Direct for UNIX 4.2.0: Documentation
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:
v 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.
v apicheck.C - Same as apicheck.c, except that it is compiled with one of the C++
compilers listed in the Sterling Connect:Direct for UNIX User Guide.
v exit_skeleton.c - This program is a skeleton of a user exit program that works in
conjunction with Sterling Connect:Direct for UNIX. It demonstrates usage of all
three user exits.
v exit_skeleton.C - Same as exit_skeleton_c, except that it is compiled with one of
the C++ compilers listed in the Sterling Connect:Direct for UNIX User Guide.
v 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.
Sterling Connect:Direct for UNIX Configuration Files
Sterling Connect:Direct for UNIX creates the following configuration files during
installation and customization. These files are required for the Sterling
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.
Chapter 2. Sterling Connect:Direct for UNIX Overview 33
Strong access control file
Improves the security of Sterling Connect:Direct for UNIX and allows,
denies, or limits root access control. This file is created when you install
Sterling Connect:Direct for UNIX. If the file is deleted or corrupted, access
to Sterling Connect:Direct for UNIX is denied to all users.
Network map file
Describes the local node and other Sterling Connect:Direct for UNIX nodes
in the network. You can define a remote node record for each node that
Sterling 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 Sterling
Connect:Direct for UNIX.
Client authentication key file
Identifies Sterling Connect:Direct for UNIX servers that a Sterling
Connect:Direct for UNIX client connects to. You can have multiple entries
for multiple servers.
Sterling Connect:Direct for UNIX Directory Structure
The following figure illustrates the Sterling 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 Sterling Connect:Direct for UNIX programs, such
as cdpmgr and ndmcmgr. The secure+ directory is available only when Sterling
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 Sterling
Connect:Direct for UNIX node name.
A d_dir/work/cd_node directory is created for each node.
Installing Sterling Connect:Direct for UNIX
Before you install Sterling Connect:Direct for UNIX, complete the worksheets to
identify all information required to perform the installation.
Sterling Connect:Direct for UNIX requires that you install a server and at least one
client location. You can install Sterling Connect:Direct for UNIX in different
configurations:
v Install the server on a local system and the clients on remote systems
v Install the server and at least one client on a local system and the remaining
clients on remote systems
Install Sterling Connect:Direct for UNIX on a local drive. Do not install Sterling
Connect:Direct for UNIX on a Network File System (NFS) resource.
v Install using a Silent Installation. See Sterling Connect:Direct for Unix silent
installation in the Mass Deployment documentation library.
34 Sterling Connect:Direct for UNIX 4.2.0: Documentation
Preparing to Install Sterling Connect:Direct for UNIX in a
Cluster Environment
Sterling 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. Sterling 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 Sterling Connect:Direct
for UNIX in a high-availability cluster environment.
Supported High-Availability Cluster Environments
Sterling Connect:Direct for UNIX is certified to operate in the following
high-availability cluster environments:
v IBM high-availability cluster multiprocessing (HACMP) environment
v Hewlett-Packard MC/Service Guard
v SunCluster versions 2.2, 3.0, and 3.2.
If you plan to install Sterling Connect:Direct for UNIX in a high-availability cluster
environment, complete the following tasks:
v Install the clustering software on each computer in the cluster, including setting
up a logical host or application package.
v Create a user with the same name and user ID on each cluster node.
v Create a Sterling Connect:Direct Secure Plus subdirectory on a shared file system
on a shared volume group.
v Ensure that the shared file system is owned by the Sterling Connect:Direct user.
v Install Sterling Connect:Direct on the shared file system.
v Perform the procedures necessary to define the high-availability settings and
configure the cluster environment.
Limitations of High-Availability Clusters
When running Sterling Connect:Direct for UNIX in a high-availability cluster
environment, be aware of the following limitations:
v If a failure occurs, all Processes being held will be restarted when Sterling
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.
v When a Sterling Connect:Direct ndmsmgr process associated with a Sterling
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
Sterling 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 Sterling 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 Sterling
Connect:Direct for UNIX PNODE sessions.
Chapter 2. Sterling Connect:Direct for UNIX Overview 35
SNODE Server Considerations for Load-Balancing Clusters
Consider the following when planning and setting up the Sterling Connect:Direct
for UNIX SNODE servers in a load balancing cluster:
v The servers used for the Sterling 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 and not a Network File System (NFS)
resource.
– All servers must be of the same platform type (for example, all Solaris SPARC
or all Linux Intel) and the same Sterling Connect:Direct for UNIX version and
maintenance level.
v The system clocks on all servers must be synchronized in order for copy
checkpoint/restart and run task synchronization to work.
v The administrator user ID used to install Sterling 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 Sterling Connect:Direct
for UNIX SNODEs in a load-balancing cluster:
v One Sterling Connect:Direct for UNIX node should be installed on each server
behind the load balancer.
v Each node should be installed by the same user ID.
v Each node should have the same Sterling Connect:Direct for UNIX node name.
v Each node should have the same node-to-node connection listening port.
v A directory should be established for the shared SNODE work area used by the
Sterling Connect:Direct for UNIX nodes behind the load balancer. This directory
should be owned by the Sterling Connect:Direct for UNIX administrator ID and
must be accessible to all of the servers behind the load balancer.
v 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 Sterling Connect:Direct for UNIX in a cluster environment, be
aware of the following limitations:
v 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.
v When shared SNODE work areas are configured and the run task is on the
SNODE, then at restart time, Sterling 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.
36 Sterling Connect:Direct for UNIX 4.2.0: Documentation
v 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.
v 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.
Preparing to Install Sterling Connect:Direct for UNIX on the Linux
for zSeries Operating System
Sterling Connect:Direct for UNIX is distributed on a DVD-ROM. Because the Linux
for zSeries operating system does not support the DVD-ROM drive installation,
you must use ftp to transfer installation files from a UNIX or Microsoft Windows
operating system. To transfer the files from a Microsoft Windows or UNIX
platform to the Linux for zSeries operating system, use the following procedure:
Procedure
1. Create a temporary directory on the computer running Linux for zSeries.
2. Insert the DVD-ROM into the appropriate drive on the computer running
Microsoft Windows or UNIX and perform one of the following actions:
v From Microsoft Windows, select Start > Programs > Accessories > Command
Prompt.
v From UNIX, use the mount command to locate the DVD-ROM drive.
3. Type the following command, where ip address is the IP address of the
computer running Linux for zSeries:
ftp ip address
4. At the prompt, type the user name and password for a user on the computer
running Linux for zSeries.
5. At the ftp prompt, set the transfer mode to binary by typing the following
command:
binary
6. Change to the temporary directory you created on the computer running Linux
for zSeries by typing the following command, where temp_dir is the directory
you created in step 1:
cd temp_dir
7. To copy the installation script from the DVD-ROM to the computer running
Linux for zSeries, perform one of the following actions:
v From Microsoft Windows, type the following command, where x is the
location of the DVD-ROM drive:
put x:\IBMS390_linux\cdinstall cdinstall
v From UNIX, type the following command:
put /cdrom/IBMS390_linux/cdinstall cdinstall
Chapter 2. Sterling Connect:Direct for UNIX Overview 37
8. To copy the Sterling Connect:Direct cpio file from the CD-ROM to the computer
running Linux for zSeries, perform one of the following actions:
v From Microsoft Windows, type the following command, where x is the
location of the DVD-ROM drive:
put x:\IBMS390_linux\cdunix cdunix
v From UNIX, type the following command:
put /cdrom/IBMS390_linux/cdunix cdunix
9. To exit the ftp application, type quit.
Conventions to Observe When Installing Sterling
Connect:Direct for UNIX
Observe the following conventions when you install Sterling Connect:Direct for
UNIX:
v If a file name contains a semicolon, precede the semicolon with a backslash (\)
character; otherwise, the shell interprets the semicolon as the start of a new
command. For example, specify the file name SNA;1 as SNA\;1.
v Acceptable responses to prompts are listed in brackets, where y specifies yes, n
specifies no, and a specifies all.
v The default response is capitalized. Press Enter to accept the default value.
v Do not use colons (:) for values in the installation and customization scripts.
v Do not use keywords for values.
v Press Enter after each entry to continue.
v Terminate any procedure by pressing Ctrl-C.
Worksheet Instructions
Before you install Sterling 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.
v Installation Worksheet
v User Authorization Information File Worksheet
v CLI/API Configuration File Worksheet
The following worksheets are provided for your convenience:
v Network Map Remote Node Information File Worksheet
v Server Authentication key File Worksheet
v 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 Sterling Connect:Direct
server is installed
Directory or path on which the distribution media will be mounted
38 Sterling Connect:Direct for UNIX 4.2.0: Documentation
Parameter Value
Destination directory where Sterling Connect:Direct will be installed,
including the full path name
Customization Worksheet
Use this worksheet during customization. Refer to the Customizing Sterling
Connect:Direct for UNIX.
Parameter
Default
Value Value to Use
Sterling Connect:Direct node name you are customizing, up to
16 characters long.
Initialization Parameters File Information
TCP/IP port number that the server monitors for an API
connection request.
1363
TCP/IP port number that the server monitors for a remote
Sterling Connect:Direct 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.
1364
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 Sterling Connect:Direct users must have an entry in the user authorization
information file.
Remote User Information Record
Sterling 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 Sterling
Connect:Direct for UNIX. Sterling 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 Sterling 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 Sterling Connect:Direct for UNIX Administration Guide.
Remote User ID at Remote Node Name mapped to Local User ID
@ =
@ =
@ =
@ =
Chapter 2. Sterling Connect:Direct for UNIX Overview 39
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.
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.
40 Sterling Connect:Direct for UNIX 4.2.0: Documentation
Local User
ID Parameter Description Value to Assign
cmd.delproc Specifies whether the user can issue
the delete 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.
y | n |a
y—Default
a—For all users
cmd.flsproc Specifies whether the user can issue
the flush 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.
y | n |a
y—Default
a—For all users
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.
Chapter 2. Sterling Connect:Direct for UNIX Overview 41
Local User
ID Parameter Description Value to Assign
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
descriptive notes to the record.
text string
________________
name Specifies the name of the user. user name
________________
phone Specifies the telephone number of the
user.
user phone
________________
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.
ulimit
Specifies the action to take when the
limit on a user output file size is
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 trillions of bytes.
The maximum value you can specify
is 1 terabyte.
42 Sterling Connect:Direct for UNIX 4.2.0: Documentation
Local User
ID Parameter Description Value to Assign
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
_dir
Specifies the directory to which the
user can download files.
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.
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.
Chapter 2. Sterling Connect:Direct for UNIX Overview 43
Local User
ID Parameter Description Value to Assign
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 Sterling Connect:Direct for UNIX
server to which 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.
1363
Host name of the Sterling 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
and UDT Only)
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 Sterling
Connect:Direct server will run.
Communication port number to call the remote
Connect:Direct server:
1364
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.
44 Sterling Connect:Direct for UNIX 4.2.0: Documentation
Parameter Default Value Value To Use
The host name on which the API is executed.
An asterisk (*) stands for any host.
*
Sterling Connect:Direct security depends on a key (similar to a password) in a
Sterling 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 Sterling Connect:Direct
is executed.
An asterisk (*) stands for any host.
*
Sterling Connect:Direct security depends on a key, similar to a password, in a
Sterling 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 Sterling Connect:Direct
To install Sterling Connect:Direct for UNIX:
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. Type the following command and press Enter to change to the DVD-ROM
drive and the directory that correspond to the UNIX platform:
cd /cdrom/<platform directory>
Refer to the following information for the name of the platform directory for
each platform.
HP PA-RISC
HP_PA-RISC
HP UX Itanium
HP_Itanium
IBM System pSeries
IBM
Chapter 2. Sterling Connect:Direct for UNIX Overview 45
Sun SPARC systems
Sun_Solaris
Red Hat
RedHat_linux
SuSE
SuSE_linux
Linux for zSeries
IBMS390_linux
Solaris/x86
Solaris_x86
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 name of the directory where Sterling Connect:Direct for UNIX
will be installed and press Enter.
6. Press Enter to confirm the location
7. Do one of the following:
v Press Enter to accept install the Server and Client on the same computer.
v Type 2 to install the Server only and press Enter.
v Type 3 to install the Client only and press Enter.
The following screen is displayed:
8. 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.
9. 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 Sterling Connect:Direct for UNIX
The customization script starts automatically after the installation is complete to set
up the Sterling Connect:Direct for UNIX operating environment. It is located in
d_dir/etc, where d_dir is the Sterling Connect:Direct installation directory, and
may be run by itself if needed for future configuration changes. The option you
select determines what Sterling Connect:Direct for UNIX operating environment is
configured: the Sterling Connect:Direct for UNIX Server only, the Sterling
Connect:Direct for UNIX Client only, or the Sterling Connect:Direct for UNIX
Server and Client.
About this task
After you customize the environment, you need to configure Sterling
Connect:Direct for UNIX for using root privilege to create a Strong Access Control
46 Sterling Connect:Direct for UNIX 4.2.0: Documentation
List (SACL) file and to set the owner and permissions of Sterling Connect:Direct
executables. You must create the SACL file and set the owner and permissions
before you can run Sterling Connect:Direct for UNIX. See Configuring Sterling
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.
v 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 Sterling Connect:Direct for UNIX Server and Setting Up the
Sterling Connect:Direct for UNIX Client.
v Type 2 to customize the Client only and press Enter.
If you are installing the Client only, complete the procedure Setting Up the
Sterling Connect:Direct for UNIX Client.
v Type 1 to customize the Server only and press Enter.
If you are installing the Sterling Connect:Direct for UNIX Server only,
complete the procedure, Setting Up the Sterling Connect:Direct for UNIX
Server.
Setting Up the Sterling Connect:Direct for UNIX Server
After you install Sterling 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.
2. If you have SNA configured, press Enter to configure SNA in the Sterling
Connect:Direct initialization parameters file.
3. If you do not use SNA, type n and press Enter to continue customizing Sterling
Connect:Direct for UNIX.
4. Type the TCP/IP port number that Sterling 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.
5. Type the hostname or IP address that Sterling Connect:Direct Monitors for
requests from remote nodes.
If you use 0.0.0.0, Sterling 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.
6. Type the TCP/IP port number that Sterling 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.
Chapter 2. Sterling Connect:Direct for UNIX Overview 47
This value is entered into the network map file in the tcp.api parameter.
7. Type the hostname or IP address that Sterling Connect:Direct monitors for
requests from Clients.
This value is entered into the network map file in the tcp.api parameter.
Sterling 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.
8. 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]
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:
v To create another remote user record, press Enter and repeat steps 2-4.
v Type n and press Enter if you do not want to create another remote user
record.
6. Do one of the following:
v If you do not want to create a local user record, type n and press Enter.
v 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 Sterling
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:
v Press Enter and repeat this procedure to create another local user record.
48 Sterling Connect:Direct for UNIX 4.2.0: Documentation
v 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. Sterling 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 Sterling Connect:Direct for UNIX Client
After you install and customize Sterling 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.
A message is displayed when the client authenticatio key file is created.
3. Press Enter .
Configuring Sterling Connect:Direct for UNIX Using Root
Privilege
You must create the SACL file and set the owner and permissions of the Sterling
Connect:Direct executables to run Sterling Connect:Direct for UNIX.
About this task
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 Sterling
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.
Chapter 2. Sterling Connect:Direct for UNIX Overview 49
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 Sterling
Connect:Direct executable files:
Procedure
1. Type the full path of the Sterling 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 Sterling Connect:Direct executable files are set,
and the following messages and prompt are displayed.
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
SNAFILE=/ndm/lib/libcdsna.s Defines SunLink as the SNA
software
Initialization
parameters file
BRXSNAFILE=/ndm/lib/
libcdbrxsna.s
Defines Brixton as the SNA
software
Initialization
parameters file
SNPSNAFILE=/ndm/lib/
libcdsnpsna.so
Defines SNAP-IX as the SNA
software
Initialization
parameters file
comm.info Identifies the IP address and
port that Sterling Connect:Direct
monitors for requests from
remote nodes
Initialization
parameters file
tcp.api Identifies the IP address and
port monitored by Sterling
Connect:Direct for requests from
clients
Network map file
rnode.listen Identifies the host used to
monitor LU 6.2 connections
Initialization
parameters file
admin.auth Determines if user ID has
administrative authority
User authorization
information file
50 Sterling Connect:Direct for UNIX 4.2.0: Documentation
Parameter Value File
tcp.port Specifies port number of the
server that the client connects to
Client configuration
file
tcp.hostname Specifies host name of the
server that the client connects to
Client configuration
file
Installing Sterling Connect:Direct File Agent
After you install Sterling Connect:Direct, install Sterling 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 Sterling 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 DVD-ROM
drive and 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 PA-RISC
HP_PA-RISC
HP UX Itanium
HP_Itanium
IBM System pSeries
IBM
Sun SPARC systems
Sun_Solaris
Red Hat
RedHat_linux
SuSE
SuSE_linux
Linux zSeries
IBMS390_linux
Solaris/x86
Solaris_x86
Chapter 2. Sterling Connect:Direct for UNIX Overview 51
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 Sterling 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 Sterling Connect:Direct Secure Plus
After you install Sterling Connect:Direct for UNIX, you can install Sterling
Connect:Direct Secure Plus at any time.
About this task
To install Sterling 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 PA-RISC series
HP_PA-RISC
HP UX Itanium
HP_Itanium
52 Sterling Connect:Direct for UNIX 4.2.0: Documentation
IBM System pSeries
IBM
Sun SPARC systems
Sun_Solaris
Red Hat
RedHat_linux
SuSE
SuSE_linux
Linux zSeries
IBMS390_linux
Solaris/x86
Solaris_x86
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 Sterling 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 Sterling Connect:Direct
Chapter 2. Sterling Connect:Direct for UNIX Overview 53
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.
SNA Support for Sterling Connect:Direct for UNIX
For LU6.2 connectivity, you must configure SNA support. Refer to SNA LU6.2
Connectivity for instructions on modifying both the initialization parameters and
network map files.
Defining High-Availability Settings in the Configuration Files
After you install Sterling Connect:Direct for UNIX on a shared file system, modify
Sterling Connect:Direct parameters to support a clustering environment. Install
Sterling 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:
v 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.
v 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.
v 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:
v Set :comm.info=logical_host_ip_name;1364:\ to configure the loopback
remote node record.
v 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.
54 Sterling Connect:Direct for UNIX 4.2.0: Documentation
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:
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:
v cd_start.sh
v 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 Sterling 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:
Chapter 2. Sterling Connect:Direct for UNIX Overview 55
Procedure
1. Place the following sample scripts and configuration files in a directory that is
available to the IBM HACMP software:
v cd_start_net.sh
v 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 Sterling
Connect:Direct with MC/Service Guard. The implementation and certification of
Sterling Connect:Direct followed the SCC’s high availability Implementation and
Certification Process. Refer to the Implementation and Certification With
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 Sterling Connect:Direct was
installed.
3. Type the following command to start Sterling Connect:Direct for UNIX Server,
where d_dir is the destination directory and cd_node is the Sterling
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:
v If you are using the Bourne or Korn shell, type the following command:
$ NDMAPICFG=d_dir/ndm/cfg/cliapi/ndmapi.cfg
$ export NDMAPICFG
v 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 Sterling Connect:Direct client:
$ d_dir/ndm/bin/direct
6. Type the following command:
Direct> select statistics;
56 Sterling Connect:Direct for UNIX 4.2.0: Documentation
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;
Sterling 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:
v Type the following command to manually shut down the Sterling
Connect:Direct server:
Direct> stop;
v When running Sterling Connect:Direct with the LU6.2 feature on HP SNA,
NCR SNA, Brixton SNA, or SunLink SNA, type the following command to
stop Sterling Connect:Direct: Direct> stop force;
v Type the following command to quit the Sterling Connect:Direct client
without shutting down the server: Direct> quit;
The client terminates automatically when you stop the server.
Sterling Connect:Direct File Agent Overview
Sterling Connect:Direct File Agent is a component of Sterling Connect:Direct that
provides unattended file management. Before using Sterling 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 Sterling
Connect:Direct File Agent to connect to a Sterling Connect:Direct server, watch the
directories that files of interest will be added to, and submit a specified Sterling
Connect:Direct Process to the server when a file is detected.
Sterling Connect:Direct File Agent provides monitoring and detection capabilities
that enhance the automation you accomplish with Sterling Connect:Direct
Processes. You cannot create Processes with Sterling Connect:Direct File Agent;
however, Sterling Connect:Direct File Agent variables can be used to pass
arguments to a Process. Sterling 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 Sterling Connect:Direct server.
Before you specify a Sterling Connect:Direct Process in the Sterling Connect:Direct
Chapter 2. Sterling Connect:Direct for UNIX Overview 57
File Agent configuration, you must create and test the Processes to ensure that it
performs tasks as expected when Sterling Connect:Direct File Agent submits the
Process.
Using the Sterling Connect:Direct File Agent configuration interface and Help
system, you define the default configuration file (Default_Config.ser). The default
configuration file defines the Sterling Connect:Direct server that Sterling
Connect:Direct for UNIX communicates with; the directory, or directories, that
Sterling Connect:Direct File Agent monitors; and how a file added to a watched
directory or a detected system event are processed.
You can configure Sterling Connect:Direct File Agent to operate in either of the
following ways:
v Watch for any file to appear in one or more watched directories and submit the
default Process after detecting the newly added file.
v 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.
Sterling 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, Sterling Connect:Direct
File Agent submits the Sterling Connect:Direct Process associated with that rule.
You can create Sterling Connect:Direct File Agent rules based on the following
properties:
v Full or partial name of the file detected in a watched directory
v Size of the file detected in a watched directory
v System event title
v System event contents (as included in a stack trace)
You can specify more than one rule in a Sterling Connect:Direct File Agent
configuration; each rule can have Sterling Connect:Direct File Agent submit a
different Process.
Although you can create multiple rules as part of a Sterling Connect:Direct File
Agent configuration, Sterling 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 Sterling Connect:Direct File
Agent to communicate with the Sterling Connect:Direct node where it is installed.
You can configure Sterling Connect:Direct File Agent to use continuous signon and
remain connected to the API port for the Sterling Connect:Direct server at all times,
or configure it to connect to the port only when it needs to. Sterling Connect:Direct
File Agent can be installed on UNIX, Microsoft Windows, and z/OS operating
systems. When you use Sterling 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 Sterling 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.
Sterling Connect:Direct File Agent can monitor multiple directories, including local
and network directories. Sterling Connect:Direct File Agent scans the watched
directories you specify in the configuration for newly added files (unless you
58 Sterling Connect:Direct for UNIX 4.2.0: Documentation
specify a rule to force other operation). By default, Sterling Connect:Direct File
Agent scans a watched directory once per minute. For example, if you start
Sterling Connect:Direct File Agent at 1:00 p.m., a file added to that watched
directory at 12:55 a.m. is not detected as newly added. If you start Sterling
Connect:Direct File Agent at 1:00 p.m., and a file is placed in the watched directory
at 1:01 p.m., then Sterling Connect:Direct File Agent detects this newly added file.
Sterling Connect:Direct File Agent detects a file only one time, unless the file is
accessed and saved with a later timestamp.
Using Sterling Connect:Direct File Agent requires an understanding of Sterling
Connect:Direct Processes, operating systems, and scripting (for regular expression
operator use with Sterling Connect:Direct File Agent rules).
Sterling Connect:Direct File Agent Operation
You can run Sterling 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 Sterling Connect:Direct File Agent is working correctly
or to specify an alternate configuration file. After you run Sterling Connect:Direct
File Agent from the command line to verify that Sterling Connect:Direct File Agent
is operating correctly, run it using the method that requires the least user
intervention.
When Sterling 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 Sterling
Connect:Direct File Agent whenever you restart the computer. On z/OS, you must
run the appropriate job to start the Sterling Connect:Direct File Agent configuration
interface, or start or shutdown the Sterling Connect:Direct File Agent.
Depending on your network and how you use Sterling Connect:Direct, there might
be more than one Sterling Connect:Direct File Agent running (on different hosts).
The first Sterling Connect:Direct File Agent that connects to a Sterling
Connect:Direct server becomes the Sterling Connect:Direct File Agent gate keeper.
The gate keeper port is used to keep track of locations monitored in case more
than one Sterling Connect:Direct File Agent are configured to watch a single
directory. The gate keeper ensures that only one Sterling Connect:Direct File Agent
detects a file that appears in a watched directory.
Sterling Connect:Direct File Agent Logging Capabilities
Sterling Connect:Direct File Agent logging capabilities vary by platform. Running
Sterling Connect:Direct File Agent from a command line using the verbose
argument turns on Sterling Connect:Direct File Agent logging when it is available.
When you run Sterling Connect:Direct File Agent as Microsoft Windows service, no
information is logged unless an error occurs.
Sterling Connect:Direct File Agent provides the following levels of status
information when logging is available on a platform:
v 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. If
you are not running in verbose mode, the system log appears in the snaps
directory (located in the Sterling Connect:Direct File Agent installation directory),
which is created when the first event occurs.
Chapter 2. Sterling Connect:Direct for UNIX Overview 59
v First Failing Status (FFS) log—One or more logs created when an error occurs.
The snaps directory is created as needed and contains the FFS logs for any
errors encountered by Sterling Connect:Direct File Agent.
Using trace commands provided for your platform can also help capture details
related to Sterling Connect:Direct File Agent operation.
Sterling Connect:Direct File Agent Configuration Interface and
Help
Instructions for configuring Sterling 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 Sterling Connect:Direct File Agent Configuration
Before you begin configuring Sterling Connect:Direct File Agent, you must use
Sterling Connect:Direct to choose or create the Processes that perform the actions
you want to automate. You will need to carefully configure Sterling Connect:Direct
File Agent to connect to the Sterling Connect:Direct server and to monitor and
detect conditions (such as a file addition to a directory). At detection, Sterling
Connect:Direct File Agent submits the Process for executing actions that need to be
performed in response to those conditions.
Refer to Sterling Connect:Direct for UNIX Configuration Examples to review some
configuration scenarios that can help you plan your Sterling Connect:Direct File
Agent configuration. When you configure Sterling 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 Sterling Connect:Direct File Agent configuration is working
correctly. After a successful test of the default configuration, you can run the
Sterling Connect:Direct File Agent Configuration Interface again to start building
and testing any Sterling 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 Sterling Connect:Direct File Agent Worksheet to gather the information to
configure Sterling Connect:Direct File Agent. Contact your system administrator for
the site-specific information to establish a connection to the Sterling Connect:Direct
server. As you complete the worksheet, run the Sterling Connect:Direct File Agent
Configuration Interface and use the Sterling 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 Sterling Connect:Direct File Agent on multiple
Sterling Connect:Direct servers.
IBM Sterling Connect:Direct Worksheet
Worksheet
Sterling Connect:Direct Server Connection Information
Userid for API (for connecting to the
Sterling Connect:Direct server) Required
Must match the user ID used to submit the
default Process.
60 Sterling Connect:Direct for UNIX 4.2.0: Documentation
Worksheet
Password for API (for connecting to the
Sterling 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 Sterling Connect:Direct server is
located) Required
API port (default =1363)1–5 digit port
number that Sterling Connect:Direct for
UNIX uses to connect to the Sterling
Connect:Direct server API. Required
Gatekeeper port (default=65530)Port used to
track directory monitoring and ensure that
multiple Sterling 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. RequiredList one valid entry
per line.
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 Sterling
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)
Chapter 2. Sterling Connect:Direct for UNIX Overview 61
If you are using X Windows, the X11 display variable is used to connect to the GUI
server for terminal emulation. The Sterling Connect:Direct File Agent Configuration
Interface will display on the monitor specified for the X11 display variable. If you
want to display the Sterling 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 Sterling Connect:Direct File Agent
Configuration Interface.
IBM Sterling Connect:Direct File Agent Configuration
Examples
The following examples illustrate three typical scenarios for using Sterling
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 Sterling 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 Sterling Connect:Direct server where
Sterling Connect:Direct File Agent is installed. The sample scenarios also assume
that the Sterling Connect:Direct Processes that will perform tasks associated with
Sterling 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. Sterling Connect:Direct File Agent can
be configured to perform the processing on a z/OS system:
v Monitor the watched data set called EASTERN.Q1.REPTS.
v 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
directories
Type EASTERN.Q1.REPTS to specify the fully qualified MVS
data set 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, Sterling Connect:Direct
File Agent is used to detect an event with IndexOutOfBoundsException in the title,
pass a string (the event title) to a Sterling Connect:Direct Process, and then submit
a Process to the Sterling 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
62 Sterling Connect:Direct for UNIX 4.2.0: Documentation
should investigate. Because the site uses a Sterling Connect:Direct mailbox system,
the configuration will include the administrator's account to be notified when
Sterling Connect:Direct File Agent submits a Process for the IndexOutOfBounds
rule.
The sample values in the following table accomplish the following processing:
v Override the default Process and submit \processfolder\oo_boundserrproc.cdp
v 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
Field Description/Example
Rules Create rule dialog box Type index out of bounds as the name of the rule you
are creating.
Match criteria list for rule
“index out of bounds”
window
Select the default criteria Not enabled: System event
title matches “ ” and click Edit match.
Edit match criterion for
rule “index out of
bounds” dialog box
v Click Enabled to enable the criteria you are about
to specify.
v Click System event title as the criterion to match
for the rule.
v Click Matches on the drop-down field to see the
options for comparison to a string.
v Click Contains to specify how the compare string
should relate to a system event title that Sterling
Connect:Direct File Agent detects.
v Type IndexOutoffBounds as the Compare String to
indicate that the system event title should include
this string.
v Click OK.
Submit Process
information for system
event rule “index out of
bounds” window
Type information into the fields that will define the
Process to submit and the mailbox user to notify after
the Process is submitted.
Process name field Type c:\processfolder\errproc.cdp to specify the path
and file name for the Process Sterling Connect:Direct
File Agent submits when a file meets the rule criteria.
Notification userid field Type adminjim@company.com to specify the user to
notify when Sterling Connect:Direct File Agent
submits the Process.
Example: Passing the UNIX Pathname for a Detected File to a
Process
Because Sterling Connect:Direct File Agent can watch multiple directories for the
appearance of a new file, the Sterling Connect:Direct Process that Sterling
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.
Chapter 2. Sterling Connect:Direct for UNIX Overview 63
Tab
Dialog box,
Window, or Field Sample Entry
File agent Watched directories Type one UNIX pathname per line for each location
Sterling Connect:Direct File Agent is to watch for the
appearance of files:
user/bin/monthend/
quartend/easterndiv/errorfiles
managers/special/reports
Sterling Connect:Direct File Agent checks these
pathnames for new files.
Default process Type the UNIX pathname and filename for the Sterling
Connect:Direct Process that Sterling Connect:Direct File
Agent is to run when a file appears in any watched
directory specified:
user/bin/admin/copynewfile.cdp
The pathname where Sterling Connect:Direct File
Agent detected a new file is passed to this Process.
Default arguments Type the Sterling 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 Sterling
Connect:Direct File Agent will pass the UNIX
pathname where the file was detected.
%FA_PATH_FOUND. is the Sterling Connect:Direct
File Agent variable used to indicate the information
to pass to the Sterling Connect:Direct Process.
About SNA LU6.2 Connections
The Sterling Connect:Direct for UNIX product supports SNA LU6.2 connections in
addition to TCP/IP connections.
Supported Interfaces
Following is a list of supported interfaces:
v Token ring
v Ethernet
v SDLC
v X.25 (QLLC)
Session Support
Sterling Connect:Direct for UNIX supports both independent and dependent LU6.2
sessions. Configuring independent LU sessions simplifies the management of
communication between nodes and ensures appropriate recovery in some
64 Sterling Connect:Direct for UNIX 4.2.0: Documentation
situations. Dependent LU sessions must be managed manually for communications
between Sterling Connect:Direct nodes and do not recover properly in some
situations.
The maximum number of independent LU sessions you configure defines the
maximum number of concurrent transfers between nodes. The total number of
sessions determines the number of UNIX transfers that can run simultaneously.
Type an even number for the maximum number of sessions so that you can divide
equally between the number of contention winner and contention loser sessions.
The recommended number of maximum sessions is 8. The recommended number
of contention winner sessions is 4. If supported, the recommended number of
automatically established sessions is 4.
APPC Requirements
APPC requirements are described in the following list:
v Sterling Connect:Direct for UNIX uses a fixed transaction program (TP) name,
NNV2DTF.
v Sterling Connect:Direct for UNIX uses basic conversations, sync level = confirm,
no conversation level security, and no PIP (program initialization parameters).
v Do not specify the transaction program (TP) name in hexadecimal.
Configuration Requirements
Configuration requirements are described in the following list:
v The Sterling Connect:Direct for UNIX daemon must start the session manager,
the LU6.2 communications component of Sterling Connect:Direct for UNIX. The
Sterling Connect:Direct for UNIX daemon monitors for inbound ALLOCATEs
and starts a session manager to handle the Process submitted by the remote
node. The SNA communications package cannot start a session manager.
v Do not configure the TP as dynamically attachable or as an autostart program.
v Do not configure a path name to a Sterling Connect:Direct for UNIX program
when you define the TP.
v For SNA packages that require that you provide a program name for a TP
definition, you must type a program name that does not exist.
SNA Considerations
SNA considerations are listed in the following section:
v Sterling Connect:Direct for UNIX is tested with the following link LU6.2 types.
Currently, not all link types are tested on all platforms.
– Token ring
– Ethernet
– SDLC leased line
– X.25 (QLLC)
v Sterling Connect:Direct for UNIX, as an LU6.2 conversation partner, supports
any defined link type supported by the SNA package manufacturer. There are no
special support or configuration requirements in Sterling Connect:Direct for
UNIX when using different link types to communicate with the remote node.
v The RU size selected for use with Sterling Connect:Direct for UNIX can strongly
affect the observed file transfer throughput. Sterling Connect:Direct for UNIX is
tested with 1K, 2K, and 4K RU sizes, with inbound and outbound pacing set to
Chapter 2. Sterling Connect:Direct for UNIX Overview 65
7. Use a 1K RU size to confirm basic functionality, and then use 2K and 4K RU
sizes while monitoring network congestion. You can realize a significant gain in
throughput by increasing RU sizes from 1K to 4K. Increasing the RU size
beyond 4K or increasing the pacing above 7 generally provides marginal
improvement, but can severely degrade network performance.
VTAM resource names must be typed in uppercase.
AIX SNA Server Configuration
For AIX SNA support, you must install and configure either the AIX SNA
Server/6000 or the eNetwork Communications Server. You can perform the
configuration manually or use the Sterling Connect:Direct for UNIX configuration
script. The script generates a set of communications profiles, which are used by
Sterling Connect:Direct for UNIX. Review and modify the values in the profile
entries to suit your environment.
The following sections provide the parameter definitions required by Sterling
Connect:Direct for UNIX and a description of the script included with Sterling
Connect:Direct.
Manually Configuring the AIX SNA Server
You can manually configure AIX SNA by modifying the values in the default
profile entries, as appropriate for your environment; however, Sterling
Connect:Direct requires that you add a TP profile name with specific parameters.
Procedure
1. Log in as root
2. Type one of the following commands:
v For AIX SNA Server/6000
mksnaobj -t’local_tp’ -c ’basic’ -w ’/usr/lpp/sna’ CDUTPPRO
v For eNetwork Communications Server
smitsnaadmin -x define_tp, tp_name=’CDUTPPRO’ conv_type=’BASIC’, \
security_rqd=’NO’, sync_level=’CONFIRM_SYNC_LEVEL’, pip_allowed=’YES’
The following table lists the parameters required by Sterling Connect:Direct.
You can assign default values to all other parameters.
Profile name
CDUTPPRO
Conversion type
basic
Full path to TP executable
/usr/lpp/sna
The path must be a valid directory that differs from the Sterling
Connect:Direct for UNIX installation directory.
About the Configuration Script
If you want to use a script to generate the Sterling Connect:Direct for UNIX
configuration for AIX SNA Server/6000 support, run the script located in
66 Sterling Connect:Direct for UNIX 4.2.0: Documentation
etc/cdsnacfg. After running the script, use SMIT to review the configuration to
ensure that the profile values are appropriate for your environment. Sample
profiles are provided as a reference.
Using the script, you can configure your IBM pSeries workstation for any of the
following options:
v Token ring
v SDLC leased line
Do not use the cdsnacfg script to configure more than one connection. The script
archives and deletes the current profile entries before adding values required by
Sterling Connect:Direct.
The script issues commands to perform the following tasks:
v Stop AIX SNA support.
v Back up the current configuration to /snadirs/sna_XXXX.sav, where XXXX is the
current month and day.
v Delete the current AIX SNA profiles. You can restore or merge saved profiles
with the smit importsna command.
v Regenerate base profiles.
v Configure AIX SNA support as required by Sterling Connect:Direct.
v Verify the AIX SNA configuration.
v Start AIX SNA support.
v Start the required SNA connections.
Running the Configuration Script
Procedure
1. Log in as root.
2. From the d_dir/etc directory, type the following command:
# cdsnacfg
The configuration script can run even if messages indicating irregular
processing are returned. Read any messages as you proceed through the
configuration. Refer to the AIX SNA documentation as required.
3. Do one of the following:
v Type 1 to select Token Ring as the connection type and press Enter. The
default is a token ring connection [1]. Go to step 5.
v Type 2 to select SDLC Lease Line as the connection type and press Enter. Go
to the next step.
4. Type the appropriate value for the following prompts or press Enter to select
the default as listed in the brackets. The token ring adapter name is an AIX
SNA assigned name. All other default values are samples that you can modify.
For a VTAM host, the Adjacent Control Point Name is the SSCPNAME. Type
host resource names in uppercase letters.
Chapter 2. Sterling Connect:Direct for UNIX Overview 67
Please enter Network Name ..................... [CDUNET] :
Please enter Adjacent Control Point Name ...... [HOSTCP] :
Please enter PU name .......................... [RS6PU01] :
Please enter Remote Link Address............... [400076543210] :
Please enter XID node ID....................... [07143210] :
Please enter local LU name .................... [RS6LU01] :
Please enter remote LU name (C:D MVS APPLID) .. [NDMAPP4] :
Please enter mode name ........................ [NDM621K] :
Please enter Token Ring Adapter name .......... [tok0] :
Please enter Token Ring Adapter name .......... [0]
5. Type the appropriate value for an SDLC leased line connection or press Enter
to select the default values in brackets. The Portmaster Adapter/A port name is
an AIX SNA assigned name. All other default values are samples that you can
modify. For a VTAM host, the Adjacent Control Point Name is the SSCPNAME.
Type host resource names in uppercase letters.
Please enter Network Name ..................... [CDUNET] :
Please enter Adjacent Control Point Name ...... [HOSTCP] :
Please enter PU name .......................... [RS6PU01] :
Please enter PU address (decimal).............. [02] :
Please enter local LU name .................... [RS6LU01] :
Please enter remote LU name (C:D MVS APPLID) .. [NDMAPP4] :
Please enter mode name ........................ [NDM621K] :
Please enter Portmaster Adapter/A port name ... [mpq0] :
6. Review the messages as the configuration script completes its final steps. If you
receive a message that Sterling Connect:Direct is unable to determine the
installed version of AIX SNA support, then perform the following steps:
v Verify your installation with SMIT.
v Run etc/snaver.sh to test for the correct installation of AIX SNA Server/6000.
v Rerun the cdsnacfg script.
For special considerations for connectivity between IBM pSeries and i5/OS
systems, refer to Connectivity Between IBM pSeries and i5/OS Systems.
Refer to the AIX SNA Server/6000 documentation for further information about
AIX SNA Server/6000.
HP SNAplus2 Configuration Requirements
For HP SNA support, you must install and configure HP SNAplus2API,
SNAplus2-Common, and SNAplus2-Link software. Perform the following steps to
configure your system:
Procedure
1. Use a text editor or xsnapadmin to create a configuration file named
/etc/opt/sna/sna_node.cfg.
2. Add the following entry to the /etc/opt/sna/sna_tps file:
["NNV2DTF"]
TYPE=QUEUED-BROADCAST
USERID=XXXXX
3. To start the SNA 3.0 support, log in as root and type the following command:
snap start
68 Sterling Connect:Direct for UNIX 4.2.0: Documentation
4. To validate or modify your configuration, start the local node, log in as root,
and type the following command:
snapadmin
For additional information about configuring for SNAplus2 10.10 connectivity,
refer to the Hewlett-Packard documentation.
The following example displays the contents of a file that contains the required
Sterling Connect:Direct AT&T Servers SNA 3.0 Invokable TP definition. This
file, sna_tps, is provided in the directory d_dir/etc.
["NNV2DTF"]
TYPE=QUEUED-BROADCAST
SNAP-IX SNA Gateway Support Configuration Requirements
For SNAP-IX support, you must install and configure the SNAP-IX SNA server
software. Documentation about SNAP_IX can be found at the following Web site:
http://www.dataconnection.com/sna/docs.htm or with the SNAP_IX product.
Procedure
1. Log on as root before executing any SNAP_IX commands.
2. Type the following command to start the SNAP_IX SNA Server application:
/opt/sna/bin/sna start
3. Create a configuration file that defines configuration statements for your
system, including the communications protocol. Either use the command line
program /opt/sna/bin/snaadmin to create or modify the /etc/opt/sna/
sna_node.cfg configuration file or use the /opt/sna/bin/X11/xsnaadmin
program to create or modify a configuration file. Refer to the SNAP_IX
documentation for a description of the available parameters.
4. Type the following command to define the NNV2DTF transaction program:
/opt/sna/bin/snaadmin
define_tp,tp_name=NNV2DTF,conv_type=BASIC,
sync_level=CONFIRM_SYNC_LEVEL, pip_allowed=NO
Following are sample statements in the file /etc/opt/sna/sna_tps, where
'xxxxxx' is a valid user ID.
[NNV2DTF]
LUALIAS = ""
DESCRIPTION = ""
USERID = xxxxxx
TIMEOUT = -1
TYPE = QUEUED-BROADCAST
Following is a sample configuration statement that is defined in the SNAP_IX
sna_node.cfg file and defines a SNAP_IX SNA Server for LU6.2 connectivity
between an Ethernet attached SUN Solaris 8 system and an z/OS mainframe. It
defines a single independent LU and one Sterling Connect:Direct node LU on
the mainframe. The VTAM resource names correspond to the samples.
Chapter 2. Sterling Connect:Direct for UNIX Overview 69
[define_node]
cp_alias = CDUPU01
description = Control Point Node
fqcp_name = CDUNET.CDUPU01
node_type = END_NODE
mode_to_cos_map_supp = YES
mds_supported = YES
node_id = <01702160>
[define_ethernet_dlc]
dlc_name = ETHER0
description = Ethernet dlc
neg_ls_supp = YES
initially_active = NO
adapter_number = 0
lan_type = 802_3_DIX
[define_ethernet_port]
port_name = ETSAP0
description = Ethernet Port 0
dlc_name = ETHER0
port_type = PORT_SATF
port_number = 0
max_rcv_btu_size = 1033
[define_ethernet_ls]
ls_name = ETHL0
description = Ethernet Link Station
port_name = ETSAP0
adj_cp_name = <0000000000000000000000000000000000>
adj_cp_type = LEARN_NODE
mac_address = <10005ad172fc>
solicit_sscp_sessions = YES
pu_name = ETHL0
[define_partner_lu]
plu_alias = NDMAPP4
description = QC.OS390.V4300 C:D Node
fqplu_name = CDUNET .NDMAPP4
plu_un_name = <0000000000000000>
parallel_sess_supp = YES
[define_local_lu]
lu_alias = CDULU01
list_name = ""
description = Local LU
lu_name = CDULU01
lu_session_limit = 0
pu_name = <0000000000000000>
[define_mode]
mode_name = NDM621K
description = NDM621K
default_ru_size = NO
max_ru_size_upp = 1024
[define_mode]
mode_name = NDM622K
description = NDM622K
default_ru_size = NO
max_ru_size_upp = 2048
70 Sterling Connect:Direct for UNIX 4.2.0: Documentation
[define_mode]
mode_name = NDM624K
description = NDM624K
default_ru_size = NO
max_ru_size_upp = 4096
Sample configuration statement (continued)
[define_directory_entry]
resource_name = CDUNET .CSDSA01
resource_type = ENCP_RESOURCE
description = MVSA SSCP
parent_name = <0000000000000000000000000000000000>
parent_type = ENCP_RESOURCE
[define_directory_entry]
resource_name = CDUNET .CSDSA01
resource_type = LU_RESOURCE
description = (Auto defined - default LU)
parent_name = CDUNET .CSDSA01
parent_type = ENCP_RESOURCE
[define_directory_entry]
resource_name = CDUNET .NDMAPP4
resource_type = LU_RESOURCE
description = QC.OS390.V4300 C:D Node
parent_name = CDUNET .CSDSA01
parent_type = ENCP_RESOURCE
[define_tp]
tp_name = NNV2DTF
description = C:D-UNIX TP
list_name = ""
conv_type = BASIC
security_rqd = NO
sync_level = NONE
enabled = YES
pip_allowed = NO
tp_instance_limit = 0
Brixton 4.1 SNA for Sun Solaris Requirements
For Brixton SNA support, use the procedures in this section to install and
configure the Brixton BrxPU2.1 SNA Server.
v For Brixton SNA support, Sterling Connect:Direct for UNIX requires Brixton
software packages BrxAPPC, BrxGMAN, BrxGMI, and BrxPU21
BrxGMAN
Brixton Gateway Manager
BRXGMI
Brixton Graphical Management Interface
BrxAPPC
Brixton LU6.2 and CPI-C APIs
v Sterling Connect:Direct for UNIX requires that you configure BrxGMAN,
BrxGMI, and BrxPU2.1 packages.
v The BrxGMI (Graphical Management Interface) generates a working
configuration that can be altered to match your needs.
Note: This is not an SNA configuration.
Configuring BrxGMAN Software
Perform the following steps to configure the BrxGMAN software:
Chapter 2. Sterling Connect:Direct for UNIX Overview 71
Procedure
1. Type the following commands to run the PU2.1 setup program:
# cd /opt/BrxPU21
# ./brxsetup
2. To configure the BrxGMAN software, type 1 and press Enter.
The BrxGMAN configuration file directory root is currently set to /etc/brixton.
The following prompt is displayed:
The BrxGMAN configuration file directory root is currently set to /etc/brixton.
Do you want to change it (Yes/No) [N]?
3. Type n and press Enter to use the default directory.
The BrxGMAN is configured for a site that runs a main DNS Server. The setup
script prompts you to change the setting.
4. Type n and press Enter to use the default DNS server configuration.
The following screen is displayed. The DNS domain name is currently set to
stercomm.com.
The DNS domain name is currently set to stercomm.com.
Do you want to change it (Yes/No) [N]?
5. Type n and press Enter to use the default DNS domain name.
The following prompt is displayed. The Brixton subdomain name is currently
set to csg.
The Brixton subdomain name is currently set to csg.
Do you want to change it (Yes/No) [N]?
6. Type n and press Enter to use the default Brixton subdomain name.
The following prompt is displayed. BrxGMAN product is set to startup
automatically each time your system reboots. The setup script prompts you to
change this setting.
The BrxGMAN product is set to startup automatically each time your system reboots.
Do you want to change it (Yes/No) [N]?
7. Type n and press Enter to continue to automatically start the BrxGMAN
product at startup.
The screen displays a prompt to verify the BrxGMAN configuration:
8. Type y and press Enter to confirm the configuration.
Configuring BrxGMI Software
To configure the BrxGMI software.
Procedure
1. Type 2 and press Enter.
The following screen prompts you to change the current Help browser.
The BrxGMI help browser is currently set to mosaic.
Do you want to change it (Yes/No) [N]?
72 Sterling Connect:Direct for UNIX 4.2.0: Documentation
2. Type n and press Enter to use the default browser.
The script prompts you to change the working directory.
3. Type n and press Enter to use the default BrxGMI working directory.
The script prompts you to verify the configuration.
4. If the configuration is correct, type y and press Enter.
Configuring BrxPU21 Software
To configure the BrxPU21 software:
Procedure
1. Type 3 to and press Enter configure BrxPU21. The setup script prompts you to
change the working directory.
2. Type n and press Enter. The setup script prompts you to change the root
directory.
3. Type n and press Enter. The setup script prompts you to change the startup
setting.
4. Type n and press Enter.
5. If the configuration is correct, type y and press Enter.
Starting BrxGMAN
To start the BrxGMAN software:
Procedure
1. Type 5 to start the BrxGMAN and press Enter.
2. Type the following command to start the Graphical Manager and configure
SNA LU6.2 definitions:
#./brxgmi.sh
Refer to the Brixton documentation for additional information about
configuring the UNIX system for Brixton SNA connectivity.
Sample Brixton BrxPU2.1 Configuration
Sterling Connect:Direct for UNIX supports platforms running Brixton SNA 4.1
Server for LU6.2 connectivity. The following sample displays a sample Brixton 4.1
SNA definition for a token ring-attached workstation. This file template is
provided in the directory d_dir/etc. The VTAM resource names correspond to the
samples given in this appendix:
Chapter 2. Sterling Connect:Direct for UNIX Overview 73
// Brixton BrxPU2.1 SNA Server Sample Configuration -
Sterling Connect:Direct for UNIX//
CP
NAME = CDUPU01
NQ_CP_NAME = CDUNET.CDUPU01
;
LU
COMMENT = "LOCAL ILU"
NAME = CDULU01
LUTYPE = 6.2
PACING = 0
SESS_LMT = 8
;
TRLINE
COMMENT = "NCP Token Interface"
NAME = NCPTIC
SOURCE_ADDRESS = X’400050000000’
LAN_RATE = RING_16Mbs
;
PU2
COMMENT = "VTAM PU"
NAME = CDUPU01
LINK_NAME = NCPTIC
MAXDATA = 2057
ROLE = Negotiable
TERMID = X’05700004’
ALS_CONNECT = Active
LMT_RES = No
ACTPU_SUPPRESS = No
RMTTERMID = X’05700004’
RMTNQ_CP_NAME = CDUNET.HOSTCP
RMTMACADDR = X’400050000004’
;
PTNR_LU
NAME = NDMAPP4
LOC_LU_NAME = CDULU01
INIT_TYPE = INITIATE_OR_QUEUE
;
MODE
NAME = NDM624K
PTNR_LU_NAME = NDMAPP4
DLC_NAME = CDUPU01
SND_MAX_RU_LB = 8
RCV_MAX_RU_LB = 8
PREF_SND_RU = 4096
PREF_RCV_RU = 4096
LCL_MAX_SESS_LMT = 8
MIN_CW_SESS = 4
MIN_CL_SESS = 4
CW_AUTOACT_LMT = 4
AUTOINIT_SL = Yes
;
TP
TP_NAME = NNV2DTF
LOC_LU_NAME = CDULU01
CONV_TYPE = BASIC
SYNC_LVL = CONFIRM
PIP = NO
PRIVILEGE = NONE
;
The LU SESS_LMT must be 2 greater than the MODE LCL_MAX_SESS_LMT.
The i5/OS definitions include the following in the DLC directive:
74 Sterling Connect:Direct for UNIX 4.2.0: Documentation
RMTNQ_CP_NAME=CDUNET.CP_NAME //Rmt Network Qualified Name
After running the Brixton configuration for the i5/OS connection, change the
i5/OS device description to match the Mode_Name defined in the Brixton
configuration.
Configuring SunLink SNA 9.1 Support for Sun Solaris
For SunLink SNA support, use the following procedure to install and configure the
SunLink SUNWpu2.1 SNA server. For SunLink SNA support, configure the
SunLink software packages: SUNWlu62, SUNWgmi, SUNWgman, and SUNWpu21.
Sterling Connect:Direct for UNIX requires that you configure SUNWgman,
SUNWgmi, and SUNWpu21 packages. The SUNWgmi (Graphical Management
Interface) generates a working configuration that can be altered to match your
needs. This is not an SNA configuration.
Procedure
1. Type the following commands to run the PU2.1 setup program:
# cd /opt/SUNWPU21
# ./sunsetup
2. Type 1 to configure the SUNWgman software. You are prompted you to
change the root directory:
3. Type n and press Enter.
4. Type n and press Enter.
The setup script prompts you to change the DNS domain name.
5. Type n and press Enter. The setup script prompts you to change the startup
option.
6. Type n and press Enter.
The following message prompts you to verify the SUNWgman configuration.
7. Do one of the following:
v If the configuration is correct, type y and press Enter.
v If necessary, type new parameters for each option. Type y and press Enter.
8. To configure the SUNWgmi software, type 2. The following message prompts
you to change the current Help browser.
9. Type n and press Enter. The script prompts you to change the working
directory.
10. Type n and press Enter. The script prompts you to verify the configuration.
11. Do one of the following:
v If the configuration is correct, type y and press Enter.
v If necessary, type new parameters for each option. Type y and press Enter.
12. Type 3 to configure SUNWpu21 and press Enter. The setup script prompts
you to change the working directory.
13. Type n and press Enter. The setup script prompts you to change the root
directory.
14. Type n and press Enter. The setup script prompts you to change the startup
setting.
15. Type n and press Enter. The setup script prompts you to verify the
configuration.
Chapter 2. Sterling Connect:Direct for UNIX Overview 75
16. Do one of the following:
v If the configuration is correct, type y and press Enter.
v If necessary, type new parameters for each option. Type y and press Enter.
You are prompted you to select a task.
17. Type 4 to start the SUNWgman.
18. Type the following command to configure SNA LU6.2 definitions:
#./sungmi.sh
Sample z/OS Definitions for an LU6.2 Connection
This section provides samples of the z/OS NCP and VTAM definitions required for
LU6.2 connectivity between Sterling Connect:Direct for UNIX and Sterling
Connect:Direct for z/OS. A sample Sterling Connect:Direct for z/OS network map
definition is also included.
Token Ring 3174-R Gateway Controller Configuration
The following sample displays sample line, PU, and LU definitions used by VTAM
to define a token ring 3174-R gateway controller for an LU6.2 connection:
76 Sterling Connect:Direct for UNIX 4.2.0: Documentation
REAL 3174 CONTROLLER, FUNCTIONS AS THE GATEWAY CONTROLLER
D1IRR1 PU ADDR=01,
DATMODE=HALF, *
MAXDATA=521, *
MAXOUT=7, *
PACING=2, *
PUDR=YES, *
DLOGMOD=SNX32702, *
MODETAB=DALLMTAB, *
USSTAB=LSUSSTAB, *
SSCPFM=USSSCS, *
PUTYPE=2, *
DISCNT=(NO), *
SECNET=NO, *
VPACING=4, *
XID=YES, *
ISTATUS=ACTIVE *
* COAX PORTS
D1IRR102 LU LOCADDR=2,ISTATUS=ACTIVE
D1IRR103 LU LOCADDR=3,ISTATUS=ACTIVE
D1IRR104 LU LOCADDR=4,ISTATUS=ACTIVE
D1IRR105 LU LOCADDR=5,ISTATUS=ACTIVE
D1IRR106 LU LOCADDR=6,ISTATUS=INACTIVE
D1IRR107 LU LOCADDR=7,ISTATUS=INACTIVE
D1IRR108 LU LOCADDR=8,ISTATUS=INACTIVE
D1IRR109 LU LOCADDR=9,ISTATUS=INACTIVE
* FOR LU6.2 ILU
CDULU01 LU LOCADDR=0,DLOGMOD=NDM621K,RESSCB=5,ISTATUS=ACTIVE
CDULU02 LU LOCADDR=0,DLOGMOD=NDM621K,RESSCB=5,ISTATUS=ACTIVE
CDULU03 LU LOCADDR=0,DLOGMOD=NDM621K,RESSCB=5,ISTATUS=ACTIVE
CDULU04 LU LOCADDR=0,DLOGMOD=NDM621K,RESSCB=5,ISTATUS=ACTIVE
*
**********************************************************************
* DOWNSTREAM PU OFF OF THE REAL 3174 GATEWAY CONTROLLER *
* INDEPENDENT LU6.2 *
***********************************************************************
CDUPU01 PU ADDR=02, *
DATMODE=HALF, *
MAXDATA=521, *
MAXOUT=7, *
PACING=2, *
PUDR=YES, *
DLOGMOD=SNX32702, *
MODETAB=DALLMTAB, *
USSTAB=LSUSSTAB, *
SSCPFM=USSSCS, *
PUTYPE=2, *
DISCNT=(NO), *
SECNET=YES, *
VPACING=4, *
ISTATUS=ACTIVE
*
DISPLAY2 LU LOCADDR=2,ISTATUS=ACTIVE
DISPLAY3 LU LOCADDR=3,ISTATUS=ACTIVE
The 3174-R token ring gateway requires that the IBM pSeries token ring adapter
address match the address configured in the 3174-R.
Token Ring 3745 Token Ring Interface Coupler (TIC)
Configuration
The following figure displays sample line, PU, and LU definitions used by VTAM
to define a token ring TIC for an LU6.2 connection:
Chapter 2. Sterling Connect:Direct for UNIX Overview 77
M1IRGPGP GROUP ECLTYPE=PHYSICAL PHYSICAL GROUP
* NTRI PHYSICAL LINE DEFINITION
M1IRG LINE ADDRESS=(1088,FULL), LAN *
LOCADD=400076543210, ’SOFT’ ADDRESS FOR TIC *
MAXTSL=4060, RANGE 265 TO 16732 *
OWNER=SA01, MVS OWNS THIS LINE *
NPACOLL=YES, NPM *
PORTADD=0, WHERE ACRS3LGP POINTS TO *
RCVBUFC=1440, RANGE 6*BFRS TO 4095 *
ADAPTER=TIC2, TIC2 *
TRSPEED=4, SPEED OF LAN *
SPAN=(8000) NETVIEW OPERAND
M1IRG1 PU SPAN=(8000)
M1IRG100 LU ISTATUS=INACTIVE, IBM RECOMMENDED *
SPAN=(8000) NETVIEW OPERAND
M1IRGLGP GROUP ECLTYPE=LOGICAL, LOGICAL GROUP *
CALL=INOUT, ALLOW DIAL IN AND DIAL OUT *
NPACOLL=YES, NPM *
OWNER=SA01, MVS OWNS THIS LINE GROUP *
PHYPORT=0, POINTS TO ACRS3 LINE PORTADD *
SPAN=(8000), NETVIEW OPERAND *
TYPE=NCP NETWORK CONTROL MODE
M1IRGT00 LINE AUTOCOPY=(35,M1IRGT01,D)
M1IRGP00 PU NEXT=(M1IRGP01,D)
ENDAUTO
********************************************************************** *
TOKEN RING NTRI SWITCHED SNA DEFINITION *
**********************************************************************
M1T2001 VBUILD TYPE=SWNET
CDUPU01 PU ADDR=01, *
PUTYPE=2, *
DISCNT=NO, *
MAXOUT=7, *
PASSLIM=7, *
ISTATUS=ACTIVE, *
IDBLK=071, *
IDNUM=43210, *
SSCPFM=USSSCS, *
MODETAB=DALLMTAB, *
USSTAB=LSUSSTAB, *
DLOGMOD=NDM621K
CDULU01 LU LOCADDR=0,DLOGMOD=NDM621K,RESSCB=5
VTAM Application Definition
The following figure shows a VTAM application (APPL) definition for an LU6.2
connection between Sterling Connect:Direct for z/OS and Sterling Connect:Direct
for UNIX:
78 Sterling Connect:Direct for UNIX 4.2.0: Documentation
NDMAPP4 APPL ACBNAME=NDMAPP4, VTAM APPLICATION ID *
APPC=YES, ENABLE TO RUN LU6.2 SESSIONS *
AUTH=(ACQ,NOCNM,NOPASS,NOPO,NOTSO,VPACE), *
EAS=6, APPROXIMATE # OF CONCURRENT SESS *
MODETAB=NDMTAB, MODE TABLE NAME *
SONSCIP=NO, NO UNBIND IN SCIP EXIT *
SRBEXIT=NO, NO SRB PROCESSING *
VPACING=7, RECEIVE PACING OF 7 *
DLOGMOD=NDMLOGM, MODE TABLE ENTRY *
PARSESS=YES, PARALLEL SESSIONS CAN BE USED *
DSESLIM=8, # OF CONCURRENT LU6.2 SESSIONS *
DMINWNL=4, # OF LOCAL CONTENTION WINNERS *
DMINWNR=4, # OF REMOTE CONTENTION WINNERS *
AUTOSES=4, # OF AUTOMATIC LU6.2 SESSIONS *
DDRAINL=ALLOW, ALLOW CNOS TO DRAIN SESSIONS *
DRESPL=ALLOW, DEF RESPONSIBILITY FOR LOCAL CNOS*
VTAMFRR=NO
VTAM Logmode Table Entries
The following figure displays a sample mode table entry for an LU6.2 connection
using a 1-K RU.
* LU6.2 LOGMODE
*
NDM621K MODEENT LOGMODE=NDM621K, *
TYPE=1, *
COS=NJE, *
FMPROF=X’13’, *
TSPROF=X’07’, *
PRIPROT=X’B0’, *
SECPROT=X’B0’, *
COMPROT=X’D0B1’, *
RUSIZES=X’8787’, 1K SEND AND RECV RUSIZE *
PSERVIC=X’060200000000000000000300’
The following figure displays a sample mode table entry for an LU6.2 connection
using a 4-K RU:
* LU6.2 LOGMODE
*
NDM624K MODEENT LOGMODE=NDM624K, *
TYPE=1, *
COS=NJE, *
FMPROF=X’13’, *
TSPROF=X’07’, *
PRIPROT=X’B0’, *
SECPROT=X’B0’, *
COMPROT=X’D0B1’, *
RUSIZES=X’8989’, 4K SEND AND RECV RUSIZE *
PSERVIC=X’060200000000000000000300’
NTRI Switched Major Node Definition
The following figure displays a sample token ring NTRI switched SNA definition
for an LU6.2 connection between Sterling Connect:Direct for z/OS and Sterling
Connect:Direct for UNIX:
Chapter 2. Sterling Connect:Direct for UNIX Overview 79
*
CDUPU VBUILD TYPE=SWNET
*
CDUPU01 PU ADDR=01, X
PUTYPE=2, X
IDBLK=071, X
IDNUM=54321, X
SSCPFM=USSSCS, X
MODETAB=DALLMTAB, X
USSTAB=RSUSSTAB, X
DLOGMOD=NDM621K
ILU CDRSC Definitions
The following figure displays a sample VTAM 3.4 CDRSC definition for
independent LUs used between Sterling Connect:Direct for z/OS and Sterling
Connect:Direct for UNIX:
*CDULU VBUILD TYPE=CDRSC
*
CDULU01 CDRSC ISTATUS=ACTIVE, X
ALSLIST=CDUPU01, ADJ LINK STATION X
MODETAB=DALLMTAB, LOGON MODE TABLE X
DLOGMOD=NDM621K, LOGON MODE TABLE ENTRY X
RESSCB=5 SESSION CONTROL BLOCKS
*
CDULU02 CDRSC ISTATUS=ACTIVE, X
ALSLIST=CDUPU01, ADJ LINK STATION X
MODETAB=DALLMTAB, LOGON MODE TABLE X
DLOGMOD=NDM624K, LOGON MODE TABLE ENTRY X
RESSCB=5 SESSION CONTROL BLOCKS
*
CDULU03 CDRSC ISTATUS=ACTIVE, X
ALSLIST=CDUPU01, ADJ LINK STATION X
MODETAB=DALLMTAB, LOGON MODE TABLE X
DLOGMOD=NDM621K, LOGON MODE TABLE ENTRY X
RESSCB=5 SESSION CONTROL BLOCKS
*
CDULU04 CDRSC ISTATUS=ACTIVE, X
ALSLIST=CDUPU01, ADJ LINK STATION X
MODETAB=DALLMTAB, LOGON MODE TABLE X
DLOGMOD=NDM622K, LOGON MODE TABLE ENTRY X
RESSCB=5 SESSION CONTROL BLOCKS
Sterling Connect:Direct Remote Node Entry
The following sample displays a UNIX remote node definition for the Sterling
Connect:Direct for z/OS network map. You must specify an LU6.2 logmode entry:
ADJACENT.NODE=(PARSESS=(6, 2) -
(UNIX.LU62.DALLAS, CDULU01, , LU62) -
LOGMODE=NDM621K -
ENVIRONMENT=UNIX)
Special Considerations When Configuring LU6.2
This information applies to the following operating systems:
v HP SNA
v SNAP-IX
80 Sterling Connect:Direct for UNIX 4.2.0: Documentation
After you install Sterling Connect:Direct for UNIX, the file pointed to by the
comm.info parameter (default name hostl1) is located in the same directory as the
configuration files. This file includes communications information for the SNA
configuration.
To configure an LU6.2 connection, modify the values for local_lu, remote_lu, and
mode. These names must correspond to the names defined in the SNA package.
The local_lu field is a required field. The following figure displays the contents of
the hostl1 file:
comm.info:\
:local_lu=LOCAL_LU:\
:remote_lu=REMOTE_LU:\
:mode=HOSTMODE:
The following figure displays values for lu and mode that correspond to the
sample MVS definitions for an LU6.2 connection as illustrated in Token Ring
3174-R Gateway Controller Configuration.
comm.info:\
:local_lu=CDULU01:\
:remote_lu=NDMAPP4:\
:mode=NDM624K:
Obtaining Traces for the Brixton LU6.2 API and SunLink P2P
The trace comm command also provides Brixton LU6.2 API and SunLink P2P
tracing control.
To activate the Brixton LU6.2 API and SunLink P2P traces, type the following
command:
trace comm level=2|3|4
To deactivate the Brixton and SunLink traces, type the following command:
trace comm level=0|1
Trace files are created in the directory where Sterling Connect:Direct for UNIX is
started. Refer to the Brixton documentation and the SunLink documentation for
additional details.
Stopping Sterling Connect:Direct on SNA Systems
Before you begin
When running Sterling Connect:Direct for UNIX with the LU6.2 on an HP SNA,
AT&T Global Information Solutions SNA, or Brixton SNA system, you must issue
the following command to stop Sterling Connect:Direct:
Direct> stop force;
Connectivity Between IBM pSeries and i5/OS Systems
To configure IBM pSeries to i5/OS connections, run the cdsnacfg script on the
pSeries. You must then modify the default AIX SNA Server/6000 configuration to
allow the automatic i5/OS configuration to build the appropriate connections.
Chapter 2. Sterling Connect:Direct for UNIX Overview 81
Before you begin
To modify the default AIX SNA Server/6000 configuration, type the following
commands. PUNAME is the PU name typed in the cdsnacfg script.
chsnaobj -t’sna_dlc_token_ring’ -b ’no’ trdlcl1
chsnaobj -t’link_station’ -w’token_ring’ -y ’trdlcl1’ -a ’no’ PUNAME
AIX SNA Error Messages
AIX SNA return codes are documented in the AIX SNA Server/6000: Transaction
Program Reference or in the file /usr/include/luxsna.h.
Setting Up Sterling 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. Sterling
Connect:Direct stores its manual pages in d_dir/ndm/man1,where d_dir is the
Sterling Connect:Direct installation directory.
2. Type the following command to copy the Sterling Connect:Direct manual pages
into the UNIX manual pages directory:
% 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 Sterling Connect:Direct manual pages
that you combined with UNIX manual pages, where command can be cdpmgr,
ndmxlt, or ndmmsg:
% man command
Accessing Sterling Connect:Direct Manual Pages
On an HP PA-RISC system, you must set the environment variable, MANPATH, to
locate the Sterling Connect:Direct manual pages.
Procedure
1. Type the following to access Sterling Connect:Direct manual pages on an HP
PA-RISC using the B shell, where command can be cdpmgr, ndmxlt, or ndmmsg:
$ MANPATH=/usr/man:/usr/contrib/man:d_dir/ndm/man1
$ export MANPATH
$ man command
2. On an HP PA-RISC system, set the environment variable, MANPATH, to locate
the Sterling Connect:Direct manual pages.
82 Sterling Connect:Direct for UNIX 4.2.0: Documentation
3. Type the following command to access Sterling Connect:Direct manual pages
on an HP PA-RISC using the C shell, where command can be cdpmgr, ndmxlt,
or ndmmsg:
% setenv MANPATH /usr/man:/usr/contrib/man:d_dir/ndm/man1
% man command
4. Type the following command to access Sterling 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
Chapter 2. Sterling Connect:Direct for UNIX Overview 83
84 Sterling Connect:Direct for UNIX 4.2.0: 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 Sterling Connect:Direct in test mode.
Maintaining configuration files
Configuration files define the operating environment for IBM Sterling
Connect:Direct. The following configuration files are created during the
customization procedure:
v Initialization parameters file
v Client configuration parameters file
v Network map file
v 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.
Sample format of a configuration file
The following table displays a portion of the initialization parameters file to
illustrate the format of Sterling Connect:Direct configuration files:
© Copyright IBM Corp. 1993, 2016 85
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 Sterling Connect:Direct connection
information
# indicates a comment
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 Sterling Connect:Direct configuration files using any text editor or
create a new configuration file using the cdcust command provided with Sterling
Connect:Direct for UNIX.
v Modifying configuration files with a text editor—You can modify Sterling
Connect:Direct configuration files with any text editor, such as vi editor.
v Creating configuration files with cdcust—Type the following command to start
the customization procedure, where d_dir is the Sterling Connect:Direct for UNIX
path name:
$ d_dir/etc/cdcust
Maintaining the initialization parameters file
Initialization parameters determine various Sterling Connect:Direct settings that
control system operation. The initialization parameters file is created when you
install Sterling Connect:Direct for UNIX and can be updated as needed.
You can modify Sterling Connect:Direct initialization parameters file using any text
editor. Before changing a value in the file, first shut down the Sterling
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.
You can also use the Sterling Connect:Direct Browser User Interface to perform
some of the procedures related to the initialization parameters file. To learn more
86 Sterling Connect:Direct for UNIX 4.2.0: Documentation
about the Sterling Connect:Direct Browser User Interface, see the documentation
related to that product in the IBM Documentation Library. If you use Sterling
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 Sterling 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:
v Parameters—Provide information including the name of the Sterling
Connect:Direct for UNIX node; the location of Sterling 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.
v Remote node connection information—The rnode.listen record includes
parameters to monitor inbound connections.
v Transmission Control Queue (TCQ) information—The tcq record defines how
long a Process is held in error before being deleted.
v 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.
v Global run task parameters—The runtask.parms record defines a parameter to
define the restart option.
v 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.
v Server authentication information—The authentication record parameters to
authenticate the server.
v User exit parameters—The user.exits record defines the programs used during a
user exit procedure.
v 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.
v AIX zFBA option—The zFBA parameter enhanced performance of large file
transfers between z/OS and AIX.
v 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.
v 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.
Chapter 3. Administration Guide 87
Sample initialization parameters file
The following example shows how some of these parameters are specified:
# 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:
# 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 Sterling Connect:Direct uses.
Required parameters are displayed in bold.
88 Sterling Connect:Direct for UNIX 4.2.0: Documentation
Path record
The ndm.path record identifies the path to Sterling Connect:Direct files. The
following table describes the parameter available for this record:
Parameter Description Value
path The path to all Sterling Connect:Direct
subdirectories and files.
path specification
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 on a cluster file system (not an
NFS). 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.
Note: Specify the same path for all nodes in a
cluster.
path
specification
Node name record
The ndm.node record identifies the name of the Sterling Connect:Direct node. The
following table describes the parameter available for this record:
Parameter Description Value
name The name of the
node.
The maximum length is 16 bytes. If a node name is
longer, 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 Sterling Connect:Direct Processes. If the service
initialization parameter is defined and if PAM is installed on the Sterling
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 Sterling Connect:Direct is operating in a
“test” mode. Use this record in conjunction with the NDMPXTBL table to enable
Chapter 3. Administration Guide 89
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
Sterling Connect:Direct.
y | n
y—Enables the test mode.
n—Disables the test mode.
The default is n.
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
special characters are allowed.
y | n
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
90 Sterling Connect:Direct for UNIX 4.2.0: Documentation
Parameter Description Values
comm.info The information needed to monitor connection requests
from remote nodes using TCP/IP or LU6.2. This
parameter is required.
v For TCP/IP connections, specify the host name or the
IP address and port number. If specifying an IP address
and port, separate parameters with a semicolon (;).
Separate multiple addresses/host names with a
comma, for example: 10.23.107.5;1364,
fe00:0:0:2014::7;1364, msdallas-dt;1364
For more information on specifying IP addresses and
host names, see IP Addresses, Host Names, and Ports.
v For LU6.2 connections, identify the profile name to
identify the name of an SNA configuration profile for
the remote connection. Sterling Connect:Direct
generates the default name, hostl1, during the
customization procedure. For AIX SNA, hostl1 refers to
the side information profile name. For HP SNA,
SunLink SNA, and Brixton SNA, hostl1 refers to the
SNA profile file located in the same directory as the
configuration files.
For TCP/IP connections, specify
the host name or the IP address
and port number:
10.23.107.5;1364
Separate multiple IP/host
addresses with a comma (,):
fe00:0:0:2014::7;1364,
msdallas-dt;1364
A space can be added after the
comma for readability.
Set the IP address to monitor 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 | udt33
tcp—For TCP/IP connections
lu62—For AIX SNA LU6.2
connections
blklu62—For other LU6.2
connections
udt33—For UDT 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
Process with Held-in-Error status
remains in the TCQ before it is
automatically deleted.
A three-digit decimal number.
Sterling Connect:Direct does not
automatically delete Processes when
max.age=0.
The default is 8 days.
ckpt.max.age The maximum number of days a
Process' checkpoint file is stored
on a disk unused before it is
automatically deleted.
An integer 0 - 2147483647. Sterling
Connect:Direct does not
automatically delete the checkpoint
file 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.
Sterling Connect:Direct Secure Plus record
The Sterling Connect:Direct Secure Plus record (Secure+ record) provides
information pertaining to remote configuration of Sterling Connect:Direct Secure
Chapter 3. Administration Guide 91
Plus from the Sterling 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:
Parameter Description Value
certificate.directory Specifies a default certificate directory for Secure+
commands issued from the Sterling Connect:Direct client
API. If the certificate directory is not configured, the
default directory created during installation is used.
Directory path name
s+cmd.enforce.secure.
connection
Specifies whether Secure+ commands are accepted from
the Sterling Connect:Direct client API on unsecure
connections.
y | n
y—Commands from
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
Sterling 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
operation before a checkpoint is taken. Following is
a list of the maximum number of digits for each
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
The maximum possible value is
1 terabyte (TB). The normal value
is 64KB.
ulimit The action taken when the limit on a user output
file size is exceeded during a copy operation.
n—Ignores the limit. n is the
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 translation
tables.
Any valid directory.
The default path is
d_dir/ndm/xlate.
92 Sterling Connect:Direct for UNIX 4.2.0: Documentation
Record Description Value
xlate.send The default translation table used when sending
data to a remote node.
Any valid directory.
The default file name is
def_send.xlt.
xlate.recv The name of the default translation table used when
copying data from a remote node.
The default file name is
def_recv.xlt in the directory
defined in the xlate.dir parameter.
continue.on.exception The method to use to handle an exception condition
in a Process. If a step fails due to a STOP
IMMEDIATE or FLUSH exception issued on the
remote node, the Process is placed in the Hold HE
queue, regardless of the value of this parameter.
y—Continues Processing with the
next step.
n—Places a Process in the Hold
queue with a value of HE.
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
maintaining the internal compression state.
1–9. The default is 4.
1—Uses the least memory and 9
uses the most memory.
ecz.windowsize The size of the compression window and history
buffer. The larger the window, the greater the
compression. However, increasing the window uses
more virtual memory.
Valid values are 9–15. The default
is 13.
retry.codes The codes to recognize as a file allocation retry
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.
Any valid error code
Chapter 3. Administration Guide 93
Record Description Value
retry.msgids Identifies the message IDs to use to support a file
allocation retry attempt.
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.
Any of the valid file allocation
retry messages.
tcp.crc Globally turn on or off the CRC function for TCP/IP
Processes.
y | n
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
Process statement overrides for CRC checking are
allowed. If this value is set to n, setting overrides
for CRC checking will be ignored.
y | n
y—Allows netmap remote node
and Process statement 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
stripped from the end of a record. If strip.blanks is
not defined in the initialization parameter, the
default value of i is used.
y | n | i
y—Strips blanks from the end of
a record
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:
v z/OS, VM, VSE, and i5OS—y
v All other platforms—n
insert.newline Arbitrarily appends an LF character at the end of
each record when receiving a datatype=text file. By
default, an LF character is not appended if one
already exists at the end of a record.
y | n
y—Arbitrarily appends an LF
character
n—Appends an LF character if
needed
94 Sterling Connect:Direct for UNIX 4.2.0: Documentation
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, Sterling Connect:Direct attempts to synchronize
the previous run task step on the SNODE with the current run task step. If
synchronization fails, Sterling 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 on an SNODE step is executing
and if synchronization fails after a
restart, Sterling Connect:Direct reads
the restart parameter to determine
whether to perform the run task step
again. Set this parameter in the
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.
y | n
y—The run task program runs
again. The default is y.
n—The Process skips the run
task step.
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 statistics data file. The statistics
file name is written in the format of
Syyyymmdd.ext, where yyyy indicates year,
mm indicates month, and dd indicates day.
The extension (ext) begins as 001. When a
statistics file reaches the defined size within
a 24-hour period, a new file is created with
the same file name. The extension value is
incremented by one.
nnnnnnnn, nnnnnnnnK,
nnnnnnnM, or
nnnnG—Establishes a
default output file size
limit for the statistics
files. K denotes 1024
bytes. M denotes
1048576 bytes. G
denotes 1073741824
bytes. The maximum
value you can specify is
1 TB.
log.commands Determines whether commands are written
to the statistics file. If you want to log all
commands except the select statistics and
select process commands, set this parameter
to y and the log.select parameter to n.
y | n
y—Commands are
written to the statistics
file.
n—Commands are not
written to the statistics
file. The default is n.
Chapter 3. Administration Guide 95
Parameter Description Value
log.select Specifies whether Sterling Connect:Direct
creates a statistics record when a select
process or select statistics command is
executed.
y | n
y—A statistics record is
created.
n—A statistics record is
not created. The default
is n.
max.age Specifies how old a statistics file must be
before it is archived. Once a day, a shell
script is executed that identifies the
statistics files that are as old as 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.
A 3-digit decimal
number. The default is 8
days.
0—no archiving.
Running a Process generates multiple statistics records. To accommodate the large
number of statistics records generated, Sterling 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.
Sterling 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.
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 during the authentication procedure.
The default is
ndmauths.
96 Sterling Connect:Direct for UNIX 4.2.0: Documentation
Parameter Description Value
server.keyfile The name and location of the key file used
during the authentication procedure.
The default is
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
user exit procedure. This exit is given control for
each statistics record that is written.
Name of the gateway control
program.
file.open.exit.program The file open exit program used during the user
exit procedure. It enables you to control file 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).
Name of the file open exit
program.
security.exit.program The security exit program used during the user
exit procedure. This exit generates and verifies
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.
Name of the security exit program.
security.exit.flag Modifies the default behavior of
security.exit.program. This is an optional
parameter.
snode_sec_exit_only |
sec_exit_only
snode_sec_exit_only— Causes
Sterling Connect:Direct to use the
security exit, when it is acting in
the role of the SNODE. After
Sterling 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 Sterling Connect:Direct is
the PNODE.
sec_exit_only—Causes Sterling
Connect:Direct to always use the
security exit. After Sterling
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
Chapter 3. Administration Guide 97
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.
fsync.after.receive parameter
Files written and closed by C:D on NFS destination may not be immediately ready
for processing due to NFS delayed writes; to avoid this, fsync was added to the
initparm to optionally call fsync function to attempt to flush all data to disk before
closing the file.
Parameter Description Value
fsync.after.receive.initparm The fsync.after.receive initparm is part of the
copy.parms record.
[y|n]. Default is y.
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
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.
[y|n]. Default is y.
Firewall navigation record
The firewall navigation record, called firewall.parms, enables you to assign a
specific TCP/IP and UDT source port number or a range of port numbers with a
particular TCP/IP and UDT address for outbound Sterling Connect:Direct sessions.
These ports also need to be open on the firewall of the trading partner to allow the
inbound Sterling Connect:Direct sessions. This feature enables controlled access to
an Sterling Connect:Direct server if it is behind a packet-filtering firewall without
compromising security policies.
Before you configure firewalls for use with UDT, review all information regarding
firewall navigation and rules beginning with Firewall Navigation.
The following parameters are available for this record:
98 Sterling Connect:Direct for UNIX 4.2.0: Documentation
Parameter Description Value
tcp.src.ports
For TCP/IP connections, remote IP addresses
and the ports permitted for the addresses
when using a packet-filtering firewall. This
parameter is required only if the local node
acts as a PNODE.
Place all values for an address inside
parentheses and separate each value for an
address with a comma.
Valid IP address with an optional mask for
the upper boundary of the IP address range
and the associated outgoing port number or
range of port numbers for the specified IP
address, for example:
(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)
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.
tcp.src.ports.list.
iterations
The number of times that Sterling
Connect:Direct scans the list of available
ports to attempt a connection before going
into a retry state.
Any numeric value from 1–255. The default
value is 2.
udp.src.ports For UDT connections, remote IP addresses
and the ports permitted for the addresses
when using a packet-filtering firewall. This
parameter is recommended if a firewall is
used whether the local node acts as a
PNODE or an SNODE.
Place all values for an address inside
parentheses and separate each value for an
address with a comma.
Valid IP address with an optional mask for
the upper boundary of the IP address range
and the associated outgoing port number or
range of port numbers for the specified IP
address, for example:
(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)
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.
udp.src.ports.list.
iterations
The number of times that Sterling
Connect:Direct scans the list of available
ports to attempt a connection before going
into a retry state.
Any numeric value from 1–255. The default
value is 2.
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:
v Sterling Connect:Direct API configuration parameters
v Sterling Connect:Direct CLI configuration parameters
v Client authentication parameters
You can modify Sterling Connect:Direct configuration files using any text editor. If
you want to create a new configuration file, use the cdcust command.
Chapter 3. Administration Guide 99
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
Sterling 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 Sterling 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 which the API usually
connects.
Host name or IP address.
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 the API usually
connects.
Port number. The default is 1363.
wait.time The number of seconds to wait
for responses from the server.
If this limit is exceeded, the
message ID XCMG000I is
displayed.
Seconds to wait. The default is 50 seconds.
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:
100 Sterling Connect:Direct for UNIX 4.2.0: Documentation
Parameter Description Value
script.dir The directory where customized script files are stored.
Specify this parameter if you have created a custom
script to format the output of the select statistics and
select process commands. The file names must be
ndmstat and ndmproc.
Directory name.
The default
directory is
ndm/bin/.
prompt.string Identifies the CLI prompt to display on the command
line when the client is started.
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.
Prompt string up
to 32 characters.
The default is
“Direct”.
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 Sterling 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 Sterling Connect:Direct Browser User Interface to perform
some of the procedures related to the initialization parameters file. To learn more
about the Sterling 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.
Chapter 3. Administration Guide 101
The network map file resides in d_dir/ndm/cfg/cd_node/netmap.cfg where d_dir is
the location where Sterling 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.
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:
v Configures settings for the local node
v Provides default configuration values that can be overridden in the remote node
entries.
Two sets of connection retry parameters are created:
102 Sterling Connect:Direct for UNIX 4.2.0: Documentation
v Short-term parameters define retry attempts in the event of a short-term
connection failure.
v 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.
Parameter Description Value
api.max.connects The maximum number of concurrent API
connections permitted for the local node.
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 Sterling Connect:Direct operation.
1–256
The default is 16.
comm.bufsize The buffer size for transmitting data to and
from a remote node for TCP/IP connections.
The value for TCP/IP has no limit (up to
2,147,483,623).
For LU6.2, the maximum is 32000.
The default is 65536 bytes.
conn.retry.stwait The time to wait between retries immediately
after a connection failure occurs. The format
is hh.mm.ss, where hh specifies hours, mm
specifies minutes, and ss specifies seconds.
The maximum value is limited to the highest
value in the clock format, 23.59.59. The
default is 00.00.30, which is 30 seconds.
conn.retry.stattempts The number of times to attempt connection
after a connection failure occurs.
0–9999
The default is 6.
conn.retry.ltwait The time to wait between long-term retry
attempts after all short-term retry attempts
are used. The format is hh.mm.ss, where hh
specifies hours, mm specifies minutes, and ss
specifies seconds.
00.00.00–23.59.59
The default is 00.10.00, or 10 minutes.
conn.retry.ltattempts The number of times to attempt a connection
after all short-term retry attempts are used.
0–9999
The default is 6.
conn.retry.exhaust.
action
Action to take after the specified short and
long-term retries have been used.
hold | delete
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 Sterling Connect:Direct
administrator or operator.
Name
Chapter 3. Administration Guide 103
Parameter Description Value
contact.phone The phone number of the Sterling
Connect:Direct administrator or operator.
Phone number
descrip Comments to include as part of the record. An unlimited text string
lu62.writex.wait If you are using SNA on an IBM AIX
operating system, use this parameter to
identify how long to wait before retrying the
connection.
0:00:00–59:59:59
The value is in hh:mm:ss format. The default
value is 1.
lu62.writex.retry.
attempts
If you are using SNA on an IBM AIX
operating system, use this parameter to
identify how many times to attempt a
connection.
0–2,147,483,647
The default value is 0.
netmap.check Enhanced security testing performed on the
SNODE. For TCP/IP connections, the remote
IP address of the incoming socket connection
is compared to the comm.info record of the
netmap.cfg file. These values must match for
an Sterling Connect:Direct session to be
established. The comm.info record can be the
official network name, an alias name listed in
the appropriate file (for example, /etc/hosts,
if the system is not running NIS or DNS), or
the IP address. For all connections, the
remote node name must be in the
netmap.cfg.
y | n
y—Specifies that the security checks are
made to verify that the remote node name is
in the netmap.cfg file. Also, checks the
network map for all nodes that
Connect:Direct will communicate with to
validate the node name and the IP address.
l—Checks the network map only for nodes
that the local Connect:Direct will initiate
sessions with.
r—Checks the network map only for 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 environment,
this parameter enables you to specify the
virtual IP address for the remote node to use
for network map checking and prevents the
Process from failing when initiated from
within a high 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.
nnn.nnn.nnn.nnn (IPv4) or
nnnn:nnnn:nnnn:nnnn:nnnn:nnnn:nnnn:nnnn
(IPv6)
For more information on specifying IP
addresses and host names, see IP Addresses,
Host Names, and Ports.
pacing.send.delay The time to wait between send operations to
the remote node. The decimal number is the
number of milliseconds between the end of
one packet and the beginning of the next
packet. Time-based pacing does not
contribute to network traffic.
The value for this parameter has no effect on
LU6.2 connections.
The format is nnn.
No limit exists for the size of this value.
The default is 0, which indicates no pacing of
this type.
pacing.send.count The number of send operations to perform
before automatically waiting for a pacing
response from the remote node. The value
for this parameter has no effect on LU6.2
connections.
No limit exists for the size of this value.
The default is 0, which indicates no pacing of
this type.
104 Sterling Connect:Direct for UNIX 4.2.0: Documentation
Parameter Description Value
proxy.attempt Enables the ID subparameter of snodeid to
contain a proxy, or dummy user ID to be
used for translation to a local user ID on the
remote system. Using a dummy user ID
improves security because neither the local
system nor the remote system requires a
valid user ID from the other side.
y | n
y—Specifies that the remote users can specify
a dummy user ID in snodeid parameter.
n—Specifies that the remote users cannot
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
runstep.max.time.to.
wait
The maximum time to wait for remote run
steps to complete. Remote run steps include
remote run task, run job, or submit
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.
0–10000
The value is in seconds.
The default value is 0.
sess.total The maximum number of concurrent
connections between all nodes and the local
node.
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 Sterling
Connect:Direct sessions allowed, which can
be as many as 999.
0–999
A 1–3 digit number.
The default is 255.
Chapter 3. Administration Guide 105
Parameter Description Value
sess.pnode.max The maximum concurrent connections, where
the local node is the initiator of the 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.
0–999
The default is 255.
sess.snode.max The maximum concurrent connections, where
the local node is the secondary node 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.
0–999
The default is 255.
sess.default The default session class for starting session
managers. A Process executes on the
specified class or any higher session class.
1–50
The default is 1.
tcp.api.bufsize The buffer size for transmitting data to and
from an Sterling Connect:Direct CLI/API.
This value has no limit. The default is 32768
bytes.
tcp.api The information needed to monitor
connection requests from the CLI or API
using TCP/IP. The host is the host name or
IP address where Sterling Connect:Direct is
running. The port identifies the
communications port for Sterling
Connect:Direct. Multiple host name/IP
addresses and port combinations can be
specified when they are separated by a
comma. This parameter is required.
host name/IP address;nnnn
host name—is the name of the Sterling
Connect:Direct host computer.
IP address—is the IP address of a machine
running Sterling Connect:Direct:
nnn.nnn.nnn.nnn (IPv4) or
nnnn:nnnn:nnnn:nnnn:nnnn:nnnn:nnnn:nnnn
(IPv6)
port—identifies the communications port for
Sterling 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;1364
You can specify multiple address/host name
and port combinations (separated with a
comma):
10.23.107.5;1364, fe00:0:0:2014::7;1364,
msdallas-dt;1364
For more information on specifying IP
addresses and host names, see IP Addresses,
Host Names, and Ports.
tcp.api.inactivity.
timeout
This is the maximum time a CMGR waits
before exiting when it has not received a
command from a client program.
0–86399 (23 hours, 59 minutes, and 59
seconds)
The value is in seconds. The default is 0,
which indicates no timeout occurs.
106 Sterling Connect:Direct for UNIX 4.2.0: Documentation
Parameter Description Value
tcp.max.time.to.wait The maximum time the local node waits for
a message from the remote node when using
TCP/IP. When the time expires, the Process
is moved to the Timer queue and Sterling
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.
0–10000
The value is in seconds. The default value is
180.
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
immediately after a connection failure
occurs. The format is hh.mm.ss, where hh
specifies hours, mm specifies minutes, and
ss specifies seconds.
The maximum value is limited to the
highest value in the clock format,
23.59.59.
The default is 00.00.30, which is 30
seconds.
conn.retry.stattempts The number of times to attempt connection
after a connection failure occurs.
0–9999
The default is 6.
conn.retry.ltwait The time to wait between long-term retry
attempts after all short-term retry attempts
are used. The format is hh.mm.ss, where hh
specifies hours, mm specifies minutes, and
ss specifies seconds.
0–23.59.59
The default is 00.10.00, or 10 minutes.
conn.retry.ltattempts The number of times to attempt a
connection after all short-term retry attempts
are used.
0–9999
The default is 6.
comm.bufsize The buffer size for transmitting data to and
from a remote node.
The value for TCP/IP has no limit (up
to 2,147,483,623).
For LU6.2, the maximum is 32000.
The default is 65536 bytes.
conn.retry.exhaust.
action
Action to take after the specified short and
long-term retries have been used.
hold | delete
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.
Chapter 3. Administration Guide 107
Parameter Description Value
tcp.max.time.to.wait The maximum time the local node waits for
a message from the remote node when using
TCP/IP. When the timer expires, the Process
is moved to the Timer queue and Sterling
Connect:Direct attempts to re-establish a
session with the remote node.
0–10,000
The value in seconds.
The default value is 180.
When set to 0, wait time is unlimited
unless limited by the operating
system.
runstep.max.time.to.
wait
The maximum time to wait for remote run
steps to complete. Remote run steps include
remote run task, run job, or submit
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.
0–10000
The value in seconds. The default
value is 0.
contact.name The name of the administrator or operator. Name
contact.phone The phone number of the Sterling
Connect:Direct administrator or operator.
Phone number
descrip Comments to include as part of the record. An unlimited string
sess.total The maximum number of concurrent
connections between all nodes and the local
node.
The sum of api.max.connects and sess.total
cannot exceed the number of file descriptors
available. This value is system dependent.
0–999
A 1–3 digit number. The default is 255.
sess.pnode.max The maximum concurrent connections,
where the local node is the initiator of the
session.
0–999
The default is 255.
sess.snode.max The maximum concurrent connections,
where the local node is the secondary node
in a session.
0–999
The default is 255.
sess.default The default session class for starting session
managers. A Process executes on the
specified class or any higher session class.
The value for this parameter overrides the
equivalent value in the local.node record.
1–50
The default is 1.
pacing.send.delay How long to wait between send operations
to the remote node. The decimal number is
the number of milliseconds between the end
of one packet and the beginning of the next
packet. Time-based pacing does not
contribute to network traffic.
The value for this parameter has no effect on
LU6.2 connections.
nnn
The size of this number has no limit.
The default is 0, which indicates no
pacing of this type.
108 Sterling Connect:Direct for UNIX 4.2.0: Documentation
Parameter Description Value
pacing.send.count The number of send operations to perform
before automatically waiting for a pacing
response from the remote node.
The value for this parameter has no effect on
LU6.2 connections.
No limit exists for the size of this
value.
The default is 0, which indicates no
pacing of this type.
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-checked sessions with systems with
multiple IP addresses, such as Sterling
Connect:Direct/Plex z/OS. Use this
parameter to list all IP addresses or host
names that are part of the multiple IP
address environment.
For Sterling Connect:Direct/Plex, this list
should include the address of each Sterling
Connect:Direct/Server with a different IP
address from the Sterling
Connect:Direct/Plex Manager.If the IP
address of the initiating node does not match
the IP address specified on the comm.info
parameter, the alternate.comminfo
parameter is checked for other valid IP
addresses.
For more information on specifying IP
addresses and host names, see IP Addresses,
Host Names, and Ports.
host name/IP address or *
host name—Host name associated with the
IP address, for example:
:alternate.comminfo=hops (where hops is a
machine on the local domain)
:alternate.comminfo=hops.csg.stercomm.com
(fully-qualified host name)
IP address——the IP address of a machine
running Sterling Connect:Direct in IPv4 or
IPv6 format:
nnn.nnn.nnn.nnn (IPv4) or
nnnn:nnnn:nnnn:nnnn:nnnn:nnnn:nnnn:nnnn
(IPv6)
For example:
:alternate.comminfo=10.23.107.5
: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.
Chapter 3. Administration Guide 109
Parameter Description Value
alt.comm.outbound Alternate communication address
(communication path) used for outbound
Processes. This parameter provides the
alternate addresses for a remote node that
has multiple NIC cards. When the local node
is the PNODE, the alternate addresses are
tried if an initial attempt to the primary
address (specified in the comm.info
parameter) fails. After a connection has been
established, if the connection is subsequently
lost, attempts to reestablish the connection
through the 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.
Fully-qualified host name/IP address;nnnn
The host name/IP address and port are
separated by a semi-colon (;). A comma
separates the list of alternate communication
paths, and the list is processed from the top
down. For example:
salmon;9400, 10.20.40.65;9500
For more information on specifying IP
addresses and host names, see IP Addresses,
Host Names, and Ports.
comm.bufsize The buffer size for transmitting data to and
from a remote node on TCP/IP connections.
The value for TCP/IP has no limit (up to
2,147,483,623).
For LU6.2, the maximum is 32000.
The default is 65536 bytes.
comm.info The information needed to initiate
connection requests to remote nodes using
TCP/IP or LU6.2. This information refers to
the network card that the local Sterling
Connect:Direct node uses to initiate
outbound requests. This value is required.
v For TCP/IP connections, specify the host
name or the IP address and port number.
If specifying IP address and port, separate
parameters with a semicolon (;).
v For LU6.2 connections, identify the profile
name to identify the name of an SNA
configuration profile for the remote
connection. Sterling Connect:Direct
generates the default name, hostl1, during
the customization procedure. For AIX
SNA, hostl1 refers to the side information
profile name. For HP SNA, SunLink SNA,
and Brixton SNA, hostl1 refers to the SNA
profile file located in the same directory as
the configuration files.
For TCP/IP connections, specify the host
name or the IP address and port number.
The default port is 1364.
For LU6.2 connections, specify a profile
name, up to 8 characters.
For more information on specifying IP
addresses and host names, see IP Addresses,
Host Names, and Ports.
comm.transport The transport protocol for the remote node. tcp | lu62 |blklu62 | udt33
tcp—TCP/IP connections
lu62—AIX SNA LU6.2 connections
blklu62—Other LU6.2 connections
udt33—UDT connections
conn.retry.stwait Time to wait between retries immediately
after a connection failure occurs. The format
is hh.mm.ss, where hh specifies hours, mm
specifies minutes, and ss specifies seconds.
The maximum value is limited to the highest
value in the clock format, 23.59.59.
The default is 00.00.30, which is 30 seconds.
110 Sterling Connect:Direct for UNIX 4.2.0: Documentation
Parameter Description Value
conn.retry.stattempts Number of times to attempt connection after
a connection failure occurs.
0–9999
The default is 3.
conn.retry.ltwait Time to wait between long-term retry
attempts after all short-term retry attempts
are used. The format is hh.mm.ss, where hh
specifies hours, mm specifies minutes, and ss
specifies seconds.
0–23.59.59
The default is 00.10.00, or 10 minutes.
conn.retry.ltattempts Number of times to attempt a connection
after all short-term retry attempts are used.
0–9999
The default is 6.
conn.retry.exhaust.
action
Action to take after the specified short and
long-term retries have been used.
hold | delete
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 Sterling Connect:Direct
administrator or operator.
Name
contact.phone The phone number of the Sterling
Connect:Direct administrator or operator.
Phone number
descrip Comments to include as part of the record. An unlimited string
pacing.send.count The number of send operations to perform
before automatically waiting for a pacing
response from the remote node. The value
for this parameter has no effect on LU6.2
connections.
No limit exists for the size of this value.
The default is 0, which indicates no pacing
of this type.
pacing.send.delay The time to wait between send operations to
the remote node. The decimal number is the
number of milliseconds between the end of
one packet and the beginning of the next
packet. Time-based pacing does not
contribute to network traffic.
The value for this parameter has no effect on
LU6.2 connections.
nnn
The size of this number has no limit. The
default is 0, which indicates no pacing of this
type.
runstep.max.time.to.
wait
The maximum time to wait for remote run
steps to complete. Remote run steps include
remote run task, run job, or submit
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.
0–10000
The default value is 0.
sess.total The maximum number of concurrent
connections between all nodes and the local
node.
The sum of api.max.connects and sess.total
cannot exceed the number of file descriptors
available. This value is system dependent.
0–999
A 1–3 digit number.
The default is 255.
Chapter 3. Administration Guide 111
Parameter Description Value
sess.pnode.max The maximum concurrent connections,
where the local node is the initiator of the
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.
0–999
The default is 255.
sess.snode.max The maximum concurrent connections,
where the local node is the secondary node
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.
0–999
The default is 255.
tcp.crc Turn on or off the CRC function for TCP/IP
Processes on the remote node.
y | n
The default is n.
Maintaining access information files
You can control access to Sterling Connect:Direct through the following
components:
v User authorization information file which contains local and remote user
information records
v Strong access control file
v Program directory to limit access
v Sterling Connect:Direct’s ability to detect shadow passwords
v Security exit
User Authorization Information File
In order for users to have access to Sterling Connect:Direct and use Sterling
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 Sterling Connect:Direct.
Sterling Connect:Direct may optionally use remote user information records to
translate remote user IDs to valid local user IDs where Sterling Connect:Direct is
installed. If an snodeid parameter is not coded on the incoming Process, Sterling
Connect:Direct uses this proxy relationship to determine the rights of remote users
to issue Sterling Connect:Direct commands and statements.
112 Sterling Connect:Direct for UNIX 4.2.0: Documentation
Sterling 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
Name
is
mapped
to
Local User
ID Result of Mapping
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.
Chapter 3. Administration Guide 113
: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:
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:
v 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
v n—Indicates that a user cannot perform the function.
v 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
authority. If set to y, the user can perform all
of the commands by default, but the specific
command parameters override the default. If
set to n, the specific command parameters
must be granted individually.
y | n
y—User has administrative authority.
n—User does not have administrative
authority.
The default is n.
cmd.chgproc Determines if the user can issue the change
process command.
A “y” value enables a user to issue the
command to targets owned by that user.
Whereas, “a” allows a user to issue the
command to targets owned by all users.
y | n | a
y—Allows the user to issue the command.
n—Prevents the user from issuing the
command. The default is n.
a—Allows the user to issue the command
against targets owned by all users.
114 Sterling Connect:Direct for UNIX 4.2.0: Documentation
Parameter Description Value
cmd.delproc Determines if the user can issue the delete
process command.
A “y” value enables a user to issue the
command to targets owned by that user.
Whereas, “a” allows a user to issue the
command to targets owned by all users.
y | n | a
y—Allows the user to issue the command.
n—Prevents the user from issuing the
command. The default is n.
a—Allows the user to issue the command
against targets owned by all users.
cmd.flsproc Determines if the user can issue the flush
process command.
A “y” value enables a user to issue the
command to targets owned by that user.
Whereas, “a” allows a user to issue the
command to targets owned by all users.
y | n | a
y—Allows the user to issue the command.
n—Prevents the user from issuing the
command. The default is n.
a—Allows the user to issue the command
against targets owned by all users.
cmd.selproc Determines if the user can issue the select
process command.
A “y” value enables a user to issue the
command to targets owned by that user.
Whereas, “a” allows a user to issue the
command to targets owned by all users.
y | n | a
y—Allows the user to issue the command.
n—Prevents the user from issuing the
command. The default is n.
a—Allows the user to issue the command
against targets owned by all users.
cmd.viewproc Determines if the user can issue the view
process command.
A “y” value enables a user to issue the
command to targets owned by that user.
Whereas, “a” allows a user to issue the
command to targets owned by all users.
y | n | a
y—Allows the user to issue the command.
n—Prevents the user from issuing the
command. The default is n.
a—Allows the user to issue the command
against targets owned by all users.
cmd.selstats Determines if the user can issue the select
statistics command.
A “y” value enables a user to issue the
command to targets owned by that user.
Whereas, “a” allows a user to issue the
command to targets owned by all users.
y | n | a
y—Allows the user to issue the command.
n—Prevents the user from issuing the
command. The default is n.
a—Allows the user to issue the command
against targets owned by all users.
cmd.stopndm Determines if the user can issue the stop
command.
y | n
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 commands
from network clients, such as IBM Sterling
Control Center or Java API, to configure
Sterling Connect:Direct Secure Plus.
Note: This parameter has no effect on local
tools, such as spadmin.sh and spcli.sh.
y | n
y—Allows the user to issue commands. The
default is y.
n—Prevents the user from issuing
commands.
Chapter 3. Administration Guide 115
Parameter Description Value
cmd.submit Determines if the user can issue the submit
process command.
y | n
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
command.
y | n
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
settings to use the keyword CRC in a Process
statement.
y | n
y—Allows the user to issue the command.
n—Prevents the user from issuing the
command. The default is n.
descrip Permits the administrator to add descriptive
notes to the record.
Unlimited text string
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
statement.
y | n
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
output file size is exceeded during a copy
operation. The value for this parameter
overrides the equivalent value for the ulimit
parameter in the initialization parameters
file.
y | n | nnnnnnnn | nnnnnnnnK |
nnnnnnnM | nnnnG
y—Honors the user file size limit. If this
limit is exceeded during a copy operation,
the operation fails.
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
this local node. If a file open exit is in use,
this parameter is passed to the exit, but it is
not enforced.
y | n
y—Allows the user to send files. The default
is y.
n—Prevents the user from sending files.
116 Sterling Connect:Direct for UNIX 4.2.0: Documentation
Parameter Description Value
pstmt.upload_dir The directory from which the user can 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.
Directory path name
pstmt.download Determines if the user can receive files to
this local node. If a file open exit is in use,
this parameter is passed to the exit, but it is
not enforced.
y | n
y—Allows the user to receive files. The
default is y.
n—Prevents the user from receiving files.
pstmt.download_dir The directory to which the user can receive
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.
Directory path name
pstmt.run_dir The directory where Sterling Connect:Direct
is 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.
Directory path name
pstmt.runjob Specifies whether the user can issue the run
job statement.
y | n
y—Allows the user to issue the statement.
n—Prevents the user from issuing the
statement. The default is n.
pstmt.runtask Specifies whether the user can issue the run
task statement.
y | n
y—Allows the user to issue the statement.
n—Prevents the user from issuing the
statement. The default is n.
Chapter 3. Administration Guide 117
Parameter Description Value
pstmt.submit Specifies whether the user can issue the
submit statement.
y | n
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
submit Processes. This is for submits within
a Process.
Directory path name
snode.ovrd Specifies whether the user can code the
snodeid parameter on the submit command
and process and submit statements.
y | n
y—Allows the user to code the snodeid
parameter
n—Prevents the user from coding the
snodeid parameter. The default is n.
pstmt.crc Gives the user the authority to specify the
use of CRC checking in a Process statement.
Setting this parameter to y enables the user
to override the initial settings in the
initialization parameters or network map
settings files.
y | n
y—Allows a user to specify CRC checking
on a Process statement.
n—Prevents a user from specifying
CRCchecking on a Process statement. The
default is n.
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 Sterling 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 checking on behalf of the
remote user. The local.id parameter
must identify a local user
information record.
Local user ID
pstmt.copy Determines if the user can issue
the copy statement.
y | n
y—Allows a user to issue the
statement.
n—Prevents a user from issuing
the statement. The default is n.
118 Sterling Connect:Direct for UNIX 4.2.0: Documentation
Parameter Description Value
pstmt.upload Determines if the user can send
files from this local node. If a file
open exit is in use, this parameter
is passed to the exit, but it is not
enforced.
y | n
y—Allows a user to send files.
The default is y.
n—Prevents a user from
sending files.
pstmt.upload_dir The directory from which the user
can 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.
Directory path name
pstmt.download Determines if the user can receive
files to this local node. If a file
open exit is in use, this parameter
is passed to the exit, but it is not
enforced.
y | n
y—Allows a user to receive
files. The default is y.
n—Prevents a user from
receiving files.
pstmt.download_dir The directory to which the user
can 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.
Directory path name
pstmt.run_dir The directory that contains the
programs 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.
Directory path name
pstmt.submit_dir The directory from which the user
can submit Processes. This is for
submits within a Process.
Directory path name
Chapter 3. Administration Guide 119
Parameter Description Value
pstmt.runjob Specifies whether the user can
issue the run job statement.
y | n
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 run task statement.
y | n
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 submit statement.
y | n
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 the record.
Text string
Strong Access Control File
To provide a method of preventing an ordinary user from gaining root access
through Sterling 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 Sterling Connect:Direct for UNIX. If you want
to give an ordinary root user access through Sterling 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 Sterling Connect:Direct
for UNIX, the sysacl.cfg file must exist. If the file is deleted or corrupted, all users
are denied access to Sterling 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 Sterling Connect:Direct. This parameter is required.
The following values can be specified for the root:deny.access parameter:
120 Sterling Connect:Direct for UNIX 4.2.0: Documentation
Parameter Description Value
deny.access Allows, denies, or limits root
access to IBM Sterling
Connect:Direct
y | n | d
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
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, Sterling 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:
v Changing the directory (cd)
v Changing PATH or SHELL environment variables
v Using command names containing a slash (/) character
v 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
Chapter 3. Administration Guide 121
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
Sterling Connect:Direct client/server security depends on a key, similar to a
password, in a Sterling 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. 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.
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 communicate or the host name of
the API you will 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.
1—16 characters and must
be unique within its key file.
MRLN SIMP A required character string, separated from
the other fields by one or more spaces.
Character string
122 Sterling Connect:Direct for UNIX 4.2.0: Documentation
Parameter Description Value
key The security key. Separate the key from
SIMP by one or more spaces.
Up to 22 characters long
including A to Z, a to z, 0 to
9, period (.), and ⌂slash (/).
Sample Client Authentication Key File
The following figure illustrates API key lists in the Clients column and server key
lists in the Servers column.
v 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.
v 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.
v 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 Sterling Connect:Direct authentication process determines if the user is
authorized to access the system.
The goal of Sterling 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 Sterling Connect:Direct API, to ensure
that the authentication process is not bypassed by an unauthorized user. The
Chapter 3. Administration Guide 123
following figure displays the components that perform authentication:
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.
124 Sterling Connect:Direct for UNIX 4.2.0: Documentation
Firewall Navigation
Firewall navigation enables controlled access to an Sterling 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 or UDT source port number or a range of source port numbers with a
specific destination address (or addresses) for Sterling Connect:Direct sessions.
Before you configure source ports in the Sterling Connect:Direct initialization
parameters, you need to review all information regarding firewall navigation and
rules, especially if you are implementing firewalls for UDT.
Implement Firewall Navigation
To implement firewall navigation in Sterling 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 Sterling Connect:Direct initialization
parameters file as needed, based on whether you are using TCP or UDT:
v tcp.src.ports
v tcp.src.ports.list.iterations
v udp.src.ports
v 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 Sterling
Connect:Direct node to communicate with the remote Sterling 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 and UDT; as a result, firewall rules for TCP and
UDT 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
Chapter 3. Administration Guide 125
UDT Firewall Navigation Rules
UDT firewall rules are applied to the UDP protocol. The recommended default
firewall rule for UDP packets is to block packets inbound to the local system and
outbound from the local system to prevent the confusion that could occur due to
the callback feature of UDT session establishment.
In the following table, the UDT 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.
UDT PNODE Rules
Rule Name Rule Direction Local Ports Remote Ports
PNODE Session
Request
Outbound Local C:D's source
ports
Remote C:D's listening
port
PNODE Session Outbound Local C:D's source
ports
Remote C:D's source
ports
UDT SNODE Rules
Rule Name Rule Direction Local Ports Remote Ports
SNODE listen Inbound Local C:D's listening
port
Remote C:D's source
ports
SNODE session Inbound Local C:D's source
ports
Remote C:D's source
ports
Firewall Configuration Examples
In the firewall configuration examples for TCP and UDT, the following IP
addresses and source ports will be used:
Note: The IP addresses in the examples have been chosen to be distinctive and are
not intended to be valid IP addresses.
v The local node has IP address 222.222.222.222 and listening port 2264. Its source
ports for communicating with the remote node are 2000–2200.
v The remote node has IP address 333.333.333.333 and listening port 3364. Its
source ports for communicating with the local node are 3000–3300.
See Session Establishment for a discussion of the differences between UDT and
TCP session establishment.
TCP Firewall Configuration Example
The Sterling 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:
v tcp.src.ports = (333.333.333.333, 2000–2200)
v 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.
126 Sterling Connect:Direct for UNIX 4.2.0: Documentation
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
UDT Firewall Configuration Example
The Sterling 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:
v udp.src.ports = (333.333.333.333, 2000-2200)
v udp.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
PNODE session Outbound 2000–2200 3000–3300
SNODE listen Inbound 2264 3000–3300
SNODE session Inbound 2000–2200 3000–3300
Blocking Outbound Packets
The recommended default rule for outbound UDP packets from the local system is
to block the packets. If you do not follow this recommendation, port usage may, at
first sight, appear to violate the firewall's inbound rules.
An example will help illustrate this situation. Suppose that in the example in the
previous section:
v The local node is the SNODE.
v The default outbound rule allows all outbound UDP packets from the local
system.
v The “SNODE session” rule is accidently omitted.
Because of the callback feature of UDT session establishment, SNODE sessions are
still likely to succeed on ports 2000–2200. This may cause confusion because ports
2000–2200 are blocked to inbound UDP packets.
If you use the recommended default outbound rule and apply the PNODE and
SNODE rules described in the previous section, there will be no confusion about
which port to use, and the UDT callback feature will function as designed, thus
supporting reliability.
Chapter 3. Administration Guide 127
Session Establishment
Session establishment differs between TCP and UDT; these differences affect how
you set up firewall rules and configure the firewall navigation initialization
parameters in Sterling Connect:Direct.
TCP Session Establishment
An Sterling Connect:Direct TCP client contacts an Sterling Connect:Direct TCP
server on its listening port. The Sterling Connect:Direct client scans the list of ports
(specified using the tcp.src.ports initialization parameter) and looks for a port to
bind to. The number of times Sterling Connect:Direct scans the list is specified
using the tcp.src.ports.list.iterations initialization parameter. If Sterling
Connect:Direct finds an available port, communication with the remote node
proceeds.
UDT Session Establishment
When an Sterling Connect:Direct UDT client contacts an Sterling Connect:Direct
UDT server on its listening port to request a session, the UDT server responds
with a different server port to use for the session. The client attempts to contact the
server on the session port. The Sterling Connect:Direct client scans the list of ports
(specified in the udp.src.ports initialization parameter) and looks for an available
port to bind to. The number of times Sterling Connect:Direct scans the list is
specified using the udp.src.ports.list.iterations initialization parameter. If the
Sterling Connect:Direct client finds an available port, communication with the
remote Sterling Connect:Direct server proceeds. If a session cannot be established
after a certain time interval, the server attempts to contact the client.
Specifying connection information
Sterling 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:
v Address or host name only
v Port number only
v Address/host name with a port number
v Multiple address/host name and port combinations
When specifying IP addresses/host names and ports for Sterling Connect:Direct,
use the following guidelines.
IP Addresses
Sterling Connect:Direct accepts both IPv4 and IPv6 addresses. Wherever an IP
address is specified in IBM Sterling Connect:Direct, you can use either IPv4 or an
IPv6 addresses.
IPv4 Addresses
IPv4 supports 2
32
addresses written as 4 groups of dot-separated 3 decimal
numbers (0 through 9), for example, 10.23.107.5.
128 Sterling Connect:Direct for UNIX 4.2.0: Documentation
IPv6 Addresses
IPv6 supports 2
128
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:
v 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
v 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
v 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
v 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
This notation is useful for compatibility addresses.
Host Names
When you specify a host name, rather than an IP address, Sterling 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:
v No blank or space characters are permitted as part of the name.
v Periods are allowed only when they are used to delimit components of
domain-style names.
v Host names are not case sensitive.
v The first and last character must be a letter or digit.
v Single-character names or nicknames are not allowed.
Chapter 3. Administration Guide 129
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 Sterling 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. Sterling
Connect:Direct supports masks for both IPv4 and IPv6 addresses as shown in the
following sample entry from the initparms.cfg file:
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.
130 Sterling Connect:Direct for UNIX 4.2.0: Documentation
(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 Sterling Connect:Direct in a test mode
You can enable a test mode for production instances of Sterling Connect:Direct to
perform the following functions:
v Test new applications and customer connections
v Prevent future production work from executing until testing is complete after
you have terminated all active production work using the Flush Process
command
v Resume regular production work after testing
v Control individual file transfers by application
v 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 Sterling 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 Sterling 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:
v A partial or full Process name
v A partial or full remote node name
v A partial or full Sterling Connect:Direct submitter ID and submitter node
combination
In addition to telling Sterling 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:
v Place the Process in the Hold queue
v Place the Process in the Timer queue for session retry
v Flush the Process from the queue
Chapter 3. Administration Guide 131
For more information on how the testing mode can be used, see Sample Test
Scenarios.
When the testing mode is enabled, Sterling Connect:Direct performs a syntax check
on the parameter table and fails initialization if the table is invalid. If the table is
valid, Sterling 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 Sterling 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 Sterling 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.
132 Sterling Connect:Direct for UNIX 4.2.0: Documentation
Command Code Description Subparameters/Examples
E Enables execution of Processes
based on table entries. Either “E”
or “D” must be the first
non-comment entry in the table.
The second column in this entry
must contain one of the following
values which indicates the
disposition of a 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
D Disables the execution of all
Processes regardless of the contents
of the parameter table and fails
Process execution with a non-zero
(error) return code and message
LPRX003E. Either “E” or “D” must
be the first non-comment entry in
the table
The parameter for command code
“E” can also be specified in
column two. This is a convenience
to make it easier to change from
“E” to “D” and vice versa without
having to change column two to a
blank for command code “D.”
P Matches Processes based on a full
or partial Process name. Supports
the wild card trailing asterisk (*).
Can be used to enable or disable
Process execution for a particular
application by using naming
conventions to match an
application.
PCOPY—Matches a single Process
PACH*—Matches all Processes
beginning with “ACH”
P*—Matches all Processes
N Matches Processes based on a full
or partial remote node name.
Supports the wild card trailing
asterisk (*).
NCD.NODE1—Matches a single
remote node name
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 wild card Sterling
Connect:Direct submitter ID and
submitter node combination. The
format is <id>@<node>.
SACTQ0ACD@TPM002—Matches
a specific ID and node
combination.
S*@TPM002—Matches all IDs from
node TPM002
SACTQ0ACD@*—Matches ID
ACTQ0ACD from all nodes
S*@*—Matches all IDs from any
node. This is another way to match
all Processes.
Chapter 3. Administration Guide 133
Command Code Description Subparameters/Examples
I Includes Processes for execution
that match the patterns in the table
which follow this command code.
Either “I” or “X” must be the
second non-comment entry in the
table. Processes which do not
match a pattern in the table are not
executed.
Note: To choose which command
code to use to select Processes,
determine 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.
ER
I
NCD.BOSTON⌂
Includes Processes for execution on
the CD.BOSTON node only.
Processes destined for all other
remote nodes are placed in the
Timer queue in session retry
X Excludes from execution those
Processes that match the patterns
in the table which follow this
command code. Either “X” or “I”
must be the second non-comment
entry in the table. Processes which
do not match a pattern in the table
are executed.
EH
X
SDALLASOPS@*⌂
Excludes Processes for execution
submitted by the ID DALLASOPS
from 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 Sterling Connect:Direct Processes to
run and not run.
Specifying Which Processes Run
In this example, Sterling 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, Sterling Connect:Direct does not execute any Process that starts
with ACH or is named DITEST01 or DITEST02. All other Processes are executed.
134 Sterling Connect:Direct for UNIX 4.2.0: Documentation
* 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, Sterling Connect:Direct executes all Processes that match one of
the following criteria:
v The specific secondary node (SNODE) name is DI.NODE1
v An SNODE whose name starts with DI0017
v Any Sterling Connect:Direct submitter ID from node DI0049
v The specific Sterling Connect:Direct submitter ID ACHAPP from any node
All Processes not matching one of the above criteria are flushed from the queue.
* 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 135
136 Sterling Connect:Direct for UNIX 4.2.0: Documentation
Chapter 4. User Guide
The User Guide contains all the information you need in order to use Sterling
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 Sterling Connect:Direct Processes
and commands from a native command line environment. You can also use the
Sterling 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
Sterling 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 Sterling 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, 2016 137
Option Description Value
Sample Command
Entry
-P Identifies the custom string to
use at the command line
prompt.
If the prompt string includes
spaces 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.
text string
Up to 32 characters.
$ direct
-PNewPrompt
$ direct -P”Test CD
on Medea”
-s Suppresses standard output.
Use this option to view only
the completion status of a
command.
none $ direct -s
-t n Enables the CLI/API trace
option. The level number, n,
identifies the level of detail in
the trace output.
1 | 2 | 4
Specify one of the
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.
$ direct -t 4
138 Sterling Connect:Direct for UNIX 4.2.0: Documentation
Option Description Value
Sample Command
Entry
-e nn Defines the error level above
which the CLI automatically
exits. If the returned error code
is greater than the error level
specified, the CLI automatically
exits.
Use this command within shell
scripts.
This parameter prevents
unwanted execution of
commands following a
command that generates an
error above the specified level.
When the CLI terminates, it
returns a UNIX exit code that
can be tested by the shell.
0 | 4 | 8 | 16
Valid values in the
error level code are:
0—Indicates successful
completion.
4—Indicates warning.
8—Indicates error.
16—Indicates
catastrophic error.
$ direct -e 16
-n name Identifies the host name of the
computer where the Sterling
Connect:Direct server (PMGR)
is running.
Note: Invoking direct with -p
or -n overrides the settings in
the ndmapi.cfg file.
Sterling Connect:Direct
host name
$ direct -n hostname
-p nnnnn Identifies the communications
port number for the Sterling
Connect:Direct node.
Note: Invoking direct with -p
or -n overrides the settings in
the ndmapi.cfg file.
1024–65535. The format
is nnnnn.
$ direct -p 2222
-x Displays command input on
standard out. Use this
command when debugging
scripts.
none $ direct -x
-r Makes the Process number
available to user-written shell
scripts. The CLI displays a
special string, _CDPNUM_
followed by a space, followed
by the Process number.
none $direct -r | grep
“_CDPNUM_”
-h Displays command usage
information if a Sterling
Connect:Direct command is
typed incorrectly.
none $ direct -h
-z Appends a newline character
after a prompt.
none $ direct -z
CLI Job Control
Sterling Connect:Direct enables you to switch the CLI Process between the
foreground and the background in shells that support job control. This capability
Chapter 4. User Guide 139
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:
v Press the suspend character (Control-Z) to stop or suspend the CLI Process.
v 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
Sterling 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 Sterling Connect:Direct Commands
You control and monitor Sterling 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 Sterling 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.
140 Sterling Connect:Direct for UNIX 4.2.0: Documentation
Abbreviations for Common Sterling Connect:Direct Commands
The following table lists valid abbreviations for commonly used parameters for
Sterling 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 Sterling Connect:Direct:
v The capability to send or receive files; you may be limited either to sending files
only or to receiving files only.
v 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.
Sterling 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 209, for details on function calls. The following conventions
are used when typing commands:
v When selecting a password or user ID, do not use Sterling Connect:Direct
keywords.
v Be aware that user names and file names are case sensitive.
v Type an individual command keyword in uppercase, lowercase, or mixed-case
characters.
v Terminate all commands with a semicolon (;).
Chapter 4. User Guide 141
v When typing commands, type the entire command name or type the first three
characters or abbreviate specific parameters. Refer to “Abbreviations for
Common Sterling Connect:Direct Commands” on page 141for a list of
abbreviations.
v Do not abbreviate Process statements and parameters.
v File names, group names, user IDs, and passwords are variable length strings
and can be any length.
v A Sterling 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 Sterling
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 Sterling
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 can
include a path name indicating the location of
the Process.
This parameter must be the first parameter.
file name including the path name
142 Sterling Connect:Direct for UNIX 4.2.0: Documentation
Parameter Description Values
class The node-to-node session 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.
1 | n
A numeric value from 1 to the value of maximum
concurrent local node connections
(sess.pnode.max). The default value is 1. The
value cannot be greater than the maximum
number of local sessions with primary control.
crc Determines if crc checking is performed. This
parameter overrides settings in the
initialization parameter, the network map, and
the Process.
Note: The user must be assigned authority to
change the crc settings in the user authority
file.
on | off
on—Turns on crc checking.
off—Turns off crc checking. The default is off.
hold Determines if the Process is placed in the Hold
queue.
When a Process is submitted with retain=yes
or retain=call, Sterling Connect:Direct ignores
the hold parameter.
yes | no | call
yes—Specifies the Process is placed in the Hold
queue in HI status until it is released by a change
process command. A Process submitted 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
submitted Process to complete execution. This
parameter is useful when the command is
issued by a shell script. When this parameter is
specified, the script waits until the Process
completes before it continues execution. The
return code of the Process is stored in the $?
variable if you are using the Bourne or Korn
shell and in $status variable if you are using
the C shell, which the shell 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.
unlimited | hh:mm:ss | 0
unlimited—Waits until the Process completes
execution.
hh:mm:ss—Waits for an interval no longer than
the specified hours, minutes, and seconds.
0—Waits until the Process completes execution. If
you specify maxdelay=0, you get the same results
as when you specify maxdelay=unlimited.
newname A new Process name that overrides the name
in the submitted Process.
A name up to 256 characters long
Chapter 4. User Guide 143
Parameter Description Values
notify The user e-mail to receive Process completion
messages. This parameter uses the rmail utility
available in the UNIX System V mail facility to
deliver the completion messages.
Note: Sterling 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.
username@hostname or user@localhost
pacct A string containing information about the
PNODE. Enclose the string in double quotation
marks.
“pnode accounting data” up to 256 characters
pnodeid Security user IDs and passwords at the
PNODE. The pnodeid subparameters can
contain 1–64 alphanumeric characters.
id [, pswd]
id—Specifies a user ID on the PNODE.
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 Transmission
Control Queue (TCQ). 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.
1–15, where fifteen is the highest priority. The
default is 10.
retain Determines if Sterling Connect:Direct retains a
copy of the Process in the TCQ. Sterling
Connect:Direct assigns a Process number to the
Process when it is placed in the retain queue.
When the Process is run, the Process number
assigned to the retain Process is incremented
by one. For example, if the Process is assigned
the Process number of 1445 in the retain
queue, the Process number is 1446 when the
Process is executed.
If you specify a start time and set 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. Sterling
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.
yes | no | initial
yes—Specifies that the system retains the Process
in the Hold queue in HR status after execution.
no—Specifies that the system deletes the Process
from the TCQ after execution. This is the default.
initial—Specifies that the system retains the
Process in the Hold queue in HR status for
automatic execution every time the Process
Manager initializes.
sacct Specifies accounting data for the SNODE.
Setting this value in the submit statement
overrides any accounting data specified in
Process.
“snode accounting data” up to 256 characters.
Enclose the string in double quotation marks.
144 Sterling Connect:Direct for UNIX 4.2.0: Documentation
Parameter Description Values
snode Identifies the name of the secondary node.
Setting this value overrides the snode value in
the Process statement. The snode parameter is
required either on the submit command or
Process statement.
name | host name | nnn.nnn.nnn.nnn or
nnnn:nnnn:nnnn:nnnn:nnnn:nnnn:nnnn:nnnn[;port
name | nnnnn]]
name—Specifies the node name of the remote
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 Sterling
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 145
Parameter Description Values
snodeid Specifies security user IDs and security
passwords on the SNODE. The snodeid
subparameters can contain one or more
alphanumeric characters.
If Sterling Connect:Direct finds that a Process
has no snodeid parameter or defines a
snodeid parameter and the initialization
parameter proxy.attempt is set to y, then any
password specified on the snodeid parameter
is ignored. A proxy user record is a remote
user record in the userfile.cfg, which
corresponds to the user name specified on the
snodeid parameter. If no proxy user record
exists, the snodeid parameter must contain a
valid user name and password for a UNIX
user who has a corresponding local user record
in the userfile.cfg file.
When proxy.attempt=n and no snodeid is
defined, Sterling Connect:Direct uses the
submitting ID and node to find a Remote User
Information record in the User Authorization
Information file. If Sterling 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.
id [,pswd [,newpswd]]
id—Specifies a user ID on the SNODE.
pswd—Specifies a user password on the SNODE.
If you specify id, you do not have to specify
pswd. This capability enables the id parameter to
contain a dummy ID to be used for translation to
a local ID on the remote system.
newpswd—Specifies a new password value. On
certain platforms, the user password changes to
the new value on the SNODE if the user ID and
old password are correct (refer to documentation
on the specific platform). If the SNODE is a UNIX
node, the password does not change.
If you specify pswd, you must also specify id. If
you specify newpswd, you must also specify
pswd. Type the values in the order of id, pswd,
and newpswd.
146 Sterling Connect:Direct for UNIX 4.2.0: Documentation
Parameter Description Values
startt Identifies the date, day, and time to start the
Process. Sterling Connect:Direct places the
Process in the Timer queue in WS (Waiting for
Start Time) status. The date, day, and time are
positional parameters. If you do not specify
date or day, a comma must precede time.
Do not code the startt parameter when you
specify retain=initial.
[date | day | daily] [,hh:mm:ss [am | pm]]
date—Specifies the day (dd), month (mm), and
year (yy), which you can code as mm/dd/yyyy
or mm-dd-yyyy. If you only specify date, the time
defaults to 00:00:00, which indicates midnight.
The current date is the default.
day—Specifies the day of the week. Values are
today, tomorrow, yesterday, 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. 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
name 1
&symbolic
name 2
&symbolic
name n
Specifies a symbolic parameter assigned a
value. The value is substituted within the
Process when the symbolic parameter is
encountered.
The value for the symbolic parameter must be
in double quotation marks if it is a 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 ¶m
and another symbolic name called ¶meter
in the same Process.)
variable string 1
variable string 2
variable string n
The symbolic name cannot exceed 32 characters.
⌂⌂
Chapter 4. User Guide 147
Parameter Description Values
tracel Specifies the level of trace to perform for a
Process. Tracing by Process can be turned on in
the submit command or as part of the Process
definition.
If you identify the snode or pnode
immediately after the trace level definition, the
trace level is turned on for all Processes
submitted to and from the node identified.
level = 0 |1 | 2 | 4
snode | pnode
file=name
level—Specifies the level of detail displayed in the
trace output. The default is 4.
0—Terminates the trace.⌂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 Sterling
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
)
pend ;
Process Submitted, Process Number = 5
148 Sterling Connect:Direct for UNIX 4.2.0: Documentation
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, Sterling 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. Sterling 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 by Process name.
The Process name is limited
to 8 characters on Sterling
Connect:Direct for Microsoft
Windows and Sterling
Connect:Direct for z/OS.
name | generic | (list)
name—Specifies the Process name, up to
8 alphanumeric characters.
generic—Specifies a nonspecific value
for the Process 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 Locate the Process to be
changed by Process number.
Sterling Connect:Direct
assigns the Process number
when the Process is
submitted.
number from 1–99,999 | (list)
number—Specifies the Process number.
list—Specifies a list of Process numbers.
Enclose the list in parentheses, and
separate each value with a comma.
Chapter 4. User Guide 149
Parameter Description Value
snode Locate the Process to be
changed by the secondary
node name. This parameter
can be used to specify a
specific remote node, a
generic value for matching
remote node names (using
pattern matching), or a list of
multiple remote node names.
The secondary node name
typically contains the 1–16
character remote Sterling
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.
remote node specification | generic | (list)
remote node specification—Identifies a
specific remote node name.
generic—Specifies a nonspecific value
for the remote node name. This generic
value, containing pattern-matching
characters, evaluates to a list of zero or
more remote node names.
list—Specifies a list of remote node
specifications. Enclose the list in
parentheses, and separate each value
with a comma.
submitter Locate the Processes to be
changed by the node
specification (the Sterling
Connect:Direct node name)
and user ID of the Process
owner. The character length
of this parameter is
unlimited.
(node specification, userid) | generic | (list)
node specification, userid—Specifies the
node specification (the Sterling
Connect:Direct node name) and user ID.
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 optional parameters for the change process command are the following:
Parameter Description Value
class Changes the node-to-node
session 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.
The default is 1.
150 Sterling Connect:Direct for UNIX 4.2.0: Documentation
Parameter Description Value
hold Moves the Process to the Hold
or Wait queue.
yes | no | call
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, Sterling Connect:Direct releases
the Process for execution
newsnode Specifies a new remote node
name to assign to the Process.
new remote node specification
prty Changes the priority of the
Process on the TCQ. Sterling
Connect:Direct 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.
1–15, where 15 is the highest priority. If
you do not specify prty, the default is
10.
release Releases the Process from a
held state. This parameter is
equivalent to hold=no.
none
tracel Changes the level of trace to
perform for a Process.
If you identify the SNODE or
PNODE immediately after the
trace level definition, the trace
level is turned on for all
Processes submitted to and
from the node identified.
level = 0 | 1 | 2 | 4
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.
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 151
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 Process name.
The Process name is limited
to 8 characters on Sterling
Connect:Direct for Microsoft
Windows and for z/OS.
name | generic | (list)
name—Specifies the Process name up to 8
alphanumeric characters long.
generic—Specifies a nonspecific value for the
Process 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 Process number. Sterling
Connect:Direct assigns the
Process number when the
Process is submitted. Valid
Process numbers range from
1–99,999.
number | (list)
number—Specifies the Process number.
list—Specifies a list of Process numbers.
Enclose the list in parentheses, and separate
each value with a comma (,).
snode Identify the Process to delete
by the secondary node name.
This parameter can be used
to specify a specific remote
node, a generic value for
matching remote node
names (using pattern
matching), or a list of
multiple remote node names.
The secondary node name
typically contains the 1–16
character remote Sterling
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.
remote node specification | generic | (list)
remote node specification—Identifies a
specific remote node name.
generic—Specifies a nonspecific value for the
remote node name. This generic value,
containing pattern-matching characters,
evaluates to a list of zero or more remote
node names.
list—Specifies a list of remote node
specifications. Enclose the list in parentheses,
and separate each value with a comma.
submitter Identify Processes to delete
by the node specification and
user ID of the Process owner.
The character length of this
parameter is unlimited.
(node specification, userid) | generic | (list)
node specification, userid—Specifies the node
specification and user ID.
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.
152 Sterling Connect:Direct for UNIX 4.2.0: Documentation
The following command deletes all nonexecuting Processes submitted by user ID
cduser on node dallas:
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 by Process name.
The Process name is
limited to 8 characters on
Sterling Connect:Direct
for Microsoft Windows
and Sterling
Connect:Direct for z/OS.
name | generic | (list)
name—Specifies the Process name, up to 8
alphanumeric characters.
generic—Specifies a nonspecific value for the
Process 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 Locate the Process to
remove by Process
number. Sterling
Connect:Direct assigns the
Process number when the
Process is submitted.
number from 1–99,999 | (list)
number—Specifies the Process number.
list—Specifies a list of Process numbers. Enclose
the list in parentheses, and separate each value
with a comma.
snode Locate the Process to
remove by the secondary
node name. This
parameter can be used to
specify a specific remote
node, a generic value for
matching remote node
names (using pattern
matching), or a list of
multiple remote node
names.
The secondary node
name typically contains
the 1–16 character remote
Sterling 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.
remote node specification | generic | (list)
remote node specification—Identifies a specific
remote node name.
generic—Specifies a nonspecific value for the
remote node name. This generic value,
containing pattern-matching characters,
evaluates to a list of zero or more remote node
names.
list—Specifies a list of remote node
specifications. Enclose the list in parentheses,
and separate each value with a comma.
Chapter 4. User Guide 153
Parameter Description Value
submitter Locate the Processes to
remove by the node
specification (the Sterling
Connect:Direct node
name) and user ID of the
Process owner.
(node specification, userid) | generic | (list)
node specification, userid—Specifies the node
specification (the Sterling Connect:Direct node
name) and user ID.
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
Process or terminates a Process
in an orderly fashion as the step
completes. This parameter is
useful if a Process is in the
executing state and waiting for
unavailable resources.
yes | no
yes—Specifies to forcibly and immediately
terminate the Process. The SMGR also
terminates immediately.
no—Specifies to terminate the Process in an
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 Hold queue where it can be
released for re-execution.
yes | no
yes—Specifies to place the Process in the
Hold 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 Sterling Connect:Direct
The stop command initiates an orderly Sterling 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.
154 Sterling Connect:Direct for UNIX 4.2.0: Documentation
You can specify the force, immediate, quiesce, or step parameters with the stop
command.
Note: The force parameter is required when running Sterling Connect:Direct with
the LU6.2 feature on any supported platform other than AIX.
Following are the parameters for the stop command:
Parameter Description
force Forcibly terminates Sterling Connect:Direct
and returns control to the operating system.
immediate Begins an immediate, but orderly shutdown
of all activity and terminates Sterling
Connect:Direct. The software terminates
connections, writes statistics records, closes
files, and shuts down.
quiesce Runs all executing Processes to completion
before shutting down Sterling
Connect:Direct. No new Processes are
started. This is the default value.
step Shuts down Sterling 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 Sterling 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, Sterling Connect:Direct selects all Processes executing or
waiting for execution. Following are the optional parameters for the view process
command:
Chapter 4. User Guide 155
Parameter Description Value
pname Locate the Process to view
by Process name.
The Process name is limited
to 8 characters on Sterling
Connect:Direct for Microsoft
Windows and Sterling
Connect:Direct for z/OS.
name | generic | (list)
name—Specifies the Process name, up to 8
alphanumeric characters.
generic—Specifies a nonspecific value for the
Process 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 Locate the Process to view
by Process number. Sterling
Connect:Direct assigns the
Process number when the
Process is submitted.
number from 1–99,999 | (list)
number—Specifies the Process number.
list—Specifies a list of Process numbers.
Enclose the list in parentheses, and separate
each value with a comma.
queue Specifies the Processes to be
viewed by the specified
queue names.
all | exec | hold | wait | timer
all—Selects Processes from all queues. This is
the 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
secondary node name. This
parameter can be used to
specify a specific remote
node, a generic value for
matching remote node
names (using pattern
matching), or a list of
multiple remote node names.
The secondary node name
typically contains the 1–16
character remote Sterling
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.
remote node specification | generic | (list)
remote node specification—Identifies a
specific remote node name.
generic—Specifies a nonspecific value for the
remote node name. This generic value,
containing pattern-matching characters,
evaluates to a list of zero or more remote
node names.
list—Specifies a list of remote node
specifications. Enclose the list in parentheses,
and separate each value with a comma.
156 Sterling Connect:Direct for UNIX 4.2.0: Documentation
Parameter Description Value
status Specifies the Processes to be
viewed by Process status. If
you do not specify a status
value, information is
generated for all status
values.
EX | HC | HE | HI | HO | HR | HS | PE
| WC | WR | WS | (list)
EX (Execution)—Specifies to select Processes
from the Execution queue.
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 157
Parameter Description Value
submitter Locate the Processes to view
by the node specification (the
Sterling Connect:Direct node
name) and user ID of the
Process owner. The length of
this parameter is unlimited.
(node specification, userid) | generic | (list)
node specification, userid—Specifies the node
specification (the Sterling Connect:Direct
node name) and user ID.
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, Sterling 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 Process name.
The Process name is limited
to 8 characters on Sterling
Connect:Direct for Microsoft
Windows and Sterling
Connect:Direct for z/OS.
name | generic | (list)
name—Specifies the Process name, up to 8
alphanumeric characters.
generic—Specifies a nonspecific value for the
Process 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 Locate the Process to select
by Process number. Sterling
Connect:Direct assigns the
Process number when the
Process is submitted.
number from 1–99,999 | (list)
number—Specifies the Process number.
list—Specifies a list of Process numbers.
Enclose the list in parentheses, and separate
each value with a comma.
158 Sterling Connect:Direct for UNIX 4.2.0: Documentation
Parameter Description Value
queue Specifies the Processes to be
selected by the specified
queue names. The default is
all.
all | exec | hold | wait | timer
all—Selects Processes from all queues. this is
the 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
secondary node name. This
parameter can be used to
specify a specific remote
node, a generic value for
matching remote node
names (using pattern
matching), or a list of
multiple remote node
names.
The secondary node name
typically contains the 1–16
character remote Sterling
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.
remote node specification | generic | (list)
remote node specification—Identifies a
specific remote node name.
generic—Specifies a nonspecific value for the
remote node name. This generic value,
containing pattern-matching characters,
evaluates to a list of zero or more remote
node names.
list—Specifies a list of remote node
specifications. Enclose the list in parentheses,
and separate each value with a comma.
Chapter 4. User Guide 159
Parameter Description Value
status Specifies the Processes to be
selected by Process status. If
you do not specify a status
value, information is
generated for all status
values.
EX | HC | HE | HI | HO | HR | HS | PE
| WC | WR | WS | (list)
EX (Execution)—Specifies to select Processes
from the Execution queue.
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.
160 Sterling Connect:Direct for UNIX 4.2.0: Documentation
Parameter Description Value
submitter Locate the Processes to
select by the node
specification (the Sterling
Connect:Direct node name)
and user ID of the Process
owner. The length of this
parameter is unlimited.
(node specification, userid) | generic | (list)
node specification, userid—Specifies the node
specification (the Sterling Connect:Direct
node name) and user ID.
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
(short or detailed) that
Sterling Connect:Direct
generates for the selected
Processes.
yes | no
yes—Generates a detailed report.
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 =>
-----------------------------------------------------------------------------------
Chapter 4. User Guide 161
Determining the Outcome of a Process
The select statistics command is used to examine Process statistics from the
Sterling Connect:Direct statistics file. The type of information in the statistics report
includes copy status and execution events.
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, Sterling 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
based on the completion
code operator and return
code values associated
with Step Termination.
You must specify the
return code.
operator, nn
operator—Specifies the completion code operator.
Following are the valid completion code
operators:
eq or = or == (equal) This is the default.
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 Sterling Connect:Direct Process
or command.
nn—Specifies the return code value associated
with Step Termination.
destfile Selects statistics based on
a destination file name.
This parameter can be
abbreviated as dest.
dest=/path/file name
For example:
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
162 Sterling Connect:Direct for UNIX 4.2.0: Documentation
Parameter Description Value
pname Locate the statistics to
select by Process name.
The Process name is
limited to 8 characters on
Sterling Connect:Direct
for Microsoft Windows
and Sterling
Connect:Direct for z/OS.
name | generic | (list)
name—Specifies the Process name, up to 8
alphanumeric characters.
generic—Specifies a nonspecific value for the
Process 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 Locate the statistics to
select by Process number.
Sterling Connect:Direct
assigns the Process
number when the Process
is submitted.
number from 1–99,999 | (list)
number—Specifies the Process number.
list—Specifies a list of Process numbers. Enclose
the list in parentheses, and separate each value
with a comma.
reccat Specifies whether the
selection of statistics file
records is based on events
or related to a Process.
CAEV | CAPR | (CAEV, CAPR)
CAEV—Specifies that the selection of statistics
file records is related to an event, such as a
Sterling Connect:Direct shutdown.
CAPR—Specifies that the selection of statistics
file records is related to one or more Sterling
Connect:Direct Processes.
Chapter 4. User Guide 163
Parameter Description Value
recids Specifies the statistics file
records to be selected by
record ID. This parameter
identifies particular types
of statistics records, such
as a copy termination
records or Sterling
Connect:Direct
initialization event
records.
record id | (list)
record id—Selects statistics file records for the
specified record ID.
list—Specifies a list of Process names. Enclose the
list in parentheses, and separate each value with
a comma.
Following are the valid record ID values:
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—Sterling 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.
164 Sterling Connect:Direct for UNIX 4.2.0: Documentation
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—Sterling Connect:Direct information
generated at startup.
NMOP—Network map file opened.
NMPR—The network map is updated through
Sterling Connect:Direct Browser User Interface,
Sterling 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.
Chapter 4. User Guide 165
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.
166 Sterling Connect:Direct for UNIX 4.2.0: Documentation
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—Sterling 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.
Chapter 4. User Guide 167
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 Sterling 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
record by the secondary
node name. This
parameter can be used to
specify a specific remote
node, a generic value for
matching remote node
names (using pattern
matching), or a list of
multiple remote node
names.
The secondary node name
typically contains the
1–16 character remote
Sterling 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.
remote node specification | generic | (list)
remote node specification—Identifies a specific
remote node name.
generic—Specifies a nonspecific value for the
remote node name. This generic value,
containing pattern-matching characters, evaluates
to a list of zero or more remote node names.
list—Specifies a list of remote node specifications.
Enclose the list in parentheses, and separate each
value with a comma.
168 Sterling Connect:Direct for UNIX 4.2.0: Documentation
Parameter Description Value
srcfile Selects statistics based on
a source file name. This
parameter can be
abbreviated as srcf.
srcf=/path/file name
For example:
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
both at and since the
specified time. The date
or day and time are
positional. If you do not
specify date or day, a
comma must precede
time.
[date | day] [, hh:mm:ss [am|pm]]
date—Specifies the day (dd), month (mm), and
year (yy), which you can code as mm/dd/yyyy
or mm-dd-yyyy. If you only specify date, the
time defaults to 00:00:00. The current date is the
default.
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 Sterling
Connect:Direct searches
for statistics records up to
and including the
designated date, day, and
time positional
parameters. If you do not
specify date or day, a
comma must precede
time.
[date | day] [, hh:mm:ss [am|pm]]
date—Specifies the day (dd), month (mm), and
year (yy), which you can code as mm/dd/yyyy
or mm-dd-yyyy. If you only specify date, the
time defaults to 00:00:00. The current date is the
default.
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.
Chapter 4. User Guide 169
Parameter Description Value
submitter Locate the statistics
records to select by the
node specification (the
Sterling Connect:Direct
node name) and user ID
of the Process owner. The
character length of the
parameter is unlimited.
(node specification, userid) | generic | (list)
node specification, userid—Specifies the node
specification (the Sterling Connect:Direct node
name) and user ID.
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 (short or detailed)
that Sterling
Connect:Direct generates
for the selected Processes.
yes | no
yes—Generates a detailed report.
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 162 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
170 Sterling Connect:Direct for UNIX 4.2.0: Documentation
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
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. Sterling 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
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. 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 Sterling
Connect:Direct working directory with the file
name CMGR.TRC. The length of the name
value is unlimited.
Chapter 4. User Guide 171
Parameter Description Value
comm To trace the data sent to
and received from a remote
Sterling Connect:Direct
system within the Session
Manager. You can set this
trace independently from
or in conjunction with the
smgr trace.
If you run both the comm
and smgr traces, trace
output for both traces is
directed to the file name of
the trace last specified.
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 Sterling
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 Sterling
Connect:Direct working directory with the file
name PMGR.TRC. The length of the name
value is unlimited.
172 Sterling Connect:Direct for UNIX 4.2.0: Documentation
Parameter Description Value
smgr To run the trace for Session
Managers created after
issuing the trace command.
Currently executing Session
Managers are unaffected.
If you run both the comm
and smgr traces, trace
output for both traces is
directed to the file name of
the trace last specified.
level=0 |1 | 2 | 4
snode | pnode | tnode
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.
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 Sterling
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
Chapter 4. User Guide 173
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'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
<-bldexp: ok
.
.
.
===================================================================================
Process Queuing
The TCQ controls Process execution as Sterling 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 Sterling Connect:Direct Activity
Sterling 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:
v retain=yes|no|initial
v hold=yes|no|call
v startt=[([date|day] [, hh:mm:ss | [am | pm]])
The following table shows how scheduling parameters affect the logical queues.
174 Sterling Connect:Direct for UNIX 4.2.0: Documentation
Scheduling
Parameter Queue Comments
None of the
scheduling
parameters specified
Wait The Process remains in the Wait queue until
Sterling 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
parameters are
specified)
The Process remains in the Wait queue until
Sterling Connect:Direct establishes a session with
the remote 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.
retain=yes and
hold=no or hold=call
Hold A copy of the Process remains in the Hold queue
to be 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
parameters are
specified)
The default for hold is no.
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:
Chapter 4. User Guide 175
The Execution Queue
Processes are placed in the Execution queue after Sterling 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
Sterling 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
176 Sterling Connect:Direct for UNIX 4.2.0: Documentation
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 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
Chapter 4. User Guide 177
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:
v 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.
v 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.
v If CRC checking is activated, a Process that generates a CRC error is placed in
the Timer queue.
Sterling 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
178 Sterling Connect:Direct for UNIX 4.2.0: Documentation
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.
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.
Sterling Connect:Direct Utilities
Sterling 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. Sterling 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 Sterling 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.
Chapter 4. User Guide 179
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.
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 source file. If no value is specified,
input is read from STDIN.
Path and name of translation
table
-ooutputfile The path and file name of the translation
table output file.
Path and name of translation
output file
180 Sterling Connect:Direct for UNIX 4.2.0: Documentation
Parameter Description Values
-rradix The radix or base of the source file input
data. All numeric values whether from
command line options or input data are
interpreted based on the radix setting.
x | d | o
x—Hexadecimal. This is the
default.
d—Decimal
o—Octal
The default is x.
-ffiller A filler byte value. The entire table is
initialized to this value before the input
data is scanned and applied to the table.
Any keyboard character,
number, or special character,
plus control characters
entered using a preceding
slash.
For example, “\0” is null.
-m The path and file name of a model
translation table. If specified, the model
table is read in and 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.
Path and file name of the
model translation table
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 179when 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:"
Chapter 4. User Guide 181
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:"
Using Translation During File Transfer Operations
Translation is specified in the copy statement of a Sterling Connect:Direct Process.
You can use the default translation table or create a new table.
Translation is specified in the copy statement of a Sterling 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 Sterling Connect:Direct Processes Web site at
http://www.sterlingcommerce.com/documentation/processes/processhome.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
182 Sterling Connect:Direct for UNIX 4.2.0: Documentation
Diagnostic Number Description
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 Sterling Connect:Direct Messages
The Sterling Connect:Direct message file contains records with text for all
messages, including errors and messages from Sterling 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.
Message File Content
The message file is structured much the same way as other Sterling 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 Sterling Connect:Direct message IDs is listed in the following table:
XxxxnnnI
Where:
X Indicates Sterling Connect:Direct
xxx is a 3-character Sterling 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
message ID.
Source module name
short.text A summary of the message. This field is
required.
Summary message, up to
72 characters
Chapter 4. User Guide 183
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.
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 Sterling Connect:Direct
nodes using Sterling Connect:Direct Processes. You have the following options for
decompressing the files. A file can either be:
v Decompressed as it is received by the remote node (available on all Sterling
Connect:Direct platforms)
v Stored on the remote node and later decompressed offline using cdsacomp
(available only on Sterling Connect:Direct and Sterling 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
184 Sterling Connect:Direct for UNIX 4.2.0: Documentation
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 Sterling Connect:Direct /bin directory.
Special Considerations for Using the Standalone Batch
Compression Utility
Consider the following when you are using cdsacomp to precompress files:
v If you precompress a file with the cdsacomp utility, then you cannot specify any
compression options in your Sterling Connect:Direct Process when you copy that
file.
v 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
v If you precompress a file with the cdsacomp utility on a Sterling Connect:Direct
node, then you cannot specify a checkpoint interval in your Sterling
Connect:Direct Process if you decompress the file as it is received by the remote
node.
v 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 Sterling Connect:Direct for
z/OS must match the logical block size of the precompressed source file on
Sterling 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 decompress. This argument is
required.
compress | decompress
The default is compress.
-i Specify the input file to precompress or
decompress. This argument is required.
full or relative path of input file
-o Specify the output file to save. If the
output file already exists, it is
overwritten. This argument is required.
full or relative path of output
file
Chapter 4. User Guide 185
Parameter Description Values
-z Use this option with “-m compress” to
override default compression values. This
argument is optional.
When decompressing, the values used
during compression are used.
level, window, memory
level—Compression level.
The range is 1–9. The default
is 1.
1—Provides the least
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.
-x Use this option to translate the file.
If this parameter is not specified, the file
is not translated.
This parameter is mutually exclusive
with -codepage.
full path to translate table file
| relative path to translate
table file
-p Use this option to specify codepages for
file conversion. Default is no codepage
translation.
This parameter is mutually exclusive
with -xlate.
source codepage, destination
codepage
186 Sterling Connect:Direct for UNIX 4.2.0: Documentation
Parameter Description Values
-d Specify the datatype of the file.
When you use “-m compress”, the
datatype values result in the following:
v text
Strips newline characters from each
record
Supports -s and -a parameters
Uses data attributes of
blocksize=23040, recfm=vb,
lrecl=23036, dsorg=ps
v binary
Uses data attributes of
blocksize=23040, recfm=u, lrecl=0,
dsorg=ps
Does not support -s and -a parameters
v 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:
v text
Inserts newline characters into each
record
Supports the -s parameter
v binary
Does not support the -s parameter
v VB
Does not support -x, -p, and -s
parameters
text | binary | VB
The default is text.
-b Specify the block size of the output file.
This parameter is valid only when you
specify ⌂“-m compress” for the
compression option.
nnnnn
The range is 4096–32760. The
default is 27920.
-s Use this option to strip trailing blanks.
This parameter is valid only when you
specify ⌂“-d text” for the datatype of the
file.
y | n
y—yes
n—no
The default is y.
Chapter 4. User Guide 187
Parameter Description Values
-a Use this option to replace zero-length
records with a single, blank character.
This parameter is valid only when you
specify the following: “-d text” and “-m
compress”.
y | n
y—yes
n—no
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 utility.
No values are available for
this 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
188 Sterling Connect:Direct for UNIX 4.2.0: 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 Sterling 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.
Chapter 4. User Guide 189
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 Sterling
Connect:Direct components are not installed, then some of the files will not be
found. For example, if the Command Line Interface (CLI) is installed but the
Sterling 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 137.
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 Sterling Connect:Direct
configuration information using the Configuration Reporting Utility (cdcustrpt).
Configuration reports can be generated for the following Sterling Connect:Direct
components:
v Base installation of Sterling Connect:Direct
v Sterling Connect:Direct Secure Plus for UNIX
v Sterling Connect:Direct for SWIFTNet for UNIX
During the Sterling Connect:Direct installation, cdcustrpt is installed in the
<installation>/etc/ directory.
190 Sterling Connect:Direct for UNIX 4.2.0: Documentation
Generating a Configuration Report on the Base Installation
Before you begin
When you use cdcustrpt to generate a report on the base Sterling Connect:Direct
installation, it reports the following types of system information:
v Name and other information of the operating system
v Space on file systems
v Virtual memory statistics
v Contents of the Sterling Connect:Direct installation directory
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 189.
In this procedure, default values are computed by the utility based on the location
and name of the installed Sterling 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 Sterling 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 191
###########################################################################
####### 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 Sterling Connect:Direct
Secure Plus for UNIX
If cdcustrpt detects the Sterling Connect:Direct Secure Plus directory in the
installation directory, <installation>/ndm/secure+/, it invokes the Sterling
Connect:Direct Secure Plus Command Line Utility (splicli.sh) to report on Secure+
parameters. If Sterling Connect:Direct Secure Plus is detected, you are prompted to
enter the path to the Sterling 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:
192 Sterling Connect:Direct for UNIX 4.2.0: Documentation
===== Begin: Secure+ parameters =====
=========================================
All secure+ nodes:
**************************************************************
* Secure+ Command Line Interface *
* Connect:Direct for UNIX v4.0.00 *
*------------------------------------------------------------*
* Copyright (c) 1999, 2008 Sterling Commerce Inc. *
* All Rights Reserved. *
**************************************************************
SPCLI> display all;
name=.Local
baserecord=brown_aix38
type=l
protocol=tls
override=n
authtimeout=120
stsenablesig=n
stsenableautoupdate=n
stslimitexportversion=y
stsenableenc=y
stsencalgs=(ideacbc128,tdescbc112,descbc56)
stsauthlocalkey=0305.095A.44E3.BD87.F476.45E8.09B1.FCCA.45ED.67B0.01AD
stsprevauthkeyexpdatetime=
stssiglocalkey=0204.BABA.613D.2FA5.AAE6.0BD4.5847.B610.A17F.C7DD.0AA2
stsprevsigkeyexpdatetime=
ssltlsseaenable=n
seacertvaldef=
ssltlstrustedrootcertfile=/home/nis01/jbrown1/CertificateWizard/cert.crt
ssltlscertfile=/home/nis01/jbrown1/CertificateWizard/athena.selfsigned.keycert.txt
ssltlsenablefipsmode=n
ssltlsenableclientauth=n
ssltlsenablecipher=(TLS_RSA_WITH_AES_256_CBC_SHA,TLS_RSA_WITH_AES_128_CBC_SHA)
2007/10/19 14:27:37 parmfile upgraded: SPV4
2007/03/27 09:25:14 jbrown1
2007/03/22 09:54:55 jbrown1
Generating a Configuration Report on Sterling Connect:Direct for
SWIFTNet for UNIX
If cdcustrpt detects the SWIFTNet directory in the installation directory,
<installation>/ndm/SwiftNet/, it includes the contents of the CDSwiftnet.cfg file in
the report. Values for password parameters are replaced by a string of asterisks (*).
The following example shows an excerpt from a sample report:
====================================================================================
Begin: /sci/users/jbrown1/swift31/ndm/SwiftNet/Version3/cfg/CDSwiftnet.cfg
====================================================================================
===Content of /sci/users/jbrown1/swift31/ndm/SwiftNet/Version3/cfg/CDSwiftnet.cfg===
o
# Connect:Direct UNIX for SWIFTNet 3.1.00 configuration file.
#
[Directory.Info]
CD.HomeDir="/sci/users/jbrown1/swift31"
CDSwiftnet.HomeDir="/sci/users/jbrown1/swift31/ndm/SwiftNet/Version3"
# Concatenate the RequestorDN and ResponderDN to these directories for the Request
Handler.
Reception.Dir="/sci/users/jbrown1/reception"
Download.Dir="/sci/users/jbrown1/download"
# This directory must be specified to use the #OLDEST_FILE feature.
Success.Dir="/sci/users/jbrown1/success"
[Log.Info]
#Log.MaxSize="1048576"
Log.MaxSize="35000"
Log.MaxVersions="5"
[connection.info]
Chapter 4. User Guide 193
# Connection information for Connect:Direct’s API port. (Used when forwarding files
to the back office.)
Comm.Info="spyglass;10102"
Userid="jbrown1"
Passwd="******** "# this is a test
#ClientInfo="/sci/users/jbrown1/swift31/ndm/SwiftNet/Version3/program/<Encrypted
userid/password file generated by the LCU>"
Writing Custom Programs
The Sterling Connect:Direct Application Programming Interface (API) allows you
to write custom programs in either C or C++ to use with Sterling Connect:Direct.
With the C functions or the C++ classes, you can create programs to perform the
following tasks:
v Establish a connection to the Sterling Connect:Direct server
v Disconnect from the server
v Receive command responses from the server
v Send commands to the server
This topic describes the format of the Sterling Connect:Direct API functions and
classes and provides samples of their use. Sample programs are provided that use
the Sterling Connect:Direct API functions and classes to issue commands and
receive responses from the Sterling 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++ V8.0 for AIX
Sun Solaris SPARC/x86 C++5.7
HP aCC: HP ANSI C++ B3910B A.03.73
HP-Itanium aCC: HP ANSI C++ B3910B A.06.07
Linux c++ version 3.3.3
Use the commands defined in the following table to compile a custom C++
program using the C++ API calls:
Platform C++ Compile Command
AIX
64-bit /usr/vacpp/bin/xlC -q64 -qinline -I../include -+ -o sdksample sdksample.C ../lib/ndmapi64.a -lbsd -ldl
-lsrc -lpthreads
32-bit /usr/vacpp/bin/xlC -qinline -I../include -+ -o sdksample sdksample.C ../lib/ndmapi.a -lbsd -ldl -lsrc
-lpthreads
Sun
32-bit /opt/SUNWspro/bin/CC -DBSD_COMP -I../include -o sdksample sdksample.C ../lib/ndmapi.a
-L/usr/ucblib -L/usr/lib -lsocket -lrpcsoc -lnsl -lelf -ldl
Note: If /usr/ucblib is not in the LD_LIBRARY_PATH variable, add ⌂-R/usr/ucblib to the compile
command.
194 Sterling Connect:Direct for UNIX 4.2.0: Documentation
Platform C++ Compile Command
64-bit /opt/SUNWspro/bin/CC -xarch=generic64 -DBSD_COMP -I../include -o sdksample sdksample.C
../lib/ndmapi64.a
-L/usr/ucblib/sparcv9 -L/usr/lib/sparcv9
-L/usr/ucblib/amd64 -lsocket -lrpcsoc -lnsl -lelf -ldl
-R/usr/ucblib/sparcv9 -R/usr/ucblib/amd64
HP
32-bit /opt/aCC/bin/aCC -AA -I../include -o sdksample sdksample.C ../lib/ndmapi.a -lrpcsoc -lnsl -ldld
-Wl,+s
64-bit /opt/aCC/bin/aCC -AA +DD64 -I../include -o sdksample sdksample.C ../lib/ndmapi64.a
-L/usr/lib/pa20_64 -lnsl -ldld -Wl,+s
HP-Itanium
32-bit /opt/aCC/bin/aCC -I../include -o sdksample sdksample.C ../lib/ndmapi.a -lrpcsoc -lnsl -ldld -Wl,+s
-lunwind
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
32-bit g++ -m32 -I../include -O -DLINUX -o sdksample sdksample.C ../lib/ndmapi.a -ldl -lnss_nis
/usr/lib/libstdc++.so.5
Note: If you are compiling for Linux z/OS, change -m32 to -m31.
64-bit g++ -I../include -O -DLINUX -o sdksample sdksample.C ../lib/ndmapi64.a -ldl -lnss_nis
/usr/lib64/libstdc++.so.5
Note: A 64-bit Linux OS installation is required to compile 64-bit binaries.
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:
Platform C Compile Command
AIX
32-bit /usr/vacpp/bin/xlc -I../include -+ -o apicheck apicheck.c ../lib/ndmapi.a -lbsd -ldl -lsrc -lC -lpthreads
64-bit /usr/vacpp/bin/xlc -q64 -I../include -+ -o apicheck apicheck.c ../lib/ndmapi64.a -lbsd -ldl -lsrc -lC
-lpthreads
Sun
32-bit /opt/SUNWspro/bin/cc -DBSD_COMP -I../include -o apicheck apicheck.c ../lib/ndmapi.a -L/usr/ucblib
-L/usr/lib -lCstd -lsocket -lrpcsoc -lnsl -lelf -ldl -lCrun
Note: If /usr/ucblib is not in the LD_LIBRARY_PATH variable, add ⌂-R/usr/ucblib to the compile
command.
64-bit /opt/SUNWspro/bin/cc -xarch=generic64 -DBSD_COMP -I../include -o apicheck apicheck.c
../lib/ndmapi64.a
-L/usr/ucblib/sparcv9 -L/usr/lib/sparcv9
-L/usr/ucblib/amd64 -lsocket -lCstd -lCrun -lrpcsoc -lnsl -lelf -ldl
-lCrun -R/usr/ucblib/sparcv9 -R/usr/ucblib/amd64
Chapter 4. User Guide 195
Platform C Compile Command
HP
32-bit /opt/ansic/bin/cc -I../include -o apicheck apicheck.c ../lib/ndmapi.a -lrpcsoc -lnsl -ldld -Wl,+s -lcl
-lstd_v2 -lCsup_v2
64-bit /opt/ansic/bin/cc +DD64 -I../include -o apicheck apicheck.c ../lib/ndmapi64.a -L/usr/lib/pa20_64 -lnsl
-ldld -Wl,+s -lcl -lstd_v2 -lCsup_v2
HP-Itanium
32-bit /opt/ansic/bin/cc -I../include -o apicheck apicheck.c ../lib/ndmapi.a -lrpcsoc -lnsl -ldld -Wl,+s -lcl
-lstd_v2 -lCsup -lunwind
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
32-bit gcc -m32 -I../include -O -DLINUX -o apicheck apicheck.c ../lib/ndmapi.a -ldl -lnss_nis
/usr/lib/libstdc++.so.5
64-bit gcc -I../include -O -DLINUX -o apicheck apicheck.c ../lib/ndmapi64.a -ldl -lnss_nis /usr/lib64/
libstdc++.so.5
Note: A 64-bit Linux OS installation is required to compile 64-bit binaries.
LinuxS390
32-bit gcc -m31 -I../include -O -DLINUX -o apicheck apicheck.c ../lib/ndmapi.a -ldl -lnss_nis
/usr/lib/libstdc++.so.5
64-bit gcc -I../include -O -DLINUX -o apicheck apicheck.c ../lib/ndmapi64.a -ldl -lnss_nis /usr/lib64/
libstdc++.so.5
Note: A 64-bit Linux OS installation is required to compile 64-bit binaries.
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 Sterling Connect:Direct
Java Application Interface is recommended for Java programs that invoke the
services of Sterling 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
137 for instructions on setting the environment variable.
Use the following Sterling 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.
196 Sterling Connect:Direct for UNIX 4.2.0: Documentation
C++ Function C Function Description
ndmapi_sendcmd() ndmapi_sendcmd_c() Sends commands to Sterling 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
Sterling Connect:Direct. The contents of the
response buffer are returned.
ndmapi_disconnect() ndmapi_disconnect_c() Terminates the API connection.
Three types of Sterling Connect:Direct command responses are returned by these
functions.
v Informational responses return information about the submitted command.
v Data responses, stored in the resp_buffer, contain data records.
v 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 Sterling 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 Sterling Connect:Direct Using
ndmapi_connect() or ndmapi_connect_c()
Use ndmapi_connect() or ndmapi_connect_c() to create a connection to Sterling
Connect:Direct so that an application can send commands and receive responses
Chapter 4. User Guide 197
from the commands. Control returns to the application when the connection is
established and Sterling 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
The following table describes the parameters for the ndmapi_connect() or
ndmapi_connect_c() function:
Parameter Description Value
error A pointer to a Sterling Connect:Direct-defined structure
that contains error information or status information.
Pointer
ndm_hostname A pointer to the text specification of the Sterling
Connect:Direct host to which the connection is made. If
this parameter is not 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.
Null-
terminated
string
ndm_portname A pointer to the host port number. If this parameter is
not 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.
Pointer
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
Sterling 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 ();
198 Sterling Connect:Direct for UNIX 4.2.0: Documentation
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():
Parameter Description Value
error A pointer to a Sterling
Connect:Direct-defined structure that
contains error information or status
information.
Pointer
resp_length A pointer to the length, in bytes, of the
application buffer to receive the
response. The API sets this parameter to
the number of bytes returned.
Pointer to number of bytes
returned or 0 if you no longer
want to receive responses.
Setting this field to zero purges
all queued responses.
resp_buffer A pointer to the application buffer that
receives the command or submit
response. This buffer should allocate
4096 bytes.
The format of resp_buffer is a free-form
text record structure. Field names are
four characters long and all uppercase.
The data can be any length and can
include blanks. The structure is:
field name=data | field name=data |...
For example:
SUBM = username | PNUM = 12 |
PNAM = proc1 |...
A local buffer, with a size greater
than or equal to that set by
resp_length and filled in by
ndmapi_recvresp() or
ndmapi_recvresp_c().
The CLI passes the resp_buffer to
AWK for parsing. Valid values
include:
ADMN—Sterling Connect:Direct
administrator name
ADPH—Sterling Connect:Direct
administrator phone number
CCOD—Completion code
CKPT—Checkpoint
CLAS—Class
CSDS—Copy step start
timestamp
CSPE—Secure+ enabled indicator
CSPP—Secure+ protocol
CSPS—Secure+ cipher suite
Chapter 4. User Guide 199
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—Sterling 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
200 Sterling Connect:Direct for UNIX 4.2.0: Documentation
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
Chapter 4. User Guide 201
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)
202 Sterling Connect:Direct for UNIX 4.2.0: Documentation
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 ndmapi_recvresp_c() calls must be
issued for more information. This flag
occurs only on select process and select
statistics commands.
None
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
);
Chapter 4. User Guide 203
Sending a Command to Sterling 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 Sterling 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,",
&resp_moreflag,
&ret_data
);
Following are the parameters for ndmapi_sendcmd() or ndmapi_sendcmd_c():
Parameter Description Value
error A pointer to a Sterling Connect:Direct-defined structure
that contains error information or status information.
Pointer
cmd_text A pointer to the null-terminated text string that specifies
the command to send to Sterling Connect:Direct. The
command text must 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.
Pointer to a text
string
resp_moreflag A pointer to the flag that indicates that more responses
are pending for the command just executed. Invoke
ndmapi_recvresp() or ndmapi_recvresp_c() to retrieve
the extra responses.
Pointer to a flag
ret_data A pointer to a structure containing internal response
information for a command. The structure is:
struct sendcmd_data {
char * cmd_name;
ulong cmd_id;
long data1;
long data2;
long data3;
};
Pointer to a
structure
sendcmd_data Provides the caller with some information about the user
request. Because parsing of command text occurs at the
CMGR, the End User Application (EUA) has no way to
identify the command that was submitted, unless it
generated the text.
Information
about the user
request
cmd_name A pointer to a string with the name of the command
submitted. The CLI uses this pointer to display
completion messages. This field enables you to display
unique completion messages without any knowledge of
a specific command in the EUA.
Pointer to name
of command
204 Sterling Connect:Direct for UNIX 4.2.0: Documentation
Parameter Description Value
cmd_id A four-byte identifier of the command that was found in
the command text. Following are the four-byte
identifiers:
/**************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.
Four-byte
identifier
data1, data2,
and data3
For future expansion. data1 is used with the submit
command to 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 Sterling Connect:Direct methods
and provides connection, command, data retrieval, and error services. Each method
returns either CD_SUCCESS or CD_FAILURE.
Chapter 4. User Guide 205
Note: The environment variable NDMAPICFG must be set to the pathname of the
client configuration file. Refer to “Starting the CLI” on page 137for instructions on
setting the environment variable.
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:
206 Sterling Connect:Direct for UNIX 4.2.0: Documentation
Method Description Parameter Return Values
Connect Provides a connection to the
Sterling Connect:Direct server.
Connect() with a void parameter
connects to the hostname and
port specified in the client
configuration file.
void or a
pointer to an
IP address
and port.
CD_SUCCESS or
CD_FAILURE
DisConnect Disconnects the current session. void CD_SUCCESS or
CD_FAILURE
SendCommand Sends a Sterling Connect:Direct
command to the server for
processing.
Pointer to a
command
text buffer.
CD_SUCCESS or
CD_FAILURE
ReceiveResponse Receives the response from a
previously issued command,
such as the select statistics
command.
void CD_SUCCESS or
CD_FAILURE
GetResponse Retrieves the response from the
ReceiveResponse call.
void Pointer to a
response buffer.
GetResponseLength Returns the length of the
previously received response
buffer.
void Length of the
response buffer from
the previously
issued call.
MoreData Returns a value indicating if
outstanding data from the
previously issued send
command call is available. If the
return value is TRUE, call
ReceiveResponse again to
retrieve more data.
void TRUE—If more data
is outstanding.
FALSE—If no data
is outstanding.
GetCommandName Returns the command name of
the previously issued send
command, such as the submit
command.
void Pointer to a
command name
buffer.
GetProcessNumber Returns the Process number of a
previously issued submit
command.
void Process number of a
submit command.
-1—If no submit
command can be
found.
GetProcessCount Returns the number of Processes
affected by the last send
command that issued a delete,
change, or flush process.
void Process number of a
submit command
that issued a delete,
change or flush
process.
-1—If no submit
command can be
found.
GetCurrentError Moves the error data pointer to
the current error in the list.
void TRUE—If successful
FALSE—If no
current error exists.
GetNextError Moves the error data pointer to
the next error in the list.
void TRUE—If successful
FALSE—If no more
errors are found.
Chapter 4. User Guide 207
Method Description Parameter Return Values
GetPreviousError Moves the error data pointer to
the previous error in the list.
void TRUE—If successful
FALSE—If no
previous error
exists.
GetFirstError Moves the error data pointer to
the first error in the list.
void TRUE—If successful
FALSE—If no error
is found.
GetLastError Moves the error data pointer to
the last error in the list.
void TRUE—If successful,
otherwise FALSE.
GetMsgID Retrieves the message of the
current error data block.
You must call one of the
GetXXXXError methods before
calling this method in order to
retrieve the proper results.
void Return Value:
Pointer to a message
ID if data block is
value.
GetFeedBackCode Returns the feedback code of the
current error data block.
void Feedback code.
GetReturnCode Returns the Sterling
Connect:Direct return code.
void One of the valid
Sterling
Connect:Direct
return code: 1,4,8,16.
GetStatus Returns the status. void Sterling
Connect:Direct
status code.
GetSubstitute Returns the current substitution
buffer associated with the error.
void Pointer to a
substitution buffer.
DisplayError Displays the current error chain
to an output location.
Parameters:
Pointer to a
file I/O
structure.
Return Value:
Returns the highest
error found in the
error chain or -1 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;
208 Sterling Connect:Direct for UNIX 4.2.0: Documentation
// 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;
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
Sterling Connect:Direct. The user exit programs are used by Sterling Connect:Direct
to invoke user-specific logic at strategic points within Sterling 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
Sterling Connect:Direct and the exit runs as long as Sterling 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:
Chapter 4. User Guide 209
Program Description
File Open Exit Sterling 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 Security Exit enables you to implement
your own security system or provide access
to a third-party security system.
User Exit Functions
A connection between the user exit and Sterling 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 Sterling 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
Sterling Connect:Direct and the user exit program.
recv_exit_msg() recv_exit_msg_c() Used by both Sterling 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 Sterling 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 Sterling 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.
210 Sterling Connect:Direct for UNIX 4.2.0: Documentation
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 user exit programs. Because the file open
and security exit 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.
Name of log file or
trace file
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 Sterling
Connect:Direct and the user exit program
were successfully initialized.
ERROR_RC Communications between Sterling
Connect:Direct and the user exit program
could not be initialized.
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 Sterling 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 can use is
EXIT_PROGRAM.
EXIT_PROGRAM
msg_type A pointer to the name of the received message.
Messages are requests from Sterling Connect:Direct
and the associated response from the user exit
program.
Pointer to message
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
Chapter 4. User Guide 211
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: Sterling 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 program can use is EXIT_PROGRAM.
EXIT_PROGRAM
fd The file descriptor of a file that the user exit program
opened in the place of Sterling Connect:Direct, similar to
one returned by the open(2) function.
File descriptor
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.
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: Sterling 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 Sterling 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 Sterling 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
212 Sterling Connect:Direct for UNIX 4.2.0: Documentation
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 can use is
EXIT_PROGRAM.
EXIT_PROGRAM
msg_type A message name. Messages are requests from
Sterling Connect:Direct and the associated response
from the user exit program.
Pointer to message
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:
Sterling Connect:Direct terminated or an
invalid value is used for the exit_flag or
msg_type parameters.
Overview of User Exit Messages
Sterling 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.
Statistics Exit Message
The statistics exit has only one type of message, the STATISTICS_LOG_MSG.
Sterling Connect:Direct sends a STATISTICS_LOG_MSG to the user exit program.
Every time Sterling Connect:Direct writes a statistic record, this message provides
an exact copy of the character string. The STATISTICS_LOG_MSG contains the
Sterling Connect:Direct statistics record.
File Open Exit Messages
The file open exit has four types of messages:
v FILE_OPEN_OUTPUT_MSG
v FILE_OPEN_OUTPUT_REPLY_MSG
v FILE_OPEN_INPUT_MSG
v FILE_OPEN_INPUT_REPLY_MSG
The file open exit has the following limitations:
v 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
Chapter 4. User Guide 213
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.
v 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 Sterling Connect:Direct.
v If the oflag specifies opening a file with write access and the user exit changes
access to read-only, Sterling Connect:Direct will fail when it attempts to write to
a read-only file.
v The upload and download parameters that restrict directory access are ignored
for this user exit.
FILE_OPEN_OUTPUT_MSG
During the copy statement process, Sterling Connect:Direct sends a
FILE_OPEN_OUTPUT_MSG to the user exit program to open the destination file.
The FILE_OPEN_OUTPUT_MSG contains:
v The open function oflag parameter (for example,
O_CREAT|O_RDWR|O_TRUNC)
v The open function mode parameter, which controls file permissions
v UNIX user ID that will own the file
v UNIX group ID that will own the file
v UNIX user name
v A copy of the Sterling Connect:Direct copy control block
v A copy of the Sterling 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 Sterling Connect:Direct
FILE_OPEN_OUTPUT_MSG. The FILE_OPEN_OUTPUT_REPLY_MSG contains:
v Status value of zero for successful or non zero for failure
v Status text message (if status value is failure, status text message is included in
the error message)
v Pipe pid (for pipe I/O, the UNIX process ID of the shell process that is
performing the shell command for pipe I/O)
v 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 Sterling Connect:Direct.
FILE_OPEN_INPUT_MSG
During the copy statement Process, Sterling Connect:Direct sends a
FILE_OPEN_INPUT_MSG to the user exit program to open the source file. The
FILE_OPEN_INPUT_MSG contains:
v The open function oflag parameter (for example, O_RDONLY)
v The open function mode parameter, which controls file permissions
v UNIX user ID that will own the file
214 Sterling Connect:Direct for UNIX 4.2.0: Documentation
v UNIX group ID that will own the file
v UNIX user name
v A copy of the Sterling Connect:Direct copy control block
v A copy of the Sterling 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 Sterling Connect:Direct FILE_OPEN_INPUT_MSG. The
FILE_OPEN_INPUT_REPLY_MSG contains:
v Status value of zero for success or non zero for failure
v Status text message (if status value is failure, status text message is included in
the error message)
v Pipe pid (for pipe I/O, the UNIX process ID of the shell process that is
performing the shell command for pipe I/O)
v Actual file name opened (used in statistics log messages)
Security Exit Messages
The security exit contains four types of messages:
v GENERATE_MSG
v GENERATE_REPLY_MSG
v VALIDATE_MSG
v VALIDATE_REPLY_MSG
CAUTION:
If the security exit is used, Sterling Connect:Direct relies on it for user ID
authentication. If the security exit is not implemented correctly, security can be
compromised.
GENERATE_MSG
Sterling 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:
v Submitter ID
v PNODE ID
v PNODE ID password, if user specified one
v SNODE ID
v SNODE ID password, if user specified one
v PNODE name
v SNODE name
GENERATE_REPLY_MSG
The user exit program sends a reply message to Sterling Connect:Direct. The
GENERATE_REPLY_MSG contains:
v Status value of zero for success or non zero for failure
v Status text message (if status value is failure, status text message is included in
the error message)
Chapter 4. User Guide 215
v ID to use for security context on the SNODE side (may or may not be the same
ID as in the generate message)
v Security token used in conjunction with ID for security context on the SNODE
side
VALIDATE_MSG
Sterling 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:
v Submitter ID
v PNODE ID
v PNODE ID password, if user specified one
v SNODE ID
v SNODE ID password, if user specified one
v PNODE name
v SNODE name
v ID to use with security token
v Security token (password, PASSTICKET, or other security token)
VALIDATE_REPLY_MSG
The user exit program sends a reply message to the Sterling Connect:Direct
VALIDATE_MSG. The VALIDATE_REPLY_MSG contains:
v Status value of zero for success or non zero for failure
v Status text message (if status value is failure, status text message is included in
the error message)
v ID used for security context
v Security token to use in conjunction with ID for security context
User Exit Stop Message
Sterling 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 Sterling
Connect:Direct Processes the copy statement Process file.
Exit Log Files
If user exit programs are specified in the initparm.cfg, Sterling 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:
v stat_exit.log
v file_exit.log
v security_exit.log
Note: You can access the log files through the normal printf() and fprintf
(stderr,...) functions.
216 Sterling Connect:Direct for UNIX 4.2.0: Documentation
The log files are located in the installed (d_dir) working directory:
.../d_dir/work/cd_node
Chapter 4. User Guide 217
218 Sterling Connect:Direct for UNIX 4.2.0: Documentation
Chapter 5. Using FASP with IBM Aspera High-Speed Add-on
for Sterling Connect:Direct for UNIX (V4.2.0.3 or later)
IBM Aspera High-Speed Add-on for Sterling 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 Sterling Connect:Direct for UNIX (V4.2.0.4 or
later) supports interoperability with Sterling Connect:Direct for Microsoft Windows
(V.4.7.0.4 or later) and Sterling 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 Sterling Connect:Direct for UNIX with IBM Aspera High-Speed Add-on
and Sterling Secure Proxy (V4.2.0.4 or later)” on page 221
You can send files using IBM Aspera High-Speed Add-on through Sterling Secure
Proxy using Sterling 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 Sterling 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:
© Copyright IBM Corp. 1993, 2016 219
v 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.
v Endpoint license - can send and receive files using FASP when connected to a
node that has a DataCenter license.
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:
v FASP (Yes | No)
v FASP POLICY (Values are the same as the FASP Local and Remote node record
parameters)
v FASP.FILESIZE.THRESHOLD (Values are the same as the FASP Local and
Remote node record parameters)
v FASP.BANDWIDTH (Values are the same as the FASP Local and Remote node
record parameters)
FASP Parameters are applicable in three different contexts:
v 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
v 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
v 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
220 Sterling Connect:Direct for UNIX 4.2.0: Documentation
fasp.policy=fixed
fasp.bandwidth=500M
fasp.filesize.threshold=10G
to
(
file = /tmp/examplein
snode
disp = rpl
)
Process statement example:
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 Sterling Connect:Direct for UNIX with IBM Aspera High-Speed
Add-on and Sterling Secure Proxy (V4.2.0.4 or later)
You can send files using IBM Aspera High-Speed Add-on through Sterling Secure
Proxy using Sterling Connect:Direct for UNIX.
FASP is supported in Sterling Secure Proxy V3.4.3 or later. If you send a file from
your local Sterling Connect:Direct for UNIX node configured for FASP, it passes
through your Sterling 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 Sterling Secure Proxy between
Connect:Direct nodes:
fasp=(yes|no|ssp,yes|no|ssp)
Chapter 5. Using FASP with IBM Aspera High-Speed Add-on for Sterling Connect:Direct for UNIX (V4.2.0.3 or later) 221
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
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
fasp=
Protocol SSP Protocol SSP Protocol SNODE
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
222 Sterling Connect:Direct for UNIX 4.2.0: Documentation
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 IBM Sterling Secure Proxy (V3.4.3 or later).
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:
v If you installed Sterling 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.
v If you upgraded from a previous version of Sterling 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:\
Chapter 5. Using FASP with IBM Aspera High-Speed Add-on for Sterling Connect:Direct for UNIX (V4.2.0.3 or later) 223
Parameter Value
fasp Optional. Default is no if the parameter is
not present. Enables FASP.
v If set to no, FASP is disabled.
v 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)
v This setting can be overridden by the
remote node record or process parameters.
v The remote server must have FASP
enabled.
fasp.filesize.threshhold Optional. Used to restrict small files from
being sent using FASP.
v 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.
v Default is 1GB.
v You can use KB, MB, or GB designators. If
no designator is included, the system uses
bits.
v 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.
v Default value can be changed, but cannot
exceed the bandwidth specified in the
license key.
v You can use KB, MB, or GB designators. If
no designator is included, the system uses
bits per second.
v This setting can be overridden by the
remote node record or process parameters,
but cannot exceed the bandwidth
specified in the license key.
224 Sterling Connect:Direct for UNIX 4.2.0: Documentation
Parameter Value
fasp.policy Optional. Specifies the fairness of each
transfer. Default is fair.
v This setting can be overridden by the
remote node record or process parameters.
v 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.
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:\
Chapter 5. Using FASP with IBM Aspera High-Speed Add-on for Sterling Connect:Direct for UNIX (V4.2.0.3 or later) 225
Parameter Value
fasp Optional. Valid values are yes and no.
Enables FASP.
v If set to no, files sent to this remote node
will not use FASP.
v If set to yes, files sent to this remote node
will default to use FASP instead of
TCP/IP.
v This setting can be overridden by the
process parameters.
v The remote server must have FASP
enabled.
fasp.filesize.threshhold Optional. Used to restrict small files from
being sent using FASP.
v 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.
v Default is 1GB.
v You can use KB, MB, or GB designators. If
no designator is included, the system uses
bits.
v 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.
v Default value can be changed, but cannot
exceed the bandwidth specified in the
license key.
v You can use KB, MB, or GB designators. If
no designator is included, the system uses
bits per second.
v This setting can be overridden by the
process parameters, but cannot exceed the
bandwidth specified in the license key.
226 Sterling Connect:Direct for UNIX 4.2.0: Documentation
Parameter Value
fasp.policy Optional. Specifies the fairness of each
transfer. Default is fair.
v This setting can be overridden by the
process parameters.
v 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.
FASP004E FASP004E: Lock timeout.
Chapter 5. Using FASP with IBM Aspera High-Speed Add-on for Sterling Connect:Direct for UNIX (V4.2.0.3 or later) 227
Non-Detailed Statistics Mode (Message ID
only) Detailed Statistics Mode
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:
v FASP=>Y indicates that FASP was used to transfer this file. FASP=>N would
indicate TCP/IP was used.
v FSPL=>FAIR is the policy negotiated for this file transfer.
228 Sterling Connect:Direct for UNIX 4.2.0: Documentation
v FSBW=>1000000000 is the bandwidth negotiated for this file transfer (in bits per
second).
v FMBC =>2 is the high water mark for the number of FASP buffers used
v FBCS =>16777216 is the FASP buffer size
v FSTH =>1073741824 is filesize threshold
v 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:
v Firewall navigation source ports should not be used with FASP
v Silent installation does not support the FASP configuration parameters
Chapter 5. Using FASP with IBM Aspera High-Speed Add-on for Sterling Connect:Direct for UNIX (V4.2.0.3 or later) 229
230 Sterling Connect:Direct for UNIX 4.2.0: Documentation
Chapter 6. Introduction to Sterling Connect:Direct Secure Plus
for UNIX
The IBM Sterling Connect:Direct Secure Plus for UNIX application provides
enhanced security for Sterling 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 Sterling Connect:Direct Secure Plus.
Introduction to Sterling Connect:Direct Secure Plus for UNIX
The IBM Sterling Connect:Direct Secure Plus for UNIX application provides
enhanced security for Sterling 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 Sterling 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:
v Authentication verifies that the entity on the other end of a communications
link is the intended recipient of a transmission.
v Non-repudiation provides undeniable proof of origin of transmitted data.
v Data integrity ensures that information is not altered during transmission.
v Data confidentiality ensures that data remains private during transmission.
Security Features
Sterling Connect:Direct Secure Plus enables you to implement multiple layers of
security. You can select one of two security protocols to secure data during
electronic transmission: Transport Layer Security (TLS) or Secure Sockets Layer
protocol (SSL). Depending on the security needs of your environment, you can also
validate certificates using the IBM Sterling External Authentication Server
application.
Sterling Connect:Direct provides alternative cryptographic solutions depending
upon the protocol enabled. The following table identifies the protocols available
and the encryption algorithms available:
© Copyright IBM Corp. 1993, 2016 231
Protocol
Encryption
Algorithm
RC4 DES Triple
DES
AES HMAC RSA DSA SHS RNG
Sterling
Connect:Direct
Secure
Plus
V4.2
SSL
TLS1.1
TLS1.2
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
Using
GSKit
FIPS
validated
toolkit.
Secure Plus UNIX Video Tutorials
You can view video tutorials about the installation, configuration, troubleshooting,
and other technical features of Sterling Connect:Direct Secure Plus for UNIX.
The Sterling Connect:Direct Secure Plus videos are useful for Sterling
Connect:Direct administrators. These tutorials provide a quicker way to access
information and remove the need to reference the Sterling Connect:Direct Secure
Plus documentation library.
Click the link below to access the Sterling Connect:Direct Secure Plus for UNIX
video channel to view tutorials about the following topics:
v Installation
v Configuration
v Troubleshooting
The Sterling Connect:Direct Secure Plus UNIX video channel can be found at this
link:Sterling Connect:Direct Secure Plus for UNIX Video Channel.
Protocol Support
Before you configure Sterling 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) and Secure Sockets
Layer Protocol (SSL)
The TLS and SSL protocols 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.
232 Sterling Connect:Direct for UNIX 4.2.0: Documentation
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.
NIST SP800-131a and Suite B support
Sterling 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:
v Enable TLS 1.2 and be prepared to disable protocols less than TLS 1.2
v Cryptographic keys adhere to a minimum key strength of 112 bits
v Digital signatures are a minimum of SHA-2
The following is included in Secure Plus for NIST SP800-131a and Suite B support:
v Support TLS 1.1 and 1.2 with SHA-2 cipher suites
v Support for SP800-131a transition and strict modes
v Support for NSA Suite B 128 and 192 bit cipher suites and modes
v Support for IBM CMS Keystore
v Support migrating existing Secure+ certificates to the IBM CMS Keystore
v 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
Sterling Connect:Direct Secure Plus Tools
Sterling Connect:Direct Secure Plus consists of five components:
v Sterling Connect:Direct Secure Plus Administration Tool (Secure+ Admin Tool)
v Parameters file (Secure+ parameters file)
v Access file (Secure+ access file)
v Strong Password Encryption Parameters file
v Sterling Connect:Direct Secure Plus Command Line Interface (Secure+ CLI).
The following sections describe these components and their function within
Sterling Connect:Direct Secure Plus.
Chapter 6. Introduction to Sterling Connect:Direct Secure Plus for UNIX 233
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 only 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 Sterling Connect:Direct Secure Plus parameters file (Secure+ parameters file)
contains information that determines the protocol and encryption method used
during encryption-enabled Sterling Connect:Direct Secure Plus operations. To
configure Sterling 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 Sterling 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 Sterling Connect:Direct node that you communicate with even if the remote
node does not use Sterling 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 Sterling Connect:Direct to interface
with Sterling External Authentication Server during SSL/TLS sessions. External
authentication is configured in this record and enabled/disabled in the local and
remote node records.
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 Sterling 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 Sterling 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 Sterling 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 Sterling 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
234 Sterling Connect:Direct for UNIX 4.2.0: Documentation
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 Sterling Connect:Direct passwords which
may be specified in a Sterling Connect:Direct Process by encrypting the Process
when it is submitted and stored in the Sterling 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.
Sterling Connect:Direct Command Line Interface
The Java-based Sterling Connect:Direct Secure Plus Command Line Interface
(Secure+ CLI) is provided to enable you to create customized scripts that automate
implementing Sterling 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 Sterling Connect:Direct environment for secure
operations, ensure that you complete the following tasks:
v Identifying Expert Security Administrator
v Assessing Security Requirements of Trading Partners
v Planning Your Implementation of Sterling Connect:Direct
v Completing the Worksheets
Identifying Expert Security Administrator
The instructions and information provided to assist you in implementing Sterling
Connect:Direct assume that you have an expert UNIX security administrator who
is familiar with your company's security environment. Identify who this individual
is within your company and work with this individual as you plan your Sterling
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 Sterling
Connect:Direct.
Planning Your Implementation of Sterling 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:
v Plan Your Implementation of the SSL or TLS Protocol
v Set Up for the TLS or SSL Protocol
Chapter 6. Introduction to Sterling Connect:Direct Secure Plus for UNIX 235
Completing the Worksheets
Before you begin
Before you configure Sterling Connect:Direct, complete the worksheets in
Configuration Worksheets. Use this information to configure the local and remote
nodes to use Sterling Connect:Direct.
Plan Your Implementation of the SSL or TLS Protocol
Before you configure Sterling 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 or
the Secured Sockets Layer (SSL) protocol.
Overview of the TLS Protocol and the SSL Protocol
The TLS and SSL protocols provide three levels of authentication:
v During the first level 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 key certificate file) and the PNODE authenticates it using one or
more trusted root certificates stored in a trusted root certificate file (the name
and location of which are specified in the remote node record for that specific
trading partner in the PNODE's Secure+ parameters file). 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 trusted
certificate file, or if the root certificate has expired, the PNODE terminates the
session. Sterling Connect:Direct writes entries to the statistics logs of both nodes,
and the session is aborted.
v The second level of authentication, called client authentication, is optional. If this
option is enabled in the SNODE's Sterling 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 trusted root certificate file. If this
authentication fails, the SNODE terminates the session and Sterling
Connect:Direct writes information about the failure to the statistics log of both
nodes.
To perform this level of authentication, the trading partner (SNODE) must have
a key certificate file available at its site and the Sterling Connect:Direct server
(PNODE) must have a trusted root file that validates the identity of either the
Certificate Authority (CA) who issued the key certificate or the entity that
created the certificate if it is self-signed.
v The third authentication level is also optional and consists of validating the
PNODE's certificate common name. When the security administrator enables
client authentication, they can also specify the common name (CN) contained in
the PNODE's ID certificate. During client authentication, the SNODE compares
the common name it has specified for the PNODE in its Sterling 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 Sterling Connect:Direct writes information about the
failure to the statistics logs of both nodes.
236 Sterling Connect:Direct for UNIX 4.2.0: Documentation
Benefits of TLS
Both the SSL protocol and the TLS protocol manage secure communication in a
similar way. However, TLS provides a more secure method for managing
authentication and exchanging messages, using the following features:
v While SSL provides keyed message authentication, TLS uses the more secure
Key-Hashing for Message Authentication Code (HMAC) to ensure that a record
cannot be altered during transmission over an open network such as the
Internet.
v TLS defines the Enhanced Pseudorandom Function (PRF), which uses two hash
algorithms to generate key data with the HMAC. Two algorithms increase
security by preventing the data from being changed if only one algorithm is
compromised. The data remains secure as long as the second algorithm is not
compromised.
v While SSL and TLS both provide a message to each node to authenticate that the
exchanged messages were not altered, TLS uses PRF and HMAC values in the
message to provide a more secure authentication method.
v To provide more consistency, the TLS protocol specifies the type of certificate
that must be exchanged between nodes.
v TLS provides more specific alerts about problems with a session and documents
when certain alerts are sent.
v If you are required to have a FIPS 140-2-validated solution, a FIPS-mode of
operation is available in Sterling Connect:Direct for the TLS protocol.
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 partners
Inefficient for large number of
trading partners
CA-signed
certificate
Eliminates having to send your
certificate to each trading partner
Trading partners must download
digital CA-signed certificate used
to verify the digital signature of
trading partner public keys.
No changes are required on the
trading partner's system if you
recreate the CA digitally-signed
certificate using the same CA
Must be purchased from
third-party vendor
Chapter 6. Introduction to Sterling Connect:Direct Secure Plus for UNIX 237
Terminology for SSL and TLS Certificates
The following defines the security terms associated with SSL and 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.
A certificate can also be self-signed and generated by any one of many
tools available, such as IBM Sterling Certificate Wizard or 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 SSL or 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
238 Sterling Connect:Direct for UNIX 4.2.0: Documentation
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 an SSL/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.
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 Sterling
Connect:Direct protocol handshake.
Set Up Sterling Connect:Direct Secure Plus
Before you can configure the node definitions that are necessary for using Sterling
Connect:Direct Secure Plus, you must complete the following tasks:
v Install Sterling Connect:Direct Secure Plus
v Starting the Secure+ Admin Tool
v Populating the Secure+ Parameters File
Chapter 6. Introduction to Sterling Connect:Direct Secure Plus for UNIX 239
Install Sterling Connect:Direct Secure Plus
You can install Sterling Connect:Direct Secure Plus using the Sterling
Connect:Direct installation script. For more information on installing Sterling
Connect:Direct Secure Plus, see the IBM Sterling Connect:Direct for UNIX Getting
Started Guide.
Note: After Sterling 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 Sterling Connect:Direct Secure Plus
administrator and Sterling Connect:Direct Server need full permission to the
Sterling Connect:Direct Secure Plus directory; no other users require access.
Starting the Secure+ Admin Tool
Before you begin
Use the Sterling Connect:Direct Secure Plus Administration Tool (Secure+ Admin
Tool) or the Sterling Connect:Direct Secure Plus Command Line Interface (Secure+
CLI) to set up and maintain a Sterling 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 Sterling 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
To access the Secure+ Admin Tool Help, from the Secure+ Admin Tool Help
menu, click the Help Topics option.
Navigate Help
When you open Help, the table of contents is displayed in the left pane, and the
active topic is displayed in the right panel. Click the icons in the following table to
navigate the Help.
Icon Name Description
Right Arrow Moves to the next Help topic.
Left Arrow Moves to the previous Help topic.
Index Displays a list of index entries; either type or scroll through the
list.
Search Searches for words or phrases contained in a Help topic.
240 Sterling Connect:Direct for UNIX 4.2.0: Documentation
Icon Name Description
Table of
Contents
Displays the table of contents.
v In the left frame of the Help window, click the topic, index entry, or phrase to
display the corresponding topic in the right frame.
v If + is displayed in front of a topic in the table of contents, click + to expand the
available topics.
v To close Help and return to Sterling Connect:Direct Secure Plus, click Close in
the top left corner of the Help window.
Populating the Secure+ Parameters File
To communicate with a trading partner using Sterling Connect:Direct Secure Plus,
you define a node record for that partner in both the Sterling Connect:Direct
network map and the Sterling Connect:Direct Secure Plus parameters file (Secure+
parameters file). To set up the Sterling 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 Sterling 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 Sterling Connect:Direct Secure Plus, you must configure
nodes for secure operations.
When you import the network map records into the Secure+ parameters file,
Sterling Connect:Direct Secure Plus parameters are disabled. To configure the
nodes for Sterling Connect:Direct Secure Plus, complete the following procedures:
v Import existing Certificates.
Chapter 6. Introduction to Sterling Connect:Direct Secure Plus for UNIX 241
v Configure or create a new CMS Key Store through the Key Management menu
on the Secure+ Admin Tool.
v Configure the Sterling 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.
v Disable remote nodes that do not use Sterling Connect:Direct Secure Plus
v 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
– To enable FIPS 140-2 mode
– To activate external authentication
v 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.
242 Sterling Connect:Direct for UNIX 4.2.0: Documentation
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:
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.
Chapter 6. Introduction to Sterling Connect:Direct Secure Plus for UNIX 243
Configuring the Sterling 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:
Field Name Field Definition Valid Values
Node Name Specifies the node record name. .Local
This is not an editable field.
Base Record Specifies the name of the base
record. If an alias record is
selected, the base record name is
displayed in this box.
Name of the local Sterling
Connect:Direct node.
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 Sterling 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 Sterling
Connect:Direct Secure Plus
parameters file, Sterling
Connect:Direct Secure Plus is
bypassed.
Enable SSL 3.0
Protocol
Enables SSL protocol to ensure that
data is securely transmitted.
The default value is Disable
Secure+.
Enable TLS 1.0
Protocol
Enables TLS protocol to ensure that
data is securely transmitted.
The default value is Disable
Secure+.
244 Sterling Connect:Direct for UNIX 4.2.0: Documentation
Field Name Field Definition Valid Values
Enable TLS 1.1
Protocol
Enables TLS protocol to ensure that
data is securely transmitted.
The default value is Disable
Secure+.
Enable TLS 1.2
Protocol
Enables TLS protocol to ensure that
data is securely transmitted.
The default value is Disable
Secure+.
Disable Disables the ability to override
values in the .Local node record
with values in the remote node
record.
The default value is Disable.
FIPS 140-2 Enables FIPS 140-2 security. The default value is Disable.
SP800-131A
Transition
Enables NIST SP800-131a security
in transition mode.
The default value is Disable.
SP800-131A Enables NIST SP800-131a security
mode.
The default value is Disable.
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
Statement Override
The default value is No.
Authentication
Timeout
Specifies maximum time, in
seconds, that the system waits to
receive the Sterling Connect:Direct
Secure Plus blocks exchanged
during the Sterling Connect:Direct
Secure Plus authentication process.
If you specify a value of 0, Sterling
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.
A numeric value equal to or
greater than 0, ranging from 0 to
3600.
The default is 120 seconds.
3. Click the TLS/SSL Options tab. The TLS/SSL 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:
v To enable external authentication on the remote node, click Yes in the Enable
External Authentication box.
Chapter 6. Introduction to Sterling Connect:Direct Secure Plus for UNIX 245
v To disable external authentication on the remote node, click No.
8. Type the Certificate Validation Definition character string defined in Sterling
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, Sterling 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 Sterling
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:
v Using a unique certificate file to authenticate a trading partner—During a TLS or
SSL 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.
v Using a self-signed certificate file to authenticate a trading partner—During a
TLS or SSL 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.
v Activating client authentication—Client authentication requires that the SNODE
validate the PNODE. If you want to enable client authentication, activate this
feature in the remote node record. If you want another layer of security, you can
activate the ability to validate the certificate common name.
v Identifying the cipher suite used by a trading partner—When configuring the
TLS or SSL 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:
246 Sterling Connect:Direct for UNIX 4.2.0: Documentation
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.
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:
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. If an alias record is
selected, the base record name is
displayed in this box.
Name of the local Sterling
Connect:Direct node.
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 Sterling 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 Sterling
Connect:Direct Secure Plus
parameters file, Sterling
Connect:Direct Secure Plus is
bypassed.
Enable SSL 3.0
Protocol
Enables SSL protocol to ensure that
data is securely transmitted.
The default value is Disable
Secure+.
Enable TLS 1.0
Protocol
Enables TLS protocol to ensure that
data is securely transmitted.
The default value is Disable
Secure+.
Enable TLS 1.1
Protocol
Enables TLS protocol to ensure that
data is securely transmitted.
The default value is Disable
Secure+.
Enable TLS 1.2
Protocol
Enables TLS protocol to ensure that
data is securely transmitted.
The default value is Disable
Secure+.
Disable Disables the ability to override
values in the .Remote node record
with values in the remote node
record.
The default value is Disable.
FIPS 140-2 Enables FIPS 140-2 security. The default value is Disable.
SP800-131A
Transition
Enables NIST SP800-131a security
in transition mode.
The default value is Disable.
SP800-131A Enables NIST SP800-131a security
mode.
The default value is Disable.
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
Statement Override
The default value is No.
Chapter 6. Introduction to Sterling Connect:Direct Secure Plus for UNIX 247
Field Name Field Definition Valid Values
Authentication
Timeout
Specifies maximum time, in
seconds, that the system waits to
receive the Sterling Connect:Direct
Secure Plus blocks exchanged
during the Sterling Connect:Direct
Secure Plus authentication process.
If you specify a value of 0, Sterling
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.
A numeric value equal to or
greater than 0, ranging from 0 to
3600.
The default is 120 seconds.
3. Click the TLS/SSL Options tab. The TLS/SSL 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:
v To enable external authentication on the remote node, click Yes in the Enable
External Authentication box.
v To disable external authentication on the remote node, click No.
8. Type the Certificate Validation Definition character string defined in Sterling
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.
248 Sterling Connect:Direct for UNIX 4.2.0: Documentation
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 Strong Password Encryption
This feature uses strong encryption to encrypt all Sterling Connect:Direct Process
data stored on disk in the Sterling 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 Sterling Connect:Direct Server must be restarted for the changes to Strong Password
Encryption to become effective.
4. Restart the Sterling 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 Sterling Connect:Direct Server must be restarted for the changes to Strong Password
Encryption to become effective.
4. Restart the Sterling 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:
Chapter 6. Introduction to Sterling Connect:Direct Secure Plus for UNIX 249
v You restore the .Password file from a backup—The .Password file is updated
each time the Sterling Connect:Direct server is started, so the backup will
probably not contain the current parameters.
v 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.
v 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:
Procedure
1. Stop the Sterling Connect:Direct server.
2. Delete the <cdinstall>/ndm/secure+/nodes/.Password file.
3. Start the Sterling Connect:Direct server.
4. Manually delete all Processes in the TCQ. Refer to the IBM Sterling
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.
Automate Setup with the Secure+ CLI
The Java-based Sterling Connect:Direct Command Line Interface (Secure+ CLI) and
sample script enable you to create customized script that automate creating an
initial installation of Sterling Connect:Direct, populating the Secure+ parameters
file, and managing node records. You can then distribute these scripts throughout
your enterprise to implement the Sterling Connect:Direct application. Before you
create the scripts for distribution, consider creating an installation of Sterling
Connect:Direct Secure Plus using the Secure+ Admin Tool and testing it to verify
the results.
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
250 Sterling Connect:Direct for UNIX 4.2.0: Documentation
Parameter Definition Values
-lo Switch to enable the display of output and error messages to
the terminal.
y | n
-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 than the specified number.
If you do not include this parameter, Secure+ CLI continues
to run even after an error has occurred.
0 | 4 | 8 | 16
-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=
enddelim=
Defines beginning and ending
character to use to enclose keywords
that use blanks and other special
characters.
Any character
The default value is “ (double
quotes).
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 Sterling 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
Chapter 6. Introduction to Sterling Connect:Direct Secure Plus for UNIX 251
An example of configuring Sterling Connect:Direct to use the SSL or TLS
protocol with the Secure+ CLI. The example demonstrates the
configuration of Sterling 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+
parameters file.
Must be initialized
before you can
define nodes.
localnode=Name of the local
node where the Secure+
parameters file will be created.
local node name
path=Location where the Secure+
parameters file will be created.
directory location
For example,
d_dir/ndm/secure+/
node
passphrase=Arbitrary set of
characters that encrypts the
Secure+ parameters file.
a string at least 32
characters long
Open
Parmfile
Opens a Secure+
parameters file so
that you can
configure it.
path=Location where the Secure+
parameters file will be created.
directory location
For example,
d_dir/ndm/secure+/
node
Close
Parmfile
Closes the Secure+
parameters file.
After this
command is
issued, no more
updates can be
performed on the
Secure+
parameters file.
None None
Refresh
Parmfile
Refreshes the
Secure+
parameters file.
This will close the
current parameters
file and reopen it,
bringing in any
changes since last
opened.
None None
Validate
Parmfile
Validates the
Secure+
parameters file and
ensures that it is a
valid file.
None None
Rekey
Parmfile
Recreates the
Secure+
parameters file if it
becomes corrupted.
passphrase=Arbitrary set of
characters that encrypts the
Secure+ parameters file.
passphrase, up to 32
characters long
252 Sterling Connect:Direct for UNIX 4.2.0: Documentation
Command Description Parameter Values
Sync
Netmap
Imports remote
node records
defined in the
Sterling
Connect:Direct
network map.
path=Location and name of the
network map file.
location of network
map file
name=Name of the node in the
network map. Use wildcard
characters to resync more than
one node at a time.
node name or
wildcard
Wildcard values are:
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 Secure+ parameters file was
last updated.
None
display all Displays all nodes in the Secure+
parameters file.
None
display localnode Displays the values defined in the
.Local node record.
None
display remotenode Displays the values defined in
remote node records.
node name or wildcard
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 the
.Client node record.
None
display seaserver Displays the values defined in the
.SEAServer record.
None
Chapter 6. Introduction to Sterling Connect:Direct Secure Plus for UNIX 253
Command Description Parameter
display protocols Displays supported security
protocols which should be defined
in a comma separated list . These
protocols are:
SSL,TLS,TLS1.1,TLS1.2
None
display securitymodes Displays supported security
modes for additional security.
These modes are: FIPS140-2 |
SP800-131A_TRANSITION |
SP800-131A_STRICT |
SUITE_B-128 | SUITE_B-192
None
display ciphersuites Displays all supported Cipher
Suites for Secure+ which can be
defined either as a single cipher
suite or in a comma separated list.
None
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
Key Store file.
File=While a default
keystore file is created at
installation and can be
used, you may need to
create a new CMS
KeyStore File.
<path to CMS KeyStore file (*.kdb)>
Default path is in:
d_dir/ndm/secure+/certificates/
cdkeystore.kdb
Passphrase=The
password for the new
KeyStore file.
A string with a minimum of three
characters and a maximum of eighty
characters.
*This password must be retained; it will
be required to administer the Secure+
KeyStore.
PopulateRoots=Populate
with standard certificate
authorities. This will
import all standard
public CA Root
certificates into the new
KeyStore file.
y | n
update keystore Updates the CMS
KeyStore
File=Path to existing
CMS KeyStore and
filename.
<path to CMS KeyStore file (*.kdb)>
Default path is in:
d_dir/ndm/secure+/certificates/
cdkeystore.kdb
Passphrase=The
password for the
KeyStore file.
The retained password which was given
at the creation of the keystore.
254 Sterling Connect:Direct for UNIX 4.2.0: Documentation
Command Description Parameter Values
import keycert Imports existing
keycerts into the
keystore file.
File=Existing key
certificate file.
*This file contains the
private key*
Full path and filename to key certificate
file to be imported.
Passphrase=Password of
key certificate file to be
imported.
Pre-defined password of key certificate
file.
Label=(optional) Name
of imported key
certificate file.
A string of characters which can be an
alias name but if it is not defined, the
Common Name of the certificate will be
the label used.
SyncNodes=Update
node/certificate
references
y | n
ImportMode=Type of
import to be used.
Add | Replace | AddOrReplace
import trustedcert Imports public
certificate files from
trading partners.
File=Trusted public file
from trading partner.
Full path and filename to trusted
certificate file to be imported.
ImportMode=Type of
import to be used.
Add | Replace | AddOrReplace
delete keystoreentry Deletes certificates
from CMS keystore.
File=Can be either key
certificate file or trusted
public trading partner
file.
Full path and filename to certificate file.
Label=Specified label of
imported certificate file.
Label which was defined at time of
import of the certificate file.
DeleteChain=Defines
whether to delete the
entire chain, if it exists.
y | n
SyncNodes=Reset
node/certificate
references
y | n
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 of Protocols to use in
the .Local node record.
Disable | SSL,TLS,TLS1.1,TLS 1.2
(See Display Protocols)
SecurityMode Disable | FIPS140-2 |
SP800-131A_TRANSITION |
SP800-131A_STRICT |
SUITE_B-128 | SUITE_B-192
(See Display SecurityModes)
Chapter 6. Introduction to Sterling Connect:Direct Secure Plus for UNIX 255
Command Parameter Values
override=Identifies if values in the
remote node can override values
defined in the .Local node record.
y | n
AuthTimeout=Specifies the maximum
time, in seconds, that the system
waits to receive the Sterling
Connect:Direct control blocks
exchanged during the Sterling
Connect:Direct authentication
process.
0–3600
The default is 120 seconds.
KeyCertLabel=Identifies the label of
the key certificate.
keycert label | null
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 Only Control Block
Information; data is sent
unencrypted. Default is Yes - data
and control block information are
encrypted.
y | n
ClientAuth = Enables client
authentication in a .Client node
record.
y | n
CipherSuites= Specifies the cipher
suites enabled.
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
Sterling Connect:Direct for UNIX
Release Notes.
comma delimited list of cipher
suites | all | null
all—Enables all ciphers.
null—Clears any existing values
from the node definition.
SeaEnable=Enables certificate
validation by Sterling External
Authentication Server
y | n
SeaCertValDef=Character string
defined in Sterling External
Authentication Server (SEAS).
character string | null
null—Clears any existing values
from 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:
256 Sterling Connect:Direct for UNIX 4.2.0: Documentation
Command Parameter Values
create remotenode model=Name of an existing node to use as
a model to copy from.
name of a valid remote node
Name=Identifies name of the remote node
record.
name
protocol=Specifies a comma delimited list
of Protocols to use in the remote node
record.
Disable | SSL,TLS,TLS1.1,TLS 1.2
|DefaultToLN
(See Display Protocols)
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
statement can override values defined in
the remote node record.
y | n | DefaultToLN
AuthTimeout=Specifies the maximum time,
in seconds, that the system waits to receive
the Sterling Connect:Direct control blocks
exchanged during the Sterling
Connect:Direct authentication process.
0–3600
The default is 120 seconds.
KeyCertLabel=Identifies the label of the
key certificate.
keycert label | null
EncryptData=If no is specified, Encrypt
Only Control Block Information; data is
sent unencrypted. Default is Yes - data and
control block information are encrypted.
y | n | DefaulttoLN
ClientAuth = Enables client authentication
with a remote trading partner.
y | n | DefaultToLN
CertCommonName=The certificate
common name defined in the certificate.
name | null
null—Clears any existing values from the
node definition.
CipherSuites= Specifies the cipher suites
enabled.
comma delimited list of cipher suites | All
| null
SeaCertValDef=Character string defined in
Sterling External Authentication Server
(SEAS).
character string | null
null—Clears any existing values from the
node definition.
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:
Chapter 6. Introduction to Sterling Connect:Direct Secure Plus for UNIX 257
Command Parameter Values
update remotenode Name=Specifies name for the remote node
record.
remote node name | wildcard
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 of
Protocols to use in the remote node record.
Disable | SSL,TLS,TLS1.1,TLS 1.2 |
DefaultToLN
(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
statement can override values defined in the
remote node record.
y | n | DefaultToLN
AuthTimeout=Specifies the maximum time,
in seconds, that the system waits to receive
the Sterling Connect:Direct control blocks
exchanged during the Sterling
Connect:Direct authentication process.
0–3600
The default is 120 seconds.
KeyCertLabel=Identifies the label of the key
certificate.
keycert label | null
EncryptData=If no is specified, Encrypt
Only Control Block Information; data is sent
unencrypted. Default is Yes - data and
control block information are encrypted.
y | n | DefaulttoLN
ClientAuth = Enables client authentication
with a remote trading partner.
y | n | DefaultToLN
CertCommonName=The certificate common
name defined in the certificate.
name | null
null—Clears any existing values from the
node definition.
CipherSuites= Specifies the cipher suites
enabled.
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 Sterling
Connect:Direct for UNIX Release Notes.
comma delimited list of cipher suites | All
| null
SeaEnable=Enables certificate validation by
Sterling External Authentication Server.
y | n | DefaultToLN
DefaultToLN—Defaults to the setting
specified in the .Local node record
SeaCertValDef=Character string defined in
Sterling External Authentication Server
(SEAS).
character string | null
null—Clears any existing values from the
node definition.
258 Sterling Connect:Direct for UNIX 4.2.0: Documentation
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 record to display
information about.
node name | wildcard value
To display information about more than
one 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:
Command Parameter Value
create alias name=The alias name to be
used.
An alias name for an existing node
name record.
basename=The name of the
existing node record.
The existing node name
Delete a Remote Node Record
The delete remotenode command deletes one or more remote node records. The
command has the following parameter:
Chapter 6. Introduction to Sterling Connect:Direct Secure Plus for UNIX 259
Command Parameter Values
delete
remotenode
name=Name of the remote node
record to display information
about.
Use wildcard characters to
delete a group of remote node
records.
remote node name | wildcard value
To display information about more
than one 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.*.
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 Protocols to use in the .Client
record
Disable | SSL,TLS,TLS1.1,TLS 1.2
| DefaultToLN
(See Display Protocols)
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 a Connect:Direct client and the
Connect:Direct server
y | n | DefaultToLN
AuthTimeout=Specifies the maximum
time, in seconds, that the system waits to
receive the Sterling Connect:Direct
control blocks exchanged during the
Sterling Connect:Direct authentication
process.
0–3600
The default is 120 seconds.
KeyCertLabel=Identifies the label of the
key certificate
keycert label | null
EncryptData=If no is specified, Encrypt
Only Control Block Information; data is
sent unencrypted. Default is Yes - data
and control block information are
encrypted.
y | n | DefaulttoLN
CipherSuites= Specifies the cipher suites
enabled.
comma delimited list of cipher
suites | All | null
260 Sterling Connect:Direct for UNIX 4.2.0: Documentation
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 of Protocols to use in
the .SEAServer record.
Disable | SSL,TLS,TLS1.1,TLS 1.2
| DefaultToLN
(See Display Protocols)
SeaHost=External authentication
host name defined in SEAS.
host name | null
null—Clears any existing values
from the node definition
AuthTimeout=Specifies the
maximum time, in seconds, that the
system waits to receive the Sterling
Connect:Direct control blocks
exchanged during the Sterling
Connect:Direct authentication
process.
0–3600
The default is 120 seconds.
SeaPort=External authentication
server port number (listening)
defined in SEAS.
port number | 61366
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 Sterling 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 Sterling Connect:Direct Server must be restarted for the changes to Strong
Password Encryption to become effective.
Chapter 6. Introduction to Sterling Connect:Direct Secure Plus for UNIX 261
Display the .Password File
The Display Password command displays the Strong Password Encryption setting
and .Password history.
Displaying the Sterling Connect:Direct Node Information
After you set up node records in Sterling 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 Sterling 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
Sterling
Connect:Direct
Secure Plus
Displays the status of Sterling Connect:Direct. N | TLS | SSL | *
N—Disabled
TLS—TLS protocol
SSL—SSL protocol
*—Default to local node
Override Displays the status of override. Enable override
in the local node to allow remote node records
to override the settings in the local node record.
Y | N | *
Y—Enabled
N—Disabled
*—Default to local node
CipherSuites Displays the TLS or SSL cipher suites that are
enabled for the node record.
Varies, based on the
cipher suites enabled.
ClientAuth Displays the status of client authentication. If the
TLS or SSL protocol is used, enabling client
authentication means the SNODE verifies the
identity of the PNODE.
Y | N | *
Y—enabled
N—Disabled
*—Default to local node
LimExpr Identifies if the Limited Export version is being
used by a remote node.
Y | N | *
Y—Enabled
N—Disabled
*—Default to local node
262 Sterling Connect:Direct for UNIX 4.2.0: Documentation
Field Name Field Definition Values
AutoUpdate Indicates if the option to automatically update
key values during communication is enabled.
Y | N | *
Y—enabled
N—disable
*—default to local node
Base Record Displays the name of the base record for the
alias records.
There are no parameter
values.
Viewing Node Record Change History
Perform the following steps to view the history of changes to a Sterling
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 Sterling Connect:Direct Secure Plus Configuration
After using Sterling Connect:Direct Secure Plus, it may be necessary to modify a
configuration. This section provides the following procedures for modifying
Sterling Connect:Direct Secure Plus information:
v Disabling Sterling Connect:Direct Secure Plus
v Deleting a Sterling Connect:Direct Secure Plus remote node record
v Resecuring the Secure+ parameters file and Secure+ access file
v Changing the cipher suites
Chapter 6. Introduction to Sterling Connect:Direct Secure Plus for UNIX 263
Disabling Sterling 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 Sterling Connect:Direct Secure Plus:
Procedure
1. Do one of the following:
v To disable all nodes in a configuration, open the local node record.
v 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 Sterling Connect:Direct operations with Sterling
Connect:Direct disabled, both trading partners must disable Sterling
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 Sterling 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:
v To delete selected node records, highlight the remote nodes to delete and
click Delete Selection.
v 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 Sterling
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 Sterling 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.
Sterling 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 Sterling Connect:Direct Secure
Plus decrypts and re-encrypts the Secure+ parameters file and Secure+ access
file.
264 Sterling Connect:Direct for UNIX 4.2.0: Documentation
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.
Sterling Connect:Direct Secure Plus Statistics Record Information
Sterling Connect:Direct logs statistics for Sterling Connect:Direct Process activity.
Sterling Connect:Direct statistics include Sterling Connect:Direct Secure Plus
information for a Process.
Fields are included in Sterling Connect:Direct Process statistics records to provide
Sterling Connect:Direct Secure Plus information about the Process. Sterling
Connect:Direct Secure Plus information is included in the Process statistics
information only when you attach to a Sterling Connect:Direct Secure Plus server.
For information on viewing statistics, refer to the IBM Sterling Connect:Direct
Browser User Interface User Guide. When you use the select statistics function to
view information about a Sterling Connect:Direct Process, statistics information
about a particular Process is displayed. If Sterling Connect:Direct Secure Plus is
enabled, Sterling Connect:Direct Secure Plus fields are also displayed.
The Sterling Connect:Direct Secure Plus fields and values available using the select
statistics function are shown in the following table:
Field Name Field Description Values
Sterling Connect:Direct
Secure Plus Enabled
Specifies whether Sterling
Connect:Direct Secure Plus is enabled.
Y | N
Sterling Connect:Direct
Secure Plus Protocol
Specifies which protocol is enabled. SSL 3.0 | TLS 1.0
Cipher Suite Displays the cipher suite used during
a session.
cipher suite name
For example:
SSL_RSA_EXPORT_WITH_RC4_40_MD5
PNode Cipher List Specifies the encryption algorithms
available for the PNODE during the
session.
IDEACBC128 | TDESCBC112 | DESCBC56
PNode Cipher Specifies the preferred data encryption
as specified in the Secure+ parameters
file of the PNODE.
Y | N | algorithm name
SNode Cipher List Specifies the encryption algorithms
available for the SNODE during the
session as specified in the Secure+
parameters file of the SNODE.
IDEACBC128 | TDESCBC112 | DESCBC56
SNode Cipher Specifies the preferred data encryption
algorithm as defined in the Secure+
parameters file of the SNODE.
Y | N | algorithm name
Control Block Cipher Specifies the algorithm used for
encrypting control blocks. This value
is determined during authentication
when the PNODE and SNODE are
merged.
IDEACBC128 | TDESCBC112 | DESCBC56
Copy Data Cipher Specifies the encryption method used
for encrypting data. The value is
determined after the values in the
SNODE and the PNODE are merged.
IDEACBC128 | TDESCBC112 | DESCBC56
Chapter 6. Introduction to Sterling Connect:Direct Secure Plus for UNIX 265
Field Name Field Description Values
PNODE Signature Enabled Indicates whether digital signatures
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.
Y | N
SNODE Signature Enabled Indicates whether digital signatures
are enabled for the SNODE. This value
is obtained from the Secure+
parameters file settings.
Y | N
Signature Enabled Identifies the digital signature value
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).
Y | N
Current Signature Verified Indicates whether the current digital
signature was verified.
Y | N
Previous Signature Verified Indicates whether the previous digital
signature was verified.
Y | N
Sterling Connect:Direct CLI Select Statistics Detail
When you use the Sterling Connect:Direct CLI select statistics function to view the
information about a Sterling Connect:Direct Process, you see statistics information
about a particular Process. Sterling Connect:Direct Secure Plus fields are shown in
bold in the following samples. The Sterling Connect:Direct field names,
descriptions, and valid values are shown in Sterling Connect:Direct Secure Plus
Statistics Record Information. For more information on Sterling Connect:Direct
certificate auditing, see Secure+ Parameters File Auditing.
Session Start (SSTR) Record
The following sample Session Start Record (SSTR) displays the output of an SSL
session:
266 Sterling Connect:Direct for UNIX 4.2.0: Documentation
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
---------------------------------------------------------------------
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
---------------------------------------------------------------------
Secure+ Parameters File Auditing
Sterling Connect:Direct provides auditing of Secure+ parameters files and
certificates for archival purposes.
The Sterling Connect:Direct Secure Plus Administration Tool (Secure+ Admin Tool)
and the Sterling Connect:Direct Secure Plus Command Line Interface (Secure+ CLI)
Chapter 6. Introduction to Sterling Connect:Direct Secure Plus for UNIX 267
log changes made to the Sterling Connect:Direct Secure Plus parameters file
(Secure+ parameters file). The following events are logged:
v Application Startup
v Init Parmfile
v Open Parmfile
v Sync Netmap
v Rekey Parmfile
v Create Node
v Update Node
v Delete Node
The Secure+ parameters file logging feature has the following operational
characteristics:
v The logging feature is always enabled and cannot be disabled.
v If errors occur when the log is being updated, the application terminates.
v Each log entry contains a timestamp, user ID, and a description of the
action/event.
v When an existing node is updated, any changed fields are reported.
v When a node is created or deleted, the values of all non-empty fields are
reported.
v Any commands that modify a node are logged.
Note: The certificates used by Sterling 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. Sterling 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 Sterling
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
268 Sterling Connect:Direct for UNIX 4.2.0: Documentation
Field Name Description
BaseRecord Name of the base record
Type Record type of local, remote, or alias
Protocol Enables Sterling 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
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.
Sterling Connect:Direct Secure Plus Certificate Auditing
In an SSL/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
an SSL/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 6. Introduction to Sterling Connect:Direct Secure Plus for UNIX 269
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)
Sterling 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 Sterling 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|'
270 Sterling Connect:Direct for UNIX 4.2.0: 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
Sterling Connect:Direct error function is not used. After the error occurs, the
session continues.
Sterling Connect:Direct Secure Plus Troubleshooting
Use the following table to help troubleshoot problems with Sterling Connect:Direct
Secure Plus:
Problem Possible Cause Solution
Sterling Connect:Direct
Secure Plus features are
enabled in the Secure+
parameters file, but the
statistics record indicates
that these functions are
disabled.
The Sterling Connect:Direct
network maps do not
contain entries for the
PNODE and SNODE.
Verify that the network map
entries for both the PNODE and
the SNODE exist.
Running a Process with a
remote node fails with an
authentication error.
Unique public/private key
pairs are generated for the
remote node record and the
.Local node record is set to
Enable Override=N.
Change the .Local node record to
Enable Override=Y.
The ENCRYPT.DATA
parameter, specified from
the COPY statement
causes the copy step to
fail with error message
CSPA080E.
The algorithm name used
in the COPY statement is
not in the supported
algorithm list for both
nodes.
Verify that the algorithm name in
the COPY statement is in the
supported algorithm list for both
nodes.
Sterling Connect:Direct
Secure Plus is installed,
but error message
CSPA001E occurs on
transfers not using
Sterling Connect:Direct
Secure Plus.
Remote node records do
not exist.
v A remote node record must
exist for every node in the
netmap. Use the Sync with
Netmap feature to create any
missing nodes.
v Disable Sterling Connect:Direct
Secure Plus by clicking Disable
Secure+ in the .Local node
record.
Signature verification fails
with error message
CSPA002E.
Configuration settings
missing or incorrect.
v If this is a non-Secure node,
make sure the remote node
record has Disable Sterling
Connect:Direct Secure Plus
selected.
v Check the Sterling
Connect:Direct Secure Plus
settings for the node.
Chapter 6. Introduction to Sterling Connect:Direct Secure Plus for UNIX 271
Problem Possible Cause Solution
Signature verification fails
with error message
CSPA003E, CSPA004E, or
CSPA005E.
v Configuration settings
missing or incorrect.
v A security attack in
progress.
v Execute standard operating
procedure for investigating
security violation.
Signature verification fails
with error message
CSPA007E.
Expired Signature Previous
Key Pair. Date exceeded or
keys have been changed.
If Auto Update is disabled, check
the expiration date for the
signature key 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
remote node fails with an
authentication error,
CSPA008E.
Authentication Previous
Key Pair Expiration Date
exceeded or keys have been
changed.
If Auto Update is disabled, check
the authentication previous key
pair expiration date for both
nodes. Check 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
with the error, CSPA010E.
v The time allowed for
strong authentication
expired.
v A security attack in
progress.
v Increase the timeout value.
v Execute standard operating
procedure for investigating
security violation.
Sterling Connect:Direct
Secure Plus session fails
with the error, CSPA011E.
An illegal attempt to
override Sterling
Connect:Direct Secure Plus
parameters.
v Turn on Enable Override in the
remote node record to allow the
COPY statement to override the
node settings.
v Check the COPY statement and
remove the override statements.
Sterling Connect:Direct
Secure Plus session fails
with the error, CSPA014E.
Sterling Connect:Direct
Secure Plus cannot read the
remote node definition.
Check the remote node definition
settings.
Sterling Connect:Direct
Secure Plus session fails
with the error, CSPA016E.
Sterling Connect:Direct
Secure Plus is not enabled
in the local node definition.
Make sure Sterling Connect:Direct
Secure Plus is enabled for the
local node.
Sterling Connect:Direct
Secure Plus session fails
with the error, CSPA019E.
Error generating digital
signature.
v Resubmit the Process.
v Call IBM Customer Support.
Sterling Connect:Direct
Secure Plus session fails
with the error, CSPA077E.
The COPY statement
requested Sterling
Connect:Direct Secure Plus
parameters but Sterling
Connect:Direct Secure Plus
is not configured.
Remove the SECURE= parameter
from the COPY statement.
Sterling Connect:Direct
Secure Plus session fails
with the error, CSPA079E.
Invalid encryption
algorithm identified in
COPY statement.
Change the ENC.DATA parameter
and specify one of the following
values: Y, N, IDEACBC128,
TDESCBC112, or DESCBC56 and
resubmit the Process.
272 Sterling Connect:Direct for UNIX 4.2.0: Documentation
Problem Possible Cause Solution
Sterling Connect:Direct
Secure Plus session fails
with the error, CSPA080E.
No common algorithms are
available for both nodes.
Verify the algorithm list for both
nodes contains at least one
common algorithm name.
Sterling Connect:Direct
Secure Plus session fails
with the error, CSPA091E.
Session attempted but
remote node is not
configured.
Make sure both nodes are
defined.
Sterling Connect:Direct
Secure Plus session fails
with the error, CSPA200E.
Both nodes are not
configured for the same
protocol.
Check the protocol setting at both
sites and verify that the same
protocol is configured at each site.
Sterling Connect:Direct
Secure Plus session fails
with the error, CSPA202E.
SSL or TLS protocol
handshake failed.
Edit the cipher suite list and add
a cipher suite used by the trading
partner.
Sterling Connect:Direct
Secure Plus session fails
with the error, CSPA203E
or CSPA204E.
The SSL or TLS protocol
could not validate the
server's certificate.
Make sure the certificate
information is typed into the node
record.
Sterling Connect:Direct
Secure Plus session fails
with the error, CSPA205E.
A trading partner is not
using TCP/IP for
communication.
Make sure that both ends of the
communication use TCP/IP.
Sterling Connect:Direct
Secure Plus session fails
with the error, CSPA206E.
The SSL or TLS protocol
could not validate the
server's certificate.
Make sure the certificate
information is entered into the
node record.
Sterling Connect:Direct
Secure Plus session fails
with the error, CSPA208E.
The common name in the
certificate received does not
match the Sterling
Connect:Direct Secure Plus
configuration.
Make sure the certificate common
name is spelled correctly and uses
the same case as that in the
certificate.
Sterling Connect:Direct
Secure Plus session fails
with the error, CSPA209E.
The certificate has expired
or is invalid.
Obtain a new certificate and
reconfigure the node record.
Sterling Connect:Direct
Secure Plus session fails
with the error, CSPA210E.
The COPY statement
attempts to override
settings in the SSL or TLS
protocol.
v The system continues to
operate.
v If desired, change the Process
statement and remove the
COPY override options.
Sterling Connect:Direct
Secure Plus session fails
with the error, CSPA211E.
The remote trading partner
failed to send a certificate.
Notify the trading partner that a
certificate is required.
Sterling Connect:Direct
Secure Plus session fails
with the error, CSPA280E.
The trusted root certificate
could not be loaded.
Check the local node
configuration and make sure the
location of the trusted root
certificate is correctly identified.
Sterling Connect:Direct
Secure Plus session fails
with the error, CSPA281E.
The trusted root certificate
is empty.
Check the local node
configuration and make sure the
location of the trusted root
certificate is correctly identified.
Sterling Connect:Direct
Secure Plus session fails
with the error, CSPA282E.
The user certificate file
cannot be loaded.
Check the local node
configuration and make sure the
location of the user certificate file
is correctly identified.
Chapter 6. Introduction to Sterling Connect:Direct Secure Plus for UNIX 273
Problem Possible Cause Solution
Sterling Connect:Direct
Secure Plus session fails
with the error, CSPA303E.
The Secure+ parameters
files have not been
initialized.
Run the Secure+ Admin Tool to
initialize the Secure+ parameters
files.
Sterling Connect:Direct
Secure Plus session fails
with the error, CSPA309E.
The SSL library failed
during the handshake.
Examine all related errors to
determine the cause of the failure.
Sterling Connect:Direct
Secure Plus session fails
with the error, CSPA311E.
Certificate validation failed. Verify that the root certificate is
properly configured. An alternate
certificate may be required.
Configuration Worksheets
Use the worksheets in this topic to record the configuration information for
Sterling Connect:Direct Secure Plus.
v The Local Node Security Feature Definition Worksheet is a record of the security
functions defined for the local Sterling Connect:Direct node.
v 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 Sterling
Connect:Direct Secure Plus operations.
Local Node Security Feature Definition Worksheet
Record the security feature definition for the Sterling 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 Sterling Connect:Direct parameters file that
you are configuring for Sterling Connect:Direct operations. Record the security feature definitions for a remote
node record on this worksheet.
Remote Node Name: _____________________________
Security Options
274 Sterling Connect:Direct for UNIX 4.2.0: Documentation
Protocol defined in the .Local node record: TLS or SSL _______
Is the remote node using the protocol defined in the .Local
node record?
Yes _______ No _______
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, Sterling 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 SSL and TLS security protocols 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.
Sterling Connect:Direct Secure Plus uses two certificate files to initiate TLS or SSL
sessions: 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 Sterling 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 Sterling
Connect:Direct Secure Plus\certificates directory when you install Sterling
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 more sophisticated configurations, you may associate individual
trusted root files with one or more node records.
Chapter 6. Introduction to Sterling Connect:Direct Secure Plus for UNIX 275
When you use a certificate signing request (CSR) tool, such as the Sterling
Certificate Wizard, you do not need to change the contents of the key certificate
file. This is created for you by the Sterling Certificate Wizard.
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:
v 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.
v 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
Sterling 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 Sterling
Connect:Direct Secure Plus and is stored in the Secure+ parameters file. Additional
encryption is used to prevent the passphrase from being discovered.
276 Sterling Connect:Direct for UNIX 4.2.0: 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.
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-----
Chapter 6. Introduction to Sterling Connect:Direct Secure Plus for UNIX 277
Model Automation Scripts
The following scripts are provided as models for creating custom scripts to define
your Sterling 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 Sterling Connect:Direct Secure Plus to Use the SSL
or TLS Protocol
The spcust_sample1 script demonstrates using the Secure+ CLI to configure
Sterling Connect:Direct Secure Plus to use the SSL or 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.
# 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
;
278 Sterling Connect:Direct for UNIX 4.2.0: Documentation
;
; -- 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
;
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"
Chapter 6. Introduction to Sterling Connect:Direct Secure Plus for UNIX 279
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.
280 Sterling Connect:Direct for UNIX 4.2.0: Documentation
Chapter 7. 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 Sterling Connect:Direct under the
control of SMF.
Place Sterling Connect:Direct under Solaris Service Management
Facility Control
This procedure uses the following sample names and files to describe how to
putSterling 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 Sterling 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 Sterling Connect:Direct using the Command Line Interface (CLI). For
information, refer to IBM Sterling 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, 2016 281
#!/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 Sterling Commerce 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
282 Sterling Connect:Direct for UNIX 4.2.0: 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
Chapter 7. About SMF 283
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.
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 Sterling Connect:Direct service by typing the following
command:./connect-direct start
c. Verify that the Sterling Connect:Direct service is running.
d. As root, stop the Sterling Connect:Direct service by typing the following
command:./connect-direct stop
e. Verify that the Sterling Connect:Direct service stopped.
6. As root, copy the SMF Service Manifest in the following sample to
/var/svc/manifest/application/connect-direct.xml.
284 Sterling Connect:Direct for UNIX 4.2.0: 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 7. About SMF 285
<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=’sterlingcommerce.com’
uri=’http://www.sterlingcommerce.com/
customer/tech_support.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 Sterling Connect:Direct FTP+ service stopped.
Controlling Sterling Connect:Direct Using the SMF Script
To place the Sterling 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 Sterling Connect:Direct service under SMF control by typing
the following command:
svcadm enable connect-direct
Verify the Sterling Connect:Direct service is running.
3. To verify Sterling Connect:Direct restarts under the control of SMF, type the
following command:
svcs -p connect-direct
Observe the Process number in use.
286 Sterling Connect:Direct for UNIX 4.2.0: Documentation
4. Stop the Sterling Connect:Direct service by using the Command Line Interface
(CLI) method. For additional information, refer to Sterling Connect:Direct
User's Guide.
Sterling Connect:Direct stops, and immediately restarts under SMF control.
5. To confirm Sterling Connect:Direct is under the control of SMF, type the
following command:
svcs -p connect-direct
The system generates a Process number different from that observed in step 3.
Implementing Solaris Role-Based Access Control with SMF for Sterling
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 Sterling Connect:Direct.
To authorize additional specific user IDs to stop and start Sterling 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:
v svcadm enable connect-direct
Chapter 7. About SMF 287
v svcadm disable connect-direct
v svcadm refresh connect-direct
Starting and Stopping Sterling Connect:Direct under SMF Control
After the Sterling 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
Sterling 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 Sterling Connect:Direct at a later time, use
the full FMRI name to avoid ambiguity. The example commands assume that only
one FMRI exists for Sterling Connect:Direct on this system, so the shortcut name is
used.
Note: The stop commands issued from the Sterling Connect:Direct CLI stop the
Sterling 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 Sterling Connect:Direct
users of the following SMF control commands: Starting the Sterling Connect:Direct
Service, and Stopping the Sterling Connect:Direct Service.
Starting the Sterling 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 Sterling 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 Sterling Connect:Direct using
the same method used before Sterling 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
Sterling Connect:Direct into a maintenance state. Correct the affected script or
FMRI file.
288 Sterling Connect:Direct for UNIX 4.2.0: Documentation
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 Sterling Connect:Direct from SMF Control
To remove Sterling Connect:Direct from SMF control, stop Sterling 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:
v /var/svc/manifest/network/connect-direct.xml
v /lib/svc/method/connect-direct
For additional information, see Managing Services in the Solaris System
Administration Guide:Basic Administration.
Chapter 7. About SMF 289
290 Sterling Connect:Direct for UNIX 4.2.0: 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
© Copyright IBM Corp. 1993, 2016 291
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
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
292 Sterling Connect:Direct for UNIX 4.2.0: Documentation
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.
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.
Notices 293
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
®
, Sterling Commerce
™
,
Sterling Information Broker
®
, and Sterling Integrator
®
are trademarks or registered
trademarks of Sterling Commerce
®
, 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, INCLUDING
BUT NOT LIMITED TO IMPLIED WARRANTIES OF MERCHANTABILITY,
NON-INFRINGEMENT, AND FITNESS FOR A PARTICULAR PURPOSE.
294 Sterling Connect:Direct for UNIX 4.2.0: Documentation
Notices 295
IBM®
Product Number: 5655-X01
Printed in USA
