Licensing Log Agent

User & Configuration Guide

V1.4

Copyright 2015 AVEVA Solutions Limited Page 1 of 10

Table of Contents
1 INTRODUCTION ........................................................................................................................... 3

2 PLANNING YOUR LOG AGENT CONFIGURATION ................................................................... 3

3 LOG AGENT CONFIGURATION .................................................................................................. 4

3.1 Overview ................................................................................................................................... 4
3.2 Mandatory INI File Settings ..................................................................................................... 4
3.3 Logging ..................................................................................................................................... 5
3.4 Web-service Transfer Mode Settings ..................................................................................... 5
3.4.1 Pre-Requisite: Installing Microsoft Web Service Enhancements (WSE) 3.0. ..................... 5
3.4.2 Web-Service Mode INI File Settings ................................................................................... 5
3.5 Email Transfer Mode Settings ................................................................................................. 6
3.6 Manual Transfer Mode Settings .............................................................................................. 7

4 RUNNING THE LOG AGENT ....................................................................................................... 8

4.1 Overview ................................................................................................................................... 8
4.2 Running The Log Agent From The Command Line .............................................................. 8
4.3 Running The Log Agent From The Windows Scheduler ...................................................... 8

APPENDIX A LOG AGENT INI FILE SETTINGS ............................................................................. 9

Copyright 2015 AVEVA Solutions Limited Version 1.4, 13 February 2015 Page 2 of 10
 1 INTRODUCTION
The AVEVA Log Agent utility is intended for use by customers using the AVEVA Licensing System
(ALS) and who are licensing their software under a pay-per-usage billing agreement. The Log Agent
transfers the license server logs to the AVEVA servers so that they can be processed and billing
reports subsequently generated.

The Log Agent supports three different transfer modes:

1. Web-service: the Log Agent connects to the AVEVA servers and transfers usage-logs. This
mode requires that the license server system has access to the Internet.
2. Email (SMTP): many license servers are located on a network without a direct Internet
connection, but do have access to internal email servers. This mode allows usage logs to be
sent in emails via an internal SMTP mail server.
3. Manual Transfer: some license servers operate in an environment where it is not possible to
use either of the previous transfer modes. In these circumstances the Manual Transfer mode
can be used. The Manual Transfer mode simply copies the usage-log files into a directory
outside of the license server environment where they can be collected by the customer and
transferred to AVEVA using any method agreed with the AVEVA License Administrators (e.g.
USB stick in the post, manually emailed to AVEVA etc.). Note: the customer is responsible
for maintaining the directory that the Log Agent transfers the usage-logs into.

All transfer modes will effectively remove a usage log from the license server operating environment
so that duplicates will not be sent to AVEVA.

Note: The customer is responsible for ensuring that usage-logs are not removed or tampered with
before they are sent to AVEVA.

2 PLANNING YOUR LOG AGENT CONFIGURATION

Before configuring the Log Agent system it is recommended that you follow the steps below:

1. Choose a transfer mode.

This may involve conversations with your System/Network Administrators who can advise you
of company security policies and any restrictions that may be in place in your license server
operating environment.

2. Identify the appropriate operating parameters.

Depending on the transfer mode you have chosen you will need to identify the configuration
parameters needed:

(a) If you choose to use the web-service then you may need to configure your network
environment e.g. a firewall may need to be configured to allow the Log Agent to connect to
the AVEVA servers.

(b) If you choose to use email then you will need to obtain the SMTP email server address
and port number as well as a username and password.

(c) If you choose the manual transfer mode then you need to liaise with your AVEVA License
Administrator to agree how you will send your usage-logs to AVEVA to be processed.

3. Decide when you will transfer your usage-logs.

The Log Agent is not a GUI and has been designed to operate without user interaction so that
it can be run automatically by the Windows Schedule Manager if desired.

Copyright 2015 AVEVA Solutions Limited Version 1.4, 13 February 2015 Page 3 of 10
 3 LOG AGENT CONFIGURATION

3.1 Overview
The Log Agent is configured by editing settings in the INI file AvevaAgent.ini that is located in the
LogAgent sub-directory in your AVEVA Licensing System installation directory. Once the INI file has
been set up the Log Agent can be executed without the need to specify any command line
parameters or for any user-interaction.

Entries in the INI file are arranged in sections, each section is introduced by a line in the following
format:

[<section-name>]

Where <section-name> is the name of a section, for example the Customer Information section is
introduced by the following line:

[Customer Information]

Each section contains one or more settings in the following format:

<parameter name>=<value>

Where <parameter name> is the name of a specific parameter that the Log Agent will use, and
<value> is the value of that parameter, for example the following lines show how the Customer Code
value is defined within the Customer Information section:

[Customer Information]
CustomerCode=CC001234

Note: Appendix A contains details of all valid INI file settings.

The following sections describe the INI file settings you need to configure based upon the transfer
mode you have chosen.

3.2 Mandatory INI File Settings

The following settings need to be set regardless of your chosen transfer mode:

a. In the [Customer Information] section the following settings need to be configured:

CustomerCode
LocationCode

Your AVEVA License Administrator will be able to advise you of the values you need to use.

b. In the [Backup] section the following setting should to be configured:

Handler

Note that this is not technically a mandatory setting but AVEVA strongly recommends that you
configure this setting.

c. The data in your usage-log files is anonymised to protect the identities of your users and their
workstation names and the billing reports you receive from AVEVA will use theses
anonymised names by default. If you want your reports to contain the real identities of your
users and workstations then set the following entry in the [Transmission] section to true,
otherwise set it to false:

AllowMapFileTransmission

Copyright 2015 AVEVA Solutions Limited Version 1.4, 13 February 2015 Page 4 of 10
3.3 Logging
By default the Log Agent will write progress messages to its standard output (the command window
display) when run from the command line. These messages can be redirected to a file by setting the
following entries in the [Debug] section:

DebugLogFile
DebugLogFileMaxSize

AVEVA recommends that these settings are configured so that a record is kept of log file transfers.

3.4 Web-service Transfer Mode Settings

3.4.1 Introduction
The log agent supports the ability to transfer the usage logs using a web-service. The diagram below
shows the system set up for a server configured to use the web-service transfer mode.

Figure 1 Web-Service System Configuration

The usage logs will be copied to the spool directory and optional backup directory by the Log Agent
each time it runs. The Log Agent will then attempt to send the all spooled usage logs in the spool
directory to the Aveva Log Receiver via the web-service. Usage log files will be removed from the
spool directory after they have been successfully transferred.

3.4.2 Pre-Requisite: Installing Microsoft Web Service Enhancements (WSE) 3.0.

In order to support the web-service transfer mode the Log Agent requires that MS WSE 3.0 is
installed. The installer, MicrosoftWSE3.0Runtime.msi, is provided with the ALS installation and can
be found in the LogAgent sub-directory in your ALS installation directory. To install MS WSE 3.0
simply double-click on MicrosoftWSE3.0Runtime.msi and follow the on-screen instructions.

3.4.3 Web-Service Mode INI File Settings

The following settings need to be configured in order to support Web-service transfer mode:

Copyright 2015 AVEVA Solutions Limited Version 1.4, 13 February 2015 Page 5 of 10
 a. In the [Transmission] section set the following entry:

UsageTransferMode=0

b. In the [Web] section set the following entry:

ServiceURL=
https://urs.aveva.com/AVEVAUsageLogWebService/AVEVAUsageLogWebService
.asmx

3.5 Email Transfer Mode Settings

3.5.1 Introduction
The log agent supports the ability to transfer the usage logs using a SMTP server. The diagram below
shows the system set up for a server configured to use the Email transfer mode.

Figure 2 SMTP Server System Configuration

The usage logs will be copied to the spool directory and optional backup directory by the Log Agent
each time it runs. The Log Agent will then attempt to send the all spooled usage logs in the spool
directory to the Aveva Log Receiver via the SMTP server. Usage log files will be removed from the
spool directory after they have been successfully transferred.

3.5.2 Email Mode INI File Settings

The following settings need to be configured in order to support Email Transfer Mode:

a. In the [Transmission] section set the following entry:

UsageTransferMode=1

b. In the [SMTP] section set the following entries appropriately:

Copyright 2015 AVEVA Solutions Limited Version 1.4, 13 February 2015 Page 6 of 10
 MailTo=urs.logs@aveva.com
SMTPServerHost
SMTPPort
MailFrom
MailCC
MailUserName
MailSSL

Your system administrator should be able to advise you as to which settings you need to use
and what the correct values should be.

3.6 Manual Transfer Mode Settings

3.6.1 Introduction
This is used by the customers who dont have internet connection on the license server or if they have
any issues with SMTP or Web Service log transfer. The diagram below shows the system set up for a
server configured to transfer the usage logs manually.

Figure 3 Manual Transfer System Configuration

The usage logs will be copied to the spool directory and optional backup directory by the Log Agent
each time it runs. The customers should copy the files present inside the LogAgentSpool directory to
an external device (for example USB device) and need to email those log files to the Aveva License
Administrator.

IMPORTANT: Usage log files must be manually removed by the user from the spool directory
after they have been successfully sent to the Aveva.

3.6.2 Manual Mode INI File Settings

The following setting needs to be configured in order to support Manual Transfer Mode:

Copyright 2015 AVEVA Solutions Limited Version 1.4, 13 February 2015 Page 7 of 10
In the [Transmission] section set the following entry:

UsageTransferMode=2

4 RUNNING THE LOG AGENT

4.1 Overview
Once the INI file has been set up the Log Agent can be run without the need for user-interaction
which makes it suitable for being run automatically using the a scheduler such as the Windows
Scheduler. Alternatively it can easily be run manually from a command window as it will use the
settings in the INI file and the user will not need to specify any command line arguments or interact
with the program when it runs.

4.2 Running the Log Agent from the Command Line

To run the Log Agent manually from the command line do the following:

1. Open a command line window (if running on Windows 7/2008 ensure that it is run as an
Administrator).
2. Change directory to the LogAgent sub-directory in your AVEVA License System installation
(usually C:\AVEVA\AVEVA Licensing System).
3. Type: AVEVALogAgent.exe.

The Log Agent will read the INI file and attempt to transfer any usage-log files. If the DebugLogFile
INI file setting has not been set the Log Agent will display progress messages on the screen as it
processes your usage-log files, otherwise you will need to view the log file configured in the INI file to
see the results of the transfer.

4.3 Running the Log Agent from the Windows Scheduler

Configuring the Windows Scheduler is not a straightforward task as different versions of Windows
require different steps to configure. It is also recommended that your system administrator is
consulted before using the Windows Scheduler to ensure that the time chosen for the transfer does
not clash or interfere with any other administrative tasks that may be active at the time.

As a guide to setting up the Windows Scheduler we recommend that you consult the official Microsoft
website for the latest information:

http://windows.microsoft.com/en-gb/windows7/schedule-a-task

NOTES

If the INI file is set to transfer the mapping XML it will be transferred each time the log agent is
run.

If there are no new entries in the active usagelog.log it will not be spooled/transferred when
the log agent is run.

The Log Agent will not transfer the active usage log (usagelog.log) if the license server is
stopped. However, the log agent will transfer the usagelog.xml file and any rotated log files
(i.e. files of the format usagelog.log.nn).

If the Log Agent is run more than once within 15 minutes, it will not transfer the active usage
log (usagelog.log) but the usagelog.xml file will be transferred.

Copyright 2015 AVEVA Solutions Limited Version 1.4, 13 February 2015 Page 8 of 10
Appendix A Log Agent INI File Settings
Section: Customer Information

Setting Description
CustomerCode Your AVEVA Customer Code as supplied by AVEVA. Can be
up to 32 characters in length. Example: UK-C1234
LocationCode The AVEVA Location Code of the server system which is
hosting the Log Agent. Valid values are from 1 - 9999.

Section: Backup

Setting Description
Handler Specifies a directory into which usage logs are copied after
they have been spooled for transmission. This user is
responsible for removing files from this directory.

Section: Transmission

Setting Description
UsageTransferMode Specifies the mode used to transfer usage-log files. Valid
values are:

0 Web Service
1 Email (SMTP)
2 Manual transfer

AllowMapFileTransmission Specifies whether the file containing de-anonymisation

information is transferred to AVEVA. Valid values are:

True send the de-anonymisation file.

False do not send the de-anonymisation file.

Section: Web

Setting Description
ServiceURL Specifies the web-service URL that the Log Agent will use to
transfer usage-log files when in Web-Service Transfer Mode.

TimeOutInterval The time in milliseconds the Log Agent will wait for a response
from the network before reporting a failure. It has a valid
range of 600,000 to 3,600,000 and a default value of
1,800,000.

Section: SMTP

Setting Description
SMTPServerHost The hostname or IP address of the SMTP email server the
Log Agent is to use when operating in Email Transfer Mode.

SMTPServerPort The port number that the Log Agent uses when
communicating with the SMPT server defined by the
SMTPServerHost setting.
MailFrom The email address that will appear in the From field in the
emails received by AVEVA.
MailTo The email address to which usage-logs are to be sent.
MailCC An optional email address to which copies of emails will be
sent.

Copyright 2015 AVEVA Solutions Limited Version 1.4, 13 February 2015 Page 9 of 10
 MailUserName The SMTP server user name the Log Agent will use to identify
itself.
MailPassword The SMTP server password that the Log Agent will use to
authenticate itself.
MailSSL A flag that indicates if SSL is required to be used when
communicating with the SMTP server: Valid values are:

true use SSL.

false do not use SSL

Section: Debug

Setting Description
DebugLogFile The name of a log file that will contain the messages
generated by the Log Agent when it runs. If left blank the Log
Agent will write messages to the console.
DebugLogFileMaxSize The maximum size in KB or MB after which the Debug log file
is rotated. Default value: 10MB.
DebugLogFileMaxCount Specifies the maximum number of rotated log files that will be
created by the Log Agent before it overwrites the original log
file.
Trace Set this to 1 to enabled more detail logging. This should only
be used when attempting to diagnose a problem.

Copyright 2015 AVEVA Solutions Limited Version 1.4, 13 February 2015 Page 10 of 10