cancel
Showing results for 
Search instead for 
Did you mean: 
cancel
Announcements

ACS 5.x: How to generate Support Bundle

14329
Views
10
Helpful
0
Comments

 

 

Introduction

 

The purpose of this document is to provide step by step procedure on how to generate support bundle from Cisco Access Control System (ACS) 5.x versions.

 

Background

 

There are times when you are not able to figure out what is going on with a particular authentication request on the ACS or you want to dig deeper to find out how ACS is internally processing the requests. Most often you are required to generate a support bundle from the ACS 5.x (similar to package.cab from ACS 4.x). This support bundle has all the low level/ tac troubleshooting level logs.

 

Step by Step Procedure

 

Steps to generate support bundle from ACS 5.x:

 

Step 1 Use any SSH client and start an SSH session that supports SSH v2.

 

Step 2 Enter the ACS hostname/IP address, ACS CLI username (acsadmin is default), port number (22), and authentication method (SSHv2). Then enter the password for the ACS CLI user.

The ACS prompt acs/admin# appears. You can now enter ACS CLI commands.

 

Step 3 Create a repository on ACS that points to an FTP server in the local subnet of the ACS.

This will be used by ACS to put the support bundle contents on the FTP server.

    acs/admin# configure

    acs/admin(config)# repository MYREPOSITORY

    "MYREPOSITORY" is a locally significant name that you want to give to the repository.

    acs/admin(config-Repository)# url ftp://tac.test.com/repository/system1

    "ftp://tac.test.com/repository/system1" the ftp path, you can use the ip address (instead of the dns name) of the local FTP server as well, like "ftp://10.10.10.1/"

    acs/admin(config-Repository)# user ftpuser password plain ftp-password

    ftpuser and ftp-password are the username and password required to connect to the local FTP server specified in previous command.

    acs/admin(config-Repository)# exit

    acs/admin(config)# exit

    acs/admin# show repository MYREPOSITORY

    This will show the contents of the FTP server home directory and verify that the newly created repository is reachable.

 

Step 4 Enter into the ACS Configuration mode, here you must supply the username and the password that you use to log in to the ACS web interface. The default username and password to access the ACS web interface are acsadmin and default, and the first time you log in to the web interface, you will be prompted to change the default password.

    acs/admin# acs-config

    Escape character is CNTL/D.

    Username: acsadmin

    Password:

    acs/admin(config-acs)#

 

Step 5 Set the desired ACS logs to debug level.

e.g.

    acs/admin(config-acs)# debug-adclient enable

    acs/admin(config-acs)# debug-log runtime level debug

    acs/admin(config-acs)# debug-log mgmt level debug

 

Step 6 At this point, we need to duplicate the issue, do whatever is causing the problem, or wait for the problem to occur again if it's not triggered by a direct sequence of events.  Once that's done, we need to gather the verbose logs created.

 

Step 7 Generate a support bundle. (Follow the instructions below only AFTER the problem has been recreated at previous step)

    acs/admin(config-acs)# exit

    For ACS 5.0 or 5.1:

    acs/admin# acs support TACBUNDLE repository MYREPOSITORY include-cores 5 include-debug-logs 5 include-local-logs 5 include-system-logs 5 include-logs 5 all-categories

    For ACS 5.2 or 5.3:

    acs/admin# acs support TACBUNDLE repository MYREPOSITORY encryption-passphrase null include-cores 5 include-debug-logs 5 include-local-logs 5 include-system-logs 5 include-logs 5 all-categories

 

    This will generate a support bundle named TACBUNDLE.tar.gz and put it on the FTP server's home directory. You can modify the number of logs from 5 to any number of files you feel would include the logs covering the occurance of the problem.

    Note: If you are running ACS version 5.2.x, then go to Step 9.

 

Step 8 [Only if you are running ACS 5.0 or 5.1] Decrypt the support bundle that you just created.

    acs/admin# acs-config

    Escape character is CNTL/D.

    Username: acsadmin

    Password:

    acs/admin(config-acs)# decrypt-support-bundle MYREPOSITORY TACBUNDLE.tar.gz

    Decrypting Support Bundle...

    Repository: MYREPOSITORY

    Support Bundle: TACBUNDLE.tar.gz

    Decryption completed successfully - decrypted bundle: dec_xxxxx.tar.gz is located on your repositry.

 

    Note: You will have to upload the decrypted bundle dec_xxxxx.tar.gz at next step.

 

Step 9 (Optional) Upload the support bundle / decrypted bundle generated at Step 7/8 to the TAC case for the TAC engineer to view the support bundle.

 

CCO Case Query tool:

http://tools.cisco.com/ServiceRequestTool/query/QueryMainPageAction.do

 

Support Bundle Directory Structure

 

File Structure

DIRECTORY/FILE NAME     DESCRIPTION
~~~~~~~~~~~~~~~~~~~     ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
./logs                            Top level log directory.  Contains local logs and a
                                       sub directory for debug logs.


./logs/systemLogs         Appliance syslog and third party logs.


./logs/debugLogs           ACS program debug logs.


./logs/localLogs             ACS local logs.  These are logs that store customer
                                  operational data.  This data is normally stored in
                                  the monitoring and reporting database, however
                                  customers may choose to log this data to local
                                  files.


./database                   This is an export of the ACS configuration database
                                  It will contain all ACS configuration except the
                                  sensitive data (credentials).  If the user wishes
                                  to also dump credentials as part of the support bundle,
                                  they may choose to do so with the 'include-config-db'
                                  option.  Giving the 'include-config-db' option will
                                  also export sensitive data to the ./database dir.


./core                          May contain core files and Java core description
                                  files.  Will also contain a generated core-image
                                  of the currently running runtime process. This image
                                  is generated using the 'gcore' program.


./view                            Top level directory for monitoring and reporting
                                  support information.


./view/conf                 Monitoring and Reporting configuration files


./view/avreports          Monitoring and Reporting reporting engine logs


./view/dbdump           Monitoring and Reporting database dump.  Contains
                                  scripts that may be used to import the data that
                                  has been exported in this bundle.  See 'IMPORTING
                                  MONITORING AND REPORTING DATA' section below for
                                  more details.


running-config          The running OS configuration of the ACS appliance


startup-config          The startup OS configuration of the ACS appliance

 

tech-support            General tech-support data on the running system

 

version                 ACS Version information

 

 

Detailed Explanation of ACS Support Options

 

Listed below are the acs support options as listed in the CLI help:
  description         Add text between quotes to be saved as a README file
  include-cores       Include core files
  include-db   Include the configuration database, original or secure
  include-debug-logs  Include debug logs
  include-local-logs  Include local logs
  include-logs        Include logs
  include-system-logs Include system logs

 

Each one of these options will be described below in the order they
are listed in the CLI.
  * 'description description_text'
    This is a simple text description of the support bundle. The description
    is inserted in the README.txt file.  This feature allows the operator
    that run the 'acs support' to associate a description to a bundle that
    may be referenced at a later date. The Description must be surrounded by
    double quotes if it contains any spaces.

 

  * 'include-cores number_of_days'
    The default behavior is to exclude all core files.
    The 'include-cores' option requires a numerical option that
    specifies the number of recent days core files were generated.
    For example, 'include-cores 3' would include all core files were generated
    during the last 3 days. If user specifies 'include-cores 0', then no
    core files would be included, including the runtime process image-core
    (core/runtime-stack.pid).
    This file is generated using gcore from the existing runtime process
    and included whenever recent_days is > 0.

 

  * 'include-db <original | secure>'
    This option allows the user to include the full ACS configuration
    database, which includes user credential information, by specifying 'original'.
    For database that does NOT include credential information, user has to specify 'secure'.
    By default the ACS configuration is not part of the support bundle.

 

  * 'include-debug-logs number_of_days'
    This option allows the user to specify how many days of debug logs to
    include in the support bundle.  The default is to include all debug
    logs.  If the user would like to exclude debug-logs completely, they
    may provide 0 for the number_of_days.

 

  * 'include-local-logs number_of_logs'
    This option allows the user to also include local logs.  Local logs are
    not included by default.  The term 'local logs' is used to describe the
    logs that store customer operational data.  This data is normally stored
    in the monitoring and reporting database, however customers may choose
    to log this data to local files. The 'number_of_logs' argument indicates
    the number of rotated logs to be packaged in the bundle. The logs are
    packaged in order they are rotated with the most recently logs packaged
    first.  For example, assume there are 7 rotated logs on the system and
    the user specifies 'include-local-logs 3' in the support bundle CLI,
    then only the last three rotated logs are packaged in the bundle.

 

  * 'include-logs number_of_days'
    This option allows the user to specify how many days of operational
    data from the monitoring and reporting database to include in the bundle.
    The default is 2 days.  The maximum is 1 year, or 365 days.  If the user
    chooses to exclude operational data completely, they may choose to give
    0 as the number of days.  Hence 'include-logs 0' would override the
    default behavior (of 2 days), and exclude all operational monitoring
    and reporting data from the support bundle.

 

    When specifying the 'include-logs number_of_days' option, the user
    will be prompted to specify what log categories to include in the
    bundle.  They can choose 'all-categories' for all log categories,
    or they may choose one or more of the following log categories:
      aaa-accounting        Include AAA Accounting data
      aaa-audit             Include AAA Auditing data
      aaa-diagnostics       Include AAA diagnostic data
      administrative-audit  Include Administrative Auditing data
      system-diagnostics    Include Systems diagnostic data

 

  * 'include-system-logs number_of_logs'
    The term 'system logs' is used to describe the ACS third party logs,
    it includes appliance syslog as well as apache (catalina.out) and monit logs and more.
    By default the recent log of each system logs is included in the support bundle.
    The most recent catalina log includes a stack trace of the management
    proces generated using the kill -quit signal.
    The 'number_of_logs' argument indicates the number of rotated logs
    to be packaged in the bundle. By default, 'number_of_logs' is 1.

 

Importing Log Data into the Monitoring and Reporting Database


  If the support bundle was downloaded through the GUI, the tag.gz file should be copied to
  an ACS machine (root mode only) and the folders should be extracted.
  And then follow the instructions below to import log data into the
  monitoring and reporting database.
  The monitoring and reporting database is exported into the
  'view/dbdump' directory.  As part of this export there are two scripts
  created that allow the user to import the database that was exported.

 

    * reload-config-tables.sh (Imports the configuration tables)
    * reload-operations-tables.sh (Imports the operational data tables)

 

  When running either of these scripts, the user will be warned that they
  may be overwriting the existing data. They will be given the opportunity
  to abort out if this is not desired.

 

  If the user intends on just importing configuration data, then he/she only
  needs to run the 'reload-config-tables.sh' script.  If the user wishes to
  import the operational data, then he/she should run
  'reload-operations-tables.sh'. If the user wishes to import both
  configuration and operational data, then he/she can run both scripts.
  It is highly advisable if the user runs both scripts, that they run
  'reload-operations-tables.sh' first, then run 'reload-config-tables.sh'.
  The reason for this is when running the 'reload-operations-tables.sh'
  script, there is an option to purge all existing data before importing.
  Doing so will insure aggregation is correct, however doing so will also
  purge any configuration tables.  Hence, it's importing to run
  'reload-config-tables.sh' after running 'reload-operations-tables'.

 

  Another item worth mentioning is the operational data aggregation.
  If the user runs reload-operations-tables.sh script, the data will be
  aggregated for the complete year.  This is done to avoid inconsistency
  between the day tables and the aggregated month tables.

 

  Running either of the two scripts is self explanatory.  There are no
  required arguments, and any input required by the user is prompted for
  with detailed help.

 

References

 

 

Downloading ACS Support Bundles for Diagnostic Information

 

http://www.cisco.com/en/US/docs/net_mgmt/cisco_secure_access_control_system/5.3/user/guide/viewer_troubleshooting_ps9911_TSD_Products_User_Guide_Chapter.html#wp1057492

 

DIRECTORY/FILE NAME     DESCRIPTION
~~~~~~~~~~~~~~~~~~~     ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
./logs                  Top level log directory.  Contains local logs and a
                        sub directory for debug logs.
./logs/systemLogs       Appliance syslog and third party logs.
./logs/debugLogs        ACS program debug logs.
./logs/localLogs        ACS local logs.  These are logs that store customer
                        operational data.  This data is normally stored in
                        the monitoring and reporting database, however
                        customers may choose to log this data to local
                        files.
./database              This is an export of the ACS configuration database
                        It will contain all ACS configuration except the
                        sensitive data (credentials).  If the user wishes
                        to also dump credentials as part of the support  bundle,
                        they may choose to do so with the 'include-config-db'
                        option.  Giving the 'include-config-db' option will
                        also export sensitive data to the ./database dir.
./core                  May contain core files and Java core description
                        files.  Will also contain a generated core-image
                        of the currently running runtime process. This  image
                        is generated using the 'gcore' program.
./view                  Top level directory for monitoring and reporting
                        support information.
./view/conf             Monitoring and Reporting configuration files
./view/avreports        Monitoring and Reporting reporting engine logs
./view/dbdump           Monitoring and Reporting database dump.  Contains
                        scripts that may be used to import the data that
                        has been exported in this bundle.  See 'IMPORTING
                        MONITORING AND REPORTING DATA' section below for
                        more details.
running-config          The running OS configuration of the ACS appliance
startup-config          The startup OS configuration of the ACS appliance
tech-support            General tech-support data on the running system
version                 ACS Version information
README.txt              This file

SECTION 2) DETAILED EXPLANATION OF ACS SUPPORT OPTIONS

Listed below are the acs support options as listed in the CLI help:
  description         Add text between quotes to be saved as a README file
  include-cores       Include core files
  include-db   Include the configuration database, original or secure
  include-debug-logs  Include debug logs
  include-local-logs  Include local logs
  include-logs        Include logs
  include-system-logs Include system logs

Each one of these options will be described below in the order they
are listed in the CLI.
  * 'description description_text'
    This is a simple text description of the support bundle. The  description
    is inserted in the README.txt file.  This feature allows the operator
    that run the 'acs support' to associate a description to a bundle that
    may be referenced at a later date. The Description must be  surrounded by
    double quotes if it contains any spaces.

  * 'include-cores number_of_days'
    The default behavior is to exclude all core files.
    The 'include-cores' option requires a numerical option that
    specifies the number of recent days core files were generated.
    For example, 'include-cores 3' would include all core files were  generated
    during the last 3 days. If user specifies 'include-cores 0', then no
    core files would be included, including the runtime process image-core
    (core/runtime-stack.pid).
    This file is generated using gcore from the existing runtime process
    and included whenever recent_days is > 0.

  * 'include-db <original | secure>'
    This option allows the user to include the full ACS configuration
    database, which includes user credential information, by specifying  'original'.
    For database that does NOT include credential information, user has  to specify 'secure'.
    By default the ACS configuration is not part of the support bundle.

  * 'include-debug-logs number_of_days'
    This option allows the user to specify how many days of debug logs to
    include in the support bundle.  The default is to include all debug
    logs.  If the user would like to exclude debug-logs completely, they
    may provide 0 for the number_of_days.

  * 'include-local-logs number_of_logs'
    This option allows the user to also include local logs.  Local logs are
    not included by default.  The term 'local logs' is used to describe the
    logs that store customer operational data.  This data is normally  stored
    in the monitoring and reporting database, however customers may choose
    to log this data to local files. The 'number_of_logs' argument  indicates
    the number of rotated logs to be packaged in the bundle. The logs are
    packaged in order they are rotated with the most recently logs  packaged
    first.  For example, assume there are 7 rotated logs on the system and
    the user specifies 'include-local-logs 3' in the support bundle CLI,
    then only the last three rotated logs are packaged in the bundle.

  * 'include-logs number_of_days'
    This option allows the user to specify how many days of operational
    data from the monitoring and reporting database to include in the  bundle.
    The default is 2 days.  The maximum is 1 year, or 365 days.  If the  user
    chooses to exclude operational data completely, they may choose to give
    0 as the number of days.  Hence 'include-logs 0' would override the
    default behavior (of 2 days), and exclude all operational monitoring
    and reporting data from the support bundle.

    When specifying the 'include-logs number_of_days' option, the user
    will be prompted to specify what log categories to include in the
    bundle.  They can choose 'all-categories' for all log categories,
    or they may choose one or more of the following log categories:
      aaa-accounting        Include AAA Accounting data
      aaa-audit             Include AAA Auditing data
      aaa-diagnostics       Include AAA diagnostic data
      administrative-audit  Include Administrative Auditing data
      system-diagnostics    Include Systems diagnostic data

  * 'include-system-logs number_of_logs'
    The term 'system logs' is used to describe the ACS third party logs,
    it includes appliance syslog as well as apache (catalina.out) and  monit logs and more.
    By default the recent log of each system logs is included in the  support bundle.
    The most recent catalina log includes a stack trace of the management
    proces generated using the kill -quit signal.
    The 'number_of_logs' argument indicates the number of rotated logs
    to be packaged in the bundle. By default, 'number_of_logs' is 1.

SECTION 3) IMPORTING LOG DATA INTO THE MONITORING AND REPORTING DATABASE
  If the support bundle was downloaded through the GUI, the tag.gz file should be copied to
  an ACS machine (root mode only) and the folders should be extracted.
  And then follow the instructions below to import log data into the
  monitoring and reporting database.
  The monitoring and reporting database is exported into the
  'view/dbdump' directory.  As part of this export there are two scripts
  created that allow the user to import the database that was exported.

    * reload-config-tables.sh (Imports the configuration tables)
    * reload-operations-tables.sh (Imports the operational data tables)

  When running either of these scripts, the user will be warned that they
  may be overwriting the existing data. They will be given the opportunity
  to abort out if this is not desired.

  If the user intends on just importing configuration data, then he/she  only
  needs to run the 'reload-config-tables.sh' script.  If the user wishes to
  import the operational data, then he/she should run
  'reload-operations-tables.sh'. If the user wishes to import both
  configuration and operational data, then he/she can run both scripts.
  It is highly advisable if the user runs both scripts, that they run
  'reload-operations-tables.sh' first, then run 'reload-config-tables.sh'.
  The reason for this is when running the 'reload-operations-tables.sh'
  script, there is an option to purge all existing data before importing.
  Doing so will insure aggregation is correct, however doing so will also
  purge any configuration tables.  Hence, it's importing to run
  'reload-config-tables.sh' after running 'reload-operations-tables'.

  Another item worth mentioning is the operational data aggregation.
  If the user runs reload-operations-tables.sh script, the data will be
  aggregated for the complete year.  This is done to avoid inconsistency
  between the day tables and the aggregated month tables.

  Running either of the two scripts is self explanatory.  There are no
  required arguments, and any input required by the user is prompted for
  with detailed help.