From 8b548776ffc3415d807f33f554dc2e30848bc1cb Mon Sep 17 00:00:00 2001 From: Kyle Evans Date: Mon, 15 Sep 2025 12:26:17 -0500 Subject: [PATCH] zfsprops(7): attempt to clarify the keylocation description The current description is somewhat difficult to parse through, and in some cases is a little unclear as to the behavior. Split it into a paragraphs based on the three distinct behaviors you may get: prompt, file URL, HTTP(S) URL. The descriptions of the file and HTTP(s) behavior seems fine, but prompt is a little vague- expand on it and make it clear that the behavior is actively based on whether the inquisitor of key-data is provided with a tty for stdin or not. Also clarify *why* one shouldn't "place keys which should be kept secret on the command line" and note that you *have* to supply the key via stdin if it's a raw key, just to be sure. Reviewed-by: Allan Jude Reviewed-by: Brian Behlendorf Reviewed-by: Alexander Motin Reviewed-by: George Melikov Signed-off-by: Kyle Evans Closes #17742 --- man/man7/zfsprops.7 | 24 ++++++++++++++++-------- 1 file changed, 16 insertions(+), 8 deletions(-) diff --git a/man/man7/zfsprops.7 b/man/man7/zfsprops.7 index 0930771c9..77e994b91 100644 --- a/man/man7/zfsprops.7 +++ b/man/man7/zfsprops.7 @@ -39,7 +39,7 @@ .\" Copyright (c) 2019, Kjeld Schouten-Lebbing .\" Copyright (c) 2022 Hewlett Packard Enterprise Development LP. .\" -.Dd August 6, 2025 +.Dd September 13, 2025 .Dt ZFSPROPS 7 .Os . @@ -1192,18 +1192,26 @@ keylocation can be with either .Nm zfs Cm set or .Nm zfs Cm change-key . +.Pp If .Sy prompt -is selected ZFS will ask for the key at the command prompt when it is required -to access the encrypted data (see +is selected, ZFS will expect the key to be provided when it is required to +access the encrypted data (see .Nm zfs Cm load-key for details). -This setting will also allow the key to be passed in via the standard input -stream, -but users should be careful not to place keys which should be kept secret on -the command line. -If a file URI is selected, the key will be loaded from the +If stdin is a TTY, then ZFS will ask for the key to be provided. +Otherwise, stdin is expected to be the key to use and will be processed as such. +Users should be careful not to place keys which should be kept secret on the +command line, as most operating systems may expose command line arguments to +other processes. +If the +.Dq raw +.Sy keyformat +was used, then the key must be provided via stdin. +.Pp +If a file URL is selected, the key will be loaded from the specified absolute file path. +.Pp If an HTTPS or HTTP URL is selected, it will be GETted using .Xr fetch 3 , libcurl, or nothing, depending on compile-time configuration and run-time