IBM Communications Server v6.2.2.1 for Linux Web Administration package

* © Copyright International Business Machines Corp. 2004,2007
* 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
-----------------
0. Third-party license terms and conditions, notices, and information
1. About this release
1.1 Package compatibility
1.2 Package configuration requirements
2. Installation process
2.1 Configuration process
3. Uninstall information
4. Known limitations and problems
5. Documentation updates
6. Notices and trademarks

0.  Third-party license terms and conditions, notices and information:

SUBJECT TO ANY STATUTORY WARRANTIES WHICH CAN NOT BE EXCLUDED, IBM MAKES NO
WARRANTIES OR CONDITIONS EITHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED
TO, THE IMPLIED WARRANTIES OR CONDITIONS OF MERCHANTABILITY, FITNESS FOR A
PARTICULAR PURPOSE, AND NON-INFRINGEMENT, REGARDING THE PROGRAM OR TECHNICAL
SUPPORT, IF ANY.

1.  About this release:

 The Communications Server for Linux Web Administration package is a tool designed to
provide remote web connectivity for managing a CS Linux server installation. A full range
of remote query and status information is provided in general and specific functional areas.
Some start and stop functions for node, port (new),  connection and host resources are also provided.
Diagnostic tools for examining logs, taking traces and capturing problem determination data should be very useful.
Use this tool for most normal operations and not for large query operations.
If you need to query results for more than several hundred LUs or connections, use direct
Telnet or SSH connections.

6.2.2.1 Information:

This release is an updated version for the 6.2.2 release. It contains the following fixes:

 There is one additional capability provided in this update. The 'Device and Ports' panels allow starting
and stopping of specific ports.  See 'Manage Ports' on this panel to control ports activation from your
browser.

 If you have a Web Admin V6.2.2 package already installed, perform the following steps to update
the software:

            rpm -F ibm-commserver-webadmin-6.2.2.1-1.noarch.rpm

You should not have to modify any configuration files, unless you renamed the 'snauser' to some other name
(see "Changing SNA user default" in section 2.1 below). You must re-run the script provided to change
the SNA user name used in the package.

6.2.2.0 Information:

 This release of the Communications Server for Linux Web Administration V6.2.2 package has
more security features than previous releases. This package includes instructions to run the
Web Admin tool under a 'sna' group id, not as 'root'. This allows a HTTP server to execute the
snaadmin commands using an id other than 'root'. Follow the instructions provided in section 2.1,
Configuration process, to provide this access. Additional query commands for RTP Tuning have
been added in this release.

1.1  Package compatibility:

The package depends on Common Gateway Interface (CGI) capabilities shipped with the 'perl'
package for Linux. You must have an Apache server or IBM HTTP Server (IHS) and the
perl-CGI RPMs installed. The distributions tested for this package are those supported for the
CS Linux products:

    - Red Hat Enterprise Linux 3 (i686,s390,s390x)
    - SUSE Linux Enterprise Server 8 (i686,s390,s390x).
    - Red Hat Enterprise Linux 4 (i686,x84_64,ppc64,s390,s390x)
    - SUSE Linux Enterprise Server 9 and 10 (i686,x84_64,ppc64,s390,s390x).
    - Red Hat Enterprise Linux 5 (i686,x84_64,ppc64,s390x)

1.1  Package configuration requirements:

This package requires the administrator of a Linux system to perform configuration.
You must update the Web Server configuration file, httpd.conf. For secure access,
use visudo to update the /etc/sudoer file. The package uses full path specification
for execution of snaadmin, sna and snagetpd executables using a 'sna' group user.
You must to create a 'snauser' user id in the 'sna' group and then assign the web
server the authority to run under that user. This will prevent vulnerable attacks by
insertion of rogue execution files in the paths executed by a 'root' user. It is assumed
that the administrator is familiar with the procedures described to configure the Web
Server so that the proper security and performance requirements are met.
 

 1.2.2 Package dependencies:

This package can be installed with the IBM Communications Server for Linux (P/N 5724-i33)
or IBM Communications Server for Linux on System z (P/N 5724-i34). These do not need to
be installed for this package to load successfully. The package was tested with the following
Web Servers:

  - Apache 1.3.26 and 27
  - IBM HTTP Server (IHS) 2.0.47.1.

Most web browsers that support CGI enabled forms will work. Netscape V4.7 will not work
with this package. The Communications Server for Linux and Communications Server for
Linux on System z products have been tested with this Communications Server Web
Administration package. For RHEL3-s390 and SLES8-s390 Linux on zSeries systems, the
perl-CGI package is not included by default. Go to http://www.redhat.com/ and
http://www.suse.com/ to get the appropriate packages. Perl-CGI-2.81-88.7.s390.rpm was used
in our testing. For security purposes, you must also install the sudo package. This allows
specific access to CS Linux Administration commands for specific users.
 

 2.0 Installation process:


The ibm-commserver-webadmin-version.rpm file installs into the /opt/ibm/sna/web directory. This
directory contains this README and the following three sub-directories that the web server should
reference:

      /opt/ibm/sna/web/cscdoc
     /opt/ibm/sna/web/cscbin
     /opt/ibm/sna/web/cscicons

These files will all have user 'bin' and group 'sna' access rights.

Follow the instructions in the 'Configuration process'  to reference these directories.
NOTE: Perform all installation instructions under  the 'root' system id.

Install the Web Administration package by using the following RPM command:
     rpm -U ibm-commserver-webadmin-version.rpm

 2.1 Configuration process:

The instructions for configuring the Web Server is designed to have
http://server_name/cscdoc/cslinuxweb.html as the main page for the Web Administration package.
You will want to put a link to this main page somewhere on the Web Server to make access easy.

Update the Web Server configuration file, usually httpd.conf, with
Alias and Directory information. For secure access, it is recommended
you use the htpasswd tool shipped with Apache or IHS to set a user and password access.

    Updating the HPPTD.CONF file:

 The Web Server uses /etc/httpd/httpd.conf, /etc/httpd/conf/httpd.conf  or
/opt/IHS-version/conf/httpd.conf as the base configuration file, depending on the Web
server installed. The http.conf file must be updated to list Alias for .../cscdoc, .../cscbin,
and .../cscicons. Secure access should be imposed using a htpasswd file.

The following additions to the httpd.conf file provide Web Server access for
the Web Administration tool:

        -   Add to ScriptAlias section:
   ScriptAlias /cscbin/ "/opt/ibm/sna/web/cscbin/"

# For CS Linux Web Administration CGI directory
    <Directory "/opt/ibm/sna/web/cscbin">
        AuthName cslinux
# type of authentication
        AuthType Basic
# the path of the password file, here in the same directory as httpd.conf
        AuthUserFile /opt/ibm/sna/.webpasswd
# the valid users
        require valid-user
        AllowOverride None
        Options None
        Order allow,deny
        Allow from all
    </Directory>

# For CS Linux Web Administration Document directory
    Alias /cscdoc "/opt/ibm/sna/web/cscdoc/"
    Alias /cscdoc/ "/opt/ibm/sna/web/cscdoc/"

    <Directory "/opt/ibm/sna/web/cscdoc">
        AuthName cslinux
# type of authentication
        AuthType Basic
# the path of the password file, here in the same directory as httpd.conf
        AuthUserFile /opt/ibm/sna/.webpasswd
# the valid users
        require valid-user
        AllowOverride None
        Options None
        Order allow,deny
        Allow from all
    </Directory>

# For CS Linux Web Administration Icon directory
   Alias /cscicons "/opt/ibm/sna/web/cscicons/"
   Alias /cscicons/ "/opt/ibm/sna/web/cscicons/"
    <Directory "/opt/ibm/sna/web/cscicons">
        Options Indexes MultiViews
        AllowOverride None
        Order allow,deny
        Allow from all
    </Directory>
 

      Setting User and Password access:

In the Directory statements listed above for the Web Administration 'html' documents
and CGI directory, the AuthUserFile is set. To build this file, use the htpasswd command
to create and set the file. An example of using this file follows:

          htpasswd -bc  /opt/ibm/sna/.webpasswd admin passw0rd

This example creates /opt/ibm/sna/.webpasswd with a user of 'admin' and a password
of 'passw0rd'. Any reference to the http://server/cscdoc/ will prompt the initial access to
request the proper user id and password.
 

     Setting Access for Web Server requests:

The permissions for CS Linux command line executables are set to the 'sna' group.
Specific configuration allows Web clients proper access to the CS Linux commands.
Before setting access to allow execution by the Web client, you must create a dummy user
in the 'sna' group. Using root authority, execute /usr/sbin/useradd -g sna snauser. This
will create a 'snauser' id in the 'sna' group.

The visudo command in Linux allows the system administrator to give specific access to a
application to run as a specific user for specific executables. Care must be taken that the
paths are fully provided so rogue execution will not be possible. Using visudo, set the
user-specific access to:

wwwrun interface = (snauser) NOPASSWD: /opt/ibm/sna/bin/snaadmin, /opt/ibm/sna/bin/snagetpd, /opt/ibm/sna/bin/sna

,where wwwrun is the Apache user ID on SLES8 (use apache for RHEL Apache systems,
use nobody for IHS systems), the interfaceis the interface that the Web Server is allowing
access over. The (snauser) is required for the web client to run as 'snauser', a member of the
'sna' group. Use the NOPASSWD option so the system will not prompt for root password
when the web server executes the script. View the /var/log/httpd/error_logs for messages if
pages do not get invoked properly.

 Changing the SNA user default:

If the user id, 'snauser', is not an ID you wish to use, you can rename the user id in the Web
Admin files by running the /opt/ibm/sna/web/rename_user.pl script. This will prompt for
the new id to use. You should backup the /opt/ibm/sna/web/cscbin directory first. This
directory contains the files where the 'snauser' id is defined in the Web Admin scripts.

3.0 Uninstall information:
Perform the following steps to remove the CS Linux Web Administration package:

   1) Remove references to the Web Admin tool from the Web Server configuration.
       Edit the httpd.conf file and remove any references to .../cscdoc, .../cscbin
       and .../cscicons.

   2) Execute visudo tool to update the /etc/sudoers file to remove the access permission
        for the Web Server from the /opt/ibm/sna/bin/... files.

   3) Remove the CS Linux Web Administration package by using the following rpm
        command:

        rpm -e ibm-commserver-webadmin

4.0 Known limitations and problems:
Forms presented by this package to allow action on SNA resources, like starting
or stopping the node, do not prompt for confirmation. The assumption is that selected
options are the chosen action as submitted on the forms.
Errors that occur due to Web Server invocation problems are logged in the
/var/log/httpd/error_log or /opt/IHS-version/logs/error_log file.

5.0 Notices and trademarks:

This information was developed for products
and services offered in the U.S.A.
SUBJECT TO ANY STATUTORY WARRANTIES WHICH CANNOT BE EXCLUDED,
IBM MAKES NO WARRANTIES OR CONDITIONS EITHER EXPRESS OR IMPLIED,
INCLUDING BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OR
CONDITIONS OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
PURPOSE, AND NON-INFRINGEMENT, REGARDING THE PROGRAM OR
TECHNICAL SUPPORT, IF ANY.
 

The exclusion also applies to any of IBM's Program
developers and suppliers.

Manufacturers, suppliers, or publishers of non-IBM Programs
may provide their own warranties.

IBM does not provide technical support, unless IBM
specifies otherwise.

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
APPN
AS/400
CICS
IBM
MQSeries
MVS
NetView
OpenPower
Power5
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.

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.

RedHat and RPM are trademarks of Red Hat, Inc.

SUSE is a trademark of Novell, Inc.

Other company, product, and service names may be trademarks or service
marks of others.