This article describes the keystroke log file retrieval procedure from BoKS Server Agents up to and including BoKS 6.7. Although the kslog file retrieval mechanism has been completely changed in BoKS 7.0, this procedure still applies as long as there are BoKS 6.7 or older Server Agents in the domain.

The following assumes that hotfix HFBM-0062-3 (BoKS 6.7) or HFBM-0139-1 (BoKS 7.0) is installed on the Master.

Resolution / Workaround

Note: The hostname of the BoKS 6.7 Server Agent is "bksclnt" in the examples below.


The kslog command is part of the keystroke logged user session. When a keystroke logged session is started, a notification is sent to the Master. The notification is a simple one line text message and boks_master stores this in a regular file: $BOKS_var/new_reports.

The message contains the hostname, the message type label kslogsession and a file identifier. The file identifier consists of hostname, a PID and a timestamp, e.g.:

bksclnt kslogsession bksclnt#24794#1489770125


The getreports script reads and parses the messages in the new_reports file. Entries labeled kslogsession are appended to the $BOKS_var/active_kslog_sessions file (without the type label).

Sample active_kslog_sessions file entry:

bksclnt bksclnt#24794#1489770125

When the user's keystroke log session has finished, yet another message is sent to the Master and stored in $BOKS_var/new_reports. This message contains hostname, type label kslog, the keystroke log file name and an MD5 checksum. The file name in turn consists of hostname, PID, timestamp and sequence number, e.g.:

bksclnt kslog bksclnt-24794-1489770125-001.log.bkz MD5:27a8989a82261a295554d4fbc4a28f0b

When getreports is executed it attempts to retrieve the file using the cadm command. If that fails, the corresponding queue entry is saved in $BOKS_var/saved_reports to be tried at the next execution round. If it's successful the queue file entry is deleted and the corresponding entry in $BOKS_var/active_kslog_sessions is deleted as well.

Sample local kslog file name:


Sample saved_reports entry:

bksclnt kslog bksclnt-24794-1489770125-001.log.bkz MD5:27a8989a82261a295554d4fbc4a28f0b 1 1489770228


The $BOKS_var/active_kslog_sessions file is read by another script, kslog_check_active_sessions. This is executed on the Master once a day (typically 5 minutes past midnight). It reacts to entries in the active_kslog_sessions file that have expired (older than 24 hours by default). Unless KSLOG_FINALIZE_STALELOG is off in $BOKS_etc/ENV, the script executes kslog_finalize session-id via cadm on the corresponding Server Agent. The session-id argument is the second field of the record in the kslog_active_sessions file (e.g. bksclnt#24794#1489770125).


The kslog_finalize command is executed on the Server Agents. It is started remotely from the Master via kslog_check_active_sessions and locally via kslog_stalefile_check.

The kslog_finalize command takes a session ID as argument and maps that to a keystroke log file name in directory $BOKS_data/kslog by default. If a keystroke log file is found, the corresponding process PID is extracted from the filename. kslog_finalize then checks if this process is alive. If so it is assumed that the keystroke logged session is still active and kslog_finalize skips the session with no further action.

However, if the process is dead, kslog_finalize reads the status parameters from the file. If the file does not contain a CHECKSUM parameter, kslog_finalize adds RESTARTED=timestamp, STATUS=STALE, ENDTIME=timestamp and CHECKSUM=file-hash to the file and reports it to the BoKS Master with type label stalekslog ready to be retrieved.

If the CHECKSUM parameter is found, the file is just reported as stalekslog ready to be retrieved.

The message is sent to the Master to be handled by getreports.


There is another script - kslog_stalefile_check - which is executed locally on the Server Agents. It scans the $BOKS_data/kslog directory for potential stale keystroke log files and calls kslog_finalize to have them picked up by the Master. (The directory location is configurable in $BOKS_etc/ENV using the parameter KSLOG_LOGFILE).

kslog_stalefile_check is executed (with option -b) from the Boot script when the server is rebooted. It is also executed from BoKS cron.

* Boot

kslog_stalefile_check -b is executed when the machine is rebooted (Boot -b).

* BoKS cron

10 0 * * * $BOKS_lib/kslog_stalefile_check

i.e. executed once a day 10 minutes past midnight.

When called from Boot (kslog_stalefile_check is called with option -b) the script processes all files in $BOKS_data/kslog. In this case kslog_finalize is called on each keystroke log file located in this directory.

When called from cron (without option -b) it only considers files older than 7 days.

The argument given to kslog_finalize is a conversion of the actual local keystroke log file name through a sed script:

sed -e 's/-[^-]*$//' -e 's/-\([^-]*\)$/#\1/' -e 's/-\([^-]*\)$/#\1/'

E.g. I have a keystroke log file in directory $BOKS_data/kslog/ on the Server Agent named: bksclnt-22866-1458214844-001.log:

# echo bksclnt-22866-1458214844-001.log | sed -e 's/-[^-]*$//' -e 's/-\([^-]*\)$/#\1/' -e 's/-\([^-]*\)$/#\1/'

You can run kslog_finalize with debug traces enabled to find out more about what it is doing:

# /opt/boksm/lib/kslog_finalize -x9 bksclnt#22866#1458214844

The debug traces are written on stderr.

A kslog stale file retrieval test

  • A keystroke log session started on Sever Agent bksclnt. Log file is $BOKS_data/kslog/bksclnt-25082-1489784297-001.log
  • Message stored in $BOKS_var/new_reports on Master:
    bksclnt kslogsession bksclnt#25082#1489784297
  • getreports executed on Master. The new_reports entry moved into $BOKS_var/active_kslog_sessions:
    bksclnt bksclnt#25082#1489784297
  • Keystroke log session killed on Server Agent with kill -9 (to not give kslog a chance to clean up):
    # kill -9 ; kill -hup ; kill -hup
  • Waiting 24 hours (... or resetting the clock on the Master and Server Agent 24 hours into the future).
  • kslog_finalize executed on the Server Agent:
    # /opt/boksm/lib/kslog_finalize bksclnt#25082#1489784297
    The stale kslog is finalized and a message sent to the Master for retrieval of the file.
  • Message stored in $BOKS_var/new_reports on Master:
    bksclnt stalekslog bksclnt-25082-1489784297-001.log.bkz MD5:8f065da5f71d7219c5180a2afca78675
  • getreports executed on Master. The stale file is retrieved and stored in $BOKS_var/kslog/stale/bksclnt/
  • Sample meta data added to the kslog report file by kslog_finalize
    93129.335 L RESTARTED=1489877426
    93129.336 L FILESEQUENCE=1
    93129.336 L STATUS=STALE
    93129.337 L ENDTIME=1489877426
    93129.337 L CHECKSUM=MD5:8f065da5f71d7219c5180a2afca78675

Still have questions? We can help. Submit a case to Technical Support.

Last Modified On: May 25, 2018