IBM Remote API Client for Linux on System z v6.3.0.2 (s390, s390x) INSTALLATION AND RELEASE NOTES 5724-I33, 5724-I34, 5765-E51 * © Copyright International Business Machines Corp. 2003, 2006 * All Rights Reserved * Licensed Material - Property of IBM * * US Government Users Restricted Rights - Use, duplication or * disclosure restricted by GSA ADP Schedule Contract with IBM Corp. Table of Contents ----------------- 1. About this release 1.1 New in this release 1.2 Product fix history 1.3 Product compatibility 2. Installation information 2.1 Hardware requirements 2.2 Software requirements 2.2.1 Linux operating system version 2.2.2 Java 2.2.3 HTTPS 2.3 Installation process 3. Uninstallation information 4. Known limitations and problems 5. Documentation updates 6. Notices and trademarks 1. About this release --------------------- IBM Remote API Client for Linux on System z provides a remote SNA API for 31-bit and 64-bit Linux for System z servers allowing it to connect to a domain of IBM Communications Server for Linux v6.2 (or later) servers or a domain of CS/AIX v6.3 (or later) servers via TCP/IP. 1.1 New in this release ------------------------ This release includes enhancements for: - client-server via HTTPS - RHEL5 & SLES10 Linux distributions 1.2 Product fix history ------------------------ Please check the web sites: http://www.ibm.com/software/network/commserver/aix http://www.ibm.com/software/network/commserver/z_lin http://www.ibm.com/software/network/commserver/support for the latest information about this product. You can use the public newsgroups: news://news.software.ibm.com/ibm.software.commserver.aix news://news.software.ibm.com/ibm.software.commserver.linux for informal Question & Answer support. 1.3 Product compatibility -------------------------- There are no known product compatibility issues with this release. 1.4 Viewing the Documentation ------------------------------ The documentation is available on the QuickStart CD in the 'DOCS' subdirectory in PDF format. The publication names and numbers map to the PDF file names as shown below: Publication name Book number PDF filename ----------------------------------- ------------ ------------ Quick Beginnings GC31-6768-01 czx00101.pdf Quick Beginnings on System z GC31-6769-01 czx00201.pdf Administration Command Reference SC31-6770-01 czx00301.pdf Administration Guide SC31-6771-01 czx00401.pdf APPC Application Suite User's Guide SC31-6772-01 czx00501.pdf APPC Programmer's Guide SC31-6773-01 czx00601.pdf CPI-C Programmer's Guide SC31-6774-01 czx00701.pdf CSV Programmer's Guide SC31-6775-01 czx00801.pdf LUA Programmer's Guide SC31-6776-01 czx00901.pdf MS Programmer's Guide SC31-6777-01 czx01101.pdf NOF Programmer's Guide SC31-6778-01 czx01201.pdf Diagnostics Guide GC31-6779-01 czx01301.pdf Glossary GC31-6780-01 czx01401.pdf For Adobe Acrobat users on Windows, there is a zip file in the DOCS subdirectory which contains the indices needed to enable cross-manual searching. To install this index: - copy the zip file to a Windows PC and un-zip it - from within Adobe Acrobat: Select Edit --> Search --> Select Indexes Within the index selection, add the books.pdx file. To perform a search: - Select Edit -->Search -->Query - Select the index you want to search OR -- insert the term for which you want to search the library. Search results will be across all the books in the library. The documentation is also available on the Internet at: http://www.ibm.com/software/network/commserver/library 2. Installation information ---------------------------- The IBM Remote API Client for Linux on System z is shipped as a compressed tar file (tgz) on the Remote API Clients CD. The tgz file contains the RPMS, install shell scripts, and licensing tool. You will need an FTP server or other method of transfering files into the Linux for System z server. This file has details for the IBM Remote API Client for Linux on System z If you are installing the client on a different platform see the README file in the proper ibm-commserver-clients subdirectory on the Remote API Clients CD. If you are installing one of the server components see the appropriate README file in the root directory on the server CD of the install media. 2.1 Hardware requirements -------------------------- IBM Remote API Client for Linux on System z requires a 31 or 64-bit System z9 or zSeries server supported by one of the Linux distributions listed in section 2.2.1 Linux operating system version. Use the 'uname -m' command to verify the CPU class. It must report 's390' to indicate a 31-bit environment or 's390x' to indicate a 64-bit environment. 2.2 Software requirements -------------------------- 2.2.1 Linux operating system version ------------------------------------- This version of IBM Remote API Client has been tested with the following Linux operating system versions. It may also run satisfactorily on other Linux distributions. RedHat Enterprise Linux 3 for S/390 (RHEL3-s390) RedHat Enterprise Linux 3 for zSeries (RHEL3-s390x) RedHat Enterprise Linux 4 for S/390 (RHEL4-s390) RedHat Enterprise Linux 4 for zSeries (RHEL4-s390x) RedHat Enterprise Linux 5 for System z (RHEL5-s390x) SUSE Linux Enterprise Server 8 for IBM Mainframe (SLES8-s390*) SUSE Linux Enterprise Server 9 for IBM Mainframe (SLES9-s390*) SUSE Linux Enterprise Server 10 for IBM Mainframe (SLES10-s390x) For each operating system version you also need to have loaded a set of optional RPMs. Some of these RPMs come from the Linux install media and some need to be downloaded (the URLs or FTP sites for the download sites are described later). Each of the RPMs which you need to download are noted with "(download)". For the 64-bit distributions, some 31-bit ('s390.rpm') packages are needed in addition to the 64-bit ('s390x.rpm') packages. These are noted in the lists below. Use the "rpm -q -a" command to see what packages are currently installed. The lists below specify the minimum recommended levels of these RPMs. Later levels should also work. RedHat Enterprise Linux 3 for S/390 (RHEL3-s390) ------------------------------------------------ Required: binutils-2.14.90.0.4-26.s390 XFree86-libs-4.3.0-35.EL.s390 rpm-4.2.3-13 (from http://rhn.redhat.com/errata/RHBA-2004-501.html) libstdc++-3.2.3-49.s390 Optional, needed for JavaCPI-C: ibm-java2-s390-sdk-5.0-3.0 (download) RedHat Enterprise Linux 3 for zSeries (RHEL3-s390x) --------------------------------------------------- Required: binutils-2.14.90.0.4-26.s390x XFree86-libs-4.3.0-35.EL.s390x XFree86-libs-4.3.0-35.EL.s390 (note 's390') glibc-2.3.2-95.3.s390x glibc-2.3.2-95.3.s390 (note 's390') glib-1.2.10-11.1.s390x glib-1.2.10-11.1.s390 (note 's390') rpm-4.2.3-13 (from http://rhn.redhat.com/errata/RHBA-2004-501.html) libstdc++-3.2.3-49.s390x Optional, needed for JavaCPI-C: ibm-java2-s390-sdk-5.0-3.0 (download) Optional, needed for HTTPS: libstdc++-3.2.3-49.s390 (note 's390') RedHat Enterprise Linux 4 for S/390 (RHEL4-s390) ------------------------------------------------ Required: xorg-x11-libs-6.8.1-23.EL.s390 xorg-x11-deprecated-libs-6.8.1-23.EL.s390 compat-libstdc++-33-3.2.3-47.3 libgcc-3.4.4-2.s390 Optional, needed for JavaCPI-C: ibm-java2-s390-sdk-5.0-3.0 (download) RedHat Enterprise Linux 4 for zSeries (RHEL4-s390x) --------------------------------------------------- Required: xorg-x11-libs-6.8.1-23.EL.s390 (note 's390') xorg-x11-deprecated-libs-6.8.1-23.EL.s390 (note 's390') compat-libstdc++-33-3.2.3-47.3.s390x libgcc-3.4.4-2.s390 (note 's390') Optional, needed for JavaCPI-C: ibm-java2-s390-sdk-5.0-3.0 (download) Optional, needed for HTTPS: compat-libstdc++-33-3.2.3-47.3.s390 (note 's390') RedHat Enterprise Linux 5 for System z (RHEL5-s390x) --------------------------------------------------- Required: libXp-1.0.0-*.s390 (note 's390') libXt-1.0.2-*.s390 (note 's390') compat-libstdc++-33-*.s390x libgcc-4.1.1-*.s390 (note 's390') Optional, needed for JavaCPI-C: ibm-java2-s390-sdk-5.0-3.0 (download) Optional, needed for HTTPS: libXtst-*.s390 (note 's390') compat-libstdc++-33-*.s390 (note 's390') compat-libstdc++-33-*.s390x SUSE Linux Enterprise Server 8, 31-bit (SLES8-s390) --------------------------------------------------- Required: binutils-2.12.90.0.15-33.s390 xshared-4.2.0-97.s390 libgcc-3.2-32 libstdc++-3.2-32 Optional, needed for JavaCPI-C: ibm-java2-s390-sdk-5.0-3.0 (download) SUSE Linux Enterprise Server 8, 64-bit (SLES8-s390x) ---------------------------------------------------- Required: binutils-2.12.90.0.15-33.s390x xshared-4.2.0-87.s390x addonlibs-32bit-8.1-9.s390 (note 's390') baselibs-32bit-8.1-9.s390 (note 's390') glibc-32bit-8.1-9.s390 (note 's390') s390-32-1.1-23.s390x libgcc-3.2-32.s390x libstdc++-3.2-32.s390x Optional, needed for JavaCPI-C: ibm-java2-s390-sdk-5.0-3.0 (download) Optional, needed for HTTPS: libgcc-3.2-32 libstdc++-3.2-32 SUSE Linux Enterprise Server 9, 31-bit (SLES9-s390) --------------------------------------------------- Required: glibc-2.3.3-98.28.s390 XFree86-libs-4.3.99.902-43.22.s390 libstdc++-3.3.3-43.24 Optional, needed for JavaCPI-C: ibm-java2-s390-sdk-5.0-3.0 (download) SUSE Linux Enterprise Server 9, 64-bit (SLES9-s390x) ---------------------------------------------------- Required: glibc-2.3.3-98.28.s390x glibc-32bit-9-200501052045.s390 (note 's390') XFree86-libs-32bit-9-200501052045.s390 (note 's390') libstdc++-3.3.3-43.34.s390x libgcc-3.3.3-43.34.s390x Optional, needed for JavaCPI-C: ibm-java2-s390-sdk-5.0-3.0 (download) Optional, needed for HTTPS: libstdc++-32bit-9-200407011411.s390 (note 's390') libgcc-32bit-9-200501052045.s390 (note 's390') SUSE Linux Enterprise Server 10, 64-bit (SLES10-s390x) ------------------------------------------------------ Required: glibc-2.4 glibc-32bit-2.4 xorg-x11-libs-32bit-6.9.0 Optional, needed for JavaCPI-C: ibm-java2-s390-sdk-5.0-3.0 (download) Optional, needed for HTTPS: compat-libstdc++-5.0.7 libstdc++-4.1.0 libgcc-4.1.0 2.2.2 Java ---------- A Java may be needed if you use the JavaCPI-C API. Using the latest Java 5 SDK from the web site below satisfies all the requirements. http://www.ibm.com/developerworks/java/jdk Install the Java SDK package with a command like: rpm -i ibm-java2-s390-sdk-5.0-3.0.s390.rpm 2.2.3 HTTPS ----------- To run the client-server connection in HTTPS mode you will need additional pre-requisites for the gskit RPM. RedHat Enterprise Linux 3 for S/390 (RHEL3-s390) ------------------------------------------------ libstdc++-3.2.3-49.s390 RedHat Enterprise Linux 3 for zSeries (RHEL3-s390x) --------------------------------------------------- libstdc++-3.2.3-49.s390 libstdc++-3.2.3-49.s390x RedHat Enterprise Linux 4 for S/390 (RHEL4-s390) ------------------------------------------------ compat-libstdc++-33-3.2.3-47.3.s390 RedHat Enterprise Linux 4 for zSeries (RHEL4-s390x) --------------------------------------------------- compat-libstdc++-33-3.2.3-47.3.s390 compat-libstdc++-33-3.2.3-47.3.s390x RedHat Enterprise Linux 5 for System z (RHEL5-s390x) --------------------------------------------------- libXtst-*.s390 (note 's390') compat-libstdc++-33-*.s390 (note 's390') compat-libstdc++-33-*.s390x SUSE Linux Enterprise Server 8, 31-bit (SLES8-s390) --------------------------------------------------- libgcc-3.2-32 libstdc++-3.2-32 SUSE Linux Enterprise Server 8, 64-bit (SLES8-s390x) ---------------------------------------------------- libgcc-3.2-32.s390 libstdc++-3.2-32.s390 SUSE Linux Enterprise Server 9, 31-bit (SLES9-s390) --------------------------------------------------- libstdc++-3.3.3-43.24 SUSE Linux Enterprise Server 9, 64-bit (SLES9-s390x) ---------------------------------------------------- libstdc++-32bit-9-200407011411.s390 (note 's390') libstdc++-3.3.3-43.34.s390x libgcc-32bit-9-200501052045.s390 (note 's390') libgcc-3.3.3-43.34.s390x SUSE Linux Enterprise Server 10, 64-bit (SLES10-s390x) ---------------------------------------------------- compat-libstdc++-5.0.7 libstdc++-4.1.0 libgcc-4.1.0 If you are running RHEL5 with SELinux in 'enforcing' mode you should run the following commands to allow the gskit libraries to be used properly: semanage fcontext -a -t textrel_shlib_t \ /usr/local/ibm/gsk7/lib/libgsk7krsw.so semanage fcontext -a -t textrel_shlib_t \ /usr/local/ibm/gsk7/icc/osslib/libcrypto.so.0.9.7 chcon -f -t textrel_shlib_t /usr/local/ibm/gsk7/lib/libgsk7krsw.so chcon -f -t textrel_shlib_t /usr/local/ibm/gsk7/icc/osslib/libcrypto.so.0.9.7 If the prerequisite RPMs are already installed when the IBM Remote API Client is installed, then the appropriate gskit RPMs (gsk7bas and gsk7bas64) will be automatically installed at that time. On a 31bit system ('s390') then gsk7bas RPM is needed. On a 64bit system ('s390x') both the gsk7bas and gsk7bas64 RPMs are needed. If the prerequisite RPMs are not installed when the IBM Remote API Client is installed and at a later time you wish to install the gskit toolkit and co-requisite updates, follow these instructions. - Follow the steps in section 2.3.1 to unpack the tgz file and then run the installgskit shell script. ./installgskit The key manager function of gskit requires a customized Java 1.4.2 JRE, which is shipped as part of the product. To invoke the key manager, just type: snakeyman 2.3 Installation process ------------------------- If you have a previous level of IBM Remote API Client already installed, follow the steps in section 3 to remove it before installing this new level. Any old configuration information will be left in place for use by the new installation. To install IBM Remote API Client for Linux on System z follow these instructions. - Copy or FTP the ibm-commserver-client-6.3.0.2-s390x.tgz file from the ibm-commserver-clients/linux-systemz directory on the Remote API Clients CD to the Linux for System z server. Make sure to use binary mode for the tgz file. - Log into the Linux for System z server as root. - Uncompress and unpack the tar file into an empty temporary directory: mkdir /tmp/ibmcs cd /tmp/ibmcs tar -xzf ibm-commserver-client-6.3.0.2-s390x.tgz - Run the installibmcscli shell script ./installibmcscli The installibmcscli shell script will test for certain pre-requisites and issue warning messages if they are not met. You will be prompted to read and accept the license agreement, then the installibmcscli tool will install the RPMs. - Add the IBM Remote API Client binary directories to your PATH. You may wish to change your profile to do this automatically. export PATH="$PATH:/opt/ibm/sna/bin" export LD_LIBRARY_PATH=/usr/lib:/opt/ibm/sna/lib export LD_RUN_PATH=/usr/lib:/opt/ibm/sna/lib If you are running 64bit applications, you would use: export LD_LIBRARY_PATH=/usr/lib64:/opt/ibm/sna/lib64 export LD_RUN_PATH=/usr/lib64:/opt/ibm/sna/lib64 For Java CPI-C applications you should also set the environment variable: export CLASSPATH=$CLASSPATH:/opt/ibm/sna/java/cpic.jar - Start IBM Remote API Client. After installation this will happen automatically when the system is rebooted. cd / sna start 2.3.1 Post-install cleanup -------------------------- When you are done with the installs, the tgz file and temporary directory created in section 2.3 may be erased. 3. Uninstallation information ----------------------------- The IBM Remote API Client packages can be removed with the following commands: /opt/ibm/sna/bin/sna stop rpm -e ibm-commserver-ptf rpm -e ibm-commserver-docs rpm -e ibm-commserver-ecl rpm -e ibm-commserver-cli rpm -e ibm-commserver /sbin/shutdown -r now Not all of these packages will be installed on every system. The IBM Remote API Client no longer requires Streams, so you can uninstall the LiS package if no other applications require it. f there are no other applications which need gskit, it can be uninstalled with the command: rpm -e gsk7bas If you are on a 64bit system you also need to run: rpm -e gsk7bas64 Uninstalling IBM Remote API Client will leave any customized configuration information behind for use by a later installation. 4. Known limitations and problems ---------------------------------- 4.1 Number of concurrent LUA+APPC+CPI-C+NOF applications -------------------------------------------------------- By default the maximum number of concurrent LUA+APPC+CPI-C+NOF applications on a IBM Remote API Client is 240. If this limit is reached, the following message will be logged in /var/opt/ibm/sna/sna.err: hh:mm:ss TZ dd mmm yyyy 16392-13(33-0) E (hostname) PID pid# (application) Failed to allocate an IPC control block. To increase this limit follow these steps: sna stop vi /etc/opt/ibm/sna/sna_clnt.net add a line: maximum_process_count=240 The largest number you can use is 4096. This new line must come right after the domain= line. sna start The client must be stopped when this change is made. You may have to increase the number of semaphore arrays available to the linux system. Use the commands: ipcs -l cat /proc/sys/kernel/sem to determine the current settings and use a command like: echo W X Y Z > /proc/sys/kernel/sem to set new limits. You may want to put that echo command into the /etc/rc.d/init.d/snastart script so that it is executed on each boot. There are two other similiar values you can set in sna_clnt.net: maximum_header_count=1250 maximum_element_count=1800 The default for these fields are shown and should be adequate for most installations. 5. Documentation updates ------------------------- See the "WhatsNew6221.txt" file in the root of the CD for more details. 6. Notices and trademarks -------------------------- 6.1 Notices ----------- This information was developed for products and services offered in the U.S.A. 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 give you any license to these patents. You can send license inquiries, in writing, to: IBM Director of Licensing IBM Corporation North Castle Drive Armonk, NY 10504-1785 U.S.A. For license inquiries regarding double-byte (DBCS) information, contact the IBM Intellectual Property Department in your country or send inquiries, in writing, to: IBM World Trade Asia Corporation Licensing 2-31 Roppongi 3-chome, Minato-ku Tokyo 106, Japan The following paragraph does not apply to the United Kingdom or any other country where such provisions are inconsistent with local law: 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 states 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. IBM may use or distribute any of the information you supply 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 Corporation P.O. Box 12195 3039 Cornwallis Road Research Triangle Park, NC 27709-2195 U.S.A. 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 information 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. Trademarks ---------- The following terms are trademarks of the IBM Corporation in the United States or other countries or both: Advanced Peer-to-Peer Networking AIX Application System/400 AS/400 CICS IBM MQSeries MVS MVS/ESA MVS/XA NetView OpenPower OS/2 Power5 pSeries S/390 SP System p System x System z System/370 System/390 SAA Systems Application Architecture VTAM WebSphere z/OS z9 zSeries The following terms are trademarks or registered trademarks of other companies: Java and all Java-based trademarks are trademarks of Sun Microsystems, Inc., in the United States, other countries, or both. UNIX is a registered trademark in the United States and other countries licensed exclusively through The Open Group. Intel and Pentium are trademarks of Intel Corporation. AMD64 is a trademark of Advanced Micro Devices, Inc. Linux is a trademark of Linus Torvalds. Microsoft, Windows, Windows NT, Windows XP, Windows 2003, and the Windows logo are trademarks of Microsoft Corporation in the United States, other countries, or both. Other company, product, and service names may be trademarks or service marks of others.