Migrating public keys

Starting with the Grizzly release (1.20240517), Deephaven stores public keys in the ACL database (etcd or MySQL) instead of the dsakeys.txt file. When upgrading an existing installation, the installer automatically imports keys from dsakeys.txt. However, when migrating to a new system, you must manually import public keys from your source system.

When to use this guide

This guide applies when migrating to a new Grizzly or later system and the source system has a legacy dsakeys.txt file containing public keys. This file exists on:

  • Pre-Grizzly systems that used file-based public key storage.
  • Grizzly or later systems that were upgraded in place — the file may be named dsakeys.txt.backup after the upgrade imported keys to the ACL store.

If your source system only uses the ACL store for public keys (no dsakeys.txt or backup file exists), export and import the ACL database instead. See etcd and MySQL backup and restore.

If you are upgrading in place (not migrating to new hardware), the installer handles key import automatically.

Prerequisites

  • Access to the source system's dsakeys.txt file. Depending on the source system's age, this file may be located at:
    • /etc/sysconfig/deephaven/auth/dsakeys.txt (newer installations)
    • /etc/sysconfig/illumon.d/resources/dsakeys.txt (older installations)
    • /etc/sysconfig/deephaven/auth/dsakeys.txt.backup (upgraded Grizzly+ systems)
  • Administrative access to the target Deephaven system.
  • The target system must be installed and configured with etcd or MySQL for ACL storage.

Procedure

1. Locate and copy the source keys file

On the source system, find the dsakeys.txt file. The location varies by installation age:

Copy whichever file exists to a location accessible from the target system:

2. Import keys on the target system

On the target system, run the following command to import the public keys:

The --ignore-existing flag skips keys that already exist in the ACL database, which is useful when merging keys from multiple sources or re-running the import.

3. Verify the import

List the imported public keys to verify the import was successful:

4. Clean up

Remove the temporary keys file:

Importing individual key files

You can also import individual public or private key files. The dhconfig acls publickeys import command accepts:

  • A dsakeys.txt file containing multiple user publickey pairs.
  • A Deephaven public key file (e.g., pub-username.base64.txt).
  • A Deephaven private key file (e.g., priv-username.base64.txt) — only the public key portion is imported.

Warning

priv-*.base64.txt files are private keys and should never leave the machine on which they were created; prefer importing the non-sensitive public key file.

For example, to import a single user's public key: