1#!/usr/bin/env python3
2"""Attach a preallocated, disposable file as a ZFS read cache."""
3import fcntl
4import json
5import os
6from pathlib import Path
7import shutil
8import stat
9import subprocess
10import sys
11import tempfile
12
13
14def ensure(pool, image, capacity, headroom):
15 if capacity < 64 * 2**20 or capacity % 4096 or headroom < 0:
16 raise ValueError("Cache capacity must be at least 64 MiB and aligned to 4096 bytes.")
17 if not image.is_absolute() or image.resolve() != image:
18 raise ValueError("Use an absolute cache path without symlinks.")
19 image.parent.mkdir(mode=0o700, parents=True, exist_ok=True)
20 with (image.parent / ".lock").open("a") as lock:
21 fcntl.flock(lock, fcntl.LOCK_EX)
22 status = json.loads(subprocess.check_output(
23 ["zpool", "status", "-jP", "--json-flat-vdevs", "--json-int", pool], text=True))
24 devices = status["pools"][pool]["vdevs"].values()
25 attached = next((device for device in devices if device.get("path") == str(image)), None)
26 if attached:
27 if attached["class"] != "l2cache" or attached["state"] != "ONLINE":
28 raise ValueError("The configured cache is not an online cache device; inspect zpool status.")
29 info = image.lstat()
30 if not stat.S_ISREG(info.st_mode) or info.st_nlink != 1 or info.st_size != capacity:
31 raise ValueError("The attached cache file differs from its configured capacity or type.")
32 return
33 if image.exists():
34 raise ValueError("An unattached file already occupies the cache path; preserve or remove it before retrying.")
35 for abandoned in image.parent.glob(".preparing-*"):
36 abandoned.unlink()
37 if shutil.disk_usage(image.parent).free < capacity + headroom:
38 raise ValueError("Insufficient SSD space for the cache and reserved OS headroom.")
39 descriptor, temporary = tempfile.mkstemp(prefix=".preparing-", dir=image.parent)
40 try:
41 with os.fdopen(descriptor, "wb") as output:
42 os.posix_fallocate(output.fileno(), 0, capacity)
43 os.fsync(output.fileno())
44 os.link(temporary, image)
45 os.unlink(temporary)
46 directory = os.open(image.parent, os.O_RDONLY | os.O_DIRECTORY)
47 try:
48 os.fsync(directory)
49 finally:
50 os.close(directory)
51 subprocess.run(["zpool", "add", pool, "cache", str(image)], check=True)
52 finally:
53 Path(temporary).unlink(missing_ok=True)
54
55
56if __name__ == "__main__":
57 try:
58 ensure(sys.argv[1], Path(sys.argv[2]), int(sys.argv[3]), int(sys.argv[4]))
59 except (ValueError, OSError, subprocess.CalledProcessError) as error:
60 raise SystemExit(str(error))