/
/ $Header: rdbms/src/server/psm/scripts/ASRU/README /main/2 2010/06/09 15:49:32 pbagal Exp $
/
/ README_ASRU
/
/ Copyright (c) 2010, Oracle. All Rights Reserved.
/
/   NAME
/     README_ASRU - README file for ASRU utility
/
/   DESCRIPTION
/     README file for ASRU utility
/
/   NOTES
/   
/
/   MODIFIED   (MM/DD/YY)
/   pbagal      05/28/10 - Change readme comments
/   canuprem    04/09/10 - Creation
/

  README for the ASM Storage Reclamation Utility Version 1.1

Table of Contents
=================
1. Description of files.
2. Environment settings.
3. Usage.
4: Known issues.

1. Description of files :
=========================

  This package contains three files other than the README namely ASRU, ASRU.pl 
  and zerofill. All these files should be in same directory.

  ASRU is a shell script wrapper for ASRU.pl. It calls ASRU.pl with appropriate
  arguements.

  ASRU.pl has the code that does the necessary actions to reclaim the allocated
  but unused space. It calls the zerofill script with appropriate arguements
  appended.

  zerofill script takes the power, name of the disks and ranges to be zeroed as
  arguements. It writes zeroes using the 'dd' command. This script can be
  customized.

2. Environment settings :
=========================

  The ASRU utility needs an ASM instance to be up . The ORACLE_SID and 
  ORACLE_HOME environmental variables have to be set appropriately before 
  executing the ASRU utility.

3. Usage :
===========
  
  Unzip the package and place all the three files in the same directory. 
  Execute 'ASRU --help' for the help message and usage.

4. Known issues:
================

4.a: ASRU fails to shrink the disks

    OVERVIEW

    ASRU will fail to reclaim deallocated space as expected. The cause of the
    failure is associated with an Oracle bug that is triggered by the ASRU
    script during the resize operation of the ASRU script. The bug does not
    cause the database/ASM instance to crash or lead to data corruption. The
    effect of the failure is that ASRU does not perform its intended
    operation.   

    BUG DESCRIPTION

    As part of shrinking the disk, ASM was not ignoring the allocated space
    set aside for the allocation tables that are created for strides. ASM
    creates an allocation table for every stride. For Disk Groups where the
    Allocation Unit size is 1MB, the stride size is 113GB. For every 113GB ASM
    creates an allocation table. As part of shrink operation, if the new size
    requires ASM to cross a stride boundary, the final validation verifying
    that all extents have been moved out correctly, ASM  would incorrectly
    assumed that there were still allocated extents. 


    CONFIGURATIONS AFFECTED

    The environmental scenario likely to trigger the failure is;
       - ASRU executed on a Disk Group consisting of LUNs greater 113 GB and
         having using an AU size of 1 MB. 
       - Sufficient deleted space being recovered that leads to the disks
         being resize past a multiple of the 113GB stride size. 
       - Oracle ASM release level prior to 11.2.0.2

    Other possible scenarios can trigger the bug where different AU sizes are
    used for the Disk Group, but the above conditions will be the most common
    conditions to trigger the bug. 

    INTERNAL FIX DESCRIPTION

    The validation was updated to ignore the AU's that are allocated for the
    physical metadata at the stride boundary when shrinking the disks.  

    PATCH INFORMATION

    Oracle customer support will provide a patch for the operating environment
    if the above conditions could affect the customer. The customer should call
    Oracle support and request an one-off patch for Bug 9523606. Support will
    require operating system type, release level, and Oracle release level to
    generate the patch.   

4b. Bug Fixes 

    1. ASRU can be executed from any directory using absolute path.
    2. The disk are resized to the nearest integral multiple of AU
       in case the AU size is not 1MB.
    3. ASRU does not hang if the ASM_POWER_LIMIT has been set to zero.
    4. Manual resize operation during the execution of ASRU has been disallowed.
    
