# 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:** ```bash 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): ```bash 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:** ```bash 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:** ```bash just check-deps ``` Checks if all required tools are installed and accessible in your `PATH`.

alias m := mount alias u := unmount MOUNTPOINT := "./mnt" # where the encrypted filesystem can be accessed VOLUME_NAME := "portable_luks_volume" # how the image should be named IMAGE_PATH := "./luks_container.img" # path where the image should be IMAGE_SIZE := "1G" # size how big the image should be required_deps := 'cryptsetup fallocate mkfs.ext4 zstd mount umount chown rmdir mkdir xxhsum' # required dependencies CHECKSUM := "xxh.checksum" default: mount # mounting the encrypted volume mount: check-deps verify-checksum decompress @echo "creating mountpoint" @mkdir -p {{MOUNTPOINT}} # creating mountpoint sudo cryptsetup luksOpen {{IMAGE_PATH}} {{VOLUME_NAME}} # opening the luks container sudo mount /dev/mapper/{{VOLUME_NAME}} {{MOUNTPOINT}} # mounting the filesystem sudo chown $USER {{MOUNTPOINT}} # setting permission for the current user to access the mount # unmounting the encrypted volume unmount: check-deps sudo umount {{MOUNTPOINT}} # unmounting the filesystem sudo cryptsetup luksClose {{VOLUME_NAME}} # closing the luks container rmdir {{MOUNTPOINT}} # removing the mountpoint just compress # compressing the image # creating an encrypted volume and mounting it create: check-deps sudo fallocate -l {{IMAGE_SIZE}} {{IMAGE_PATH}} # allocating the file sudo cryptsetup luksFormat {{IMAGE_PATH}} {{VOLUME_NAME}} # formating the file for luks sudo cryptsetup luksOpen {{IMAGE_PATH}} {{VOLUME_NAME}} # opening the luks container sudo mkfs.ext4 /dev/mapper/{{VOLUME_NAME}} # formatting the container with a filesystem mkdir -p {{MOUNTPOINT}} # creating a mountpoint sudo mount /dev/mapper/{{VOLUME_NAME}} {{MOUNTPOINT}} # mounting filesystem # compressing the image compress: @echo "Compressing the image and removing the original" zstd --rm --adapt {{IMAGE_PATH}} # decompressing the image decompress: @echo "Decompressing the image and removing compressed version" zstd --rm -d {{IMAGE_PATH}}.zst create-checksum: @xxhsum {{IMAGE_PATH}}.zst > {{CHECKSUM}} verify-checksum: @xxhsum -c {{CHECKSUM}} # Check if all required dependencies are installed check-deps: #!/usr/bin/env sh missing_deps="" # Loop through each dependency in the list for dep in {{required_deps}}; do # Check if the command exists in the PATH if ! command -v "$dep" > /dev/null 2>&1; then # If not found, add it to the list of missing dependencies (with a space separator) missing_deps="$missing_deps $dep" fi done # Check if the missing_deps variable has content (trim whitespace first) if [ -n "$(echo $missing_deps | xargs)" ]; then echo "Error: The following required dependencies are missing:" >&2 # Use xargs to print each missing dependency on a new line, prefixed with ' - ' echo "$missing_deps" | xargs -n1 printf " - %s\n" >&2 echo "Please install them and try again." >&2 # Exit with a non-zero status code to indicate failure exit 1 else # Optional: message indicating success echo "All dependencies satisfied." fi