You are on page 1of 10

Licensing Log Agent

User & Configuration Guide


V1.3

Copyright 2014 AVEVA Solutions Limited

Page 1 of 10

Table of Contents
1

INTRODUCTION ........................................................................................................................... 3

PLANNING YOUR LOG AGENT CONFIGURATION ................................................................... 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

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 2014 AVEVA Solutions Limited

Version 1.3, 17 December 2014

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 2014 AVEVA Solutions Limited

Version 1.3, 17 December 2014

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 2014 AVEVA Solutions Limited

Version 1.3, 17 December 2014

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
3.4.1

Web-service Transfer Mode Settings


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 2014 AVEVA Solutions Limited

Version 1.3, 17 December 2014

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 2014 AVEVA Solutions Limited

Version 1.3, 17 December 2014

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
3.6.1

Manual Transfer Mode Settings


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 2014 AVEVA Solutions Limited

Version 1.3, 17 December 2014

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 2014 AVEVA Solutions Limited

Version 1.3, 17 December 2014

Page 8 of 10

Appendix A Log Agent INI File Settings


Section: Customer Information
Setting
CustomerCode
LocationCode

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

Section: Backup
Setting
Handler

Description
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
UsageTransferMode

Description
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
ServiceURL

Description
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
SMTPServerHost

Description
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.
The email address that will appear in the From field in the
emails received by AVEVA.
The email address to which usage-logs are to be sent.
An optional email address to which copies of emails will be
sent.

MailFrom
MailTo
MailCC

Copyright 2014 AVEVA Solutions Limited

Version 1.3, 17 December 2014

Page 9 of 10

MailUserName
MailPassword
MailSSL

The SMTP server user name the Log Agent will use to identify
itself.
The SMTP server password that the Log Agent will use to
authenticate itself.
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
DebugLogFile

DebugLogFileMaxSize
DebugLogFileMaxCount

Trace

Description
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.
The maximum size in KB or MB after which the Debug log file
is rotated. Default value: 10MB.
Specifies the maximum number of rotated log files that will be
created by the Log Agent before it overwrites the original log
file.
Set this to 1 to enabled more detail logging. This should only
be used when attempting to diagnose a problem.

Copyright 2014 AVEVA Solutions Limited

Version 1.3, 17 December 2014

Page 10 of 10