DON'T REINVENT THE COW

This is a place for Systems Administrators and IT Professionals to find and share ideas, solutions and templates. If you have something that helps you solve a problem, chances are it will help someone else too. So pay it forward and send an email to TheAgreeableCow at gmail. Full mudos to you!

Saturday 8 September 2012

SysAdmin Modular Reporting (SAMReports)

What is it?
The SysAdmin Modular Reporting framework provides a consistent, flexible data collection and reporting tool with 'traffic light' style alerts for your environment. Written in Powershell using an easy to follow style, the frameworks collates any number of user generated plugins (function scripts), into a single report for any Windows system supporting Powershell.

For a full overview of the framework and information to help create your own scripts

Please see the Quick Start Guide (pdf)


Here's a quick extract from the Veeam report (see full example below).


Download Latest Version
The reporting framework consists of the Core Components and a collection of separate Modules which contain the individual functions that combine to create a final report.

View the scripts on GitHub
*I encourage you to review and understand any script downloaded from the internet. Also ensure to "unblock" each .ps1 files (Right click | Properties | Unblock), to avoid the [D] Do not run [R] Run once [S] Suspend security prompts.

Please note; this is very much a community sourced project. Please send any suggestions, ideas or plugins to theagreeablecow@gmail.com


Core Components
There is one parent script called Get-SAMReport.ps1, which is the script that you launch (either manually or via a scheduled task). Typical syntax is like this:

    Get-SAMReport [module] [output]

For example

    Get-SAMReport Exchange OnScreen

The first thing this script does is collect a number of user defined variables, a style sheet layout and global functions. These are all stored in the _Assets folder and are universally applicable to all reporting modules:
  • Global_Variables.ps1*
    • Contains all of your relevant server names, email contacts etc.
    • Primary report colours, headings etc
  • Global_StyleSheet.ps1
    • All of the HTML format coding
  • Global_Functions.ps1
    • A central location for any functions that need to be called
*As a minimum, you need to customise the Global_Variables.ps1 script.

Then, depending on the module chosen, Get-SAMReport.ps1 will then parse all of the scripts in the relevant module's subfolder. These scripts are based on a standard template so the results can then be imported and aggregated to generate the final report. Any script in the specified module subfolder will be run, in the order listed. If you don't like a script, just remove it or rename the .ps1 extension.

Example of the folder structure


Modules and Templates
The framework is designed to work with any system that supports Powershell v3.0 or later.
For each system module there is a subfolder for individual scripts. There is a high level 'Module Variables.ps1' script which acts like the 'Global Variables' script, but is limited just to that module. Each of the remaining scripts are called in order and produce a standardised output. This output is very specific and must be in the supplied format. Currently the parent script can accept up to four separate results per child script:

  • Results Text (html formatted)
  • Results Data (html formatted table)
  • Results Alert (Alert, Warning, Good colour codes)
  • An attachment (found on any UNC path)
Each of these scripts contain further variables (such as servers or service names) and thresholds that you can customise. So feel free to tweak these to suit your environment. Have a look at some of the examples provided and you'll soon get a feel for the methodology.

NB. The scripts need to be stored and run from a server that contains the relevant management tools and Powershell plugins.


Scheduled Tasks
The reports are best suited to being run as a scheduled task. The typical syntax for running is as follows:

Start a program: C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe
Arguments: -NonInteractive c:\SAMReports\Get-SAMReport.ps1 Exchange
Start in: c:\SAMReports\

There is a 'Scheduled Task Example.xml' file in the assets folder which can be imported to make this process easier.

Ensure the script is run manually at least once for each module you want to use. You will be prompted for your "Run As" credentials for that module. These will be saved using ConvertTo-SecureString for future use in a hashed 'ModuleCredentials.xml' file. To changed the saved credentials, remove this file and re-run script manually once more.


Example Plugin
This is a simple example showing the typical framework for a module plugin.


Reporting
Once the results have been aggregated into the final report, you will be able to view the relevant data that you have gathered and also quickly see any Warnings or Alerts based on your thresholds. Even specific text with each section can be highlighted accordingly. The overall title of the report will also reflect the worst result, so for example if there were 8 sections and only one showed a Alert, the report title will be coloured as a Alert.

Here is an example of a full report


As I said earlier, this is a community driven project if you have any suggestion or module scripts you have created, I would love to include them here - with full mudos to you of course.

 Cheers,
         (__)
         (oo)  ok
   /------\/  /
  / |    ||
 *  /\---/\
    ^^   ^^



14 comments:

  1. Hello,

    Great scripts and reports!
    I have one remarks on the first plugin called 01_Veeam_Get-JobStatusSummary.ps1
    In fact, what I have seen :
    if a retry is done on a backup job, the last sessions functions will contains only the VM that fails on the first time.
    So for all count, if a retry is done (on success or failure), the counting will "forget' all VMs that belong to the job and didn't need a retry.

    Do you have any solutions? Would like to do something but I am a beginner on powershell and don't see how to do this properly...

    Thanks for your return

    ReplyDelete
  2. This is an awesome script! I've shared this with my local Veeam SE team here in Australia. One quick question, is there a way to run wildcards through the list of VM's to exclude from Veeam backup monitoring?
    Line 20 of the following script 05_Veeam_Get-UnprotectedVMs.ps1

    ReplyDelete
  3. Hi there, Do you plan(or already have) on putting some documentation together for other people to write modules that fit into SAMReports?

    ReplyDelete
    Replies
    1. This comment has been removed by the author.

      Delete
    2. This comment has been removed by the author.

      Delete
  4. I'm having a lot of trouble getting this to work with Veeam 7. I noticed in a few lines of global_functions you reference veeams files in the C:\Program Files\Veeam\Backup & Replication\ folder, whereas in version 7 they are in C:\Program Files\Veeam\Backup & Replication\Backup

    We seem to be getting hung up on this error. Any ideas?

    Get-VBRJob : Cannot validate argument on parameter 'Name'. The argument is null or empty. Supply an argument that is
    not null or empty and then try the command again.
    At C:\Users\user\Desktop\SAMReports ALL\SAMReports\_Assets\02_Global_Functions.ps1:110 char:33
    + $InputObj = Get-VBRJob -Name $Name
    + ~~~~~
    + CategoryInfo : InvalidData: (:) [Get-VBRJob], ParameterBindingValidationException
    + FullyQualifiedErrorId : ParameterArgumentValidationError,Veeam.Backup.PowerShell.Command.GetVBRJob

    ReplyDelete
  5. Do you have a new version that works for Veeam ver 8? Thanks

    ReplyDelete
  6. This comment has been removed by the author.

    ReplyDelete
  7. Thank you for your site just found it ! The Internet is a big place lol !
    I was wondering if the download files are in a new location the link no longer works thank you
    Download Latest Version
    The reporting framework consists of the Core Components and a collection of separate Modules which contain the individual functions that combine to create a final report.
    Download all scripts - Version 2.0 July 2014 (ZIP file)*

    ReplyDelete
    Replies
    1. No longer available - all modules can be sourced from Github via the links above.

      Folder structure as follows:

      get-SAMReport.ps1
      \_Assets
      00_Global_Variables.ps1
      01_Global_StyleSheet.ps1
      02_Global_Functions.ps1
      \Certificates

      \Exchange

      etc

      Delete
  8. Hi,

    Do you have any plans to update the script to support newer versions of Veeam?
    I currently have some issues trying it on our setup as it fails the below

    Cannot find an overload for "op_Subtraction" and the argument count: "2".
    At C:\Temp2\Veeam\02_Veeam_Get-JobStatusDetails.ps1:40 char:3
    + $Age = ((Get-Date) - $Finish).Days

    Method invocation failed because [Veeam.Backup.Core.CRemoteWinFileCommander] does not contain a method named 'Create'.
    At C:\Temp2\_Assets\02_Global_Functions.ps1:73 char:5
    + ... $FileCommander = [Veeam.Backup.Core.CRemoteWinFileCommand ...

    Get-VBRJob : Cannot validate argument on parameter 'Name'. The argument is null or empty. Provide an argument that is not null or empty, and then try the command again.
    At C:\Temp2\_Assets\02_Global_Functions.ps1:110 char:33
    + $InputObj = Get-VBRJob -Name $Name


    I do get a report out however it's missing some bits such as, start and finish time, backup storage status

    let me know if it's because I missed a configuration

    ReplyDelete
  9. Get-SAMReport.ps1' is not recognized as the name of a cmdlet

    ReplyDelete
  10. first of all, this is an awesome script! How can I add a csv output format?

    ReplyDelete
  11. Is possible to run the script for multiple Veeam servers?

    ReplyDelete