This section describes how certain aspects of the license status can be monitored.

Introduction

The emulator periodically checks the presence of a valid license. The checking period is specified on the license (default: once per hour) and can be different for the different Charon emulator products. Should no valid license be found, this will be logged in the emulator log file. As the emulator continues to run only for a limited time without the license, it is important to receive timely information about the license problem. This section describes some methods for monitoring the log file on Linux and Windows.

Monitoring the Emulator on Linux

Emulator Log Files on Linux

The log-file contents differ depending on Charon products and versions. The following shows some examples:

The following Charon-AXP/VAX log file excerpt shows the message written after the license dongle has been removed for Charon-AXP/VAX versions before version 4.9:

The following Charon-AXP/VAX log file excerpt shows the message written after the license dongle has been removed for Charon-AXP/VAX version 4.9:

The following Charon-SSP log file excerpt shows the message written after the license dongle has been removed:

The following Charon-HPA version 1.7.4 log file excerpt show the message written after the connection to the license dongle has been lost or the dongle has been removed:

20160927:150512.34743:PDC CHASSIS:0XCE0F State=  INITIALIZE

20160927:150619.152882:Device EWA0 (enp6s0) : RX up

20161009:200646.683932:err:Contact with license key lost ...

20161009:200646.684279:err:Please reinsert the key within 15 minutes

otherwise emulator will stop.

The following Charon-HPA version 1.11 log file excerpt show the message written after the connection to the license dongle has been lost or the dongle has been removed:

Monitoring the Emulator Log Files Using logwatch

If the use of the Linux Toolkit is not an option for some reason, there are several different ways log files can be monitored on Linux. One possibility is to use the logwatch utility.

The following very basic example shows how to monitor the emulator log files with logwatch and send an email if the dongle removal message appears in the emulator log file. 

 This example does not apply to Charon-SSP Baremetal.

Installing logwatch

Logwatch is available via the standard repositories of the supported Linux versions. If it is not yet installed, the installation can be performed using the command:

Information on how to customize logwatch can, for example, be found here: http://www.stellarcore.net/logwatch/tabs/docs/HOWTO-Customize-LogWatch.html.

Creating a logwatch Setup for Charon Log Files

The Charon log file must be added to the logwatch configuration before it can be monitored.

All customizations should be done on files in the directory /etc/logwatch.

To change settings in the general logwatch configuration, copy the file /usr/share/logwatch/default.conf/logwatch.conf to the directory /etc/logwatch/conf/. In this copy you can modify the settings as desired. For example, the email address to which notifications will be sent.

The following files must be added to the logwatch configuration in order to monitor the Charon log file:

• Log file definition file
• Service definition file
• Log file analysis script
• Timestamp adaption file

Logwatch Example

1. Create the log file definition file:

Create a file with the names of the log files in the directory /etc/logwatch/conf/logfiles/.

For example, add a file named /etc/logwatch/conf/logfiles/charon.conf with the following content:

The name of the log file must be specified relative to the LogDir parameter (default /var/log). Wildcards are possible.

2. Create the service definition file:

Create a file including the name of the log file definition in the directory /etc/logwatch/conf/services/.

For example, add a file named /etc/logwatch/conf/services/charon.conf with the following content:

3. Create the log file analysis script:

Create a script in the directory /etc/logwatch/scripts/services/ that is able to extract the relevant messages from the Charon log file. The script will receive the lines of the log file via standard input.

For example, create a file named /etc/logwatch/scripts/services/charon with the following content:

4. Create a timestamp adaption script:

The time range that can be provided to logwatch must be translated into the timestamps of the Charon emulator log file. To do this, create a file in the directory /etc/logwatch/scripts/logfiles/charon/ containing the necessary commands.

For example, create the file /etc/logwatch/scripts/logfiles/charon/applydate with the following content (as an existing applydate script was used as template, the copyright must be preserved):

5. Run the logwatch command to check the Charon emulator log file for a removed license message:

This command overrides the LogDir, mail, range and service parameters of the default configuration. A command similar to this could be added to crontab in order to check the Charon emulator log file every few minutes.

Sample crontab entry (for the root user) to check the Charon log file every 5 minutes:

If the error code indicating a removed dongle is found in the indicated time range, a mail similar to the following will be sent to the root user (the email content can be customized).

The following exhibit shows a sample logwatch message for Charon-AXP/VAX versions before Charon-AXP/VAX 4.9:

The following exhibit shows logwatch sample logwatch message for Charon-AXP/VAX 4.9:

Monitoring aksusbd Messages in the Linux System Log

 This example does not apply to Charon-SSP Baremetal as the underlying operating system is not accessible to the user.

The background process aksusbd logs its messages via the journald daemon. These logs can be extracted using the journalctl command.

To extract messages specific to the aksusbd software for the last five minutes, use the following command:

If a dongle had been removed within this time span, the output is similar to the following:

If a dongle is connected, a message similar to the following will be displayed:

A journalctl command similar to the one above can be run regularly within a cron-job that sends an alert if the license has been removed. This method of monitoring has the advantage of being independent of different emulator log file formats and the different check periods set for the individual products. 

Charon-AXP/VAX version 4.9 and Charon-HPA version 1.10 and newer also show messages corresponding to the journalctl messages in the emulator log file (with a delay of about one minute) that can be captured by log monitoring tool such as logwatch. Below is a sample for the Charon-AXP/VAX product:

Charon License Expiration Check

The Charon Linux Toolkit includes a license expiration check utility that can send alert emails, and/or execute a custom script, a specified number of days before the license expires. This utility can be installed in standalone-mode to be used on Charon-AXP, Charon-VAX, Charon-SSP (non-Baremetal versions) and Charon-HPA without installing the Charon Linux Toolkit.

To download the utility, you must issue a request via email to the Stromasys support team or ask your reseller.

Please refer to How-to install Charon license expiration check on a Linux server for detailed installation and configuration instructions.

Charon-HPA Special Monitoring Options

Charon-HPA versions 1.10 and higher offer an additional feature to support alerts in the case of license problems.

The Charon-HPA configuration file supports the following new parameters that can be used to alert the user to potential license problems:

License logging level:

Starting with Charon-HPA version 1.11, periodic (once per hour) log messages indicating a successful periodic license check are disabled by default to avoid cluttering the log file. They can be re-enabled by adding the parameter

system.license_logging_level = 2

to the emulator configuration file. Setting the parameter to 0 or 1 will disable the messages.

Please note that this parameter must be placed towards the end of the configuration file and will not work if placed before the memory configuration.

Monitoring the Emulator Log File on Windows

Charon-AXP/VAX/PDP come with the logmond (Log Monitor & Dispatcher) utility. This utility can monitor the emulator log for events indicating that the license has been removed. The knowledge base article CHARON Log monitoring on Windows (logmond) describes the use of this tool in detail. This section will provide an example for one possible use.

Currently, there is no comparable utility for the Charon-AXP/SMA product.

Emulator Log File Examples

The following Charon-AXP/VAX log file excerpt (before version 4.9) shows the message written after the license dongle has been removed:

The following log file excerpt from Charon-AXP/VAX 4.9 shows the messages written after the license has been removed, the periodic checks to verify whether the license has become available again, and finally the message to indicate the stop of the emulator due to the missing license:

 Please note that not all messages are shown in the log excerpt above because the configuration parameter log_repeat_filter was set to on (default).

To receive all messages, this parameter must be set to off in the emulator configuration file. This will create a more detailed output as shown below. In particular, it shows the grace period after which the emulator will stop:

The following Charon-AXP/SMA log file excerpt shows the message written after the dongle has been removed:

Basic Information About Log Monitor & Dispatcher

The program runs in the background either as a normal program or as a Windows service and monitors the emulator log files for events indicating the removal of the license (message code 0000002A, 00000351, or 00000424 - depending on Charon-AXP/VAX version).

When such an event is detected, logmond runs a file named nolicense.bat. This file contains the custom actions to be performed when the event is detected. For example, it can be used to create an entry in the Windows event log or to send an email.

 Starting with version 4.9 of Charon-AXP/VAX, logmond will also monitor messages with code 0000040B in the log file (indicating that the emulator has started to use a different license). If such a message occurs, it will run a file called license_changed.bat. The examples in this section refer to the nolicense.bat file.

To see all the command-line options of the utility open a command window (press WIN+R and enter cmd.exe or use the Start menu) and enter the following command:

This will display a list program options in a separate window, similar to the one below:

Working with the Log Monitor & Dispatcher

The logmond program can be started manually in background mode for the log files of individual emulator instances or as a Windows service. If started as a service, it will detect all emulator instances that also run as Windows services.

Recommendations:

Make sure that the nolicense.bat file is located in the home directory of the Charon emulator instance you want to monitor.

Use the rotating log files mechanism or use a single log file with append mode.

Install your emulator instances as services, they will then be able to start when the Charon Windows server boots. Then install and start the Charon log monitor also as a Windows service (named EmulatorLogMonitor). This eliminates the need to start logmond manually and newly added emulator services will be automatically taken into account.

Starting and Stopping the Log Monitor & Dispatcher in Background Mode

Starting logmond

To start logmond as a normal program running in the background: 

Press WIN+R and enter cmd.exe or start the command window via the Start menu.

Change the current directory to the folder containing the Charon log file and the nolicense.bat file.

Start the Log Monitor & Dispatcher to work with one log file or rotating log files, as shown below.

Stopping logmond

To stop the Log Monitor & Dispatcher application, open the Task Manager, find the logmond.exe process and terminate it.

Starting and Stopping the Log Monitor & Dispatcher as a Windows Service

Adding and Starting logmond as a Service

To add logmond as a Windows service named EmulatorLogMonitor and to start it:

Open the command window (cmd.exe) via the Start menu using the Run as Administrator option.

Install the Log Monitor & Dispatcher as a Windows service using the commands shown below.

Stopping the Service

You can stop the service using the Windows Service management tool, or you can enter the following command in a command window (as Administrator):

The nolicense.bat File

If the Log Monitor & Dispatcher detects that a license was removed, it executes the file nolicense.bat. This file contains the command needed to alert the user to the fact that the Charon license was removed from the system.

Path Considerations with Respect to nolicense.bat

To start nolicense.bat, logmond checks its current directory for the existence of nolicense.bat. 

The current directory for this purpose depends on how logmond was started:

If logmond is started with only the path to the log file, the current directory will be the one in which the user is while starting the background process. Change your current working directory to the one containing nolicense.bat before starting logmond.

If logmond is started as a service with a specific log file path passed to it, it will also consider the directory from which the user performs the command as the current directory. So, change your current working directory to the one containing nolicense.bat before starting the service.

If you start logmond providing the Charon service name, the program will use the home directory of the Charon service as its current directory. So, the nolicense.bat file has to be in this directory as well.

If you start logmond with the -e parameter (automatically assumed when creating a Windows service as described in the section above), a slave process will be created for each additional Charon service and the home directory of this service will be the current working directory of the slave process. This is where the nolicense.bat file should be kept.

To find the home directory of a specific Charon service, open the CHARON service manager, right-click on the emulator name in question and select View Configuration from the menu. The picture below shows an example.

Example: Create a Windows Event

A variety of mechanisms can be implemented in nolicense.bat to inform the user about the license problem. Examples:

Create a Windows event.

Send an email or perform other actions using a PowerShell script.

The following example shows a one line nolicense.bat file to create a Windows event:

Stromasys recommends using the PowerShell command to write events instead of the "eventcreate" program as some other events are created with PowerShell scripts. Using the eventcreate command in this case will fail as the source, Charon, will not be accepted.

This example will create the following event if the license is removed:

The parameters set in the nolicense.bat file are highlighted in the screenshot above.

Using the Windows Event viewer and the Windows Task Manager, it is also possible to attach an action to the event, such as running a program.

License Expiration Check on Windows

Starting with Charon-AXP/VAX/PDP version 4.8 the license expiration check utility is installed with the Charon emulator kit. The details of this utility are described in the user's guides of the Charon-AXP/VAX/PDP for Windows. This section provides a short overview.

This utility is executed once a day at 09:00 AM and will send Windows Application Events 15 days before license expiration. No other action will be taken unless you customize the expiredlicense.bat script.

The installation process installs the utility and the default expiredlicense.bat file under the Charon installation folder, usually in C:\Program Files\CHARON\Redistributables\Stromasys. It also provides examples on how to send alerts via email.