#-----------------------------------------------------------------------
# Licensed Materials - Property of IBM
#
# IBM Tape System Library Manager
#
#
# (C) Copyright IBM Corp. 2004, 2015 All Rights Reserved
#
# US Government Users Restricted Rights - Use, duplication or
# disclosure restricted by GSA ADP Schedule Contract with IBM Corp.
#-----------------------------------------------------------------------
#
#                              README File
#                          TSLM_1.1.1.4_Server
#
#
#-----------------------------------------------------------------------



#-----------------------------------------------------------------------
# Table of Contents
#-----------------------------------------------------------------------
0. About this Release
1. About this Readme
2. Installation Information
3. Installation File List 
4. Fix List
5. How to apply the fix pack
6. Prerequisite
7. ITDT for TS3500 shuttle discovery
8. Additional Information
9. Notices and Trademarks

#-----------------------------------------------------------------------
# 0. Important Notes in this Release - TSLM 1.1.1.4 Server & Client
#-----------------------------------------------------------------------
Notes for 1.1.1.4
- The following operating systems were tested certified as TSLM client.
  - RHEL 6.5
  - SLES 11 SP3
  - Windows Server 2012

Notes for 1.1.1.3:
- Drop DB of TSLM is not required. (DB Schema is not changed basically.)
- mm.xml must be updated before new types of cartridges (JD, JL or JZ) are inserted.
 (See. #8.10)
- HDM must be updated before the server for the HDM recognizes TS1150 drives.
 (See. #8.11)
- ibmatl driver must be updated for TS1150 drives.
 (It's bundled in TSLM this package) (See. #2.2.1)

- DriveType and DriveModel for TS1150 at ermm3494.cfg are specifed as below.
#
# Which drive type and model to use
#
DriveType = 3592
DriveModel = E08

#-----------------------------------------------------------------------
# 1. About this Readme
#-----------------------------------------------------------------------

This Readme file provides the latest information about TSLM that is 
either not yet included in the product documentation or has changed 
since publication. 
The content is intended to be used concomitantly with the TSLM User's
Guide.

For detailed information about TSLM and its components, refer to the 
TSLM User's Guide.


#-----------------------------------------------------------------------
# 2. Installation Information
#-----------------------------------------------------------------------
Installation information is in the TSLM User's Guide.

Additional installation information follows:


# 2.1 3494 Tape Library Driver

These files are for a 3494 Tape Library Driver that supports TS1150 tape
drives:
    - tslm/drivers/atldd/aix64/atldd.6.8.8.0
    - tslm/drivers/atldd/linux64/ibmatl.6.8.8.0.x86_64.rpm
For details about this driver, see the "IBM Tape Device Drivers 
Installation and User's Guide" that is available at the following link:
http://www-01.ibm.com/support/docview.wss?uid=ssg1S7002972&aid=1



# 2.2 Red Hat Enterprise Linux 6.4

Red Hat Enterprise Linux (RHEL) 6.4 is supported for the TSLM server and
TSLM client since TSLM V1.1.1.1. This section provides important
information about the additional software requirements and the required
installation steps that you must follow when you install TSLM V1.1.1.1
(or later) on RHEL 6.4 systems.

# 2.2.1 Additional software requirements


 1. Linux Tape and Medium Changer Device Driver (lin_tape driver)

 TSLM requires the lin_tape driver for the control of TS3500 Tape 
 Libraries. The lin_tape driver supported RHEL 6.4 since version 2.3.0.
 Therefore, install the lin_tape driver 2.3.0 or later on the target
 RHEL 6.4 systems.

 As described later, you will need to upgrade Linux kernel on the RHEL
 6.4 systems to the kernel version that the lin_tape driver 2.3.0 
 supports. After the kernel upgrade, execute the rpmbuild command to
 build the lin_tape driver on the upgraded kernel, and install it.

 For more information about the lin_tape driver 2.3.0, see the lin_tape
 README file.

 Note: At the installation of the lin_tape driver on the TSLM server,
       you can use following functions of the lin_tape driver to
       adequately manage the device files for Medium changers:

         - Persistent Naming Support
         - Control Path Failover Support for Tape Libraries

       For more information about the functions of the lin_tape driver,
       see the IBM Tape Device Drivers Installation and User's Guide.


 2. 3494 Tape Library Driver (ibmatl driver)

 TSLM requires the ibmatl driver for the Control of optional TSLM 3494
 Emulation. The TSLM fix pack version 1.1.1.3 or later include the ibmatl driver
 version 6.8.8.0. If the TSLM 3494 Emulation is used, install the
 ibmatl driver on the target RHEL 6.4 systems.
 


 3. Linux Kernel

 The lin_tape driver 2.3.0 supports RHEL 6.4 with minimum kernel version
 2.6.32-358.18.1.el6. This requires kernel upgrade from the default
 kernel version on RHEL 6.4 (2.6.32-358.el6) to the 2.6.32-358.18.1.el6
 or later version, when you use the lin_tape driver 2.3.0.

 For details about the newer kernel packages, check the information on
 the Red Hat Network website. For example, for kernel version
 2.6.32-358.18.1.el6, refer to the following information:

     kernel security and bug fix update (RHSA-2013:1173-1)
     http://rhn.redhat.com/errata/RHSA-2013-1173.html

 For details about kernel upgrade, see the Red Hat Enterprise Linux
 Deployment Guide.

 You will need to upgrade the kernel package and some prerequisite
 packages for the kernel and the lin_tape driver. For example, the
 kernel-firmware and the kernel-devel packages must be upgraded.
 
 The system must be rebooted for the kernel update to take effect.


 

4. Korn Shell

 The korn shell script files that are included in the TSLM server and
 client packages require that Korn Shell is installed on the system.
 And the DB2 on the TSLM server also requires that the supported Korn
 Shell is installed.

 Check if the ksh93 (ksh-20100621-19.el6 or newer) package is installed
 on the target RHEL 6.4 systems.



 5. Perl

 The perl script files that are included in the TSLM server and client
 packages require that Perl interpreter program is installed on the
 system.

 Check if the perl (perl-5.10.1-129.el6 or newer) package is installed
 on the target RHEL 6.4 systems.



 6. sg3_utils

 The TSLM Host Drive Manager (HDM) requires that the sg_inq command
 in the sg3_utils package is installed on the system.

 Check if the sg3_utils (sg3_utils-1.28-4.el6 or newer) package is 
 installed on the target RHEL 6.4 systems.



 7. IBM Tivoli Storage Manager

 IBM Tivoli Storage Manager is a host application of TSLM. Tivoli
 Storage Manager uses the TSLM ELM interface to communicate with the
 TSLM server. 

 Although TSLM is compatible with Tivoli Storage Manager V5.5, V6.1, 
 V6.2, V6.3, and V6.4, make sure that you use the suitable Tivoli
 Storage Manager version that supports RHEL 6.4, and set up the software
 components appropriately on the RHEL 6.4 system. For more information
 about the Tivoli Storage Manager supported operating systems, see the
 following link and related Tivoli Storage Manager publications.

     "Overview - Tivoli Storage Manager Supported Operating Systems"
     http://www-01.ibm.com/support/docview.wss?uid=swg21243309


# 2.2.2 Required additional installation steps on RHEL 6.4 systems


 1. DB2

 On the RHEL 6.4 systems, extra setup is required after installation of
 a DB2 package that is included in TSLM V1.1.0,  V1.1.1 or V1.1.3 media.

 After you install DB2 on the RHEL 6.4 system from the DB2 package
 (version 9.7 fix pack 4), autostart of a DB2 instance on reboot does
 not work. To correct this issue, refer to the documentation on the
 following web page and complete the steps that are provided:

     Autostart of DB2 instance on reboot does not work on RHEL6 systems
     http://www.ibm.com/support/docview.wss?uid=swg21497220

 Also, there are some required and recommended kernel parameter settings
 on the RHEL 6 systems, when you are running the DB2 (version 9.7 fix 
 pack 4). For more information about the settings, see the documentation
 on the following web page:

     Information Management Solution Portal Home
     https://www.ibm.com/developerworks/community/wikis/home/
      wiki/Information%20Management

       Select "Red Hat Enterprise Linux (RHEL) 6 - DB2 9.7" on the left
       navigation pane, as shown in the following example:

       > Supported Linux Environments
        > DB2 and DB2 Connect 9.7 for Linux - Supported Environments
         > Red Hat Enterprise Linux (RHEL) 6 - DB2 9.7



 2. TSLM server

 You can configure your system to automatically start the TSLM server
 components when your system restarts.

 If you want the Media Manager and the Library Managers to start on
 system restart, add the ermmStart and ermmLmStart commands to your
 system boot process. 

 For RHEL 6 systems, you must create configuration files on the
 /etc/init directory. Follow these steps as a guide:

 2-1. Create a configuration file that is named /etc/init/mm.conf to
      start the Media Manager. Here is an example of the file:

       # mm - TSLM Media Manager
       start on stopped rc RUNLEVEL=[2345]
       stop on starting rc RUNLEVEL=[!2345]
       exec su - ermm -c ermmStart

 2-2. Create a configuration file (named as /etc/init/lm.conf) to start
      the Library Manager. Here is an example of the file:

       # lm - TSLM Library Manager
       start on stopped rc RUNLEVEL=[2345]
       stop on starting rc RUNLEVEL=[!2345]
       exec su - ermm -c ermmLmStart

 2-3. Make sure that the configuration files that you created in the
      preceding steps are not executable. Here is an example of valid
      file permission settings:

       -rw-r--r-- 1 root root 80 Jul 24 13:21 lm.conf
       -rw-r--r-- 1 root root 78 Jul 24 13:20 mm.conf


 

3. 3494 Tape Library Driver (ibmatl driver)

 After you install the ibmatl driver 6.8.8.0 on RHEL 6 from a RPM
 package that is included in TSLM media or fix pack, autostart of the
 IBM Library Manager Control Point Daemon on reboot does not work. 
 To correct this issue, you must follow these steps.

 3-1. Remove following entry in the /etc/inittab file for starting the
      IBM Library Manager Control Point Daemon (/etc/lmcpd), that is
      installed from the ibmatl driver package.

       lmcp:234:once:/etc/lmcpd

 3-2. Create a configuration file that is named /etc/init/lmcp.conf to
      start the /etc/lmcpd. Here is an example of the file:

       # lmcp - IBM Library Manager Control Point Daemon
       start on stopped rc RUNLEVEL=[2345]
       stop on starting rc RUNLEVEL=[!2345]
       exec /etc/lmcpd

 3-3. Make sure that the configuration file is not executable. Here is
      an example of valid file permission settings:

       -rw-r--r-- 1 root root 139 Oct 22 18:45 lmcp.conf


#-----------------------------------------------------------------------
# 3. Installation File List
#-----------------------------------------------------------------------
The level of this TSLM package is:
          TSLM 1.1.1.4

You can use the tslmlevel command to show the level of each TSLM
package. For details about the tslmlevel command, see Chapter 2 of the
TSLM User's Guide.

#
# TSLM_1.1.1.4_Server
This package includes the following installation files:
    Package name        Levels
    ---------------     ---------------
    tslm.mm             1.1.1.4
    tslm.lm             1.1.1.4
    tslm.cli            1.1.1.4
    tslm.libbal         1.1.1.4
    tslm.3494           1.1.1.4
    tslm.pwgen          1.1.1.4
    

#-----------------------------------------------------------------------
# 4. Fix List (updated)
#-----------------------------------------------------------------------
The following fixes are included in level 1.1.1.4
 77079 tslm-audit3494.pl supports multiple libraries

The following fixes are included in level 1.1.1.3

 74403 Multithreaded HDM could return incomplete response to MM
 74566 Bugfix related to EMM3002E
 74582 Bugfix of HDM -  "pring $socket" to "syswrite (<soket>,
 74641 Bugfix of Shuttle control to avoid a deadlock condition
 74738 Tune lock mechanism of CMCLM in order to improve performance  
 74846 Bugfix of segfault and unprintable problem in Media Manager 
 75052 Reduce load of make_connection in case of many requests
 75107 Bugfix of Media Manager. Pick wrong PCL at IEE(shuttle)
 75480 car is reserved forever
 75581 added checking by 0x200-0x300 for CMC elements
 76877 '_' was handled as unprintable character unexpectedly
 76950 non-home unmounts concurrently take destination conflict       
 75839 support TS1150 - HDM, MM and ELM                          
 75840 support TS1150 - 3494api                                  
 76055 pwenc function not working on Windows 2012 R2                  
 76058 ermmtool authenticates AI with incorrect pw specified          
 74544 Add trace facility to ermmTapeutil for Windows                 
 76215 support extra information capturing tool (Linux Only) 
 76393 add validity check to DB2 schema for avoiding unprintable char 
 76461 tslm-audit3494.pl consumes much CPU/Memory resource            
 76462 core was generated at mparser
 76599 crash, Unprintable, slow responce problem related to 3494 emul, icu updated 
 74181 ermmTsmSync de-allocates vol. 

The following fixes are included in level 1.1.1.1

  73007 Open/Close/Polling reduction to the tape library devices
  73318 Code optimization in SCSI RES handling for the move command
  73449 Fix for password setting in ermmCollectLogs.pl tool
  73692 ermmCollectLogs.pl tool failed to create a tar file
  74264 Fix for some CMCLM implementations
  74295 Fix for tslm-audit3494.pl

The following fixes are included in level 1.1.1.0

  70029 Perl default path in installer is wrong (backslash)   
  70559 Support HDM multiple processes on one platform            
  70884 Adding sample scripts for the TSM migration                
  71177 lscart with wrong library information returns info  
  71546 Add the process for WORM LTO cartridges                   
  72474 Typo in createAllocScript.pl                               
  72535 Drive selection in mount                                   
  72568 Multithreading in HDM                                      
  72619 Wrong caseCompare() method for library name                 
  72638 Polling car arrival at source lib as well as destination  
  72871 Shuttle unlock error recovery                             
  72872 Retrial RES in move cmd of Library Manager                
  73122 Secondary hdm configuration

The following fixes are included in level 1.1.0.5

  70567 Fix for local drive is free while waiting for shuttle car      
  70590 Change default trace size in config file                       
  70972 Check if the slot is I/O during unmount process                
  71056 Detecting of error related to SCSI ioctl lin_tape,atape        
  71091 LM_E_LIBRARY handling in the shuttle mount                    
  71104 SCS UPDATE 6.1 to change timeout value 90sec to 15min          
  71297 Clear pOriginalMount after original mount cmd is queued        
  71298 Schedule one local mount for one unmounted drive               
  71310 No volser handling with shuttle environment                    
  71321 Update make connection retry count in cmc layer                
  71335 SimpleThread causes core                                       
  71349 Need to initialize scsi pointer in ScsCmcIeeMonitor            


The following fixes are included in level 1.1.0.4

  70301 Mount JA cart. into JAG4 using 3494 emulation
  70315 Default Cartridge Type JA from 3592 library
  70333 Add ability to update default cart 
  70394, 70395 Added VOLSER Status mode using 3494 emulation
  70476 Remove some unnecessary exports from migration scripts
  70514 Fix DeallocGroup not being allocated after migration
  70516 Support readonly capabilities for LTO drives
  70531 Fix AllocatedFromGroup not being restored after migration
  70581 Fix a minor error checking problem in migration scripts


The following fixes are included in level 1.1.0.3

  70251 Add fixes for support of remote DB2 on z/OS
  70252 Change SQL script for creating triggers on DB2 on z/OS
  70318 Add migration scripts for remote DB2 on z/OS 

Important:
The configuration where a TSLM database is installed on a remote DB2 
on a z/OS requires release 1.1.0.3 or later.


The following fixes are included in level 1.1.0.2

  68676 incorrect package prefix in ermmCollectLogs.pl 
  69422 Add index in ermm table definition for zOS    
  69426 mtlib/3494 problem
  69536 support tslm-audit3494.pl                 
  69568 LTO6 Support   
  69598 Encrypted password was not set when pwenc was selected     


The following fixes are included in level 1.1.0.1

  68094 TSLM remote unmonut is not working.
  68259 need to support the READONLY access mode for all drive types
        Workaround: Use READWRITE setting in TSM
  68349 ermmTsmSync cannot read the message file (AIX only)
        Workaround : 
           chmod 755 /opt/IBM/ermm/lib/nls/ts_L10N
           chmod 444 /opt/IBM/ermm/lib/nls/ts_L10N/ts_en_us.pm
  ----- Unmount fails when the home slot of the mounted cartridge is
        occupied


#-----------------------------------------------------------------------
# 5. How to apply the fix pack
#-----------------------------------------------------------------------
This part is the description about fix pack in the Fix Central.
Get the tar.gz file of TSLM package from the Fix Central.

    1. Extract the tar.gz file to the local disk.
    2. Copy the following system packages in TSLM DVD to the
       corresponding subdirectories in the local disk:
            tslm/aix64/tslm64-system-1.3.2.x.bff
            tslm/linux64/tslm-system-1.3.2-x.x86_64.rpm
            Note: x is the component version of system package and
                  varies depending on TSLM version

    3. Updating TSLM Server.
        3-1. Stop all the applications that use TSLM.
        3-2. Stop the Library Managers and the Media Manager
        3-3. Uninstall TSLM Server component
             Notice) TSLM database MUST NOT be dropped.
                     Use -p option when using uninstall script.
             Detail information is described in "Uninstalling TSLM" of 
             Chapter 2 of TSLM User's Guide.
        3-4. Backup configuration files under /opt/IBM/ermm/conf 
             directory. 
        3-5. Install TSLM Server component
             Note: If your DB2 is on a remote z/OS, you need to install
                   TSLM server components manually.
                   The automatic installation script can NOT be used.
                   For manual installation, refer to the "Custom
                   installation" section in Chapter 2 of the TSLM User's
                   Guide.
                   For setting up the TSLM database on a remote DB2 on
                   z/OS, refer to Appendix B of the TSLM User's Guide.
        3-6. Restore the configuration files of the Library Managers
             from backed up files taken by step 3-3.
        3-7. Configuration file of the Media Manager (mm.xml) has been
             updated by this fix pack. Recreate mm.xml file using new
             mm.xml.smp file. 
        3-8. ermmCollectLogs.pl is a tool to collect trace files of TSLM
             for trouble shooting purpose. 
             ermmCollectLogs.pl has been updated by this fix pack. 
             Download this script from the Fix Central and place it to 
             /opt/IBM/ermm/bin directory.
             Information about ermmCollectLogs.pl is in 
             ermmCollectLogs.readme.txt under /opt/IBM/ermm/bin
             directory.

    4. Updating TSLM Client
      4-1. For AIX/Linux platforms
        4-1-1. Stop all the applications that use TSLM.
        4-1-2. Uninstall TSLM Client components.
               Use -p option when you uninstall TSLM with uninstallation
               script.
               Refer to the following section of the TSLM User's Guide
               for more details of uninstallation:
                   "Uninstalling TSLM" in Chapter 2
        4-1-3. (Optional) Backup configuration files under the following
               directory:
                   /opt/IBM/ermm/conf
                   /opt/IBM/ermm/client/tsm
                   /opt/IBM/ermm/client/3494 (when 3494 package is
                                              installed)
        4-1-4. Install TSLM Client components.
               Use the -c option (and also when necessary, the -e option)
               when you install TSLM with an installation script.
               Refer to the following sections in Chapter 2 of the TSLM
               User's Guide for more details of installation:
                   "Automatic installation on AIX and Linux platforms"
                   "Custom installation"
               Note: When you install TSLM with the installation script,
                     you will be asked if you like to use the existing
                     configuration files. Answer "yes" to these
                     questions if you like to continue to use the
                     configurations in the previous installation.
                     If you answer "no", new configuration files will be
                     created.

      4-2. For HP-UX/Solaris/Windows platforms
        4-2-1. Uninstall the client installation files on your system:
                 tslm.hdm
                 tslm.elm
                 tslm.cli
                 tslm.pwgen
               
        4-2-2. Install the client installation files in this package.
        
        For details about uninstalling and installing the installation
        files, see the "Custom installation" section in Chapter 2 of
        TSLM User's Guide. 

#-----------------------------------------------------------------------
# 6.  Prerequisite
#-----------------------------------------------------------------------
A TSLM Server needs the following version of IBM tape driver:

      AIX :   Atape     12.5.8.0 or later
      Linux:  lin_tape  2.3.0 or later

#-----------------------------------------------------------------------
# 7. ITDT for TS3500 shuttle discovery
#-----------------------------------------------------------------------
The IBM Tape Diagnostic Tool (ITDT) is an independent tool that
provides diagnostics on tape drives and libraries. 

The ITDT HDP Discover function scans the host for attached TS3500
devices and uses their data to discover the HD-P system. If it is
successful, it delivers two maps that represent the logical and
physical HD-P environment.

After the configuration of TS3500 Shuttle Complex, you need to verify
that ITDT HDP Discover function works correctly at TSLM server.

Example)
  itdt hdp discover -d /dev/IBMchanger0 -d /dev/IBMchanger1
  -d /dev/IBMchanger2  -d /dev/IBMchanger3

    where /dev/IBMchanger0, /dev/IBMchanger1, /dev/IBMchanger2 and
    /dev/IBMchanger3 are the device file name of the libraries connected
    by the Shuttle Complex.

The following trace log files will be created after running ITDT:

    - ibmscs.log
    - ibmscs.info
    - ibmscs.data

They are under /var/log on Linux and /var/adm/ras on AIX.
The owner of those files will be root user, then change the access
permissions so that TSLM can write log records to them.

    chmod 777 ibmscs.*


#-----------------------------------------------------------------------
# 8. Additional Information
#-----------------------------------------------------------------------
# 8.1 Additional explanations of TSLM messages

 1. EMM2903E

 EMM2903E:      Communication with library not possible errno(2):
                No such file or directory
 Explanation:   Communication between the Library Manager and the library 
                is not possible.
                Device file to SCSI Medium changer was not found.
 System action: Command execution fails.
 User response: Check the library manager configuration file of the
                target library. Verify that the library manager was
                configured with the existing device file to the SCSI media
                changer for the library. 
                Using persistent naming is recommended. Otherwise a device
                file name can change when reloading the tape device
                driver, restarting the host, or changing SAN
                configuration.
                              

 EMM2903E:      Communication with library not possible errno(5):
                Input/output error
 Explanation:   Communication between the Library Manager and the library 
                is not possible.
                Access to the library failed.
 System action: Command execution fails.
 User response: Ensure that there is no connection failure on the control 
                path to the target library. If there are multiple
                control paths, ensure that the tape driver is configured
                to use the control path failover function for them.
                If a TS3500 shuttle complex is being used, ensure that there 
                is no failure on it.
                              

 EMM2903E:      Communication with library not possible errno(13):
                Permission denied 
 Explanation:   Communication between the Library Manager and the library 
                is not possible.
                Access permission to IBM tape devices was denied.
 System action: Command execution fails.
 User response: Ensure that LM (user ermm) has the authority to obtain
                the special file names for IBM tape devices. Check the
                access permission to the IBM tape devices.


 2. EMM2914E

 EMM2914E       Library failure.
 Explanation:   An internal library error occurred.
 System action: Command execution fails.
 User response: Perform the recovery action in the following note, if
                applicable. Or, contact your TSLM administrator.

 Note: This error message might be shown if TSLM sends a request to a 
       library through a control path that becomes unavailable.
       For example, the control path can become unavailable when a 
       power-on reset of the controlling tape drive occurs. If a tape 
       cartridge is mounted in the tape drive, the volume information for 
       that cartridge might be lost from the TSLM server database. In 
       that case, any subsequent operations that use the cartridge will 
       fail. To recover the volume information and regain access to the 
       cartridge, perform following steps:

       1. Issue an audit command for the local library of the cartridge.
       2. Issue an lsdrive command, and verify that the cartridge is in
          the tape drive.
       3. Issue the following unmount command to unmount the cartridge
          from the specified tape drive:
            unmount -d <drive name>
       4. Issue the following lsslot command, then verify that the
          cartridge was moved to an internal slot:
            lsslot -pcl <cartridge PCL>


 3. EMM2909E and EMM2S01E

 EMM2909E             Destination location d_name is full.
 Explanation:         The drive where you want to mount a cartridge is
                      full.
                      The destination slot for the move operation is not
                      available because it is occupied by another
                      cartridge. Near this error message, 
                      another error message EMM2S01E can be seen that
                      shows a SCSI command error with 
                      sense key 0x5, ASC 0x3b and ASCQ 0xd
                      (Medium Destination Element Full).
 In the message text: 
   d_name    The drive name.
 System action:       Command execution fails.
 User response:       Check TSLM library inventory. Contact your TSLM
                      administrator.

 Note: This error message can be generated as a result of two or more 
 remote mount operations that are requested concurrently. In this case,
 TSLM tries the failed operation again to recover automatically, and 
 no user action is required.


# 8.2 Configuring device files for SCSI media changers on Linux platforms

Make sure that device files for SCSI media changers that provide access
to Library Managers for TSLM servers that run on Linux platforms are
properly configured. This configuration is critical for correct operation
of TSLM. This way, Library Managers can refer to the correct device
files needed to handle respective target libraries. The device files for
the SCSI media changers are configured with the Linux Tape and Medium
Changer Device Driver (lin_tape driver) and Linux udev service. The
following important information and example are provided to help avoid
configuration errors for the device files on Linux platforms.

 1. Using multiple control paths to a target library

 In most cases, a tape library has multiple tape drives, which can
 provide multiple control paths to the library through them. For higher
 availability, configure the tape library so that it has at least two 
 control paths.

 You must configure the lin_tape driver so that it can use the control 
 path failover (CPF) function for the multiple control paths. With the 
 CPF function, one of the control paths for the same SCSI media changer
 is used for primary control path. Any other control paths are each used 
 as an alternate path. This way, an application can continue to use the 
 same SCSI media changer by referring to a device file on one of the 
 control paths, even if the control path become unavailable. 

 Verify that the option setting "alternate_pathing=1" for the lin_tape
 driver CPF function is included in /etc/modprobe.conf or
 /etc/modprobe.conf.local (or, if you are running RHEL 6 or higher, a
 user-customized configuration file, for example 'lin_tape.conf', under
 the /etc/modprobe.d directory).

   options lin_tape alternate_pathing=1

 Note: if another option is set, each option must be separated with
       space characters. If you change the configuration file, you must
       reload the lin_tape driver, as in the following command sequence.

         lin_taped stop
         modprobe -r lin_tape
         depmod
         modprobe lin_tape
         lin_taped

 Also, verify that the primary and alternate control path can be 
 referenced in the /proc/scsi/IBMchanger file.

 When you create a Library Manager configuration file using the
 ermmLmConfig command, you must specify the device file on the primary
 control path for the SCSI media changer of the target library. Also, you
 must not create another configuration file for the same SCSI media
 changer specifying a different device file, because it can cause
 inconsistent configuration in the TSLM database.


 2. Using persistent names for the device files

 Once a Library Manager is configured, the device file for the target
 SCSI media changer is tied with the serial number for the device.
 However, the device file name for the SCSI media changer 
 (for example, /dev/IBMchanger0, /dev/IBMchanger1) might change when a 
 system restart, reload of the lin_tape driver, or changes in connected 
 devices occur, because detecting connected devices is not done with the 
 same sequence.
 
 Therefore, you must use persistent names for the device files to avoid
 this type of problem. Linux udev provides a dynamic device management 
 function. You can make symbolic links with persistent names to the 
 device files for the SCSI media changer by using a rule-based 
 configuration file for the udev.

 Before making the rules file, use the udevinfo command (RHEL5) or
 udevadm info command  (RHEL6/SLES11) to look into the serial numbers for 
 the devices that the udev handles.

 For example, for the /dev/IBMchanger0, execute the following command. 

 (RHEL5)
 udevinfo -a -p `udevinfo -q path -n /dev/IBMchanger0` | grep serial_num

 Here is the expected result:
 SYSFS{serial_num}=="0000078A03810403"

 (RHEL6/SLES11)
 udevadm info --attribute-walk --name /dev/IBMchanger0 | grep serial_num

 Here is the expected result:
 ATTR{serial_num}=="0000078A03810403"

 This next example shows a Linux host that detects two SCSI media changer 
 devices.
 Note: Each device file (/dev/IBMchanger0 and /dev/IBMchanger2) in the example 
 refers to the same SCSI media changer, but with different control paths.
 
 Device file        SCSI media changer serial number
 /dev/IBMchanger0   0000078A03810403
 /dev/IBMchanger1   0000078A03810405
 /dev/IBMchanger2   0000078A03810403


 For the preceding configuration, create a rules file '98-lin_tape.rules'
 under the /etc/udev/rules.d directory to describe the rules to make
 persistent names to corresponding serial numbers, which are checked
 as above.

 Describe one rule per line, to create a symbolic link (SYMLINK=="...") 
 for a device file (KERNEL=="...") that has a specific attribute (for
 example, SYSFS{serial_num}=="..."). Optionally, you can set the file
 attributes for owner (OWNER="..."), group (GROUP="..."), and access
 mode (MODE="...") to the device file. It is useful to ensure that the
 TSLM user 'ermm' can access to the devices.

 For the preceding example, plan to create symbolic links and a rule file
 that are similar to the following ones:

 Symbolic link with persistent name SCSI media changer serial number
 /dev/lin_tape/by-id/IBMchanger0    0000078A03810403
 /dev/lin_tape/by-id/IBMchanger1    0000078A03810405

 The rule file includes the following rules:

 KERNEL=="IBMchanger*", SYSFS{serial_num}=="0000078A03810403",
  SYMLINK="lin_tape/by-id/IBMchanger0" OWNER="root" GROUP="root"
  MODE="666"
 KERNEL=="IBMchanger*", SYSFS{serial_num}=="0000078A03810405",
  SYMLINK="lin_tape/by-id/IBMchanger1" OWNER="root" GROUP="root"
  MODE="666"

 Note: The preceding rules are actually to be described in two lines for
       respective symbolic links.

 Apply the rules by reloading the lin_tape driver.

 After that, issue the following command, and verify that the symbolic
 links are created based on the rules:

 ls -l /dev/lin_tape/by-id/

 The expected result is like this:
 lrwxrwxrwx 1 root root 17 Oct 24 22:18 IBMchanger0 -> ../../IBMchanger0
 lrwxrwxrwx 1 root root 17 Oct 24 22:18 IBMchanger1 -> ../../IBMchanger1

 When you change the rules file later on, you can apply the change by
 following command execution sequence:

 (RHEL5)
 udevcontrol reload_rules
 udevtrigger

 (RHEL6/SLES11)
 udevadm control --reload-rules
 udevadm trigger

 When you configure a Library Manager, use the persistent names for the
 symbolic links (for example, /dev/lin_tape/by-id/IBMchanger0)

 Note: Currently, TSLM can support persistent names only for SCSI media 
       changers, which will be referred by Library Managers on the
       TSLM server. For tape drives, a TSLM client does not support
       persistent names, which will be referred by the Host Drive Manager
       (HDM). Every time HDM restarts, it collects available tape drives
       (for example, /dev/IBMtape0, /dev/IBMtape1,) on the TSLM client
       host. You can see the /opt/IBM/ermm/conf/hdmdrive.cfg file, which
       is generated at HDM restart time. The tape drive configuration
       is sent to the Media Manager on the TSLM server. An impact is
       that any obsolete Drive Manager definitions remain if the tape
       device file name is changed on the TSLM client side.



# 8.3 3494 Emulation

 1. Mount JA cartridge into TS1140 (JAG4) drives using 3494 emulation

 'readonlyCartridge' parameter in ermm3494.cfg

 This parameter can take values of 'true' or 'false'. 
 Set 'readonlyCartridge=true' to use the JA cartridges on the TS1140
 drives.
 The cartridges that TSLM can mount for each parameter are as shown
 here:

   1) 'readonlyCartridge=true'
    1-1) TS1150 Tape Drive:
      JK, JC, JY, JL, JD, JZ
    1-2) TS1140 Tape Drive:
      JJ, JR, JA, JW, JB, JX, JK, JC, JY
    1-3) TS1130 Tape Drive
      JJ, JR, JA, JW, JB, JX,
    1-4) TS1120 Tape Drive
      JJ, JR, JA, JW, JB, JX,
    1-5) 3594J1A Tape Drive
      JJ, JR, JA, JW

   2) 'readonlyCartridge=false' or no specification
    2-1) TS1150 Tape Drive:
      JK, JC, JY, JL, JD, JZ    
    2-2) TS1140 Tape Drive:
      JB, JX, JK, JC, JY
    2-3) TS1130 Tape Drive
      JJ, JR, JA, JW, JB, JX,
    2-4) TS1120 Tape Drive
      JJ, JR, JA, JW, JB, JX,
    2-5) 3594J1A Tape Drive
      JJ, JR, JA, JW


 2. VOLSER Status mode using 3494 emulation

 'volserExMode=true' parameter in ermm3494.cfg configuration file

 The function of the Mounted VOLSER in the Device Data Message (Message
 type is X'06') can be changed by this parameter.
 For instance, the '-qD' option in mtlib command provides the Device Data 
 information that is shown in the following example: 
 (This example shows the information that is listed while a cartridge is
 fully mounted.)

 monnaka:/home/kurobe777/WGTEST # mtlib -l tsukiji -x 00933970 -qD

 Device Data:
    mounted volser.............310001
    mounted category...........FF00
    device category............0000
    device state...............Device installed in Library.
                               Device available to Library.
                               Volume is loaded.
                               ACL is installed.
                               Auto Fill is enabled.
    device class...............3592-E05
    extended device status.....00

 In this request command, the mounted volser value is provided only
 if the cartridge has been loaded completely.
 With the default setting, no volser value is indicated 
 when in the loading, unloading, or unloaded state.

 By specifying 'volserExMode=true' in the ermm3494.cfg configuration
 file for the 3494 emulation, the 3494 emulation shows the mounted
 volser value when in the loading, unloading or loaded states.
 
 Therefore, if the drive is in a cartridge loading state or a cartridge 
 unloading state, the request of the device data will be shown as 
 presented in the following example:
 (No "Volume is loaded" message is indicated.)

 monnaka:/home/kurobe777/WGTEST # mtlib -l tsukiji -x 00933970 -qD

 Device Data:
    mounted volser.............310001
    mounted category...........FF00
    device category............0000
    device state...............Device installed in Library.
                               Device available to Library.
                               ACL is installed.
                               Auto Fill is enabled.
    device class...............3592-E05
    extended device status.....00


 3. Limitations in the 3494 emulation

  1) Use of mtlib command 
    Some of the mtlib command options are not supported due to a 
    limitation of the TSLM 3494 emulation.
      - Query library information for Library data (-qL)
        Note: Output is shown, however, some of the library data 
        might not reflect the actual current library configuration.
      - Query library information for Statistical data (-qS)
        Note: Output is shown, however, some of the statistical data 
        might not reflect the actual current library status.
      - Query library information for Reserved Category List (-qR)
      - Query library information for Category Attribute List (-qA)
      - Cancel pending request option (-c)

  2) Setting up drive configuration
    Make sure that the Host Device Manager is restarted for the target
    tape drives and connects to the Media Manager successfully as a
    preparation, before restarting the lmcpd daemon on the client.
    It should be confirmed, because the lmcpd queries tape drive
    configuration settings and caches them just after connecting to the 
    TSLM 3494 Emulation. So, if drive configuration is changed by adding 
    or deleting drives, you need to restart the Host Device Manager and 
    the lmcpd daemon again.

  3) Use of TS3500 Shuttle Complex
    TSLM 3494 Emulation can be used with TS3500 Shuttle Complex
    environment. Since mounting and unmounting tape cartridges is done
    with specified tape drives, you must check each tape drive devnum and
    location (local or remote) in advance manually. Then, you must select
    a suitable tape drive for the operation to optimize performance by
    considering the case where the cartridge is moved across the Shuttle
    Connection.


# 8.4 Force-cancel for mount task in progress

When you cancel a mount task that is in progress by using the TSLM CLI
'cancel task_ID' command forcibly, you must execute the 'audit' command
to the corresponding library after the cancel is completed. This 'audit'
command maintains a consistent database. 
Also, check the status of any corresponding tape cartridges by using the
'lscart' and the 'lsslot' commands.

The cancel command can be used only for tasks that are in a "blocked"
state.

For more information about TSLM CLI commands, see the TSLM User's
Guide - "Chapter 6. Command Line Interface (CLI)".


# 8.5 "Appendix E. Running dual TSLM servers on one TSLM client" in the
      TSLM User's Guide

Consider the example procedure provided in step 4 (from the steps to run
another HDM process on one TSLM client):

 4. Configure the secondary HDM configuration file. The name of the file
 is composed of the following string of characters (where "+" indicates
 concatenation): "genhdm.cfg" + "." + "ermmGenHDM_" followed by the name
 chosen in step 1. For example:

  # cd /opt/IBM/ermm/conf
  # vi genhdm.cfg.ermmGenHDM_tsukiji

In the preceding example, the scratch file
'genhdm.cfg.ermmGenHDM_tsukiji' is created. If wanted, one could also
use the 'genhdm.cfg' file as a template, as shown in the following
example procedure: 

 # cd /opt/IBM/ermm/conf
 # cp genhdm.cfg genhdm.cfg.ermmGenHDM_tsukiji
 # vi genhdm.cfg.ermmGenHDM_tsukiji

After either procedure, the secondary HDM configuration file must be
edited, primarily the following parameters:

 #
 # IP address of TSLM MediaManager host
 #
 server = <IP address of secondary TSLM server>
 .
 .
 .
 #
 # Name of logfile
 # For Windows operating systems this parameter is not applicable.
 # (the Windows environment variable IBMHDMLOGFILE is used instead).
 #

 logfile = /opt/IBM/ermm/log/ermmGenHDM_<name decided in step 1>.log

Notes: 
For RHEL 6 systems, you must create configuration files on the
 /etc/init directory instead of /etc/inittab. Follow these steps as a guide:

1) Create a configuration file that is named /etc/init/hdm.conf to
start the Host Driver Manager configured with /opt/IBM/ermm/conf/genhdm.cfg .
Here is an example of the file:

# hdm - tslm host drive manager
start on stopped rc RUNLEVEL=[2345]
stop on starting rc RUNLEVEL=[!2345]
respawn
exec /opt/IBM/ermm/bin/ermmGenHDM

2) Create a configuration file (named as /etc/init/hdm_tsukiji.conf) to start
the Host Driver Manager configured with /opt/IBM/ermm/conf/genhdm.ermmGenHDM_tsukiji.cfg .
Here is an example of the file:

# hdm - tslm host drive manager
start on stopped rc RUNLEVEL=[2345]
stop on starting rc RUNLEVEL=[!2345]
respawn
exec /opt/IBM/ermm/bin/ermmGenHDM_tsukiji

3) Make sure that the configuration files that you created in the
      preceding steps are not executable. Here is an example of valid
      file permission settings:

       -rw-r--r-- 1 root root 80 Jul 24 13:21 hdm.conf
       -rw-r--r-- 1 root root 78 Jul 24 13:20 hdm_tsukiji.conf


# 8.6 Moving a cartridge between libraries with the 'move' command

When you execute the TSLM CLI 'move' command to move a cartridge between
libraries that are connected by a shuttle connection, error EMM2909E is
generated when the destination slot is already occupied by another
cartridge.

For example:

 ermmtool> move -pcl CART1 -lib DEST_LIB -toslot DEST_SLOT
 EMM2909E: Destination location DEST_SLOT is full. 3584 sense data:

where CART1, DEST_LIB, and DEST_SLOT are the actual names of the
cartridge label, destination library, and destination slot,
respectively.

Recover from this type of error situation by following these steps:

 1. Issue the following lsslot command to check where the cartridge is
    located:

     ermmtool> lsslot -pcl CART1

    The following error message is expected as a result:
    EMM7009I: No matching records found.

 2. Issue the audit command for the source library:

     ermmtool> audit SRC_LIB

    where SRC_LIB is the actual name of the source library.

 3. Issue the audit for the destination library:

     ermmtool> audit DEST_LIB

 4. Issue the following lsslot command to check where the cartridge is
    located:

     ermmtool> lsslot -pcl CART1

 5. At this time, the cartridge is expected in a slot in the CMC
    slotgroup.

    Note: CMC is the slotgroup for the slots that are assigned to the
          shuttle station.

    To avoid blocking shuttle station use, you must move the cartridge
    to an available location.
    Issue the following move command to move the cartridge to an
    internal slot:

     ermmtool> move -pcl CART1 -tosg internal

 6. Issue the following lsslot command to list the slot where the
    cartridge was moved:

     ermmtool> lsslot -pcl CART1


# 8.7 How to update a TSLM configuration when the number of slots in a 
      connected library is changed.

The following procedures describe how to correctly update the TSLM
configuration when expanding a TS3500 library (a), and when 
increasing (b) or decreasing (c) the value of the maximum 
number of cartridges in a logical TS3500 library.
  
 a. Procedure when expanding a TS3500 library
 
    Add a new library manager when you add expansion frames to a
    library. See "Configuring and starting the Library Manager (LM)"
    in chapter 4 of the TSLM User's Guide. Also see
    "Changing tape resources in a tape library connected to TSLM"
    and "Adding a TS3500 Tape Library" in chapter 7 of the guide.

 b. Procedure when increasing the value of maximum number of cartridges
    in a library
 
    Run the 'lsslot' command to verify slot configuration, then run the
    'audit' command. Run the 'lsslot' command to verify slot
    configuration again.

 c. Procedure when decreasing a value of maximum number of cartridges
    in a library

    This procedure requires stopping all other operations related to
    this logical library. However, TSLM processes do not need to stop,
    and cartridge and volume information is not affected.
    
    For this procedure, TSLM requires the 'rmslot' command to remove all
    of the current slot entries at once.
    After the value is decreased, execute the 'audit' command.

    Use the 'lsslot' command to verify slot configuration before and after
    executing the 'rmslot' and the 'audit' command.

    Important note: DO NOT USE the 'rmlm' AND 'rmlib' commands to
    remove the remaining slot entries. Otherwise, an unstable situation
    can occur when the same library and the same library manager are
    re-created later for the library that was removed previously by
    those commands. For example, loss of cartridge and volume
    information occurs in the re-created library. In that case, the
    TSLM user must restart TSLM processes (both Media Manager and
    Library Manager) to clean up the unstable state in the processes.


# 8.8 Regular expressions option of TSLM CLI commands

Some TSLM CLI commands have a regular expressions option (-regex) to
specify pattern matching expressions to select multiple objects at once.
The grammar of the regular expression in TSLM is based on the ICU
Regular Expressions engine.
(See http://userguide.icu-project.org/strings/regexp)

Note: These TSLM CLI commands have the -regex option:
      chcart, chcg, chdrive, lscart, lsmess, lsvol, rmai, rmapp, rmdm,
      rmlm, rmslot



# 8.9 Mixing drive device types in a single library has limitations
TS1150 tape drive type supports the following cartridge media types and Gen5 format newly.
There are some limitations of TS1150 in case of mixing drive device types in a single library
as same as TS1140.
The detail information how to configure the TSLM in case of these mixing drive configurations is 
described at "Mixing drive device types in a single library has limitations" at Chapter 9
in TSLM User's Guide.

TS1150 Tape Drive
JJ/JR    N/A
JA/JW   N/A
JB/JX   N/A
JK        Capacity=500GB, Performance=250MBps, Read/Write Support (Format Generation=Gen4)
JK        Capacity=900GB, Performance=300MBps, Read/Write Support (Format Generation=Gen5)
JC/JY   Capacity=4TB, Performance=250MBps, Read/Write Support (Format Generation=Gen4)
JC/JY   Capacity=7TB, Performance=300MBps, Read/Write Support (Format Generation=Gen5)
JL        Capacity=2TB, Performance=360MBps, Read/Write Support (Format Generation=Gen5)
JD/JZ   Capacity=10TB, Performance=360MBps, Read/Write Support (Format Generation=Gen5)

Where, Gen5: 3592 E08 format.

# 8.10 mm.xml must be updated before new types of cartridges (JD, JL or JZ) are inserted
The previous version of mm.xml does not include the description of JD, JL and JZ types of cartridges.
Therefore, mm.xml must be updated before new types of cartridges are inserted.
Otherwise, the type of the new cartridges can be assigned to a different type.
(It can be checked by 'lscart' command.)
If an audit operation with new cartridges is executed without updating mm.xml mistakenly,
Cartridge information of new type of cartridges must be removed by 'rmcart' command once
after restarting Media Manager with new mm.xml.

# 8.11 HDM must be updated before the server for the HDM recognizes TS1150 drives
The previous version of HDM does not work on the server that recognizes TS1150 drives.
Therefore, HDM must be updated before the server for the HDM recognizes TS1150 drives.

# 8.12 ermmTsmSync script must be run while no TSM jobs are running
ermmTsmSync script refers information of a TSM volume history and it's updated
when the TSM job is completed.
Therefore, the execution of ermmTsmSync script while some TSM jobs are running 
can be a cause of volume inconsistence between TSM and TSLM.

# 8.13 Configuration of the CLI on Windows platform
In order to modify the configuration of TSLM CLI (ermmtool), 
please modify C:\Program Files\IBM\ermm\conf\ermmcli.conf file.
Also, the directory of the configuration file is specified by an environment value 'IBMCLICONFIGFILE' 
and it's set to 'C:\Program Files\IBM\ermm\conf' directory as the default value.





#-----------------------------------------------------------------------
# 9. Notices and Trademarks
#-----------------------------------------------------------------------

# 9.1 Trademarks

IBM and AIX are trademarks of International 
Business Machines Corporation in the United States, other countries,
or both.

Linux is a trademark of Linus Torvalds in the United States, other
countries, or both.

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


#-----------------------------------------------------------------------
                   ### End of README ###