UCOS backup reporter

From ip tuning
Jump to: navigation, search
Remember this is a command line tool! If you're using Windows, clicking on the icon will not show anything! Use the command line!

Use this tool to generate reports on your UCOS DRF backups.

Requirements

  • Pre compiled binaries exist for Windows
  • If your want to run directly in Perl - (Linux, MacOS X, Windows with Perl, etc...):
    • The following modules need to be installed (most, if not all might already be available on your Perl installation):
      • File::Find
      • Data::Dumper
      • Time::Local
      • XML::Simple
      • Net::Domain
      • Getopt::Long
      • Config::Std
    • Tested in Windows using http://www.activestate.com/activeperl, MacOS X and Debian Linux

Required backup directory structure

  • Backup directories need to be inside a base directory. If not, you need to run an instance of tool for each backup base directory
  • Each backup directory might contain several backup jobs for a cluster (CUCM, UCCX and PLM) or a server (UCCX)
  • Do not mix backup jobs from different products, clusters or servers in the same backup directory!
    • ubr will consider all manifest files to belong to the same product, cluster or server!
    • Collaboration products prior to version 10.X, DRF did not include the host name of the master DRF backup server in the manifest file name. This could lead to a server deleting backup jobs from another server when it reached the maximum number of backups to keep.
    • Sample structure:
\---backup
    +---AMER
    |   +---CUCM
    |   +---CUCX-PUB
    |   +---CUCX-SUB
    |   \---UCCX
    +---APAC
    |   +---CUCM
    |   +---CUCM-AUS
    |   +---CUCX-AUS
    |   \---UCCX
    +---EMEA
    |   +---CUCM
    |   +---CUCX-PUB
    |   +---CUCX-SUB
    |   \---UCCX
    +---PLM
    \---PREPROD
        \---CUCX

How does it work?

  • Crawls all folders from a base directory, searching for files with a name ending in drfComponent.xml.
    • These are UCOS DRF backup job manifest files. These files represent each backup job existing in the backup directory.
  • For each manifest file, check which features and components that that particular backup job contains
  • Checks if DRF manifests lists the entire backup job, each feature and each component as a “SUCCESS”
  • If all previous points are a "SUCCESS", recreate the name of each component TAR file
    • Check if this component TAR file exists
  • Sum all the TAR component file sizes and generate a total size per backup job
  • Recursively do this for all backup jobs and additional directories and files found under the base directory
  • Generate an HTML report.

Flows

Main flow

ubr program execution is quite simple:

ubr main flow

XML check flow

This is the XML check flow. Notice that any check that is not a success immediately skips any further validation checks:

ubr xml check flow

Screenshots

Sample screenshot

Important notes

  • Because TAR file checksums stored inside the job manifests are encrypted, there's no way to validate the TAR files integrity
    • Therefore, ubr does not check for TAR file integrity. It only checks if the file exists and adds the file size to the backup job total
  • A backup directory is considered "EXPIRED" only if its newest backup job is older than the maximum backup age.
    • Other backup jobs that are older than the newest are only tested if their TAR files exist. Therefore it's normal to see a backup directory considered expired (with red background), but any additional backup jobs are considered a success (with a green background).

Known bugs and issues

These can be found in GitHub at https://github.com/azevedo-manuel/ubr/issues

Configuration

The current version of ubr supports three configuration options.

The parameters take precedence over the other in the following order (lower means lower precedence):

  1. Built in parameters
  2. Configuration file
  3. Command line switches

Built in parameters

This section applies only if you use the script directly. Windows users that use the compiled version cannot change these options. Any configurable parameter must be changed in the ubr.pl file directly:

#
# App parameters

my $baseDir             = "./backup";

my $newerBackupMaxDays  = 3;

my $HTMLRemoveBaseDir   = 1;
my $HTMLRemoveXMLString = 1;

my $debug               = 0;

my $sortNewestFirst     = 1;
my $sortDirectoriesAsc  = 1;

Parameters description

  • $baseDir
    • This is the root directory where the backups are stored. Please see above notes about for expected directory format
    • Note: directories must be entered in Unix format (forward slash '/' as directory separator). This is the same for all platforms!
  • $newerBackupMaxDays
    • Backups with age equal or older are considered expired
  • $HTMLRemoveBaseDir
    • Cosmetic: Removes the base directory defined in $baseDir from the directory list
  • $HTMLRmoveXMLString
    • Cosmetic: Removes the “drfComponent.xml” part of the manifest filename in the HTML report
  • $sortNewestFirst
    • Sort backup jobs by newest first. If value is zero, sorts by oldest first
  • $sortDirectoriesAsc
    • Sort directories by their name in ascending order. If value is zero, sorts the directories by descending order
  • $debug
    • Debug: Used during development, can be used to see mostly the validation of the XML manifest and component files. The debug outputs are HTML comments

Configuration file

If not defined by a command-line switch, ubr tries to find the ubr.conf file and read any parameters it can find.

In the file, a parameter is anything that does not start with # and contains a colon followed by data.

The default ubr.conf has all options commented. Just change and uncomment them to your liking.

The current ubr.conf is:

# This is a comment
# All options defined here can be overwritten by command line switches, which take higher priority
# If the command line switch is not defined, then this configuration will take it's value
# If the switch is also not defined, the default value will be used.

# The root directory where the backups are.
# DEFAULT: ./backup
#baseDir: ./backup


# The minimum number of days a directory newest backup is considered expired.
# DEFAULT: 3
#newerBackupMaxDays: 3

# Remove the base directory path from the directory listing.
# Remove: 1. Do not remove: 0
# DEFAULT: 1
#HTMLRemoveBaseDir: 1

# Removes  '_drfComponent.xml'  from   the backup job name.
# Remove: 1. Do not remove: 0
# DEFAULT: 1
#HTMLRemoveXMLString: 1

# Enable Debug. Debug messages are send as HTML comments.
# Enabled: 1. Disabled: 0
# DEFAULT: 0
#debug: 0

# Sorts newest backup jobs first.
# Newest first: 1. Newest last: 0
# DEFAULT: 1
#sortNewestFirst: 1

# Sorts directories in ascending order.
# Ascending: 1. Descending: 0
# DEFAULT: 1
#sortDirectoriesAsc: 1


# *** UNIMPLEMENTED ***
# This section contains the logging options
# Logging enabled: 1. Logging disabled: 0
# DEFAULT: 1
logging: 1

# *** UNIMPLEMENTED ***
# Logging to a file. If no file given, logs to console
# Default: STDIN
logfile: output.log

Command line switches

These parameters can be included in the command line. They take precedence over both the built-in parameters and the configuration file parameters.

Usage: ubr.pl -options

where options are:

 Options with arguments:
 --conf         or -c   Another config file.                        Default value is 'ubr.conf'
 --basedir      or -b   The root directory where the backups are.   Default value is './backup'
 --newermaxdays or -n   The minimum number of  days a  directory    Default value is 3 days
                        newest backup is considered expired.

 Boolean (True/False) options:
 --removebasedir        Removes the base directory path from the    Default value is 'true'
                        directory listing.
 --removexmlstring      Removes  '_drfComponent.xml'  from   the    Default value is 'true'
                        backup job name.
 --sortnewestfirst      Sorts newest backup jobs first.             Default value is 'true'
 --sortdirectoriesasc   Sorts directories in ascending order.       Default value is 'true'

 Options without arguments:
 --help         or -h   This menu
 --debug        or -d   Enable diagnostics debug messages

 Note:    The boolean options can  be negated by replacing '--' with '--no-' and thus make it false.

 Example: If you want to order the directory  listing  in  descending,
          just write the option as '--no-sortdirectoriesasc'

These switches overwrite both the built-in defaults or the 'ubr.conf' configuration file

All options are case sensitive!


Installation

The script can be run from anywhere in the computer. The $baseDir parameter can be absolute or relative to the script's location. By itself, the script runs only once and outputs HTML content to the standard input.

It can be installed in a HTTP server as a CGI.

Linux/Unix

It can also be configured in a cron job to send an email. A sample configuration follows (send an email each day at 5am):

0 5 * * * perl ubr.pl | mail -a "Content-type: text/html" -a "From:ubrbackup@backupexample.com" -s "ubr Report" user@example.com

You can also enable ubr.pl executable bit and skip entering perl.

Windows

If using ActiveState Perl in Windows, calling ubr.pl directly invokes Perl automatically. As an alternative, a pre-compiled binary is available for download.

You might want like in the Linux installation to be able to send a report periodically.

The source code includes a file named generate-email-report.ps1. This is a PowerShell script that will run uBR and send the report via email.

Please update the source code before you use it.

On a side note, configuring Task Scheduler for PowerShell script running requires invoking PowerShell and the script as a parameter.

It's also recomended to run the script and uBR in the same directory:

Ubr-task-scheduler-powershell.PNG

Download

You can download the latest version here: https://github.com/azevedo-manuel/ubr