Overview

This plugin automatically unlocks your encrypted disks and starts the array at boot time.

The plugin protects your disk encryption key using Shamir's Secret Sharing. Your disk encryption key is stored encrypted on the flash drive, protected by a randomly-generated wrapping key. This wrapping key is split into multiple pieces—you configure how many pieces to create and how many are needed to unlock your drives. At boot, the plugin retrieves the required number of pieces from locations you specify (like web servers, SSH hosts, or DNS records), reconstructs the wrapping key, decrypts your disk encryption key, and unlocks your array automatically.

Key Features

• Automatic Array Unlock: Automatically unlock encrypted arrays at boot time without manual intervention.

• Shamir's Secret Sharing Protection: Your disk encryption key is protected by a wrapping key that is split into multiple pieces for enhanced security.

  • Configure how many pieces to create and how many are required to reconstruct the wrapping key

  • No single location stores the complete wrapping key needed to decrypt your disk encryption key

  • Pieces are displayed once during setup as base64 strings—store them securely in accessible locations

  • If pieces are lost, a new set must be generated

• Flexible Retrieval Methods: Supports most backends available in rclone for retrieving key pieces, and also in DNS TXT records. Examples:

  • HTTP/HTTPS servers: :http,url='https://server.my.ts.net:888/key2':

  • SSH/SFTP servers: :sftp,host=server2.my.net,user=root,key_file=/config/.ssh/id_ed25519:/root/key3

  • DNS TXT records: dns:testkey.domain.tld

• Non-Invasive Security: Protects your keyfile with the distributed wrapping key without modifying disk encryption headers or drive configuration.

Installation

This plugin is available via Community Applications.

It can also be installed manually. Use the following path to install from the Unraid WebGUI (Plugins -> Install Plugin):

Main release:

https://raw.githubusercontent.com/dkaser/unraid-auto-unlock/main/plugin/auto-unlock.plg

Preview Releases (gets updates more frequently):

https://raw.githubusercontent.com/dkaser/unraid-auto-unlock/main/plugin/auto-unlock-preview.plg (Preview)

Configuration

Detailed configuration information is available at https://edac.dev/unraid/auto-unlock/setup/

Changelog

https://github.com/dkaser/unraid-auto-unlock/releases

Feedback & Support

Questions, suggestions, or issues?

Reply to this thread or open an issue on GitHub: https://github.com/dkaser/unraid-auto-unlock/issues

Edited December 17, 2025Dec 17 by EDACerton

On 12/5/2025 at 5:09 AM, EDACerton said:

Installation

This plugin is currently in public preview. Use the following path to install from the Unraid WebGUI (Plugins -> Install Plugin):

https://raw.githubusercontent.com/dkaser/unraid-auto-unlock/main/plugin/auto-unlock-preview.plg

It's available in CA!🥳

The "main" (non-preview) version is available now, and should be in CA soon (just waiting on its approval there).

What's the correct identifier to use Backblaze as a S3 provider? I've tried all of the combinations of "provider=Backblaze" I can think of and I keep getting

NOTICE: s3: s3 provider "Backblaze" not known - please set correctly

On 12/23/2025 at 11:06 AM, Bobat said:

What's the correct identifier to use Backblaze as a S3 provider? I've tried all of the combinations of "provider=Backblaze" I can think of and I keep getting

NOTICE: s3: s3 provider "Backblaze" not known - please set correctly

For B2, there's a couple of different options that you can take:

Using the S3 provider "Other":

:s3,provider=Other,access_key_id=KEY_ID,secret_access_key=APPLICATION_KEY,endpoint=ENDPOINT_FROM_BUCKET_INFO:BUCKET_NAME/piece.txt

Using the B2 Provider:

:b2,account=KEY_ID,key=APPLICATION_KEY:BUCKET_NAME/piece.txt

Awesome, got this working now. Great plugin, thanks!

Not having any luck with a piece stored on my websever. DNS works fine. Can't figure it out...

If I take the same URL and paste it into firefox, it immediately returns the correct chunk of the key

Testing path: :http,url='https://www.[removed].com/share/share2.txt':
2:31PM DBG Debug logging enabled
2:31PM DBG Build information git_dirty=no revision=0ac10a054a7fbb2167a048698b053eeb4ace32b4 tag=2025.12.16.0447
2:31PM DBG Read fsState from var.ini fsState=Started
2:31PM DBG var.ini found and readable fsState=Started
2:31PM FTL Failed to execute command error="failed to fetch share: failed to open object: object not found"
Result: FAIL

Any ideas?

Edited December 31, 2025Dec 31 by dgriff

4 minutes ago, dgriff said:

Not having any luck with a piece stored on my websever. DNS works fine. Can't figure it out...

If I take the same URL and paste it into firefox, it immediately returns the correct chunk of the key

Testing path: :http,url='https://www.[removed].com/share/share2.txt':
2:31PM DBG Debug logging enabled
2:31PM DBG Build information git_dirty=no revision=0ac10a054a7fbb2167a048698b053eeb4ace32b4 tag=2025.12.16.0447
2:31PM DBG Read fsState from var.ini fsState=Started
2:31PM DBG var.ini found and readable fsState=Started
2:31PM FTL Failed to execute command error="failed to fetch share: failed to open object: object not found"
Result: FAIL

Any ideas?

What happens if you run

curl https://…

From the command line?

6 hours ago, dgriff said:

Not having any luck with a piece stored on my websever. DNS works fine. Can't figure it out...

If I take the same URL and paste it into firefox, it immediately returns the correct chunk of the key

Testing path: :http,url='https://www.[removed].com/share/share2.txt':
2:31PM DBG Debug logging enabled
2:31PM DBG Build information git_dirty=no revision=0ac10a054a7fbb2167a048698b053eeb4ace32b4 tag=2025.12.16.0447
2:31PM DBG Read fsState from var.ini fsState=Started
2:31PM DBG var.ini found and readable fsState=Started
2:31PM FTL Failed to execute command error="failed to fetch share: failed to open object: object not found"
Result: FAIL

Any ideas?

Update: it turns out that using the http implementation in rclone doesn't work as smoothly as I would like (it works fine for files in the root, but as soon as you add a subdirectory it breaks).

If you update to the latest plugin version, you should be able to add a plain http(s) URL to the config as:

https://www.[removed].com/share/share2.txt

That should work better.

On 12/31/2025 at 8:40 PM, EDACerton said:

Update: it turns out that using the http implementation in rclone doesn't work as smoothly as I would like (it works fine for files in the root, but as soon as you add a subdirectory it breaks).

If you update to the latest plugin version, you should be able to add a plain http(s) URL to the config as:

https://www.[removed].com/share/share2.txt

That should work better.

Indeed it does, working now, thanks again!

I'm having trouble setting up the tool. I enter the passphrase or keyfile and get the following message...

---

Initializing... 9:10AM INF Verifying that key can unlock disks keyfile=/root/keyfile 9:10AM INF LUKS encrypted device found device=/dev/sda1 9:10AM ERR Failed to unlock LUKS device error="exit status 4" device=/dev/sda1 9:10AM INF LUKS encrypted device found device=/dev/sdb1 9:10AM ERR Failed to unlock LUKS device error="exit status 4" device=/dev/sdb1 9:10AM INF LUKS encrypted device found device=/dev/sdc1 9:10AM ERR Failed to unlock LUKS device error="exit status 4" device=/dev/sdc1 9:10AM INF LUKS encrypted device found device=/dev/sdd1 9:10AM ERR Failed to unlock LUKS device error="exit status 4" device=/dev/sdd1 9:10AM INF LUKS encrypted device found device=/dev/sdg1 9:10AM ERR Failed to unlock LUKS device error="exit status 4" device=/dev/sdg1 9:10AM INF LUKS encrypted device found device=/dev/sdh1 9:10AM ERR Failed to unlock LUKS device error="exit status 4" device=/dev/sdh1 9:10AM FTL Failed to execute command error="keyfile test failed: keyfile could not decrypt any LUKS devices" Result: FAIL

---

Currently, my hard drives are decrypted using event-driven scripts.

# Auto Unlock Array

tar -xzf /boot/custom/bin/events -C /usr/local/

if [[ ! -e /root/keyfile ]]; then

7z x -p'XXXXXXXXXX' /boot/custom/key.7z -o/root/

fi

which works without any problems.

Here are the test results for my keys, which are valid.
==================================================
--- LUKS Encryption Analysis ---
==================================================

Analysis Mode: SIMPLE
Generated: 2026-01-16 09:02:52

Found 5 LUKS encrypted device(s)

--- Simple Device List ---
✅ /dev/md1p1 (Array Device) - Keyfile valid
✅ /dev/md2p1 (Array Device) - Keyfile valid
✅ /dev/md3p1 (Array Device) - Keyfile valid
✅ /dev/md4p1 (Array Device) - Keyfile valid
✅ /dev/md5p1 (Array Device) - Keyfile valid

The Main Version in CA is the recommended Stable and the Preview the Beta Version for Testing/not Production Systems?

Yes

Thank you for the plugin.

I have a similar problem as this guy on GitHub: https://github.com/dkaser/unraid-auto-unlock/issues/65

After entering my passphrase (no keyfile!) I see this output:

Initializing...
12:28AM INF Verifying that key can unlock disks keyfile=/root/keyfile
12:28AM INF LUKS encrypted device found device=/dev/sda1
12:28AM ERR Failed to unlock LUKS device error="exit status 4" device=/dev/sda1
12:28AM INF LUKS encrypted device found device=/dev/sdb1
12:28AM ERR Failed to unlock LUKS device error="exit status 4" device=/dev/sdb1
12:28AM INF LUKS encrypted device found device=/dev/sdc1
12:28AM ERR Failed to unlock LUKS device error="exit status 4" device=/dev/sdc1
12:28AM INF LUKS encrypted device found device=/dev/sde1
12:28AM ERR Failed to unlock LUKS device error="exit status 4" device=/dev/sde1
12:28AM INF LUKS encrypted device found device=/dev/sdg1
12:28AM ERR Failed to unlock LUKS device error="exit status 4" device=/dev/sdg1
12:28AM INF LUKS encrypted device found device=/dev/sdi1
12:28AM ERR Failed to unlock LUKS device error="exit status 4" device=/dev/sdi1
12:28AM FTL Failed to execute command error="keyfile test failed: keyfile could not decrypt any LUKS devices"
Result: FAIL

This doesn't make much sense because I haven't selected a keyfile
The passphrase I entered is correct

1 hour ago, ParityPenguin said:

Thank you for the plugin.

I have a similar problem as this guy on GitHub: https://github.com/dkaser/unraid-auto-unlock/issues/65

After entering my passphrase (no keyfile!) I see this output:

Initializing...
12:28AM INF Verifying that key can unlock disks keyfile=/root/keyfile
12:28AM INF LUKS encrypted device found device=/dev/sda1
12:28AM ERR Failed to unlock LUKS device error="exit status 4" device=/dev/sda1
12:28AM INF LUKS encrypted device found device=/dev/sdb1
12:28AM ERR Failed to unlock LUKS device error="exit status 4" device=/dev/sdb1
12:28AM INF LUKS encrypted device found device=/dev/sdc1
12:28AM ERR Failed to unlock LUKS device error="exit status 4" device=/dev/sdc1
12:28AM INF LUKS encrypted device found device=/dev/sde1
12:28AM ERR Failed to unlock LUKS device error="exit status 4" device=/dev/sde1
12:28AM INF LUKS encrypted device found device=/dev/sdg1
12:28AM ERR Failed to unlock LUKS device error="exit status 4" device=/dev/sdg1
12:28AM INF LUKS encrypted device found device=/dev/sdi1
12:28AM ERR Failed to unlock LUKS device error="exit status 4" device=/dev/sdi1
12:28AM FTL Failed to execute command error="keyfile test failed: keyfile could not decrypt any LUKS devices"
Result: FAIL

This doesn't make much sense because I haven't selected a keyfile
The passphrase I entered is correct

Do you have any encrypted pools, or all of the encrypted drives in the array?

2 minutes ago, EDACerton said:

Do you have any encrypted pools, or all of the encrypted drives in the array?

I dont have any pools, only an array with 2 not encrypted parity disks and 6 encrypted xfs disks.

10 minutes ago, ParityPenguin said:

I dont have any pools, only an array with 2 not encrypted parity disks and 6 encrypted xfs disks.

Gotcha. There’s a known problem where you can’t set up the plugin with the array started if all of the encrypted disks are in the array.

I should have a fix for that in a day or two.

40 minutes ago, EDACerton said:

Gotcha. There’s a known problem where you can’t set up the plugin with the array started if all of the encrypted disks are in the array.

I should have a fix for that in a day or two.

Thank you for the information, after stopping the array it actually worked!

Thanks for making such a great plugin! It works as intended and the documentation was easy to follow!

I have 1 questions;

• I've already setup rclone with pcloud for syncing some data, the documentation states "Most rclone backends should work for piece storage.", can i use that configured location for storing a piece? If so, could you help me with the location string? Based on the availably documentation i couldn't figure out how to set it up

@EDACerton is there still support on this plugin? If my question is out of scope please let me know.