76 lines
3.4 KiB
Markdown
76 lines
3.4 KiB
Markdown
# 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`.
|