---
title: ACL storage
sidebar_label: ACL storage
---

Deephaven stores access control list (ACL) data in a backend database. This includes users, groups, passwords, public keys, and all access control rules.

## Storage options

Deephaven supports two options for ACL data storage:

| Backend  | Description                                                | Recommended for             |
| -------- | ---------------------------------------------------------- | --------------------------- |
| **etcd** | Distributed key-value store (same cluster as other config) | New installations (default) |
| **SQL**  | MariaDB or MySQL database (`dbacl_iris`)                   | Legacy installations        |

New installations default to etcd. Existing installations using MySQL continue to use MySQL unless explicitly migrated.

### etcd storage

When using etcd for ACL storage, Deephaven leverages the same etcd cluster used for other system configuration. This is enabled by the following properties:

```properties
IrisDB.groupProvider=etcd
IrisDB.permissionFilterProvider=etcd
authentication.server.customauth.class=com.illumon.iris.db.v2.permissions.EtcdDbAclProvider
iris.enableManagedUserAuthentication=true
```

### SQL storage

SQL-based ACL storage uses the `dbacl_iris` database. Configuration is set via properties:

```properties
MysqlDbAclProvider.host=localhost
MysqlDbAclProvider.db=dbacl_iris
MysqlDbAclProvider.ssl=false
MysqlDbAclProvider.user=irisro
MysqlDbAclProvider.passwordFile=/etc/sysconfig/deephaven/auth/db_acl_ro_passphrase.txt
MysqlDbAclProvider.readWriteUser=irisrw
MysqlDbAclProvider.readWritePasswordFile=/etc/sysconfig/deephaven/auth/db_acl_write_server_passphrase.txt
```

## Migrating from SQL to etcd

To migrate ACL data from SQL to etcd:

1. **Export ACL data** from the SQL store:

   ```bash
   sudo -u irisadmin /usr/illumon/latest/bin/dhconfig acls export --direct --file /tmp/acl-migration.xml
   ```

2. **Update properties** to use etcd (as shown above).

3. **Import ACL data** into etcd:

   ```bash
   sudo -u irisadmin /usr/illumon/latest/bin/dhconfig acls import --direct --file /tmp/acl-migration.xml
   ```

4. **Restart all services** using `dh_monit`:

   ```bash
   sudo /usr/illumon/latest/bin/dh_monit restart
   ```

See [Migrating ACLs to etcd](../installation/basic-install.md#appendix-g-migrating-acls-to-etcd) for detailed instructions.

## Backup and restore

### Export ACL data

Export ACLs to an XML file using `dhconfig acls`:

```bash
sudo -u irisadmin /usr/illumon/latest/bin/dhconfig acls export --file /tmp/acls-backup.xml
```

Export specific ACL types:

```bash
sudo -u irisadmin /usr/illumon/latest/bin/dhconfig acls export \
  --file /tmp/acls-backup.xml \
  --type passwd \
  --type publickeys \
  --type usergroup
```

Available types: `passwd`, `publickeys`, `usergroup`, `tableacls`, `columnacls`, `inputtableeditors`, `groupstrategy`, `strategyaccount`, `systemuser`.

### Import ACL data

```bash
# Import, failing on conflicts
sudo -u irisadmin /usr/illumon/latest/bin/dhconfig acls import --file /tmp/acls-backup.xml

# Import, overwriting existing entries
sudo -u irisadmin /usr/illumon/latest/bin/dhconfig acls import --file /tmp/acls-backup.xml --overwrite

# Replace entire ACL database (requires --direct)
sudo -u irisadmin /usr/illumon/latest/bin/dhconfig acls import --file /tmp/acls-backup.xml --replace-all --direct
```

> [!WARNING]
> The `--replace-all` option deletes all existing ACL data before importing.

After import, restart the authentication server and ACL write server:

```bash
sudo -u irisadmin monit restart authentication_server
sudo -u irisadmin monit restart db_acl_write_server
```

## Related documentation

- [Migrating ACLs to etcd](../installation/basic-install.md#appendix-g-migrating-acls-to-etcd)
- [dhconfig acls command reference](../configuration/dhconfig/acls.md)
- [etcd and MySQL backup](../backup-restore-migrate/etcd-and-acls-backup.md)
- [Permissions overview](./permissions-overview.md)