Configuration Items
This chapter contains instructions for making configuration changes on SafeNet ProtectServer client and server systems. The procedure for editing configuration items is different for SafeNet Network HSMs, client workstations, and systems hosting SafeNet PCIe HSMs. Please refer to the section relevant to your system:
>Client/PCIe HSM Server Configuration
>Network HSM Server Configuration
Overview
During installation, configuration items are created on the host system. Configuration changes are made by editing the values associated with these items. This chapter describes how to make such changes on your system.
Item values can exist at four configuration levels. When a configuration item is queried, item locations are searched in order of level precedence:
1.Temporary: Any changes made at the temporary configuration level override any corresponding entries at the user, system, and default levels.
2.User: Changes made at the user level override any corresponding entries at the system and default levels.
3.System: System changes override default-level entries.
4.Default: If no changes have been made at any other level, the default value for the configuration item is used. Default configuration values cannot be changed.
On Windows operating systems, user and system configuration information is stored in the Registry. On Unix-based systems, configuration files are used. Temporary configuration items are applied using environment variables on both Windows and Unix-based platforms.
Regardless of the platform, a common naming convention for configuration items has been followed. Understanding this naming convention will help you locate and change the appropriate configuration items when required.
Configuration items are hierarchical in structure, with the root node ET. Child nodes of the root represent the class of the item, and are typically product abbreviations, such as PTKC (SafeNet ProtectToolkit-C) or HSM (Hardware Security Module). Nodes under class represent the component, such as LOGGER or SMS. Finally, nodes under component represent the configuration item, such as FILE, MODE, or NAME. Configuration items therefore take the form:
ET_<class>_<component>_<item>
For a list of configurable items, see:
>PCI Mode Client Configuration Items
>Network Mode Client Configuration Items
>Network Mode Server Configuration Items
Client/PCIe HSM Server Configuration
The procedure for configuring client/PCIe HSM host systems differs between Windows and Linux. Please refer to the relevant section below:
Windows
Temporary
Temporary configuration changes are made using environment variables. Since environment variables are not hierarchical, the hierarchy is implicitly defined by the name of the variable.
Example:
In Network mode, to temporarily change the length of time the HSM will wait before timing out a connection attempt:
In a command prompt, enter set ET_HSM_NETCLIENT_CONNECT_TIMEOUT_SECS=<time_in_seconds>
User
User configuration changes are made in the registry tree starting from HKEY_CURRENT_USER\SOFTWARE\SafeNet.
Example:
In Network mode, to change the length of time the HSM will wait before timing out a connection attempt:
1.Open regedit to HKEY_CURRENT_USER\SOFTWARE\SafeNet.
2.Add a new key entitled HSM and open it.
3.Add a new key entitled NETCLIENT and open it.
4.Add a new string named ET_HSM_NETCLIENT_CONNECT_TIMEOUT_SECS.
5.Set the value data to the desired time in seconds.
System
System configuration changes are made in the registry tree starting from HKEY_LOCAL_MACHINE\SOFTWARE\SafeNet.
Example:
The name of the SafeNet ProtectToolkit-C file where the logger library writes log information (ctlog.log) is stored in the Windows registry as a string value for the entry:
ET_PTKC_LOGGER_FILE
This is located in the key:
HKEY_LOCAL_MACHINE\SOFTWARE\SafeNet\PTKC\LOGGER
Unix
Temporary
Temporary configuration changes are made using environment variables. Since environment variables are not hierarchical in nature, the hierarchy is implicitly defined by the name of the variable.
User
User Configuration is a set of files located in the $HOME/.safenet directory.
System
System Configuration is a set of files located in the /etc/default directory.
The User and System Configuration files are of the form: et_<class>. Entries in the file are of the form: ET_<class>_<component>_<item>=<value>.
Example:
The name of the SafeNet ProtectToolkit-C file where the logger library writes log information (ctlog.log) is stored in the /etc/default/et_ptkc file as the entry:
ET_PTKC_LOGGER_FILE=/ctlog.log
Network HSM Server Configuration
Server configuration settings on the SafeNet Network HSM are edited by transferring a new configuration file to the appliance, and applying it using PSESH.
To change the Network HSM server configuration:
1.Create a text file on your client workstation that lists each configuration item and its desired value. For a list of editable configuration items and their valid values, see Network Mode Server Configuration Items.
For example:
ET_HSM_NETSERVER_OLD_WORKER_COUNT=5
ET_HSM_NETSERVER_V2_WORKER_COUNT=12
ET_HSM_NETSERVER_READ_TIMEOUT_SECS=40
ET_HSM_NETSERVER_WRITE_TIMEOUT_SECS=40
ET_HSM_NETSERVER_CONN_TIMEOUT_COUNT=5
ET_HSM_NETSERVER_FRAG_SIZE=5000
ET_HSM_NETSERVER_ALLOW_RESET=OnHalt
ET_HSM_NETSERVER_PORT=12396
ET_HSM_NETSERVER_LOG_CHANNEL=0
ET_HSM_NETSERVER_LOG_NAME=etnetserver
ET_HSM_NETSERVER_LOG_LEVEL=0
2.Transfer the configuration file (et_hsm.txt in the example below) to the appliance using pscp (Windows) or scp (Linux/UNIX):
| Windows |
pscp <filename> admin@<server_host/IP>: pscp et_hsm.txt admin@192.168.0.123: admin@192.168.0.123's password: ******** et_hsm.txt | 0 kB | 0.4 kB/s | ETA: 00:00:00 | 100% |
| Linux/UNIX |
scp <filename> admin@<server_host/IP>: scp et_hsm.txt admin@192.168.0.123: admin@192.168.0.123's password: ******** et_hsm.txt | 0 kB | 0.4 kB/s | ETA: 00:00:00 | 100% |
3.Login to PSESH as admin.
4.If desired, check to ensure that the configuration file was transferred to the appliance.
psesh:>files show
psesh:>files show
SCP Folder Content
------------------
total 0.4K
0.4K et_hsm.txt
Command Result : 0 (Success)
5.Set the etnetserver configuration file. See sysconf etnetcfg in the PSESH Command Reference Guide for syntax.
psesh:>sysconf etnetcfg set <filename>
psesh:>sysconf etnetcfg set et_hsm.txt
WARNING !! This command will modify the settings of the appliance.
It could affect client connections, and result in an unusable system.
If you are sure that you wish to proceed, then type 'proceed', otherwise type 'quit'
> proceed
Proceeding...
The config file has been set. To apply the changes, please restart etnetserver
Command Result : 0 (Success)
6.Restart the etnetserver service.
psesh:>service restart etnetserver
7.View the new configuration to confirm the changes.
psesh:>sysconf etnetcfg show
psesh:>sysconf etnetcfg show
etnetserver is running
Current etnetserver configuration
ET_HSM_NETSERVER_OLD_WORKER_COUNT=5
ET_HSM_NETSERVER_V2_WORKER_COUNT=12
ET_HSM_NETSERVER_READ_TIMEOUT_SECS=40
ET_HSM_NETSERVER_WRITE_TIMEOUT_SECS=40
ET_HSM_NETSERVER_CONN_TIMEOUT_COUNT=5
ET_HSM_NETSERVER_FRAG_SIZE=5000
ET_HSM_NETSERVER_ALLOW_RESET=OnHalt
ET_HSM_NETSERVER_PORT=12396
ET_HSM_NETSERVER_LOG_CHANNEL=0
ET_HSM_NETSERVER_LOG_NAME=etnetserver
ET_HSM_NETSERVER_LOG_LEVEL=0
Command Result : 0 (Success)
