Upgrade

This chapter details how to update an existing KeySafe 5 install to the latest version.

Upgrade from v1.5 KeySafe 5 Service Deployment

Entrust recommends that you back up your data and configuration items before performing an upgrade, as described in KeySafe 5 Service Backup.

  1. Stop the running KeySafe 5 Service.

  2. Uninstall the existing KeySafe 5 Service as described in the KeySafe 5 v1.5 documentation.

  3. Install the new KeySafe 5 Service. The installation package can be found in the keysafe5-service directory of the KeySafe 5 release package.

    On Linux:

    1. Run sudo tar -C / -xf /path/to/keysafe5-server-1.7.0-Linux.tar.gz to unpack the KeySafe 5 Service binaries and associated scripts into the /opt/nfast/ directory.

    2. Run sudo /opt/nfast/keysafe5/server/sbin/install to install KeySafe 5 Service.

    On Windows:

    1. Double-click on keysafe5-server-1.7.0-windows.msi and follow the Installation Wizard.

    2. Restart KeySafe 5 Service using the standard Windows Services facility.

  4. Open the KeySafe 5 WebUI (by default at https://127.0.0.1:18080) and check that you can see your existing KeySafe 5 data.

  5. Upgrade each KeySafe 5 Agent as described in Agent Upgrade.

Configuration File Changes

The following configuration parameters have been added in this version of KeySafe 5 Service. These parameters and their default values can be found in the config.yaml.example file shipped with this version. To change any of these settings from their default values, copy the relevant parameters into your existing config.yaml file and restart the KeySafe 5 Service. Default values apply to any configuration parameters not explicitly set in config.yaml. For details on configuration items, see KeySafe 5 Service Configuration.

Existing configuration items that have been updated:

Parameter Description Default Value

database.type

Type of database to use. Now supports mongodb in addition to sqlite.

sqlite

database.timeout

Timeout for database requests has increased from 30s to 60s.

60s

The new configuration items are as follows:

Parameter Description Default Value

database.mongodb.hosts

MongoDB database hosts list, comma separated. IPv6 addresses must be in the form [host]:port.

database.mongodb.replica_set

Name of the MongoDB replica set.

database.mongodb.database_name_prefix

Database name prefix. Use this if pointing multiple KeySafe 5 instances at the same MongoDB server to avoid database conflict.

database.mongodb.auth.type

Authentication method for the MongoDB connection. Valid values: none, pwd, x509.

x509

database.mongodb.auth.auth_database

The name of the Authentication Database for MongoDB.

database.mongodb.auth.username_file

File containing the MongoDB username. Only applicable if auth.type=pwd.

/opt/nfast/keysafe5/server/database/username

database.mongodb.auth.password_file

File containing the MongoDB password. Only applicable if auth.type=pwd.

/opt/nfast/keysafe5/server/database/password

database.mongodb.auth.client_cert_file

x.509 client certificate. Only applicable when auth.type=x509.

/opt/nfast/keysafe5/server/database/tls.crt

database.mongodb.auth.client_key_file

x.509 client private key. Only applicable when auth.type=x509.

/opt/nfast/keysafe5/server/database/tls.key

database.mongodb.tls.enabled

Set to false to disable TLS for the MongoDB connection.

true

database.mongodb.tls.ca_cert_file

Server CA certificate for MongoDB TLS.

/opt/nfast/keysafe5/server/database/ca.crt

database.mongodb.tls.min_protocol_version

Minimum TLS protocol version for MongoDB. Valid values: TLSV1_0, TLSV1_1, TLSV1_2, TLSV1_3.

TLSV1_2

database.mongodb.tls.cipher_suites

Allowed cipher suites for MongoDB TLS.

ECDHE-ECDSA-AES256-GCM-SHA384, ECDHE-RSA-AES256-GCM-SHA384, ECDHE-ECDSA-AES128-GCM-SHA256, ECDHE-RSA-AES128-GCM-SHA256, ECDHE-ECDSA-CHACHA20-POLY1305, ECDHE-RSA-CHACHA20-POLY1305

database.mongodb.connect_timeout

Timeout for connection to the MongoDB server.

30s

database.mongodb.selection_timeout

Timeout for selecting a connection from the connection pool.

30s

database.mongodb.socket_timeout

Timeout waiting for read/write on the socket.

30s

database.mongodb.min_pool_size

Minimum connections in the MongoDB connection pool.

1

database.mongodb.max_pool_size

Maximum connections in the MongoDB connection pool.

100

monitoring.metric_samples_storage_retention_time

Duration to retain metric samples in storage. Supported units: y, w, d, h, m, s, ms.

1y

monitoring.metric_samples_storage_retention_size

Maximum total size of storage blocks to retain. Set to 0 to disable size-based retention. Supported units: B, KB, MB, GB, TB, PB, EB.

0

monitoring.database_directory

Absolute path to the directory where metric samples and alert databases are stored.

%NFAST_DATA_HOME%/kmdata/databases

monitoring.email_smarthost

SMTP server used for sending alert notifications. For example, smtp.example.com:465.

monitoring.email_from

Sender address used in alert notification emails.

noreply@entrust.com

monitoring.email_auth_enabled

Enable authenticated sending for the SMTP server. The SMTP server must support TLS, and its CA certificate must be in the OS trust store.

false

monitoring.email_auth_username_filepath

Absolute path to the file containing the SMTP username for authentication.

monitoring.email_auth_password_filepath

Absolute path to the file containing the SMTP password for authentication.

monitoring.host_address

Address of the host shown in the email alert footer link. If not set, the footer is not displayed. For example, https://127.0.0.1:18080.