From 4dc21d7ed1788d23ac92b49cab2f9b423e1b9f5e Mon Sep 17 00:00:00 2001
From: Thomas Waldmann <tw@waldmann-edv.de>
Date: Wed, 13 May 2026 01:14:24 +0200
Subject: [PATCH] docs: improve macOS Keychain instructions (fixes #5156)

(cherry picked from commit fb8bab1c2d1122d84cf5a3ee2f49e624923390a2)
---
 docs/faq.rst | 16 +++++++++++++---
 1 file changed, 13 insertions(+), 3 deletions(-)

diff --git a/docs/faq.rst b/docs/faq.rst
index 086a300b0..fc16b9d08 100644
--- a/docs/faq.rst
+++ b/docs/faq.rst
@@ -493,15 +493,25 @@ Using ``BORG_PASSCOMMAND`` with macOS Keychain
   the built-in ``security`` command, you can access it from the command line,
   making it useful for ``BORG_PASSCOMMAND``.
 
-  First generate a passphrase and use ``security`` to save it to your login
-  (default) keychain::
+  To store an existing passphrase in your login (default) keychain::
 
-    security add-generic-password -D secret -U -a $USER -s borg-passphrase -w $(head -c 32 /dev/urandom | base64 -w 0)
+    security add-generic-password -a $USER -s borg-passphrase -w YOUR_PASSPHRASE
+
+  Alternatively, to generate a new random passphrase and store it::
+
+    security add-generic-password -a $USER -s borg-passphrase -w $(head -c 32 /dev/urandom | base64 -w 0)
 
   In your backup script retrieve it in the ``BORG_PASSCOMMAND``::
 
     export BORG_PASSCOMMAND="security find-generic-password -a $USER -s borg-passphrase -w"
 
+  .. note::
+    If you run ``borg`` using ``sudo``, you must use the ``-E`` (preserve environment)
+    flag to ensure ``BORG_PASSCOMMAND`` is available and executed as the correct
+    user to access the keychain::
+
+      sudo -E borg create ...
+
 Using ``BORG_PASSCOMMAND`` with GNOME Keyring
   GNOME also has a keyring daemon that can be used to store a Borg passphrase.
   First ensure ``libsecret-tools``, ``gnome-keyring`` and ``libpam-gnome-keyring``