justfiles/luks-portable

Portable LUKS Volume Manager (using just)

This justfile provides commands to create, manage, mount, and unmount a portable, encrypted LUKS volume stored in a file. It also includes compression and checksum verification for the volume image.

Features

• Create a new LUKS encrypted volume within a file.
• Mount the encrypted volume to a specified mountpoint.
• Unmount the encrypted volume.
• Compress the volume image using zstd for portability/storage.
• Decompress the volume image.
• Create and verify checksums for the compressed image.
• Automatically checks for required dependencies.

Requirements

The following dependencies must be installed on your system: cryptsetup, fallocate, mkfs.ext4, zstd, mount, umount, chown, rmdir, mkdir, xxhsum.

The check-deps recipe will verify these before most operations.

Configuration

You can modify these variables at the top of the justfile:

• MOUNTPOINT: Directory where the decrypted filesystem will be mounted (default: ./mnt).
• VOLUME_NAME: Internal name used by cryptsetup for the mapped device (default: portable_luks_volume).
• IMAGE_PATH: Path to the LUKS container file (default: ./luks_container.img).
• IMAGE_SIZE: Size for the container file when creating it (default: 1G).
• CHECKSUM: Path to the checksum file (default: xxh.checksum).

Usage

Note: Most commands require sudo privileges for cryptsetup and mount/umount operations. You will likely be prompted for your password.

1. Create a new encrypted volume:

   just create
   

   This will:

   • Allocate a file (IMAGE_PATH) of IMAGE_SIZE.
   • Format it as a LUKS volume.
   • Open the LUKS volume.
   • Create an ext4 filesystem inside it.
   • Create the MOUNTPOINT directory.
   • Mount the filesystem to MOUNTPOINT.
   • (Important) After creation, you should immediately just unmount to compress the initial empty image if desired.

2. Mount the existing volume:

   • If the image is compressed (.zst extension):

     just mount # or 'just m' or simply 'just' (default)
     

     This will: check dependencies, verify checksum (if xxh.checksum exists), decompress the image, create the mountpoint, open the LUKS container, mount the filesystem, and set user ownership on the mountpoint.
   • If the image is not compressed: You might need to manually run the steps after decompression or adapt the mount recipe. The default flow assumes starting from a compressed state.

3. Unmount the volume:

   just unmount # or 'just u'
   

   This will: unmount the filesystem, close the LUKS container, remove the mountpoint directory, and compress the image file (IMAGE_PATH -> IMAGE_PATH.zst), removing the original.

4. Manual Compression/Decompression:

   • Compress: just compress (Compresses IMAGE_PATH, removes original)
   • Decompress: just decompress (Decompresses IMAGE_PATH.zst, removes compressed version)

5. Checksum Management:

   • Create checksum: just create-checksum (Creates xxh.checksum from IMAGE_PATH.zst)
   • Verify checksum: just verify-checksum (Verifies IMAGE_PATH.zst against xxh.checksum)

6. Check Dependencies:

   just check-deps
   

   Checks if all required tools are installed and accessible in your PATH.