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.

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)

  1. Add your internal parcel repository to Cloudera Manager following the instructions in Configuring Cloudera Manager Server Parcel Settings.
  2. 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.
  3. (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)

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

  1. Stop the keytrusteed service: 
    sudo service keytrusteed stop
  2. 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
  3. Install the Cloudera Repository

    Add the internal repository you created. See Configuring Hosts to Use the Internal 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
  4. 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 Configuring a Local Package Repository.

  5. Upgrade Key Trustee Server: 
    sudo yum update keytrustee-server python-keytrustee
  6. 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)

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.

Migrate Apache Web Server to CherryPy

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.

  1. 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"
  2. 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
  3. 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
  4. (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"
  5. 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",
  6. Restart the Apache web server. Run this command on all Key Trustee Servers: 
    sudo service httpd restart
  7. Start the Key Trustee daemon (which starts the CherryPy web server). Run this command on all Key Trustee Servers: 
    sudo service keytrusteed start
  8. 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

  1. Stop the httpd service: 
    sudo service httpd stop
  2. 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
  3. Install the Cloudera Repository

    Add the internal repository you created. See Configuring Hosts to Use the Internal 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
  4. Upgrade Key Trustee Server: 
    sudo yum update keytrustee-server python-keytrustee
  5. 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:
  1. (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.
  2. 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.
  3. 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
  4. 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
  5. 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.
  6. 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
  7. Restart the Key Trustee Server service (Key Trustee Server service > Actions > Restart).
  8. (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