nShield Audit Log Service
Introduction
The nShield Audit Log Service (nshieldauditd) retrieves and removes audit logs from HSMs that are available to the local hardserver and are listed in the nShield audit log service’s configuration file.
There are two types of audit logs: nCore audit logs and signed system logs.
It retrieves nCore audit logs, see Audit Logging, from PCIe HSMs running firmware version 13.5 or later and from network-attached HSMs running firmware version 13.6 or later.
nShield Audit Log Service and the new audit databases support the new audit logs for 13.5 firmware onwards only.
It does not retrieve the CEF-format audit logs from earlier firmware versions (the legacy audit configuration settings in [auditlog_settings] continue to be supported for those logs, and verification thereof can be done with the separate cef-audit-verify tool).
|
It also retrieves signed system logs from nShield 5s HSMs running firmware version 13.5 or later and nShield 5c HSMs running firmware version 13.6 or later. See System logging (nShield 5 HSMs).
Both types of logs are saved in separate local database files stored by default in a subdirectory of NFAST_KMDATA.
The service must be configured to enable log fetching from available HSMs. Once configured, the service runs automatically in the background without user intervention.
| Connect XC and 5c HSMs enrolled in a Security World with audit-logging enabled (including a Common-Criteria (CMTS) compatible Security World) will continuously generate nCore audit-logs and, if these audit-logs are not transferred and removed by the nshieldauditd service, the HSMs may run out of disk space and will not process certain commands until their audit-logs are transferred and removed. |
| 5s and 5c HSMs generate signed system logs internally in v13.5 onwards. These logs also need to be transferred and removed by the nShield Audit Log Service. This is true even when the Security World does not have audit-logging enabled. |
nShield Audit Log Service configuration
The nShield Audit Log Service is configured by editing a YAML-format configuration file. Configuration changes can be applied by restarting the service.
Restarting nshieldauditd on Linux
The nShield Audit Log Service can be restarted on Linux by running the following command as root:
/opt/nfast/scripts/init.d/nshieldauditd restartInstead of restart use stop followed by start parameters to explicitly stop and start the service respectively.
Restarting nshieldauditd on Windows
The service can be stopped and started from an elevated (Administrator) Windows command prompt using these commands:
net stop "nShield Audit Log Service"
net start "nShield Audit Log Service"To restart the service as a single operation, run the following PowerShell command from an elevated (Administrator) PowerShell shell:
Restart-Service "nShield Audit Log Service"Editing the configuration file on Linux
The configuration file is located at /opt/nfast/kmdata/auditlogs/nshieldauditd.conf.
Editing the file requires membership of the nfast group.
Editing the configuration file on Windows
The configuration file is located at C:\ProgramData\nCipher\Key Management Data\auditlogs\nshieldauditd.conf by default.
Editing the file requires the privileges of the built-in local Administrators group.
Default configuration file
The default configuration is created when the service first starts, and looks as follows:
# nShield Audit Log Service config file
#
# This configuration file is in yaml format.
#--------------------------------------------------------------------
# modules is the list of ESNs of HSMs from which to fetch nCore and
# (if applicable) syslog audit.
# By default, no modules are included in the list.
# Set modules: ["AAAA-AAAA-AAAA", "BBBB-BBBB-BBBB"] to enable fetching
# of audit from modules with ESNs AAAA-AAAA-AAAA and BBBB-BBBB-BBBB
# Comment out or delete the modules: [] line to fetch audit from
# all modules.
modules: []
#--------------------------------------------------------------------
# syslog_fetch_interval_hours specifies the time in hours to wait
# between fetching the nShield 5 HSM syslog audit.
# It is always fetched when the service first starts.
# Default value is 12.
#syslog_fetch_interval_hours: 12
#--------------------------------------------------------------------
# suppress_repeat_logs_interval specifies the time
# to wait for repeated log messages to be logged again.
# Set interval values in 's'(seconds), 'm'(minutes), or 'h'(hours),
# for example: '0s', '5m', '10h' etc.
# If set to '0s' then no logs will be suppressed.
# Recommended to set it to '0s' while in debug mode.
# Default value is '5m'.
#suppress_repeat_logs_interval: '5m'
#--------------------------------------------------------------------
# logging_level controls the verbosity of log messages from the nShield Audit Log Service's own operations (not the audit logs themselves)
# Available levels in increasing order of severity are DEBUG, INFO, WARNING, ERROR, or CRITICAL (default is INFO)
#logging_level: INFOConfigurable options
modules
The nShield Audit Log Service only fetches logs from the modules that are specified in the configuration file.
If the modules field is commented out or absent then all HSMs available to the local hardserver will be monitored by the nShield Audit log service;
this provides a shorthand if the goal is to fetch audit from all enrolled modules.
By default, the modules field is an empty list, so this must be configured to enable the fetching of logs.
Only one client system of the modules should enable log fetching, otherwise the audit log services will conflict with each other;
that is why the user must explicitly opt-in to enable the fetching, to prevent any conflicts from default configuration.
You can add or remove a module by editing the configuration file and restarting the nShield Audit Log Service.
The ESN of each module to be enrolled should be specified within quotes and separated with a comma.
| To fetch nCore or signed system logs from a network-attached HSM (Connect XC or 5c) the client machine where the nShield Audit Log Service has been configured must have been enrolled as a privileged client of that HSM. |
| Security World HSM estates with multiple client machines must configure just one client’s nShield Audit Log Service to monitor any given HSM, although different nShield Audit Log Services may be configured to monitor different subsets of HSMs. If multiple services fetch logs from the same HSM, then each client’s databases will only contain some of the log records. |
syslog_fetch_interval_hours
This option configures how often the service should fetch the signed system logs from the HSM.
By default, syslog_fetch_interval_hours is commented out and the default value of 12 hours will be used.
The interval in the configuration file is in hours. The interval must be set in between 1 and 168 hours.
| Signed system logs are produced at a relatively low rate, and fetching and removing the logs itself produces an audit record. This is why fetching of the logs is infrequent, unlike the continuous streaming of records that is done for nCore audit. |
| Signed system logs are not produced by nShield Solo XC and nShield Connect XC HSMs. |
suppress_repeat_logs_interval
This option configures how often the service should show repeated log messages.
By default, suppress_repeat_logs_interval is commented out and the default value of 5 minutes will be used,
The interval for log suppression can be set in seconds, minutes or hours.
It is recommended to set the suppress_repeat_logs_interval to 0 when debugging.
|
logging_level
This option configures how much debug information is recorded in the service’s application log. This is for monitoring the nShield Audit Log Service’s operation in fetching nCore and signed system logs, and does not control the verbosity of that actual audit log data.
By default the service logging level is set to INFO, which will also report any higher severity messages.
This is the recommended setting, although logging can be reduced by setting WARNING, ERROR, or CRITICAL to restrict only to messages at that log level or above.
If additional logging is desired, the DEBUG setting can be set, but note that this will write considerably more information to the service log, and will also slow down service operation as it will also include a human-readable representation of the nCore audit logs as they arrive.
This is only recommended when investigating issues or if advised to do so by nShield Support.
On Linux, the service debug log is /opt/nfast/log/nshieldauditd.log.
On Windows, the service debug log can be viewed in the Windows Event Viewer (nCipherAuditSvc event source) or can be queried using nshieldeventlog -s nCipherAuditSvc -c 10 (for example) to view the most recent 10 lines of the service Event Log (adjust -c parameter for a larger number of lines, or use the -f parameter to write to a file).
When first configuring the system, it is recommended to check the service debug log to ensure that it reports that it has detected the intended modules and enabled log fetching for them.
Warrants
The nShield Audit Log Service attempts to retrieve the KLF2 warrant for each configured module automatically. It stores the warrants in the nCore audit log database for their module.
In nShield 5 HSMs, this warrant is embedded in the module and is always available.
In nShield XC HSMs, the KLF2 warrant must be present in one of the following locations in the filesystem of the machine running the nShield Audit Log Service, depending on how you are interacting with the HSM:
-
/opt/nfast/kmdata/warrants(Linux) orC:\ProgramData\nCipher\Key Management Data\warrants(Windows)
This is the same location as where a warrant should be placed if using nShield Remote Administration smartcards. -
/opt/nfast/kmdata/hsm-<ESN>/warrants(Linux) orC:\ProgramData\nCipher\Key Management Data\hsm-<ESN>\warrants(Windows)
Where<ESN>is the ESN of the relevant module.
This is where nShield Connect XC warrants are automatically placed on the RFS. If the warrant is not here, you will need to reconfigure (see rfs-setup) and reboot the HSM to copy the warrant to the correct location.
|
nShield Connect XC To run the nShield Audit Log Service on a different client machine to the RFS, you must first copy the warrant file to |
If there was no warrant present when the nShield Audit Log Service was started, you can still verify the chain up to the root of trust post-hoc with nshieldaudit.
Copy the warrant to /opt/nfast/kmdata/warrants or C:\ProgramData\nCipher\Key Management Data\warrants on the machine where you are running nshieldaudit.
When it displays the information, for example in nshieldaudit ncore query, it always re-runs the verification of the chain and will pick up the warrant from the aforementioned location.
|
Log databases
The nShield Audit Log Service saves the nCore audit logs and signed system logs in local database files.
Logs for each module are saved in their own database in a subdirectory of the auditlogs directory named after the ESN of that module.
To back-up the log databases, first stop the nShield Audit Log Service, recursively copy the auditlogs directory, then start the service again.
Stopping the service during backup ensures that a consistent state of the database files is copied, with no temporary transaction files being present.
If restoring from backup, the original permissions and ownership of files and directories should be restored.
|
Linux
The databases are located in /opt/nfast/kmdata/auditlogs.
The directory and its contents have read and write permissions for nfast group by default.
To restrict access to a different group, run the /opt/nfast/sbin/install script with NSHIELDAUDITD_GROUP environment variable set to the name of the alternate group.
This must be set every time install is run in order to retain this setting.
The nshieldauditd service user will be added to the alternate group automatically, and the group will be created during install if it does not already exist.
Windows
The databases are located in C:\ProgramData\nCipher\Key Management Data\auditlogs.
Access is restricted to members of the built-in Administrators group (with elevated privilege) and the nShield Audit Log Service itself. To allow access to other users or groups without elevated privilege, the DACL of the directory may be modified, but note that it will be reset to defaults when the nShield software is re-installed.
Alternative log database directory
The above log database locations can be overridden by setting the environment variable NFAST_AUDIT_LOGDIR to the alternative location.
This can be another local directory, or a network share.
If NFAST_AUDIT_LOGDIR is set, that also changes the service configuration file location to be inside that directory, that is, NFAST_AUDIT_LOGDIR/nshieldauditd.conf.
Set the environment variable NFAST_AUDIT_SERVICE_CONF if a different location is desired for the configuration file.
These environment variables must be set in the environment of the service, and of any tools which read the logs.
On Windows, set the environment variables in the Windows system variables, and on Linux in the /etc/nfast.conf file, in order to make them visible to the service.
The service must be restarted for the change to take effect.
| If you already have audit logs stored in the default location, it is recommended that the nShield Audit Log Service be stopped, the existing contents moved to the new location, and then the service started after setting the environment variables, so that the existing portion of the logs are not lost. |
Read the audit log databases
The nShield Audit Log Service databases are accessed with the command line tool nshieldaudit which manages logs using different subcommands as explained in the following sections.
By default, running the nshieldaudit subcommands requires membership of nfast group on Linux and an elevated (Administrator) command prompt on Windows.
nshieldaudit <subcommand>
The audit logs in the databases are not in a human-readable format.
Therefore, to be made human-readable, they must be exported to a file using the nshieldaudit tool.
|
Timestamps reported by nshieldaudit and in the audit logs themselves are UTC.
|
nshieldaudit supports the following subcommands:
Reading signed system logs
The nshieldaudit syslogs subcommand allows the user to access the signed system logs stored in the database.
nshieldaudit syslogs [-h] {query,export,info}This subcommand takes the following parameters:
| Parameter | Description |
|---|---|
--help or -h |
Show the help message and exit |
query |
Show the contents of the signed system logs database |
export |
Export the audit data to a file in JSON format |
info |
An overview of one or more log entries |
Querying available signed system logs
Use the nshieldaudit syslogs query subcommand to quickly see what signed system logs databases are available, an overview of the date and sequence ranges of their content, and a "Log Status" to summarize any detected verification errors or missing data.
nshieldaudit syslogs query [-h] [-e ESN(s) [ESN(s) ...]]The subcommand nshieldaudit syslog query takes the following parameters:
| Parameter | Description |
|---|---|
--help or -h |
Show the help message and exit |
-e ESN(s) [ESN(s) …] or --esn ESN(s) [ESN(s) …] |
One or more ESN(s) of the HSM(s) that generated the audits |
A typical output looks like the following:
$ nshieldaudit syslogs query
--esn AAA1-BBB2-CCC3
Sequence numbers: --start 1 --end 7775
Time: --from 2024-01-13_12:11:03 --to 2024-05-28_08:31:40
Malformed Logs: 0
Unverified Logs: 0
Unattested Logs: 0
Missing Sequences: None
Log Status: OK
--esn 1ABC-1DEF-1GHI
Sequence numbers: --start 13 --end 125
Time: --from 2024-05-23_13:05:48 --to 2024-05-28_07:48:33
Malformed Logs: 0
Unverified Logs: 0
Unattested Logs: 0
Missing Sequences: 1-12
Log Status: Issues foundnshieldaudit syslogs info
This subcommand allows the user to see a more detailed summary of the available signed syslogs, for a given ESN, than the nshieldaudit syslogs query subcommand.
It allows the time ranges and number of log lines in each of the sequence numbers in the signed syslogs to be listed, in support of constraining the range of interest when retrieving the log contents using the export subcommand.
nshieldaudit syslogs info [-h] -e ESN(s) [ESN(s) ...] [--start START_INDEX] [--end END_INDEX] [--from FROM_DATE] [--to TO_DATE]The subcommand nshieldaudit syslog info takes the following parameters:
| Parameter | Description |
|---|---|
--help or -h |
Show the help message and exit |
-e ESN(s) [ESN(s) …] or --esn ESN(s) [ESN(s) …] |
One or more ESN(s) of the HSM(s) that generated the audits |
The subcommand nshieldaudit syslog info allows the user to add the following filters:
| Parameter | Description |
|---|---|
--start START_INDEX |
Start index of the audits desired |
--end END_INDEX |
End index of the audits desired |
--from FROM_DATE |
Start date of the audits desired (UTC) |
--to TO_DATE |
End date of the audits desired (UTC) |
Exporting signed system logs to JSON format or text format
Use the subcommand nshieldaudit syslogs export to export the signed system logs data to a file.
The output file is written in JSON format (default), or in the human-readable text format if the -t or --text parameter is added.
nshieldaudit syslogs export [-h] -e ESN(s) [ESN(s) ...] [-v] -f FILE [--overwrite] [--malformed] [-t] [--start START_INDEX] [--end END_INDEX] [--from FROM_DATE] [--to TO_DATE]The subcommand nshieldaudit syslog export takes the following parameters:
| Parameter | Description |
|---|---|
--help or -h |
Shows the help message and exits |
-e ESN --esn ESN |
Required: the ESN of the module whose signed system logs is to be exported |
-v, --verify |
Re-verify signatures whilst exporting; this significantly increases export time. (default is to report cached verification status) |
-f FILE, --file FILE |
Required: Store output in this file (in JSON format) |
--overwrite |
Overwrite the output file if it exists |
--malformed |
Export malformed logs |
-t, --text |
Export of human-readable summary of logs in the text format rather than full JSON |
The subcommand nshieldaudit syslog export allows the user to add the following filters:
| Parameter | Description |
|---|---|
--start START_INDEX |
Start index of the audits desired |
--end END_INDEX |
End index of the audits desired |
--from FROM_DATE |
Start date of the audits desired (UTC) |
--to TO_DATE |
End date of the audits desired (UTC) |
Run nshieldaudit syslogs query first in order to get parameters that can be copied to produce the nshieldaudit syslogs export command-line.
|
By default, the output format is JSON format (it is formatted with whitespace indentation to also be human-readable).
To emit in a more compact human-readable text format, add the --text parameter.
In many cases --text will be the more convenient format to use for browsing the data, and it is faster to export and produces a smaller output file.
Example command (text output):
nshieldaudit syslogs export --esn 5323-D01E-6DC0 -tThe output file will contain content like the following.
2024-11-12 06:51:19 HDR to=2024-11-12 07:51:33 esn=5323-D01E-6DC0 seq_no=1231
2024-11-12 06:51:19 nshield5 monitor[3987]: New log file: current seq-no=1231
2024-11-12 06:51:19 nshield5 monitor[3987]: Last log: {'signature': {'key': 'AAAA...', 'sig': 'AAAA...', 'mech': 'ecds...', 'hash': 'a684...'}, 'seq-no': 1230}
2024-11-12 06:51:19 nshield5 monitor[3987]: Command response: {'log-data': '2024-11-12 05:51:06 nshield5 moni...', 'signature': {'key': 'AAAA...', 'sig': 'AAAA...', 'mech': 'ecds...', 'hash': 'a684...'}, 'seq-no': 1230}
2024-11-12 06:51:28 nshield5 monitor[4002]: Command args: {'subcommand': 'expirelog', 'seq_no': 1230}
2024-11-12 06:51:28 nshield5 monitor[4002]: Removed saved log file messages.saved.1230
2024-11-12 06:51:28 nshield5 monitor[4002]: Command response: None
2024-11-12 07:51:33 nshield5 monitor[4017]: Command args: {'subcommand': 'exportlog', 'saved_log': False}Run nshieldaudit syslogs export --malformed to export malformed logs into a file.
By default the export file will be in JSON format unless -t or --text parameter is added.
nshieldaudit syslogs export --malformed -f ./log_export -e 5323-D01E-6DC0 --text --overwriteReading nCore audit logs
The nshieldaudit ncore subcommand allows the user to read nCore audit logs from the database.
nshieldaudit ncore [-h] {query,export}This subcommand takes the following parameters:
| Parameter | Description |
|---|---|
--help or -h |
Show the help message and exit |
query |
Shows the contents of the audit logs database |
export |
Export the audit data to a file in JSON (default) or text format |
Querying available nCore audit logs
Use the nshieldaudit ncore query subcommand to quickly see what nCore audit log databases are available, an overview of the date and index ranges of their content, and a "Log Status" to summarize any detected verification errors or missing data.
nshieldaudit ncore query [-h] [-e ESN(s) [ESN(s) ...]] [-l LOGID [LOGID ...]]This subcommand takes the following parameters:
| Parameter | Description |
|---|---|
--help or -h |
Show the help message and exit |
-e ESN(s) [ESN(s) …] or --esn ESN(s) [ESN(s) …] |
One or more ESN(s) of the HSM(s) that generated the audits |
-l LOGID [LOGID …] or --logid LOGID [LOGID …] |
One or more LogID(s) of the nCore audit-log(s) |
A typical output looks like this:
$ nshieldaudit ncore query
--esn A1A1-B2B2-C3C3 --logid f515236b5a4970f0e0ac7a3c2852c6b53fee28e3
Indexes: --start 1 --end 6546650
Time: --from 2024-05-30_12:21:56 --to 2024-06-04_13:16:25
KML Status: Verification chain OK
Finalized Status: Finalized
Malformed Segments: 0
Unverified Segments: 0
Missing indexes: None
Log Status: OKA brief description of each field:
| Parameter | Description |
|---|---|
Indexes |
First and last Audit Index present in the local database for this log. |
Time |
UTC timestamps of the first and last audit records for this log. |
KML Status |
Status of verification chain of the KML public key (used to sign audit records) up to the nShield HSM root of trust. |
KML Error |
This field only appears if there is an error in KML Status, to give more details on KML verification error. |
KML Warning |
This field only appears if it was not possible to find a warrant to verify the chain of trust. |
Finalized Status |
|
Malformed Segments |
Count of the number of audit log segments that could not be processed. |
Unverified Segments |
Count of the number of audit log segments that failed to verify with the KML key. |
Missing indexes |
List of the ranges of Audit Indexes that are missing in the database. This is inclusive counting, for example |
Log Status |
|
Exporting nCore audit to JSON or text format
Use the nshieldaudit ncore export subcommand to export the audit data to a file.
The output file is written in JSON format (default), or in the human-readable text format if the -t or --text parameter is added.
nshieldaudit ncore export [-h] -e ESN(s) [ESN(s) ...] -l LOGID [LOGID ...] [-v] -f FILE [--overwrite] [-t] [--start START_INDEX] [--end END_INDEX] [--from FROM_DATE] [--to TO_DATE]
The nshieldaudit ncore export command can take some time if there is a very large amount of data to export.
|
The subcommand nshieldaudit ncore export takes the following parameters:
| Parameter | Description |
|---|---|
--help or -h |
Show the help message and exit |
-e ESN or --esn ESN |
Required: ESN of the module whose logs to export |
-l LOGID or --logid LOGID |
Required: The specific LogID from this module to export |
-t, --text |
Export of human-readable summary of logs in text format rather than full JSON |
-v, --verify |
Re-verify signatures whilst exporting; this significantly increases export time. (default is to report cached verification status) |
-f FILE, --file FILE |
Required: Store output in this file |
--overwrite |
Overwrite the output file if it exists |
--malformed |
Export malformed logs |
The subcommand nshieldaudit ncore export allows the user to add the following filters:
| Parameter | Description |
|---|---|
--start START_INDEX |
Start index of the audits desired |
--end END_INDEX |
End index of the audits desired |
--from FROM_DATE |
Start date of the audits desired (UTC) |
--to TO_DATE |
End date of the audits desired (UTC) |
Run nshieldaudit ncore query first in order to get parameters that can be copied to produce the nshieldaudit ncore export command-line.
|
The --esn and --logid options must be supplied to specify the log whose data to export (the nshieldaudit ncore query command can be used to get these parameters), along with the --file parameter to specify the output file path.
By default, the output format is JSON format (it is formatted with whitespace indentation to also be human-readable).
To emit in a more compact human-readable text format, add the --text parameter.
In many cases --text will be the more convenient format to use for browsing the data, and it is faster to export and produces a smaller output file.
Example command (text output):
$ nshieldaudit ncore export --esn 4210-02E0-D947 --logid 9455993eca529189f44a4861d2c23ef359f549ff --text --file ncore.audit.4210-02E0-D947.txt
100%The output file will contain content like the following. Note that identical repeated operations within each "segment" of log like this are collated with the "REPEAT=+17" field which indicates that this command was repeated a further 17 times, that is, 18 times total. This reduces the verbosity of data when the system is under load.
2024-06-07 22:43:59.876 HDR logid=9455993eca529189f44a4861d2c23ef359f549ff runid=2 start=36398476 end=36398546 signtime=2024-06-07_22:43:59.883
2024-06-07 22:43:59.876 idx=36398476 src=Host cmd=Sign rc=OK obj=162 REPEAT=+17
2024-06-07 22:43:59.877 idx=36398477 src=Host cmd=Sign rc=OK obj=161 REPEAT=+19
2024-06-07 22:43:59.877 idx=36398480 src=Host cmd=Sign rc=OK obj=163 REPEAT=+15
2024-06-07 22:43:59.878 idx=36398484 src=Host cmd=Sign rc=OK obj=160 REPEAT=+16Run nshieldaudit ncore export --malformed to export malformed logs into a file.
By default the export file will be in JSON format unless -t or --text parameter is added.
nshieldaudit ncore export --malformed -f ./log_export_ncore -e 5323-D01E-6DC0 --text --overwrite -l 0032bf17c0aeb84aefa31c29f846886d39710eff
Audit records are verified automatically as they arrive by the nShield Audit Log Service.
To re-verify records when exporting, pass the --verify option, otherwise the cached verification status is reported in the output file.
Re-verification will significantly increase the time to export the logs.
|
Monitoring and managing audit data sources
Hardserver audit database storage limit
The hardserver has its own audit database as the temporary staging area for nCore audit records from modules that are local to it. This ensures that the audit records are not lost whilst waiting to be handed over to the nShield Audit Log Service.
-
For Linux it is located at
/opt/nfast/hardserver.d/audit.db. -
For Windows it is located at
C:\ProgramData\nCipher\hardserver.d\audit.db. -
For network-attached HSMs (Connect XC and 5c), it is stored internally on the device.
| This is not the same database as the nShield Audit Log Service database which is located as described in Log databases. |
There is a configuration section auditdb_settings, which is present on both client-side and in network-attached HSMs configuration. If the section is missing, then the defaults will be applied.
To learn more about the configuration section, see Audit Database setting.
A default auditdb_settings configuration section is as follows:
[auditdb_settings]
# Start of the auditdb_settings section
# Hardserver settings for (new format v13.5 and later) nCore audit logging
# database.
# Each entry has the following fields:
#
# Minimum available megabytes of free-space for audit DB to operate.
# (default=0 for auto-configured)
# free_space_min_mb=MB
#
# Maximum total size of audit DB in megabytes. (default=0 for no limit)
# db_size_max_mb=MB
#
# Maximum number of audit indexes in audit DB. (default=0 for no limit)
# audit_indexes_max=COUNT| This is not the same configuration file as the nShield Audit Log Service configuration file (which is described in nShield Audit Log Service configuration). |
By default network-attached HSMs (5c or Connect XC) pause HSM auditing when 500 MB of free space is left in the appliance, and client-side hardservers pause auditing of local HSMs when 50 MB of free space is left in the local storage.
When HSM auditing is paused, any nCore commands which require the creation of an audit record will be denied.
The paused status of an HSM will also be visible in the output of the enquiry tool in the hardware status field.
The configuration section changes can be applied dynamically by pushing configuration to a network-attached HSM.
For local modules run the cfg-reread command to apply a change.
Checking nCore audit temporary storage usage
In normal usage, when the nShield Audit Log Service is operating correctly, the amount of temporary storage consumed for audit on HSMs should be small, as the data is being offloaded to the long-term databases. The following commands can be used to monitor to help detect issues.
Checking temporary storage for nCore audit usage for on a network-attached HSM (Connect XC or 5s) can be checked using the command stattree RemoteServers 1 ServerGlobals (replacing 1 with whatever the module number is).
Local temporary storage for nCore audit usage for Solo XC or 5s can be checked using the command stattree ServerGlobals.
The AuditDBUsedSpaceMB field states the number of megabytes of space consumed by the temporary database (where data is staged before being fetched by the nShield Audit Log Service).
The AuditDBFreeSpaceMB field states the number of megabytes of available space on the same partition as that temporary database.
Example output (for local storage usage):
stattree ServerGlobals | grep AuditDB
-AuditDBFreeSpaceMB 102694
-AuditDBUsedSpaceMB 45Checking or repairing hardserver audit database
The nshieldaudit serveradmin subcommand enables the system administrator to check or repair, if needed, the temporary database of nCore audit logs not yet processed by the nShield Audit Log Service.
It requires a privileged connection to the hardserver (membership of nfast group by default on Linux, and elevated Administrator command prompt by default on Windows).
If managing a network-attached HSM, that must also have been enrolled as privileged.
This command only interacts with the hardserver to query its internal staging database that temporarily stores nCore audit data, and does not relate to the long-term databases that the nshieldaudit ncore and nshieldaudit syslogs subcommands provide access to.
To learn more about the hardserver internal audit.db, see hardserver audit database.
nshieldaudit serveradmin [-h] [-m MODULE] [-q] [-e ESN] [-l LOGID] [--delete] [--end END] [--force] [--delete-status] [--recreate-db] [--no-confirm]This subcommand takes the following parameters:
| Parameter | Description |
|---|---|
-m or --module |
Module ID of source data server. Use 0 to refer to local hardserver. |
-e or --esn |
ESN of the log. Required when deleting. |
-q or --query |
query status of logs |
-l or --logid |
Log id of audit logs. Required when deleting. |
--delete |
Manually delete logs. Log deletion is normally automatic. This option should only be used in a recovery situation. |
--end |
When deleting audit logs the index of the last logs to be deleted. |
--force |
When deleting override check on whether logs have already been exported. |
--delete-status |
Delete the audit export status information. Not recommended unless the LogID is reported as finalized. |
--recreate-db |
Deletes entire database and creates a new empty database. Not recommended except in a recovery situation. |
--no-confirm |
Omits the interactive confirmation for --delete and --recreate-db options. |
Querying hardserver database contents
Run nshieldaudit serveradmin --query to query the contents of the hardserver’s temporary staging database.
The required hardware capabilities of the host machine running the nShield Audit Log Service depend on the amount of audit-log data that it needs to export, verify and expire.
By running nshieldaudit serveradmin --query the user can monitor that the nShield Audit Log Service is successfully keeping up with offloading nCore audit records.
nshieldaudit serveradmin --query reports on the local system’s hardserver by default (this will show information for audit from Solo XC and 5s modules).
To query the temporary staging database of a network-attached HSM (Connect XC or 5c), add the -m or --module parameter to specify the module number of that HSM.
Example output (showing both the completed offload of a "Finalized" log as well as the in-progress offload of the log for the currently loaded Security World):
nshieldaudit serveradmin --query -m1
--esn=4210-02E0-D947 --logid=1330c21f241db5b2d86f5ddb99bccaacf12453df
Indexes still on source data server (inclusive): --start=0 --end=0
Total remaining index count: 0
Exported to index: 218871
Log creation time: 2024-04-08 10:12:56.145
Log status: Finalized
--esn=4210-02E0-D947 --logid=9455993eca529189f44a4861d2c23ef359f549ff
Indexes still on source data server (inclusive): --start=749879020 --end=749880109
Total remaining index count: 1090
Exported to index: 749879019
Log creation time: 2024-06-07 20:57:03.480
Log status: UnfinalizedPlaceholder records of previously encountered logids seen by the system are kept by default (as in the "Finalized" log example above).
If you wish to delete these placeholders for a "Finalized" log, you may issue the command nshieldaudit serveradmin --delete --delete-status --esn=4210-02E0-D947 --logid=1330c21f241db5b2d86f5ddb99bccaacf12453df -m1 (replacing 1 with the module number in -m1 - this may be omitted if it is a local module, and passing the actual --esn and --logid values for the log status information to be deleted).
Forcibly deleting records or re-creating hardserver database
The nshieldaudit serveradmin --delete command can be used to delete records up to a specified --end value.
The nshieldaudit serveradmin --recreate-db command can be used to delete the entire database, that is, all status tracking information and any nCore audit records not yet offloaded will be lost.
In both cases, if interacting with a remote module, add the -m1 (or appropriate module number) parameter to specify which hardserver the command should be sent to.
These commands will prompt for confirmation by default. They are not intended to be issued except in non-production test systems or as emergency recovery options if advised to do so by nShield Support.
Checking signed system logs HSM storage
The percentage free space for signed system logs temporary storage for a 5s or 5c can be queried using the command appliance-cli -m1 gethsmenvstats, replacing 1 with the module number.
This is not applicable to XC modules.
Example output showing 90% free space, that is, only 10% used:
appliance-cli -m1 gethsmenvstats | grep log_free_space
"log_free_space": 90,Large consumption of this storage space is not expected in normal usage as signed system logs are only written occasionally, and the HSM stores the logs in a compressed form.