Sunday, 17 August 2014

Command History to Syslog for CDOT Version 2: Part 1/2 - User Guide

Introduction

This is a User Guide for using the PowerShell script:

- CommandHistoryToSyslogForCDOT.ps1 Version 2 (V2)

Note: You can change the name of the script.

The script is tested with NetApp Clustered Data ONTAP 8.2.1 - but should work fine with other 8.2.X releases - and connects to Clustered Data ONTAP systems, pulls down the command-history.log, and then sends updates to a syslog server. This script exists as a workaround for burt 281938 “Unable to send Audit Log information via syslog” which is due to be fixed in a later release.

Pre-requisites

- PowerShell 3 (which necessitates requiring a suitable Windows 2008R2/Windows 7 or better server/client)
- CommandHistoryToSyslogForCDOT.ps1
- A suitable user account on the server/client which can use PowerShell 3 and run scripts
- A folder on the server/client with read/write access
- A user login to Cluster(s) with the application HTTP and admin role

Note: The Data ONTAP PowerShell toolkit is not a requirement.

Setup

The script can be run from any usable location (e.g. C:\Users\USERNAME).
To get display the help output, run the following command from PowerShell:

.\CommandHistoryToSyslogForCDOT.ps1 -help

The help output is listed at the end of the document.

Create a folder on the D drive called say SYSLOG4CDOT (D:\SYSLOG4CDOT)

Run the following to setup the INI file which holds the Syslog Server’s IP address, and UDP port information:

.\CommandHistoryToSyslogForCDOT.ps1 -setup -workingDirectory D:\SYSLOG4CDOT

Command History to Syslog for CDOT (v2 - August 2014)
=====================================================

MAIN PROGRAM: -setup parameter detected, running setup.

Command History to Syslog Setup
===============================

This setup script will create an INI file in the filepath D:\SYSLOG4CDOT\CommandHistoryToSyslogForCDOT.ini, with the fo
llowing details:

1) Syslog Server FQDN / IP Address.
2) Syslog Server UDP Port (Default = 514).

Enter Syslog Server FQDN / IP Address?: 10.10.10.17
Enter Syslog Server UDP Port (Default = 514)?: 514

Running the Script for the First Time against a Cluster and Node

When the script is run for the first time, it will prompt for username and password to connect to the SPI (Note: These credentials will be used for all clusters). Alternatively, the -setcredential parameter can be used to set or reset the credential. The credentials are saved as an encrypted string in the working directory. This encrypted string can only be unencrypted by the user who created it.

To run against a particular cluster and a particular node (PRICLU1 and NACLU1N1 in this example):

.\CommandHistoryToSyslogForCDOT.ps1 -cluster PRICLU1 -node NACLU1N1 -workingDirectory D:\SYSLOG4CDOT

Command History to Syslog for CDOT (v2 - August 2014)
=====================================================

MAIN PROGRAM: Got contents of INI file from D:\SYSLOG4CDOT\CommandHistoryToSyslogForCDOT.ini
MAIN PROGRAM: The program needs to store credentials for connecting to the SPI. The credential is stored as an encrypte
d string - at D:\SYSLOG4CDOT\CommandHistoryToSyslogForCDOT_DJC.creds - that only DJC can use.
MAIN PROGRAM: Enter user with access to the SPI (The username must be entered with CASE SENSITIVITY as displayed via CDO
T::> security login show)?: admin

Image: Windows PowerShell Credential Request appears on script first run

MAIN PROGRAM: Send command history to syslog for cluster PRICLU1:NACLU1N1
FN:SCH2S: Reading the contents of D:\SYSLOG4CDOT ...
FN:SCH2S: ... and looking for items like PRICLU1_NACLU1N1*
FN:SCH2S: Download links at https://PRICLU1/spi/NACLU1N1/etc/log/mlog/
FN:SCH2S: CONDITION 1 - we have no previous saved command-history.log.XXXXXXXXXX
FN:SCH2S: Download file from https://PRICLU1/spi/NACLU1N1/etc/log/mlog/command-history.log.0000000001 and save as D:\SY
SLOG4CDOT\PRICLU1_NACLU1N1_command-history.log.0000000001
FN:SCH2S: Return to main program.

The first time the script runs against a particular cluster and node, it displays “CONDITION 1 - we have no previous saved command-history.log.XXXXXXXXXX”

The contents of the working directory (including the script) are now:

Notice the PRICLU1_NACLU1N1_command-history.log.0000000001.

Running the Script for the Subsequent Times against a Cluster and Node

We use the same syntax:

.\CommandHistoryToSyslogForCDOT.ps1 -cluster PRICLU1 -node NACLU1N1 -workingDirectory D:\SYSLOG4CDOT

Command History to Syslog for CDOT (v2 - August 2014)
=====================================================

MAIN PROGRAM: Got contents of INI file from D:\SYSLOG4CDOT\CommandHistoryToSyslogForCDOT.ini
MAIN PROGRAM: Detected credentials file at D:\SYSLOG4CDOT\CommandHistoryToSyslogForCDOT_DJC.creds. Getting content.
MAIN PROGRAM: Send command history to syslog for cluster PRICLU1:NACLU1N1
FN:SCH2S: Reading the contents of D:\SYSLOG4CDOT ...
FN:SCH2S: ... and looking for items like PRICLU1_NACLU1N1*
FN:SCH2S: Download links at https://PRICLU1/spi/NACLU1N1/etc/log/mlog/
FN:SCH2S: Renamed the file D:\SYSLOG4CDOT\PRICLU1_NACLU1N1_command-history.log.0000000001  to D:\SYSLOG4CDOT\PRICLU1_NA
CLU1N1_command-history.log.previous
FN:SCH2S: CONDITION 2 - We have the latest command-history.log and just need to send updates
FN:SCH2S: Download file from https://PRICLU1/spi/NACLU1N1/etc/log/mlog/command-history.log.0000000001 and save as D:\SY
SLOG4CDOT\PRICLU1_NACLU1N1_command-history.log.0000000001
FN:SCH2S: File size of latest file and previous file is the same (2861621) - no updates.
FN:SCH2S: Return to main program.

This time the program registers “CONDITION 2 - We have the latest command-history.log and just need to send updates”.
When the command-history.log cycles in between runs of the script, you will see “CONDITION 3: The command-history.log has cycled. We need to send what was not sent in the last saved command-history.log, then the contents of any newer log files.”

Running the Script in Batch Mode

The script will take a batch file, with a list of clusters and nodes, as in the example file (which we’ll call “clustersAndNodes.txt”) with the contents below:

# Clusters and Nodes
PRICLU1,NACLU1N1
PRICLU2,NACLU3N1
SECCLU1,NACLU2N1
SECCLU2,NACLU4N1
NACLU5,NACLU5N1,NACLU5N2

In the above we have 5 clusters and 6 nodes.

To run from the batch file:

.\CommandHistoryToSyslogForCDOT.ps1 -batch clustersAndNodes.txt -workingDirectory D:\SYSLOG4CDOT

Command History to Syslog for CDOT (v2 - August 2014)
=====================================================

MAIN PROGRAM: Got contents of INI file from D:\SYSLOG4CDOT\CommandHistoryToSyslogForCDOT.ini
MAIN PROGRAM: Detected credentials file at D:\SYSLOG4CDOT\CommandHistoryToSyslogForCDOT_DJC.creds. Getting content.
MAIN PROGRAM: BATCH: Send command history to syslog for PRICLU1:NACLU1N1
FN:SCH2S: Reading the contents of D:\SYSLOG4CDOT ...
FN:SCH2S: ... and looking for items like PRICLU1_NACLU1N1*
FN:SCH2S: Download links at https://PRICLU1/spi/NACLU1N1/etc/log/mlog/
FN:SCH2S: Removed the file D:\SYSLOG4CDOT\PRICLU1_NACLU1N1_command-history.log.previous
FN:SCH2S: Renamed the file D:\SYSLOG4CDOT\PRICLU1_NACLU1N1_command-history.log.0000000001  to D:\SYSLOG4CDOT\PRICLU1_NA
CLU1N1_command-history.log.previous
FN:SCH2S: CONDITION 2 - We have the latest command-history.log and just need to send updates
FN:SCH2S: Download file from https://PRICLU1/spi/NACLU1N1/etc/log/mlog/command-history.log.0000000001 and save as D:\SY
SLOG4CDOT\PRICLU1_NACLU1N1_command-history.log.0000000001
FN:SCH2S: File size of latest file and previous file is the same (2861621) - no updates.
FN:SCH2S: Return to main program.
MAIN PROGRAM: BATCH: Send command history to syslog for PRICLU2:NACLU3N1
FN:SCH2S: Reading the contents of D:\SYSLOG4CDOT ...
FN:SCH2S: ... and looking for items like PRICLU2_NACLU3N1*
FN:SCH2S: Download links at https://PRICLU2/spi/NACLU3N1/etc/log/mlog/
FN:SCH2S: CONDITION 1 - we have no previous saved command-history.log.XXXXXXXXXX
FN:SCH2S: Download file from https://PRICLU2/spi/NACLU3N1/etc/log/mlog/command-history.log.0000000001 and save as D:\SY
SLOG4CDOT\PRICLU2_NACLU3N1_command-history.log.0000000001
FN:SCH2S: Return to main program.
MAIN PROGRAM: BATCH: Send command history to syslog for SECCLU1:NACLU2N1
FN:SCH2S: Reading the contents of D:\SYSLOG4CDOT ...
FN:SCH2S: ... and looking for items like SECCLU1_NACLU2N1*
FN:SCH2S: Download links at https://SECCLU1/spi/NACLU2N1/etc/log/mlog/
FN:SCH2S: CONDITION 1 - we have no previous saved command-history.log.XXXXXXXXXX
FN:SCH2S: Download file from https://SECCLU1/spi/NACLU2N1/etc/log/mlog/command-history.log.0000000001 and save as D:\SY
SLOG4CDOT\SECCLU1_NACLU2N1_command-history.log.0000000001
FN:SCH2S: Return to main program.
MAIN PROGRAM: BATCH: Send command history to syslog for SECCLU2:NACLU4N1
FN:SCH2S: Reading the contents of D:\SYSLOG4CDOT ...
FN:SCH2S: ... and looking for items like SECCLU2_NACLU4N1*
FN:SCH2S: Download links at https://SECCLU2/spi/NACLU4N1/etc/log/mlog/
FN:SCH2S: CONDITION 1 - we have no previous saved command-history.log.XXXXXXXXXX
FN:SCH2S: Download file from https://SECCLU2/spi/NACLU4N1/etc/log/mlog/command-history.log.orig and save as D:\SYSLOG4C
DOT\SECCLU2_NACLU4N1_command-history.log.orig
FN:SCH2S: Return to main program.
MAIN PROGRAM: BATCH: Send command history to syslog for NACLU5:NACLU5N1
FN:SCH2S: Reading the contents of D:\SYSLOG4CDOT ...
FN:SCH2S: ... and looking for items like NACLU5_NACLU5N1*
FN:SCH2S: Download links at https://NACLU5/spi/NACLU5N1/etc/log/mlog/
FN:SCH2S: CONDITION 1 - we have no previous saved command-history.log.XXXXXXXXXX
FN:SCH2S: Download file from https://NACLU5/spi/NACLU5N1/etc/log/mlog/command-history.log.0000000001 and save as D:\SYS
LOG4CDOT\NACLU5_NACLU5N1_command-history.log.0000000001
FN:SCH2S: Return to main program.
MAIN PROGRAM: BATCH: Send command history to syslog for NACLU5:NACLU5N2
FN:SCH2S: Reading the contents of D:\SYSLOG4CDOT ...
FN:SCH2S: ... and looking for items like NACLU5_NACLU5N2*
FN:SCH2S: Download links at https://NACLU5/spi/NACLU5N2/etc/log/mlog/
FN:SCH2S: CONDITION 1 - we have no previous saved command-history.log.XXXXXXXXXX
FN:SCH2S: Download file from https://NACLU5/spi/NACLU5N2/etc/log/mlog/command-history.log.0000000001 and save as D:\SYS
LOG4CDOT\NACLU5_NACLU5N2_command-history.log.0000000001
FN:SCH2S: Return to main program.

Running the Script Repeatedly

There are two optional parameters:

PARAMETER -repeatMinutes
Runs every XXX minutes (requires the user running it is not logged off) {default = 5 minutes}. If repeatIterations is not specified, it will run until the user gets logged off.

PARAMETER -repeatIterations
The number of times to repeat running (requires the user running it is not logged off) {default = 0 or infinite repeats}. If RepeatMinutes is not specified, it will run every 5 minutes.

The above can be used to set the script running and leave it running. Example syntax:

.\CommandHistoryToSyslogForCDOT.ps1 -batch clustersAndNodes.txt -workingDirectory D:\SYSLOG4CDOT -RepeatMinutes 1

Will run every ten minutes (actually sleep for 10 minutes after it’s done a run), and run infinitely (or until the user is logged off.)

Logging

The script logs the programs output (not the messages it sends to syslog), and captures any exceptions which are thrown by the program, to the log:

CommandHistoryToSyslogForCDOT.log

The log will cycle once when it gets to 5MB in size.

Contents of the Working Directory

In the example below we have:

- clustersAndNodes.txt - this is the optional batch file
- CommandHistoryToSyslogForCDOT.ini - the INI file which just holds the syslog server IP and UDP port information
- CommandHistoryToSyslogForCDOT.log - the active log file (for capturing exceptions and non-syslog outputs)
- CommandHistoryToSyslogForCDOT.log.old - the old log file
- CommandHistoryToSyslogForCDOT.ps1 - the script (which can be run from any suitable place)
- CommandHistoryToSyslogForCDOT_DJC.creds - a credentials file created by the user DJC

Then for every cluster and node there is a file:

- CLUSTERNAME_NODENAME_command-history.log.XXXXXXXXXX
- CLUSTERNAME_NODENAME_command-history.log.previous

With the XXXXXXXXXX file being name as it is on the SPI (note that there are all 0000000001 below because using Simulators - this has been tested on real systems with logs cycling roughly every night.) The .previous one is as was downloaded the previous time.


APPENDIX: Help Output

PS D:\SYSLOG4CDOT> .\CommandHistoryToSyslogForCDOT.ps1 -help

Command History to Syslog for CDOT (v2 - August 2014)
=====================================================

SYNOPSIS
========

Command History to Syslog for Clustered Data ONTAP 8.2.X (V2 - August 2014 by DJC).

SYNTAX
======

.\CommandHistoryToSyslogForCDOT.ps1

.\CommandHistoryToSyslogForCDOT.ps1 -help

.\CommandHistoryToSyslogForCDOT.ps1 -setup -workingDirectory DIRECTORYPATH

.\CommandHistoryToSyslogForCDOT.ps1 -cluster CLUSTERNAME -node NODENAME -workingDirectory DIRECTORYPATH
{-repeatMinutes XXX -repeatIterations XXX}

.\CommandHistoryToSyslogForCDOT.ps1 -batch FILEPATH/FILENAME -workingDirectory DIRECTORYPATH
{-repeatMinutes XXX -repeatIterations XXX}

.\CommandHistoryToSyslogForCDOT.ps1 -setCredential -workingDirectory DIRECTORYPATH

DESCRIPTION
===========

In CDOT 8.2.1 it is not possible to send the contents of the command-history.log to a syslog server natively. This script gets around this by using a Windows Server 2008R2/7+ as a proxy, reading the command-history.log files over the SPI, and comparing a read (at say time T2) to a previously stored read from last time the script ran (at say time T1).

PARAMETERS
==========

PARAMETER -help
Displays the help output.

PARAMETER -workingDirectory
This is the working directory where the INI file is, and command-history.logs are saved to (also any batch instruction file can be in here too.) For everything but -help, this parameter is mandatory. The folder must be pre-created.

PARAMETER -setup
Runs setup which creates an ini file containing syslog server FQDN/IP and syslog server UDP port.

PARAMETER -cluster
The cluster FQDN/IP to connect to (must be used with -node).

PARAMETER -node
The nodename (CASE SENSITIVE - as from the output of '::> node show') (must be used with -cluster).

PARAMETER -batch
Runs from a batch instructions file containing clusters and their nodes.
The batch file is a simple txt file. Comments beginning with # are allowed. Clustername must come first on the line, then the nodes follow separated by commas. Example:
CLUSTER1,NODE1,NODE2,NODE3

PARAMETER -repeatMinutes
Runs every XXX minutes (requires the user running it is not logged off) {default = 5 minutes}. If repeatIterations is not specified, it will run until the user gets logged off.

PARAMETER -repeatIterations
The number of times to repeat running (requires the user running it is not logged off) {default = 0 or infinite repeats}. If RepeatMinutes is not specified, it will run every 5 minutes.

PARAMETER -setCredential
This allows pre-setting/resetting of the credential required to log in via the SPI, or resetting of a previous entered credential. This is an optional switch, if the first time the script runs it detects no credential file, it will prompt for credentials and create one.

NOTES
=====

i) It handles when logs rotate, and can handle any number of log rotations between times it is run.
ii) The downloaded command-history.logs are saved locally as CLUSTERNAME.NODENAME.command-history.log.XXXXXXXXXX.
iii) This script uses all native PowerShell 3 commands. It doesn't require the DataONTAP PowerShell toolkit.
iv) The user connecting to the SPI needs only HTTP application, but requires admin role
- ::> sec login cre -user syslogger -app http -auth password -role admin
v) The repeat parameters were devised as a workaround to environments where there is the GPO 'Network access: Do not al
low storage of credentials'.
vi) Thrown Exceptions are recorded along with some additional output in CommandHistoryToSyslogForCDOT.log

PS D:\SYSLOG4CDOT>

No comments:

Post a Comment