---
title: Migrating public keys
sidebar_label: 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](./etcd-and-acls-backup.md).

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:

```bash
# Check all common locations
ls -la /etc/sysconfig/deephaven/auth/dsakeys.txt \
       /etc/sysconfig/deephaven/auth/dsakeys.txt.backup \
       /etc/sysconfig/illumon.d/resources/dsakeys.txt 2>/dev/null
```

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

```bash
scp <path-to-dsakeys.txt> target-server:/tmp/dsakeys.txt
```

### 2. Import keys on the target system

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

```bash
sudo -u irisadmin /usr/illumon/latest/bin/dhconfig acls publickeys import \
    --file /tmp/dsakeys.txt \
    --ignore-existing
```

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:

```bash
sudo -u irisadmin /usr/illumon/latest/bin/dhconfig acls publickeys list
```

### 4. Clean up

Remove the temporary keys file:

```bash
rm /tmp/dsakeys.txt
```

## 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:

```bash
sudo -u irisadmin /usr/illumon/latest/bin/dhconfig acls publickeys import \
    --file /path/to/pub-username.base64.txt
```

## Related documentation

- [Backup, Restore, and Migration overview](./backup-and-restore.md)
- [Public and private keys](../configuration/public-and-private-keys.md)
- [dhconfig ACLs](../configuration/dhconfig/acls.md)
- [Public and private key authentication](../security/keys-and-keyfiles.md)