Latest revision as of 12:52, 11 May 2017

Overview

The audit scripts can be run on Swivel appliances and allow information to be emailed to one or more addresses.

The same scripts can be installed on a Windows Swivel installation.

Prerequisites

AuditScripts.zip

Swivel Appliances: If you use localhost on an appliance, Sendmail must be configured and running

Audit Script Swivel Appliance Installation

The Audit scripts can be run on Swivel Hardware and Virtual Appliances. Installing the scripts requires the use of a SFTP program such as WinSCP and may require Command Line access through the CMI, as well as access to the Swivel Administration Console.

Configuring the Swivel Appliance for Agent XML Authentication

To allow communication from the Audit scripts to the Swivel core, configure an agent on the Swivel Administration console, see Agents How to Guide . If running 3.9 or later, you must indicate that the agent can acts as a repository

Download the Audit Script

Download AuditScripts.zip then Copy zip file to /usr/local/bin

Unzip files so that

/usr/local/bin/com/swiveltechnologies/pinsafe/client/admin

contains

AdminAPI.class, BaseAdminXmlRequest.class, UserAudit.properties etc etc

permissions need to be -rwxr-x--x

Configure the Audit Script for Swivel Appliances

Edit UserAudit.properties (/usr/local/bin/com/swiveltechnologies/pinsafe/client/admin/UserAudit.properties)

customer=customerName The name of the end-customer

swivelurl=http://localhost:8181/pinsafe The url of the Swivel server, default will work for appliance install

swivelsecret = secret Shared secret, needs to match that as set on the Swivel Server for the local agent

mailhost = localhost Host that will forward the email

mailfrom = admin@localhost The sender email address

mailto = billing@swivelsecure.com To where the email will be sent, mulitple addresses separated by a semi-colon

mailsubject= Customer User Count The subject of the email

billday = 25 The day of the month that the report will be sent out. It will only email reports out on this date. If the date is not current then no email will be sent.

Running the Audit Script on Swivel Appliances

To run the script within the /usr/local/bin/ folder type:

 ./audit.sh 

The script interrogates the Swivel Server and appends to a csv file the result, in the folder /usr/local/bin with the date and number of users in the database.

The filename is in the format /usr/local/bin/<customername><repositoryname><month>.<year>.csv

On the billing day of each month the script emails a summary of the results to the specified email address. No email is sent if it is not a billing day.

You can specify a specific reposistory for the report, so it only counts users in that repository eg:

 ./audit.sh XML

For testing you can set the billing date to today's date

 ./audit.sh XML

If you want the count to include all users, use ALL as the repository name

 ./audit.sh ALL 

Configure the Audit script to run automatically on Swivel Appliances

Edit the audit.sh file itself to select the repository you want the script to run against:

java -cp mail.jar:. com.swiveltechnologies.pinsafe.client.admin.UserAudit $1 $2

Replace $1 and $2 with the repository name(s).

E.g. java -cp mail.jar:. com.swiveltechnologies.pinsafe.client.admin.UserAudit localxml

Note - If the repository name is two words (or more) then you must put the repository name in speechmarks. I.e "local xml".

Once the script works you can copy to /etc/cron.daily and the script should run everyday.

You can edit the audit scipt to change what users are counted. eg

java -cp mail.jar:. com.swiveltechnologies.pinsafe.client.admin.UserAudit rep1

java -cp mail.jar:. com.swiveltechnologies.pinsafe.client.admin.UserAudit rep2

would create two separate reports to be generated and sent.

If you need to install the script elsewhere, you need to edit the AUDIT_HOME variable in the script.

Audit Script Windows Installation

Unlike Swivel Appliances, Swivel Windows installations are not standardised.

The general principles of how to deploy and use the scripts is described here.

1) Download File:AuditScripts.zip then Copy zip file to a suitable location eg c:\Users\user

2) unzip files so that

c:\Users\user\AuditScripts\com\swiveltechnologies\pinsafe\client\admin contains

AdminAPI.class, BaseAdminXmlRequest.class, UserAudit.properties etc etc

3) Edit UserAudit.properties

customer=customerName The name of the end-customer

swivelurl=http://localhost:8080/pinsafe The url of the Swivel server

swivelsecret = secret Shared secret, needs to match that as set on the Swivel Server for the local agent

mailhost = localhost Host that will forward the email

mailfrom = admin@localhost The sender email address

mailto = billing@swivelsecure.com To where the email will be sent, mulitple addresses separated by a semi-colon

mailsubject= Customer User Count The subject of the email

billday = 25 The day of the month that the report will be sent out

You need to configure local as an agent on the server/appliance.

If running 3.9 or later, you must indicate that the agent can acts as a repository

4) To run the script type you need to create a batch file, audit.bat

cd c:\Users\crussell\AuditScripts

set CLASSPATH=.;.\mail.jar

java com.swiveltechnologies.pinsafe.client.admin.UserAudit %1 %2

The filename is in the format <customername><repositoryname><month>.<year>.csv

On the billing day of each month the script emails a summary of the results to the specified email address.

You can specify a specific repository for the report, so it only counts users in that repository eg: audit.bat XML

For testing you can set the billing date to today's date

If you want the count to include all users, use ALL as the repository name

audit.bat ALL

5) Once the batch file is working it can be run automatically by creating a scheduled task to call the batch file

Refer to http://www.hosting.com/support/windows-server-2008/create-a-scheduled-task-in-windows-server-2008

Testing

Once you are happy with changes you have made within UserAudit.properties, you can send a test e-mail to the e-mail address configured in this file. In order to do this, you must change the 'billingday' to the day you are testing on. For example, if you are testing on the 12th May, then billingday = 12.

Troubleshooting

On Swivel hardware and Virtual appliances the emails are logged under /var/log/maillog, to view the logs use;

 tail /var/log/maillog

No email is sent if it is not a billing day.

If mails are not being sent check the 'mailhost' in UserAudit.properties

try to telnet to it on port 25

Example: your mailhost is 'mail.yourcompany.net' then try:

 telnet mail.yourcompany.net 25

Wait a few moments, do you get a connection or any feedback from the server e.g.

 [admin@primary bin]# telnet mail.yourcompany.net 25 Trying 1.2.3.4...
 
 Connected to mail.yourcompany.net (1.2.3.4).
 
 Escape character is '^]'.
 
 220 mail.yourcompany.net Microsoft ESMTP MAIL Service ready at Thu, 27 Nov 2014 11:38:32 +0000

Error Messages

Error Occurred - Check PINsafe logs: This error may arise for a number of reasons but make sure that UserAudit.properties contains the correct information. Also, if you are running the command ./audit.sh ALL, this may throw up the error so try running ./audit.sh.

./audit.sh: Permission denied Check the file permissions on the audit.sh and other files.