Cloudera Enterprise 5.15.x | Other versions

Upgrading Cloudera Navigator Key Trustee Server 5.4.x or Higher

If you are upgrading Key Trustee Server from 3.8 to 5.5 or higher, see Upgrading Cloudera Navigator Key Trustee Server 3.8 to 5.5 Using the ktupgrade Script.

CAUTION:

Cloudera recommends that you do not create new encryption keys, encryption zones, or clients during an upgrade.

Note: Before upgrading Key Trustee Server, back up the Key Trustee Server. See Backing Up and Restoring Key Trustee Server and Clients for instructions.

Setting Up an Internal Repository

You must create an internal repository to install or upgrade the Cloudera Navigator data encryption components. For instructions on creating internal repositories (including Cloudera Manager, CDH, and Cloudera Navigator encryption components), see the following topics:

Upgrading Cloudera Navigator Key Trustee Server 5.4.x or Higher Using Cloudera Manager

Minimum Required Role: Cluster Administrator (also provided by Full Administrator)

Note: These instructions apply to using Cloudera Manager only. To upgrade Key Trustee Server using the command line, skip to the Upgrading Cloudera Navigator Key Trustee Server 5.4.x or Higher Using the Command Line (CherryPy Web Server) or Upgrading Cloudera Navigator Key Trustee Server 5.4.x or Higher Using the Command Line (Apache Web Server) section.

Add your internal parcel repository to Cloudera Manager following the instructions in Configuring Cloudera Manager Server Parcel Settings.
Download, distribute, and activate the latest Key Trustee Server parcel on the cluster containing the Key Trustee Server host, following the instructions in Managing Parcels.
Important: The KEYTRUSTEE parcel in Cloudera Manager is not the Key Trustee Server parcel; it is the Key Trustee KMS parcel. The parcel name for Key Trustee Server is KEYTRUSTEE_SERVER.
After you activate the Key Trustee Server parcel, Cloudera Manager prompts you to restart the cluster. Click the Close button to ignore this prompt. You do not need to restart the cluster after installing Key Trustee Server.
(High Availability Key Trustee Servers Only) Enable synchronous replication. On the active Key Trustee Server, run the following command:
```
$ sudo ktadmin enable-synchronous-replication --pg-rootdir /var/lib/keytrustee/db
```

Upgrading Cloudera Navigator Key Trustee Server 5.4.x or Higher Using the Command Line (CherryPy Web Server)

Important: Use these instructions only if you have previously migrated Key Trustee Server to use the CherryPy web server instead of the Apache web server. Otherwise, skip to Upgrading Cloudera Navigator Key Trustee Server 5.4.x or Higher Using the Command Line (Apache Web Server) .

The following instructions apply to both standalone and high availability Key Trustee Servers. For standalone Key Trustee Server, follow the instructions that refer to the active Key Trustee Server. For high availability Key Trustee Servers, follow the instructions on all Key Trustee Servers, unless otherwise indicated.

Upgrade Key Trustee Server

Stop the keytrusteed service:
```
$ sudo service keytrusteed stop
```
Install the EPEL Repository
Dependent packages are available through the Extra Packages for Enterprise Linux (EPEL) repository. To install the EPEL repository, install the epel-release package:
1. Copy the URL for the epel-release-<version>.noarch file for RHEL 6 or RHEL 7 located in the How can I use these extra packages? section of the EPEL wiki page.
2. Run the following commands to install the EPEL repository:
```
$ sudo wget <epel_rpm_url>
$ sudo yum install epel-release-<version>.noarch.rpm
```
  Replace <version> with the version number of the downloaded RPM (for example, 6-8).
If the epel-release package is already installed, you see a message similar to the following:
```
Examining /var/tmp/yum-root-jmZhL0/epel-release-6-8.noarch.rpm: epel-release-6-8.noarch
/var/tmp/yum-root-jmZhL0/epel-release-6-8.noarch.rpm: does not update installed package.
Error: Nothing to do
```
Confirm that the EPEL repository is installed:
```
$ sudo yum repolist | grep -i epel
```
Install the Cloudera Repository
Add the internal repository you created. See Modifying Clients to Find the Repository for more information.
Import the GPG key by running the following command:
```
$ sudo rpm --import http://repo.example.com/path/to/RPM-GPG-KEY-cloudera
```
Install the CDH Repository
Key Trustee Server and Key HSM depend on the bigtop-utils package, which is included in the CDH repository. For instructions on adding the CDH repository, see To add the CDH repository. To create a local CDH repository, see Creating a Local Yum Repository for instructions.

Upgrade Key Trustee Server:

$ sudo yum update keytrustee-server python-keytrustee

Start the keytrusteed service:
```
$ sudo service keytrusteed start
```

(High Availability Key Trustee Servers Only) Enable Synchronous Replication

Run the following command on the active Key Trustee Server to enable synchronous replication after upgrading:

$ sudo ktadmin enable-synchronous-replication --pg-rootdir /var/lib/keytrustee/db

Migrate Key Trustee Server to Cloudera Manager

Skip to Migrating Unmanaged Key Trustee Server to Cloudera Manager for instructions on migrating Key Trustee Server to Cloudera Manager control if you have not already done so during a previous upgrade.

Upgrading Cloudera Navigator Key Trustee Server 5.4.x or Higher Using the Command Line (Apache Web Server)

Important: Use these instructions only if you have not yet migrated Key Trustee Server to use the CherryPy web server instead of the Apache web server. The Apache web server is not supported in versions 5.5 and higher.

Migrate Apache Web Server to CherryPy

Note: Confirm that all ports listed in Data at Rest Encryption Requirements are open before proceeding.

For versions 5.4.0 and higher, Key Trustee Server uses CherryPy for the front end web interface; lower versions use the Apache web server. The Apache web server is not supported in versions 5.5 and higher. The CherryPy service is managed using the keytrusteed service. The Apache web server is managed using the httpd service. Before upgrading, run the following commands to migrate the web server from Apache to CherryPy.

On the active Key Trustee Server, run the ktadmin db --configure command as follows:
```
$ sudo ktadmin db --configure --port 11381 --pg-rootdir /var/lib/keytrustee/db --slave keytrustee02.example.com
```
Replace keytrustee02.example.com with the hostname of the passive Key Trustee Server. For standalone Key Trustee Server, omit the --slave keytrustee02.example.com portion of the command.
If you use a database directory other than /var/lib/keytrustee/db, create or edit the /etc/sysconfig/keytrustee-db file and add the following:
```
ARGS="--pg-rootdir /path/to/db"
```

Export the Key Trustee Server database. Run the following commands on the active Key Trustee Server:

$ sudo -u postgres pg_dump keytrustee > /var/lib/keytrustee/ktdbexport.pgsql
$ chown keytrustee:keytrustee /var/lib/keytrustee/ktdbexport.pgsql

Start the Key Trustee Server database and import ktdbexport.pgsql:

$ sudo -u keytrustee /usr/pgsql-9.3/bin/pg_ctl -D /var/lib/keytrustee/db start --log /var/lib/keytrustee/db/pg_ctl.log
$ sudo -u keytrustee /usr/pgsql-9.3/bin/createdb --host /tmp --port 11381 -O keytrustee keytrustee
$ sudo -u keytrustee psql -d keytrustee -h /tmp -p 11381 < /var/lib/keytrustee/ktdbexport.pgsql

Note: The /etc/init.d/postgresql script does not work when the PostgreSQL database is started by Key Trustee Server, and cannot be used to monitor the status of the database. Use /etc/init.d/keytrustee-db instead.

(High Availability Key Trustee Servers Only) Start the passive Key Trustee Server. Run the following commands on the passive Key Trustee Server:

$ sudo ktadmin --confdir /var/lib/keytrustee/.keytrustee init-slave --master keytrustee01.example.com --pg-rootdir /var/lib/keytrustee/db --no-import-key --master-host-port 11381 --logdir /var/lib/keytrustee/.keytrustee/logs --postgres-config=local --no-start
$ sudo -u keytrustee /usr/pgsql-9.3/bin/pg_ctl -D /var/lib/keytrustee/db start

If you use a database directory other than /var/lib/keytrustee/db, create or edit the /etc/sysconfig/keytrustee-db file and add the following:

ARGS="--pg-rootdir /path/to/db"

Edit /var/lib/keytrustee/.keytrustee/keytrustee.conf on all Key Trustee Servers to reference the new database and port. Set the DB_CONNECT parameter as follows:
```
    "DB_CONNECT": "postgresql://localhost:11381/keytrustee?host=/tmp",
```
Restart the Apache web server. Run this command on all Key Trustee Servers:
```
$ sudo service httpd restart
```
Start the Key Trustee daemon (which starts the CherryPy web server). Run this command on all Key Trustee Servers:
```
$ sudo service keytrusteed start
```
After verifying that the Key Trustee daemon and CherryPy web server are running, stop the Apache web server and original database and prevent them from starting after reboots. Run these commands on all Key Trustee Servers:
```
$ sudo service httpd stop
$ sudo -u postgres /usr/pgsql-9.3/bin/pg_ctl -D /var/lib/pgsql/9.3/keytrustee stop
$ sudo chkconfig httpd off
$ sudo chkconfig postgresql-9.3 off
```

Upgrade Key Trustee Server

Stop the httpd service:
```
$ sudo service httpd stop
```
Install the EPEL Repository
Dependent packages are available through the Extra Packages for Enterprise Linux (EPEL) repository. To install the EPEL repository, install the epel-release package:
1. Copy the URL for the epel-release-<version>.noarch file for RHEL 6 or RHEL 7 located in the How can I use these extra packages? section of the EPEL wiki page.
2. Run the following commands to install the EPEL repository:
```
$ sudo wget <epel_rpm_url>
$ sudo yum install epel-release-<version>.noarch.rpm
```
  Replace <version> with the version number of the downloaded RPM (for example, 6-8).
If the epel-release package is already installed, you see a message similar to the following:
```
Examining /var/tmp/yum-root-jmZhL0/epel-release-6-8.noarch.rpm: epel-release-6-8.noarch
/var/tmp/yum-root-jmZhL0/epel-release-6-8.noarch.rpm: does not update installed package.
Error: Nothing to do
```
Confirm that the EPEL repository is installed:
```
$ sudo yum repolist | grep -i epel
```
Install the Cloudera Repository
Add the internal repository you created. See Modifying Clients to Find the Repository for more information.
Import the GPG key by running the following command:
```
$ sudo rpm --import http://repo.example.com/path/to/RPM-GPG-KEY-cloudera
```

Upgrade Key Trustee Server:

$ sudo yum update keytrustee-server python-keytrustee

Start the httpd service:
```
$ sudo service httpd start
```

(High Availability Key Trustee Servers Only) Enable Synchronous Replication

Run the following command on the active Key Trustee Server to enable synchronous replication after upgrading:

$ sudo ktadmin enable-synchronous-replication --pg-rootdir /var/lib/keytrustee/db

Migrate Key Trustee Server to Cloudera Manager

Continue to Migrating Unmanaged Key Trustee Server to Cloudera Manager for instructions on migrating Key Trustee Server to Cloudera Manager control if you have not already done so during a previous upgrade.

Migrating Unmanaged Key Trustee Server to Cloudera Manager

Minimum Required Role: Cluster Administrator (also provided by Full Administrator)

For simplified and centralized administration, perform the following steps to move Key Trustee Server under Cloudera Manager control (if you have not already done so) after upgrading Key Trustee Server:

(Recommended) Create a new cluster in Cloudera Manager containing only the hosts the Key Trustee Server will be installed on. Cloudera strongly recommends installing Key Trustee Server in a dedicated cluster to enable multiple clusters to share the same Key Trustee Server and to avoid restarting the Key Trustee Server when restarting a cluster. See Adding and Deleting Clusters for instructions on how to create a new cluster in Cloudera Manager.
Download, distribute, and activate the Key Trustee Server parcel, following the instructions in Managing Parcels. After you activate the Key Trustee Server parcel, Cloudera Manager prompts you to restart the cluster. Click the Close button to ignore this prompt. You do not need to restart the cluster after installing Key Trustee Server.
Stop the active and passive Key Trustee Server web servers using the command that corresponds to your backing web server. See Migrate Apache Web Server to CherryPy for more information.
For Apache web servers:
```
$ sudo service httpd stop
```
For CherryPy web servers:
```
$ sudo service keytrusteed stop
```
Stop the active Key Trustee Server database. Run the following command on the active Key Trustee Server:
```
$ sudo -u keytrustee /usr/pgsql-9.3/bin/pg_ctl -D /var/lib/keytrustee/db stop
```
Warning: Do not stop the passive Key Trustee Server database. If it is stopped, start it before proceeding by running the following command on the passive Key Trustee Server:
```
$ sudo -u keytrustee /usr/pgsql-9.3/bin/pg_ctl -D /var/lib/keytrustee/db start
```
Add the Key Trustee Server service to your cluster, following the instructions in Adding a Service. When customizing role assignments, assign the Active Key Trustee Server and Active Database roles to the active Key Trustee Server host, and the Passive Key Trustee Server and Passive Database roles to the passive Key Trustee Server host.
Stop the passive Key Trustee Server database. Run the following command on the passive Key Trustee Server:
```
$ sudo -u keytrustee /usr/pgsql-9.3/bin/pg_ctl -D /var/lib/keytrustee/db stop
```
Restart the Key Trustee Server service (Key Trustee Server service > Actions > Restart).
Important: Starting or restarting the Key Trustee Server service attempts to start the Active Database and Passive Database roles. If the Active Database is not running when the Passive Database attempts to start, the Passive Database fails to start. If this occurs, manually restart the Passive Database role after confirming that the Active Database role is running.
(High Availability Key Trustee Servers Only) Enable synchronous replication. Run the following command on the active Key Trustee Server:
```
$ sudo ktadmin enable-synchronous-replication --pg-rootdir /var/lib/keytrustee/db
```

Page generated May 18, 2018.