Chapter 1: About This Manual

AKM VM Migration Upgrade to v4.6

This guide is intended to provide the steps and prerequisite tasks needed to perform an upgrade to the new 4.6 version of AKM for VMware. AKM 4.6 will be using the Ubuntu OS (previously Suse Linux), so upgrades to this version will require a migration of your AKM DB. It is advised that this process be overseen by a Townsend support technician via web call.

Change Log

The following table provides information on the changes to this documentation:

Chapter 2: Pre-requisites for Current AKMs

• Submit an AKM Upgrade Ticket with Support
• Update backup and restore module
• Generate backups of each AKM
• Build the replacement 4.6 VMs

Submit an AKM Upgrade Ticket with Support

You will first need to submit a support ticket via the Townsend Security Support portal located at the following address. if you require credentials to access the site, please request them at the link or email support@townsendsecurity to request support credentials

https://www.townsendsecurity.com/support

Backup and Restore Module

Once you have submitted your ticket to Townsend Security Support, you will need to check the backup and restore module version on your current production AKMs. You can access this by using the webmin user interface ( https://(your.akm.ip):3886 ). Once you have authenticated to the web interface, navigate to “Webmin Configuration”.

You will then select “Webmin Modules” from the icons shown. Check your current backup restore module version by clicking the delete tab. the current version should be displayed in the list of installed modules.

NOTE: if the version shown is any lower than 1.15 you will need to install an updated backup and restore module.

Updating the Backup and Restore Module

NOTE: The new module will be attached to your support ticket for download. this file will be called “akmbr.wbm.gz”. This step must be performed on Each AKM that will be migrated.

Click on the “Install” tab and select “From upload file”. Find “akmbr.wbm.gz” on your local system and then click the button to “Install Module”. To be certain the module was installed correctly, you can click on the delete tab again to confirm the version number has changed.

Generate Backup Files

A secret key backup and an application bacup must be taken of each AKM in your production environment. Backups are taken from the Webmin user interface under “AKM Backup and Restore”. If you do not already have backup locations configured, more information on AKM backup procedures can be found at:

https://docs.townsendsecurity.com/akm_server_management_guide/#chapter-3-backup-and-restore

Chapter 3: Prepare Target AKMs for Migration

NOTE: If you are using AKM HSMs your upgrade path will require a re-image of your AKM hardware. This process is slightly different than the standard migration process. at this point you should consult with the support technician via the upgrade ticket to confirm the order in which to re-image the AKMs. This will mitigate any downtime in your production environment.

Build New VMs from AKM 4.6 Image

AKM for VMware

AKM for Microsoft Azure

AKM for Amazon Web Services

Upload Backup and License Files to Target AKMs

You will need to upload 3 files to your replacement AKM’s file system under /home/admin/uploads. This can be done using Webmin, by selecting “File Manager”, or you can use Filezilla or SCP.

The three files that are needed will be:

• License.txt
• akm_secret_backup_*
• akm_application_backup_*

With those three files present under /home/admin/uploads you can return to the AKM shell’s “akm-menu” in VMware or via an SSH connection.

Chapter 4: Initialize New AKMs

akm-menu

From the “akm-menu” you will take option 1 to “Initialize AKM”. There are 3 options to initialize here, you will select option 3 to initialize from backups. Once the option is selected you will be asked if you would like to preserve your certificate structure from the previous AKMs. Selecting “No” will generate an entirely new PKI, and new client certificates will need to be distributed to the client side.

NOTE: If you would like your certificate structure preserved you will need to take individual backups of each of your old AKMs. You will then initialize each replacement AKM with the backup files respective to its role.

Once you hit enter the upgrade/migration process will start. You will be prompted once the migration is complete.

Chapter 5: Confirm Key Migration via AKM Administrative Console

NOTE: At this point you may experience issues authenticating your secondary or mirror AKMs to the AKM Administrative Console or the Client, you will need to alter the /etc/akm/akm.conf file, on the AKM, to correct the issue. there should be two of these files present under /etc/akm following the initialization. one of them will be “akm.conf.old”. confirm that this is present. The support technician assisting you will provide instructions to correct issue.

AKM Administrative Console.

Once your AKM(s) are initialized from the backups you will want to confirm that all of the expected production keys exist on the AKM database. To do this you may need to re-issue the admin authentication certificates to the AKM Administrative console. Those will be available for download from the AKM filesystem at /home/admin/downloads. For more information on configuring AKM Administrative Console see:

AKM Administrative Console Guide

NOTE: If you selected “y” for Yes, to preserve your previous AKMs CA and certificate structure you should not need to re-apply certificates to your AKM Administrative console connection, you can simply “File” > “Edit Key Server”, to alter the originally configured connection and replace the old AKM IP with your new IP.

Once you have established a connection in AKM Administrative Console you will want to display the key name list, under “Manage Keys” to confirm that all the expected keys are present.

NOTE: If you use SQL Server TDE your key list can be found under the “Key connection for SQL server” drop down. the option will be “Display EKM Key List”

Re-establish Mirroring

It may be necessary to re-configure mirroring between your new AKMs. this will be done in the AKM Administrative Console using the “Set Mirror Address” option under “Mirroring”. more information on the configuration of mirroring in Admin Console can be found in the document below:

https://docs.townsendsecurity.com/akm_administrative_console_guide/#chapter-15-mirroring

Chapter 6: Re-establish, or Confirm the Client Connection

Re-Configure the Client Connection to AKM

If you chose not to preserve your previous AKM certificate structure, you will need to re-distribute the client authentication certificates to any client that requests keys from AKM. You will need to download the AKM client authentication material from the AKM filesystem at /home/admin/downloads/*user.zip. information specific to each client side connection type can be found at the links below.

MongoDB
.NET C#
Linux C
Java
Oracle
Perl
Python
PHP
IBMi Zos
IBMi
TDE & SQL Server EKM
SQL Server UDF

Confirm the Client Connection

If you chose to preserve your old AKM certificates during the migration from the backup files, you should be able to simply update the IP in your client side configuration and test key retrieval. If there are any errors at this point you will need to update your AKM Upgrade support ticket and include any client side error messages you see as well as the AKM error log. The AKM error log is located at /var/log/townsend/akm

Final Steps

1.) Confirm that the client side connection is active with your support technician. this can be done on the upgrade call, or via the support ticket.
2.) Request, and apply the replacement permanent licenses for the new AKMs.
3.) Migrate all production client connections to the new AKMs.

Chapter 7: Future Software Updates

Each time you log into the Webmin UI, you will see new package updates available on the dashboard.

When you click on the package updates section you will be taken to a list of the available updates. You should see something similar to the image below.

You can apply all available updates by selecting the select all option. Once you have made your selection you can click the button to Update Selected Packages. You can specify to be alerted of new updates via email if you need. This feature can be found by scrolling to the bottom of the list. You will be able to set an interval to check for updates, as well as provide an email and specify any action to be taken.

After clicking Update Selected Packages you will be taken to the screen below to confirm and install the updates. Click on Install Now when you are ready to begin the update.

You will see the output similar to what is shown below. The update process is done when you see install complete at the bottom of the output window.

Your updates will be complete at this point and any future updates can be applied in this manner as well.

NOTE: An alternative method to update your AKM can be completed via the AKM shell, but it is important that you initialize your AKM prior to attempting an update. This method requires access to the AKM shell using SSH, Putty, your VM console, or a dummy console. Once connected, you can issue the command sudo apt-get update to list the available packages for update. When you are ready to apply the update, you will issue the command sudo apt-get upgrade. The process may take several minutes to finish.