I am making this post, because I started my adventure in unRAID and wanting to run LUKS encrypted drives. As a result, I wanted to be confident with LUKS management; but, the information I researched on LUKS on unRAID was scattered, non-existent, or outdated.

Before putting data onto an encrypted drive, I made it my mission to understand LUKS and managing the headers in case of corruption. I could not find a nice summary/guide to achieve the following within unRAID:

1. Backup a LUKS Header (Steps 1-5)

2. Intentionally corrupt the Header (this was conducted for testing; do not perform under normal operation)

3. Restore the LUKS Header (Steps 6-10)

My goals with this post is to hopefully provide a guide or reference to individuals in the community that are at a point like me, and to receive feedback from those more experienced to further refine this process for myself and others.

I documented my steps running through a backup/corruption/restore process for replication and sharing.

For understanding unRAID partitions and labels see unRAID Data Recovery Docs. Quick summary table below:

Label	Typical path	Usage	Parity protected?
Disk 7	/mnt/disk7	Unraid mount point	Yes (if array disk)
Array partition	/dev/md7p1	Unraid-managed device	Yes
Raw partition	/dev/sdj1	Direct device access	No

• For array drives, always use the Unraid-managed device (such as /dev/md5p1) to preserve parity protection

• Using the raw partition (e.g. /dev/sdj1) will not update parity, leaving it invalid

---

THE INTENTIONAL HEADER CORRUPTION AND RESTORE WAS CONDUCTED ON MY NEW SERVER WITHOUT ANY DATA ON IT

MAKE DATA BACKUPS. YOU ARE RESPONSIBLE FOR YOUR DATA

---

Unraid OS 7.3.0-beta2

Below is an actual run through after having one 12TB drive formatted to xfs-encrypted.

1. Array started in Maintenance Mode

   • in this mode the md (unRAID-managed) driver is active

   • allows me to read/write header while simultaneously updating parity (I want this to simulate header corruption with a running array and, therefore, parity updating with the corruption)
      

lsblk

# outputs
NAME        MAJ:MIN RM   SIZE RO TYPE  MOUNTPOINTS
 loop0         7:0    0   731M  1 loop  /usr
 loop1         7:1    0   299M  1 loop  /lib/firmware
 sda           8:0    0  10.9T  0 disk  
 └─sda1        8:1    0  10.9T  0 part  
 sdb           8:16   0  10.9T  0 disk  
 └─sdb1        8:17   0  10.9T  0 part  
 md1p1         9:1    0  10.9T  0 md    
 └─md1p1     251:0    0  10.9T  0 crypt # here 

 

cryptsetup luksDump /dev/md1p1
# outputs LUKS header information and keyslots in use.

• confirms you're looking at correct md unRAID-managed device with a LUKS header

mkdir -p /boot/config/luks_backups 
# making a folder on boot drive to save my LUKS header backup file (this will also get copied offiste)

 

5. NOTE: I use Serial Number of HDD to ensure the matching of backup files to the physical device. (I am not sure what name persists in unRAID if I physically move drives around, so I used the serial no.)

   For this example I've replaced my S/N with WD-a1a1a1; but wherever you see this, replace with the Serial Number of your drive.

cryptsetup luksHeaderBackup /dev/md1p1 --header-backup-file /boot/config/luks_backups/WD-a1a1a1_header.img

• naming the backup header file like this ensure you know which drive it belongs to

• verify UUID of the backup file and the header of the drive

cryptsetup luksUUID /dev/md1p1
cryptsetup luksUUID /boot/config/luks_backups/WD-a1a1a1_header.img

• UUIDs should match
   

---

the following Bash command is just during testing to simulate LUKS corruption; DO NOT DO DURING NORMAL BACKUP AND/OR RESTORE PROCESS

dd if=/dev/zero of=/dev/md1p1 bs=1M count=10
# writes 10 MB of 0s to the start of the drive ! THIS WILL BREAK THE HEADER !
# LUKS version 2 (you can see this in luksDump) headers are 16 MB so writing 10 MB will wipe out header without touching data beyond the header

cryptsetup luksDump /dev/md1p1
# tests the header is "corrupted"; it will output "not a valid LUKS header"

---

 

6. To simulate a server with a corrupted header on an Array that hasn't started up; I stopped the Array that was running in Maintenance mode.

   • once stopped, you cannot start the Array again without formatting the drive with a new passphrase; DO NOT DO THIS IF YOU KNOW YOU HAVE DATA ON THE DRIVE AS IT WILL BE ERASED

   • you will see a yellow padlock next to drive and show that it will be encrypted once formatted (it will say its unmountable). Our drive is already encrypted, just unRAID doesn't think it is because the header is corrupted

   • DO NOT START ARRAY AT THIS POINT; DO NOT FORMAT THE DRIVE
      

7. take note of the Serial No. of the drive to be restored (WD-a1a1a1 in this test case)

   • with the unRAID array not started, md device no longer exists and we will now be targeting the "raw partition" atsdbX

     ls -l /dev/disk/by-id/ | grep [SERIAL]
     
     # outputs
     lrwxrwxrwx 1 root root  9 Apr  6 14:57 ata-WD-a1a1a1 -> ../../sdb
     lrwxrwxrwx 1 root root 10 Apr  6 14:57 ata-WD-a1a1a1-part1 -> ../../sdb1 #find the serial device that matches and note the raw partition

   • sdb1 in this case
      

cryptsetup luksHeaderRestore /dev/sdb1 --header-backup-file /boot/config/luks_backups/WD-a1a1a1_header.img
# confirm with an uppercase YES

cryptsetup luksDump /dev/sdb1
# should output the LUKS header information now that it's restored :)

 

9. Refresh Main page on WebGUI (see Addendum A below)

   • the server will still show the same issue as before; unRAID still doesn't know the drive is encrypted and wants to format it (it shows as unmountable)...DON'T DO IT

   • even though the physical bits on the platter are now correct, the unRAID management layer is still holding onto the "Error" status from when it last polled the drive and found it broken.

   • It needs to re-scan the partition table and see the valid LUKS signature you just restored.

   • The "Force Rescan"

     • Go to the Main tab.

     • Change the Slot 1 assignment to "None" (or whatever slot #)

     • Wait 2 seconds.

     • Change the Slot 1 assignment back to your Physical Drive Serial.

     • Check the UI: should now see that unRAID detects the device as an encrypted drive (green padlock)

   • Start the Array up :)
      

10. IMPORTANT PARITY STEP

    • because we intentionally corrupted the LUKS header (by writing 0s over it) while targeting the unRAID-managed device path md1p1 to simulate real-world corruption in a parity running array, these 0s updated on the parity disk as well

    • THEN, we restored the LUKS header to the device partition (non unRAID-managed) at sdb1. Because of this, PARITY WILL BE INVALID (would detect on next Parity Check, but don't wait for next scheduled check)

    • manually initiate and Parity Check with "write corrections to parity" enabled

      • because we wrote over the first 10MB of zeros it shows 2556 errors corrected (from my Googling, this seems to line up(ish) with the 10 MB of zeros we wrote over the header and with 4096 Byte stripes on parity; 10 MB / 4096 bytes = 2560 error sectors)

Edited April 21Apr 21 by mikescott
Edit 1: Addendum A added | Edit 2: Cleaned up some formatting

Addendum A

My continued pursuit to better understand LUKS and drive management with unRAID has continued, and I think I have gained additional understanding how the drives and headers work. But, I would love feedback from the more experienced people in here; there is no official documentation outlining what I am discussing here (which is why I am documenting it here), I am just testing and troubleshooting to understand the system more; and sharing here for continued reference and, hopefully, feedback.

My understanding now of the bytes on the drive in its different states are as follows (we will use the raw partition sdb1 and the mapped unRAID managed partition md1p1 as an example)

• Array is stopped: md1p1 does not exist and we will only see sdb1

  • in this "raw" partition state I believe the data on the drives starts like this: | unRAID metadata ---- | LUKS header ---- | your actual data --------------------- |

  • we can run cryptsetup luksDump /dev/sdb1 for header information

• Array running (maintenance or normal): the drive is now mapped to unRAID managed partition md1p1

  • in this unRAID managed partition state, the first parts of the data on the drive now start with the LUKS header: | LUKS header ---- | your actual data --------------------- |

  • we can run cryptsetup luksDump /dev/md1p1 for header information (targeting sdb1 now will not work)

Above I backed up the header from unRAID managed md1p1 (which is good) and successfully restored to raw partition sdb1; while this worked, I now wonder if this is the reason for Step 9 necessitated above. I wrote over the unRAID metadata (I think several KB), with the header restore and the refresh was needed for unRAID to add its metadata back to the beginning of the drive, and obviously invalidating our Parity requiring a check and correction.

This leaves me with the thought that the Gold Standard for header restore would be to obviously restore to md1p1 , and this makes sense. The only question I have, to which I do not have an answer yet (haven't tested and can't remember during my original test-run), is if it was possible to start the Array in Maintenance mode with an unmountable drive in the array (remember it shows as unmountable bc the header was corrupted (intentionally for testing)). I'm fairly confident the Start button was greyed out, but don't recall if I tried toggling Maintenance Mode on or not, and if I did, would the Start button become available to select? Would love input on the ability of starting Array in maintenance mode with unmountable drives in array.

If this is not possible, then I am left to assume the header backup from md1p1 and restoring to the raw sdb1 is the only "plan of action" for restoring your headers.

Edited April 14Apr 14 by mikescott

Just a quick thanks for this info, recently setup Unraid and encrypted disks and used it to backup my LUKS headers.

13 hours ago, thorium said:

Just a quick thanks for this info, recently setup Unraid and encrypted disks and used it to backup my LUKS headers.

Glad to hear it :) Remember to copy the header backups somewhere outside/off your physical server, and to make additional header backups of new drives added to the array down the road (each drive has their own header). While one passphrase (aka. key) unlocks all the drives in your array (aka. your vault) in unRAID, each drive has a different header (aka. lock).