* * (c) Copyright International Business Machines Corp. 2002 * 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. * IBM Communications Server v6.0.1.1 for Linux INSTALLATION AND RELEASE NOTES PRPQ 5799-RQA 1. Updates ---------- Please check the web site: http://www.ibm.com/software/network/commserver/linux for the latest information about this PRPQ 2. Packaging ------------ The CS/Linux demo is packaged as a tar file containing this README, the base RPM package, and an install shell script. The v6.0.1.1 level of CS/Linux is a free, downloadable, demo package. It contains a subset of the function of the CS/Linux v6.0.1.0 PRPQ. 3. Introduction --------------- CS/Linux provides SNA connectivity for your Intel based Linux system, allowing it to connect to IBM mainframe and AS/400 computers, as well as other workstations. This demo package will work for 90 days from the date of installation. After that time the sna daemons will no longer start. CS/Linux v6.0.1.1 demo package supports the following out-of-the-box uncustomized kernels: RedHat 7.3 - 2.4.18-3 SuSE 8.0 - 2.4.18-4GB RedHat 9 - 2.4.20-8 & 2.4.20-9 SuSE 8.2 - 2.4.20-4GB Use the 'uname -r' command to verify the kernel level. CS/Linux will not install on other kernels including "custom" variations of the kernels listed above. CS/Linux v6.0.1.1 demo package supports the following classes of CPUs: i686 (Pentium II, Pentium III, Pentium 4) Use the 'uname -m' command to verify the CPU class. 4. Viewing the Documentation ---------------------------- The CS/Linux documentation is available online at: http://www.ibm.com/software/network/commserver/library 5. Pre-requisite Products ------------------------- 5.1 Linux Operating System Version This demo version of CS/Linux supports the following operating system versions: Redhat 7.3 SuSE 8.0 Redhat 9 SuSE 8.2 For each operating system version you also need to have loaded a set of optional RPMs. RedHat 7.3 ---------- glibc-kernheaders-2.4-7.14 kernel-source-2.4.18-3 gcc-2.96-110 make-3.79.1-8 openmotif21-2.1.30-1 XFree86-libs-4.2.0-8 SuSE 8.0 -------- kernel-source-2.4.18.SuSE-35 gcc-2.95.3-216 make-3.79.1-292 binutils-2.11.92.0.10-89 glibc-devel-2.2.5-38 openmotif-2.1.30MLI4-288 xshared-4.2.0-64 RedHat 9 ---------- glibc-kernheaders-2.4-8.10 kernel-source-2.4.20-8 or kernel-source-2.4.20-9 gcc-3.2.2-5 make-3.79.1-17 binutils-2.13.90.0.18-9 glibc-devel-2.3.2-11.9 openmotif-2.2.2-14 XFree86-libs-4.3.0-2 XFree86-4.3.0-2 SuSE 8.2 -------- kernel-source-2.4.20.SuSE-30 gcc-3.3-23 make-3.80-25 binutils-2.13.90.0.18-21 glibc-devel-2.3.2-6 XFree86-libs-4.3.0-15 XFree86-4.3.0-15 openmotif-2.2.2-204 5.2 Linux Streams (LiS) 2.16.0 CS/Linux uses the LiS streams implementation. The 2.16.0 level of LiS is required. This package can be obtained from the following URL. ftp://ftp.gcom.com/pub/linux/src/LiS/LiS-2.16.0.tgz If you already have a previous level of LiS installed, it should be completely uninstalled by doing: PATH=$PATH:/sbin cd /usr/src/LiS make uninstall make very-clean cd rm -rf /usr/src/LiS* /sbin/shutdown -r now If you are running SuSE 8.0 you should run the following commands to make sure the kernel source is consistent with running kernel: cp -p /boot/vmlinuz.config /usr/src/linux-2.4.18.SuSE/.config cp -p /boot/vmlinuz.autoconf.h \ /usr/src/linux-2.4.18.SuSE/include/linux/autoconf.h cp -p /boot/vmlinuz.version.h \ /usr/src/linux-2.4.18.SuSE/include/linux/version.h mv /usr/src/linux-2.4.18.SuSE/.kversion \ /usr/src/linux-2.4.18.SuSE/.kversion.save If you are running SuSE 8.2 you should run the following commands to make sure the kernel source is consistent with running kernel: cp -p /boot/vmlinuz.config /usr/src/linux-2.4.20.SuSE/.config cp -p /boot/vmlinuz.autoconf.h \ /usr/src/linux-2.4.20.SuSE/include/linux/autoconf.h cp -p /boot/vmlinuz.version.h \ /usr/src/linux-2.4.20.SuSE/include/linux/version.h mv /usr/src/linux-2.4.20.SuSE/.kversion \ /usr/src/linux-2.4.20.SuSE/.kversion.save Copy the file LiS-2.16.0.tgz to your Linux machine in binary mode. Copy it to /usr/src. Execute the following set of commands to install LiS. PATH=$PATH:/sbin cd /usr/src tar -xzf LiS-2.16.0.tgz cd /usr/src/LiS-2.16 make Select the default answer to all the questions make install See http://www.gcom.com/LiS/index.html for more information on LiS. 5.3 OpenMOTIF CS/Linux uses the MOTIF implementation from the Open group at the 2.2 level. For RedHat 7.3, RedHat 9, and SuSE 8.2 this is the 'openmotif-2.2.2' RPM on the linux CDs. For SuSE 8.0 this is available from http://www.motifzone.org/download or other open source sites. In testing we used this RPM: http://ftp.motifzone.net/2.2/linux-rpm/x86/openmotif-2.2.2-3_ICS.i386.rpm 5.4 Java A Java may be needed for CS/Linux, for the JavaCPI-C API. Different components of CS/Linux require different minimum Java levels and Java components, but using the Java 1.3.1 SDK from the web site below satisfies all the requirements. http://www-106.ibm.com/developerworks/java/jdk Install the Java 1.3.1 SDK package with a command like: rpm -i IBMJava2-SDK-1.3.1-2.0.i386.rpm For SuSE 8.0 use the IBMJava2-SDK-1.3-258 RPM from the SuSE 8.0 install CDs. For RedHat 9 and SuSE 8.2, which use the 2.4.20 kernels, you might also have to run: export LD_ASSUME_KERNEL=2.4.1 in order to use the current Java RPMs with those linux distributions. 6. Installing and Starting CS/Linux ---------------------------------- 6.1 CS/Linux base To install CS/Linux you will need the base RPM, CS-LINUX-6.0.1.1-1.i386.rpm and the installcslinux shell script To install this RPM follow these instructions. - Log into the machine as root. - UnTar the demo package tar -xvf CSLinux6011.tar - Issue the following command to install CS/Linux ./installcslinux For machines with limited memory, e.g. 64Meg, a reboot is required. For larger systems this may not be needed. If the CS/Linux node fails to start, check the /var/log/messages file for an entry like: kernel: SNA Trace Driver can only get X blocks of memory - please reboot If these messages persist even after rebooting you need more memory. - Add the CS/Linux binary directories to your PATH. You may wish to change your profile to do this automatically. export PATH="$PATH:/opt/sna/bin:/opt/sna/bin/X11" export LD_LIBRARY_PATH=/usr/lib:/opt/sna/lib export LD_RUN_PATH=/usr/lib:/opt/sna/lib For Java CPI-C applications you should also set the environment variables: export CLASSPATH=$CLASSPATH:/opt/sna/java/cpic.jar export LD_PRELOAD=/usr/lib/libpLiS.so - Start CS/Linux. Note that after installation this will happen automatically when the machine is rebooted. cd / sna start - Run the CS/Linux MOTIF administration tool. We strongly recommend you use the Motif administration program until you are familiar with CS/Linux operation. Simply follow the instructions you are given. xsnaadmin & 7. Connectivity Options ----------------------- CS/Linux can be used over Ethernet or Token Ring adapters. CS/Linux has been tested with several different ethernet adapters using several different linux device drivers. CS/Linux has been tested with the IBM 16/4 PCI token ring adapter (olympic driver) and the IBM LANStreamer adapter (lanstreamer driver). Other adapters (such as Madge) using these or other drivers are also expected to work. See the web site http://www.ibm.com/software/network/commserver/linux/sysreq for a complete list of adapters and drivers which have been tested. If you want to use an adapter for CS/Linux but not for tcp/ip, you have to manually tell linux to load the device driver and enable the adapter. For RedHat 7.3 this is done by having an entry in the /etc/modules.conf file for that adapter and modifying the appropriate /etc/sysconfig/network-scripts/ifcfg-* file to look something like this: DEVICE=eth1 ONBOOT=yes BOOTPROTO=none For SuSE 8.0 this is done by having an entry in the /etc/modules.conf file for that adapter and modifying the appropriate /etc/sysconfig/network/ifcfg-* file to look something like this: DEVICE=eth1 BOOTPROTO="none" STARTMODE="onboot" 8. Removing CS/Linux -------------------- The CS/Linux package can be removed with the following commands: sna stop rpm -e CS-LINUX /sbin/shutdown -r now This will have to be done before installing the non-demo package. 9. Known Limitations -------------------- 9.1 TN3270 Server With the default RedHat 7.2 and 7.3 kernel values, the CS/Linux TNServer is limited to 8192 open files/sockets. That means a max of 8192 tn3270 clients or 4096 TN-Redirector clients (because redir uses 2 sockets per client): ( (#_of_ReDir_clients * 2) + #_of_TN3270_clients ) < 8192 This limit can be increased by following the instructions in: /usr/src/linux*/Documentation/filesystems/proc.txt where it says: file-nr and file-max -------------------- The kernel allocates file handles dynamically, but doesn't free them again at this time. The value in file-max denotes the maximum number of file handles that the Linux kernel will allocate. When you get a lot of error messages about running out of file handles, you might want to raise this limit. The default value is 8192. To change it, just write the new number into the file: # cat /proc/sys/fs/file-max 8192 # echo 16384 > /proc/sys/fs/file-max # cat /proc/sys/fs/file-max 16384 This method of revision is useful for all customizable parameters of the kernel - simply echo the new value to the corresponding file. If the customer hits this limit they will see this in /var/opt/sna/sna.err: hh:mm:ss TZ dd mmm yyyy 4102-6(0-1) E (hostname) PID pid# (snatnsrvr_mt) O/S accept call failed with error code 23. hh:mm:ss TZ dd mmm yyyy 4102-8(1-1) E (hostname) PID pid# (snatnsrvr_mt) Failed to initialize TN3270 or TN Redirector Client due to serious error. The default limit is larger in SuSE 8.0 but also depends on which SuSE 8.0 kernel you are using and how much memory the PC has. Use the 'cat /proc/sys/fs/file-max' command to see what the current limit is. 9.2 Number of concurrent LUA+APPC+CPI-C+NOF applications There is an O/S limit that prevents more than 255 open Streams (i.e. applications) on CS/Linux at once. CS/Linux itself uses some of these streams internally. That means the total number of concurrent LUA+APPC+CPI-C+NOF applications must be less than about 230. If the customer hits this limit they will see this in /var/opt/sna/sna.err: hh:mm:ss TZ dd mmm yyyy 16388-10(1-0) E (hostname) PID pid# (application) Error opening Stream to SNA kernel subsystem. Errno = 28 (No space left on device) hh:mm:ss TZ dd mmm yyyy 16385-6(1-10) E (hostname) SNA Kernel open error 28. 9.3 Support of Laptop PCs In general CS/Linux will run on laptop PCs, which use pcmcia cards, but you may have trouble shutting down linux on a laptop with CS/Linux. In this scenario you will see messages like: Stopping pcmcia: cardmgr[X]: exiting unregister_netdevices: waiting for ethX to become free The shutdown will hang at this point and you will have to power-off. 9.4 Using applications and TPs built on older levels There are two issues when trying to use applications and TPs that were compiled on older levels of Linux, CS/Linux and LiS. a) LiS 2.1.6.0 This level of LiS, which is required for some of the new linux distributions and is strongly recommended, may also require that you set the environment variable: export LD_PRELOAD=/usr/lib/libpLiS.so for old applications and TPs to work properly. You can also recompile your applications and TPs and not worry about that environment variable. b) RedHat 9 and SuSE 8.2 These new distributions are based on a linux kernel level (2.4.20) which includes a new threading model. You may have to recompile your applications on these distributions for them to work properly or you may be able to set the environment variable: export LD_ASSUME_KERNEL=2.4.1 to force the old threading model. 10. Sample Programs -------------------- CS/Linux comes with the common set of applications from the APPC Application Suite: aping acopy, aftp, aftpd atell, atelld aname, anamed arexec, arexecd The invokable TP definitions for these applications are in /etc/opt/sna/asuite.tps. These can be activated with the command: /opt/sna/bin/snatpinstall -a /etc/opt/sna/asuite.tps CS/Linux also comes with a few sample source code programs in /opt/sna/samples which you can compile. Examples of the configuration, compile and run steps are below. More details are in the appropriate "Programmer's Guide" for each API. 10.1) "asample" snaadmin define_mode, mode_name=LOCMODE snaadmin define_local_lu, lu_alias=TPLU1, lu_name=TPLU1 snaadmin define_local_lu, lu_alias=TPLU2, lu_name=TPLU2 cd /opt/sna/samples gcc -o asample2 -I /usr/include/sna \ -L /opt/sna/lib -lappc -lsna -lcsv -lpLiS asample2.c gcc -o asample1 -I /usr/include/sna \ -L /opt/sna/lib -lappc -lsna -lcsv -lpLiS asample1.c ./asample2 & ./asample1 /etc/hosts 10.2) "csample" snaadmin define_mode, mode_name=LOCMODE snaadmin define_local_lu, lu_alias=TPLU1, lu_name=TPLU1 snaadmin define_local_lu, lu_alias=TPLU2, lu_name=TPLU2 snaadmin define_cpic_side_info, sym_dest_name=CPICTEST, lu_alias=TPLU1, \ partner_lu_name=TPLU2, tp_name=TPNAME2, mode_name=LOCMODE snaadmin define_tp, tp_name=TPNAME2 snaadmin define_tp_load_info, tp_name=TPNAME2, userid=root, \ path=/opt/sna/samples/csample2, type=QUEUED, \ env=APPCTPN=TPNAME2, env=APPCLLU=TPLU2, \ env=LD_LIBRARY_PATH=/usr/lib:/opt/sna/lib|LD_RUN_PATH=/usr/lib:/opt/sna/lib cd /opt/sna/samples gcc -o csample2 -I /usr/include/sna \ -L /opt/sna/lib -lcpic -lappc -lsna -lcsv -lnof -lpLiS csample2.c gcc -o csample1 -I /usr/include/sna \ -L /opt/sna/lib -lcpic -lappc -lsna -lcsv -lnof -lpLiS csample1.c chmod ugo+s csample2 export APPCLLU=TPLU1 export APPCTPN=TPNAME1 ./csample1 /etc/hosts unset APPCLLU unset APPCTPN 10.3) "lsample" snaadmin define_*_dlc, ... snaadmin define_*_port, ... snaadmin define_*_ls, ... cd /opt/sna/samples gcc -o lsample -I /usr/include/sna \ -L /opt/sna/lib -llua -lsna -lcsv -lpLiS lsample.c export SNATBLG=/opt/sna/samples/luatblg.dat ./lsample LUNAME 10.4) "JPing" rpm -q -a | grep Java make sure the Java SDK is installed snaadmin define_node, ... snaadmin define_cpic_side_info, sym_dest_name=SIDE, ... PATH=/opt/IBMJava2-131/jre/bin:/opt/IBMJava2-131/bin:$PATH export LD_LIBRARY_PATH=/usr/lib:/opt/sna/lib export CLASSPATH=$CLASSPATH:/opt/sna/java/cpic.jar export LD_PRELOAD=/usr/lib/libpLiS.so cd /opt/sna/samples javac JPing.java java JPing SIDE