Audit scripts
Contents
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
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.
