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.
Charon-AXP/VAX 4.9 and Charon-HPA 1.10 and newer will grant a grace period of 12 hours after all valid licenses have disappeared. Older versions of these products and other emulator products will continue to run without a license until the next scheduled license check (default 1 hour).
Monitoring the Emulator on Linux
At the time of writing, the monitoring strategy for Charon-AXP+ is still being developed. Hence, the rest of this section refers to host-based Charon emulator products.
Emulator Log Files on Linux
If you use the Charon Linux Toolkit for Charon-AXP/VAX, you can use it to monitor the emulator log files and have it provide alerts should the license be removed or otherwise become unavailable.
Please refer to Charon Linux Toolkit for more information. The rest of this section provides an example of how to monitor the emulator log files with generally available Linux tools should it not be possible to use the Linux Toolkit.
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:
20160809:185509:INFO :0:000003E6:ll_sentine(1820): Performing regular license check ...20160809:185509:ERROR:2:000003E8:ll_sentine( 379): Sentinel HASP RunTime Error 7.20160809:185509:INFO :0:00000351:ethane.cxx(3056): session: Detected removal of the license. Normal operation is supported for 59 minutes from now.
|
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:
<lines removed>
|
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.
The messages in the emulator log file are not written immediately when the license is removed. With the exception of Charon-AXP/VAX 4.9, they are reported in the log when the emulator performs a periodic license check and discovers that the license has disappeared. Charon-AXP/VAX 4.9 writes messages to the emulator log (with a short delay) that reflect the messages written to the system log by aksusbd. The aksusbd daemon reports the removal of a license almost instantaneously in the system log.
If possible, use the monitoring capabilities of the Charon Linux Toolkit. This will provide alerts for both message types and additional monitoring features, for example monitoring and alerting based on counters.
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:
# yum install logwatch |
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.
Most of the general settings can also be modified by command-line parameters when starting the program. Please refer to the logwatch man page.
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
This example is very much simplified and will not work for all cases. Should the Charon log file format change in the future, it will have to be modified. It is intended to demonstrate the concept and is not a solution suited for a production environment.
The examples of the analysis script and the time stamp adaption script are specific to the Charon-AXP and Charon-VAX products. Different formats are required for the Charon-SSP and Charon-HPA products.
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:
LogFile = "ds20-v1.log" |
The name of the log file must be specified relative to the LogDir parameter (default /var/log). Wildcards are possible.
The Charon-AXP/VAX log file configuration can be set to automatically rotate the log file at configurable intervals. If this is the case, the currently active log file can be accessed by a softlink with the default name <hw-model>.log. The LogFile parameter can be set to the softlink. As the logwatch command is typically started via the cron utility, it will automatically use the current log file. Other Charon products also provide a log-rotation feature. Please refer to the appropriate product documentation for details.
Note: Even though there would have to be frequent runs to catch the message about a removed dongle before the emulator stops, there is a small risk that the log rotation and the logwatch run could overlap, causing the dongle removal message to be missed. Hence, the use of rotating log files is not recommended when using logwatch. This risk can be avoided by using the Linux Toolkit.
Some versions of logwatch convert the log file path to lowercase. This prevents the log files from being found if uppercase characters are used in the LogDir target. A workaround is to create a softlink consisting of lowercase characters pointing to the target directory and to use the softlink as the LogDir value.
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:
|
For Charon-AXP/VAX version 4.9, the egrp-line above must be adapted to the new log-messages format. For example to "if echo $LINE|egrep '(00000424|Communication with the license key|Application will stop)' &> /dev/null;"
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):
|
The script above does not cover all parameters possible for the range parameter of logwatch. It is provided only as an example for informational purposes.
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:
*/5 * * * * /usr/sbin/logwatch --logdir=/opt/charon/log --output=mail --mailto=root |
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
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:
$ journalctl --since="$(date '+%Y-%m-%d %H:%M:%S' -d '5 minutes ago')" -t aksusbd --no-pager |
If a dongle had been removed within this timespan, the output is similar to the following:
Aug 12 14:57:49 host1 aksusbd[17450]: aksusbd_usb_dev_remove: device '/dev/aks/hasp/1-14.2'
|
If a dongle is connected, a message similar to the following will be displayed:
Apr 11 19:44:37 redhat7.localdomain aksusbd[15047]: aksusbd_usb_dev_connect: device '/dev/aks/hasp/2-1'
|
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:
|
If you use Charon-AXP/VAX, the Linux Toolkit can be used to implement this monitoring option.
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:
| Parameter | Description |
|---|---|
| hasp_lost_usr_cmd | Runs a user-defined script or a executable if Charon disconnects from current valid license and no other valid license is found. This action is called every hour during the 12 hours grace period (at the end of which Charon-HPA stops unless a license has been found). The script or command started receives three parameters from Charon-HPA: key-id, product-license-id, and termination time. Usage example: |
| license_changed_usr_cmd | Runs a user-defined script or an executable when Charon-HPA disconnects from one license and connects to another for any reason. The script or command started receives four parameters from Charon-HPA: old-key-id, old-product-license-id,new-key-id, and new-product-license-id. Usage example: |
| license_expiration_warning_usr_cmd | Runs a user-defined script or an executable when the license expiration time is within few hours. The default setup is: starting 24 hours before expiration this script is invoked each hour. The script or command started receives three parameters from Charon-HPA: key-id, product-license-id, expiration time. Usage example: |
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
license_logging_level = 2
to the emulator configuration file. Setting the parameter to 0 or 1 will enable 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:
20160809:185509:INFO :0:000003E6:ll_sentine(1820): Performing regular license check ...20160809:185509:ERROR:2:000003E8:ll_sentine( 379): Sentinel HASP RunTime Error 7.20160809:185509:INFO :0:00000351:ethane.cxx(3056): session: Detected removal of the license. Normal operation is supported for 59 minutes from now.
|
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:
|
The following Charon-AXP/SMA log file excerpt shows the message written after the dongle has been removed:
2016-10-04 01:43:15:231: ES40-1: license: Error 7, CHARON can't detect HASP key and will shutdown within 60 minutes2016-10-04 01:58:15:243: ES40-1: license: Error 7, CHARON can't detect HASP key and will shutdown within 45 minutes2016-10-04 02:13:15:253: ES40-1: license: Error 7, CHARON can't detect HASP key and will shutdown within 30 minutes2016-10-04 02:28:15:260: ES40-1: license: Error 7, CHARON can't detect HASP key and will shutdown within 15 minutes2016-10-04 02:43:15:269: ES40-1: license: Emulator stopped on error 7...Appropriate license key is not present
|
Basic Information About Log Monitor & Dispatcher
Location of the Log Monitor & Dispatcher:
Charon-AXP/VAX versions before version 4.8: Depending on the type of host system (x64 or x86) used, the program will be located in the x86 or the x64 subdirectory in the C:\Program Files\CHARON\Utilities_<version>\ directory.
Charon-AXP/VAX versions 4.8 and higher: The installation directories for all the utilities and Charon executables are C:\Program Files\CHARON\Build_<version>\x86 and C:\Program Files\CHARON\Build_<version>\x64 depending on the architecture of the host system.
The examples in this chapter use the x64 architecture.
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).
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.
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.
Description | Commands to Start logmond as a Background Application |
|---|---|
Start logmond for a single log file. |
|
or | |
Start logmond for a rotating log file. |
|
<log-directory> is the directory where the rotating log files are stored <log-prefix> is the same as the configuration_name value in corresponding Charon configuration file (or hw_model if configuration_name is not specified). |
Several Log Monitor & Dispatcher processes can run simultaneously.
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
When the Log Monitor & Dispatcher runs as a Windows service, it will detect Charon instances that also run as Windows services. It cannot detect Charon instances that are manually started or started via the Charon Launcher.
To monitor the log files of manually started instances, use logmond in background mode as described above.
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.
Step | Description | Commands to Install logmond as a Windows Service |
|---|---|---|
1 | Remove an existing service, if needed. |
|
2 | Install logmond as a service |
|
3 | Start the service |
|
By default, the service configuration is set for manual startup. To start it automatically at system startup, modify the setting in the Windows Service management tool.
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.
The script cannot execute interactive applications.
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:
Sample content of 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.
If you installed this utility manually before installing Charon-AXP V4.8, the scheduled task will remain unchanged.
If you remove all Charon emulator products from the server, the scheduled task will be disabled. It will not be deleted.
For versions prior to Charon-AXP/VAX 4.8 the utility can be installed manually. Please refer to Charon on Windows - Automated License Expiration Check for details on the use of this tool.