---
title: Configuration properties backup and restoration
sidebar_label: Configuration properties
---

This guide demonstrates how to import and export Deephaven configuration, either as a complete suite or as individual components.

The sections below demonstrates how to export and import each restorable configuration type:

- [ACLs](#acl-db-restore)
- [Persistent Queries](#persistent-queries-restore)
- [Schema files](#schema-file-restore)
- [Routing files](#routing-files-restore)
- [Property files](#property-files-restore)

Backups may be done with the [Deephaven backup script](./backup-and-restore.md#deephaven-backup-script) or exported individually, as demonstrated below.

## Configuration backup

The data in etcd can be exported as separate files and imported into the new cluster with the [dhconfig tool](../configuration/dhconfig/overview.md). This allows the transfer of specific sets of properties instead of the entire dataset.

### Individual configuration backup

Backups for the complete suite or individual components of configurations may be done in a single step with the [Deephaven backup script](./backup-and-restore.md#deephaven-backup-script). Alternatively, individual configuration types can be exported with the following commands (shown with their backup-script equivalent):

```bash
# Each of the following commands is run as the "irisadmin" user. This may be different on your
# system, depending on installation properties. In all cases, the command should be run from
# a directory where this user has write permissions OR the "filename" should be a full path
# to a directory where the user has write permissions. The same goes for "pre_existing_path";
# the user must have write access to the directory.

# ACL export ("-A" or "--ACLs" from backup script) with:
sudo -u irisadmin /usr/illumon/latest/bin/dhconfig acls export --file [filename]

# Persistent Queries backup ("-p" or "--persistentQueries" from backup script) with:
sudo -u irisadmin /usr/illumon/latest/bin/dhconfig pq export --file [filename]

# Schemas backup ("-s" or "--schema" from backup script) with:
sudo -u irisadmin /usr/illumon/latest/bin/dhconfig schema export --directory [pre_existing_path]

# Primary routing backup (included in "-r" or "--routing" from backup script) with:
sudo -u irisadmin /usr/illumon/latest/bin/dhconfig routing export --file [filename]

# DIS routing backup (included in "-r" or "--routing" from backup script) with:
sudo -u irisadmin /usr/illumon/latest/bin/dhconfig dis export --directory [pre_existing_path]

# Property files backup ("-P" or "--propertyFiles" from backup script) with:
sudo -u irisadmin /usr/illumon/latest/bin/dhconfig properties export --directory [pre_existing_path]
```

There are several options for exporting configurations. For more details on additional options, see the full [dhconfig tool](../configuration/dhconfig/overview.md) documentation.

## Configuration restore

The following section demonstrates how to restore configuration, whether backed up with the [Deephaven backup script](./backup-and-restore.md#deephaven-backup-script) or individually exported with the [dhconfig tool](../configuration/dhconfig/overview.md).

> [!NOTE]
> If restoring on a different server, it is best practice to perform a backup on the target system _before_ running the restoration commands.

### ACL DB restore

The `dhconfig` tool can be used to import ACL data to any Deephaven deployment. See [`dhconfig acls`](../configuration/dhconfig/acls.md) for more details on additional options.

Specifically, to import ACLs with `dhconfig acls`, use the following command:

```bash
# ALC restore with:
sudo -u irisadmin /usr/illumon/latest/bin/dhconfig acls import --file [filename]
```

ACL files for export and import can be .xml or .json. The options `--overwrite` or `--replace-all` are often used with `dhconfig acls import` to direct the system on how to handle the data being imported with respect to any existing data. These options are covered in more detail in the [CLI ACL editor](../permissions/cli-acl-editor.md) documentation.

### Persistent Queries restore

Persistent Query configurations can be imported with the following command:

```bash
# Persistent Queries restore with:
sudo -u irisadmin /usr/illumon/latest/bin/dhconfig pq import --retain-serial --file [filename]
```

There are a number of options for importing Persistent Queries. See the full [dhconfig pq](../configuration/dhconfig/pq.md) documentation for additional options. In particular:

- If you're restoring to a different Deephaven installation, the `--server-override` option may be useful.
- If you want to include temporary Persistent Queries, add the `--include-temporary` parameter. Temporary Persistent Queries will be re-run when they're added. Since temporary Persistent Queries are typically used for one-time tasks, they are not imported by default.
- If you want to re-import the helper queries, then include the `--include-non-displayable` parameter.

### Schema file restore

Schema files are placed into a `.tar` file by the [Deephaven backup script](./backup-and-restore.md#deephaven-backup-script), so if the backup was created with that tool, the first step is to extract the schemas on the target system. If the configuration was exported directly with `dhconfig schema export --directory`, the following step can be skipped. To extract schemas from the `.tar` file:

```bash
# Create a unique temporary directory and extract the schema tar file into it
TEMP_SCHEMA_DIR=$(sudo -u irisadmin mktemp -d -t schemas.XXXXXX)
sudo -u irisadmin tar -xvf [schemas_file].tar  -C ${TEMP_SCHEMA_DIR}
```

Then, you can import the schema files from the directory.

To import all the schemas in a directory:

```bash
# Schemas restore with:
sudo -u irisadmin /usr/illumon/latest/bin/dhconfig schema import --directory [pre_existing_path]
```

See the full [dhconfig schema](../configuration/dhconfig/schemas.md) documentation for details on schema import options. In particular:

- The `--namespace` option can restrict the imports to specific namespaces.
- The `--force` option overwrites any existing schemas on the target system with the versions from this directory.

### Routing files restore

Two types of routing files can be restored: routing files exported with the `dhconfig routing export` command and routing files exported with the `dhconfig dis export` command.

To import:

```bash
# Primary routing restore with:
sudo -u irisadmin /usr/illumon/latest/bin/dhconfig routing import --file [filename].yml

# DIS routing restore with:
sudo -u irisadmin /usr/illumon/latest/bin/dhconfig dis import --file [dis_routing_file].yml
```

The `dhconfig dis import` will fail if the routing configurations already exist on the system. Add `--force` to overwrite existing configurations. To import a single configuration from the file, extract the appropriate section into a new file. See the full [dhconfig routing](../configuration/dhconfig/routing.md) and [dhconfig dis](../configuration/dhconfig/dis.md) documentation for details on the routing import options.

> [!WARNING]
> If the primary routing file is imported to a different server, it must be edited to update host names.
>
> If you want to overwrite the entire set of DIS configurations, use the `--clobber` flag. However, be cautious with this flag, as it will also delete any configurations not in the file you are importing.

### Property files restore

The [Deephaven backup script](./backup-and-restore.md#deephaven-backup-script) places property files into a `.tar` file, so if the backup was created with that tool, the first step is to extract the schemas on the target system. If the configuration was exported directly with `dhconfig properties export —-directory`, the following step can be skipped.

To extract property files from the `.tar` file:

```bash
# Create a unique temporary directory and extract the properties tar file into it
TEMP_PROP_DIR=$(sudo -u irisadmin mktemp -d -t props.XXXXXX)
sudo -u irisadmin tar -xvf [props_file].tar -C ${TEMP_PROP_DIR}
```

You can import individual property files with the command:

```bash
# For each desired property file, restore with:
sudo -u irisadmin /usr/illumon/latest/bin/dhconfig properties import --file [filename]
```

> [!WARNING]
> It is critical that `iris-endpoints.prop` properties from one instance **not** be imported to a different instance because hostnames and IP addresses defining the cluster are defined within the configuration. Changes made to `iris-defaults.prop` and `iris-endpoints.prop` will be overwritten during the next install/upgrade process.
>
> The `iris-environment.prop` file should be checked carefully to verify that there are no host names or IP addresses listed in the property file. If there are, you will need to edit the file to ensure that host these values are updated for the new cluster.

## Related documentation

- [Backup, Restore, and Migration overview](./backup-and-restore.md)
- [etcd and MySQL backup and restore](./etcd-and-acls-backup.md)
- [File system backup and restore](./configuration-files-backup.md)
- [Table migration](./table-migration.md)
- [Workspace data backup and restore](./workspace-data-backup.md)