Detail how to use macOS/GNOME/KDE keyrings for repo passwords (fixes #392) #2837

milkey-mouse · 2017-07-16T22:30:41Z

I haven't tested the macOS instructions yet, they were made with a careful reading of the security man pages. I also haven't made the equivalent tutorial for the KDE keyring equivalent (KWallet) yet.

milkey-mouse · 2017-07-16T22:34:17Z

If anyone reading this has a Mac and is willing to test the Mac instructions that would help (otherwise I'll have to go down to the Apple store and hope none of their Geniuses™ notice me 😉)

enkore · 2017-07-17T06:56:38Z

docs/faq.rst

+  .. note:: For this to automatically unlock the keychain it must be run
+    in the ``dbus`` session of an unlocked terminal; for example, running a backup
+    script as a ``cron`` job might not work unless you also ``export DISPLAY=:0``
+    so ``secret-tool`` can pick up your open session.


Note: accessing the session bus of a different user, even as root, was made more complex some time ago.

$ cat /etc/dbus-1/session-local.conf <busconfig> <policy context="default"> <allow user="root"/>  </policy> </busconfig>

env vars: DISPLAY, XAUTHORITY=/home/.../.Xauthority, DBUS_SESSION_BUS_ADDRESS=unix:path=/run/user/1000/bus

The note that's there already was copied pretty much verbatim from discussion in #392. Should I add another note about this/replace the existing one?

Why would you need to access the session bus of a different user for a backup script anyway? If you had borg create in root's crontab?

Between a rock and a hard place: Document largely undocumented things about a platform which changes on a whim? Or don't document it, but someone(?) who attempts it will find it difficult to do so?

I can't recommend either.

If you had borg create in root's crontab?

Yes; it can also be used to send notifications to the desktop [of a specific user, Linux is not a multi-user OS].

Not sure if this is the best place to comment, but I hope this helps someone who stumbles over this and can point me to the right place where it could be added.

This is how I use GNOME Keyring with borg in a user cron job (as I need a unlocked terminal (which I read as unlocked GNOME session) anyway):

export BORG_PASSCOMMAND='sudo -u $USERNAME DISPLAY=:0 DBUS_SESSION_BUS_ADDRESS=unix:path=/run/user/1000/bus secret-tool lookup borg-repository repo-name' sudo -E borg create /path/to/repo:mybackup-{now} /path/to/backup

Please note the Important note about permissions. You will have "problems" accessing the repository as the normal user after running sudo -E borg.

The secret key was added as described as user $USERNAME:

secret-tool store borg-repository repo-name --label="Borg Passphrase"

enkore · 2017-07-17T06:59:20Z

docs/faq.rst

+  directory and use permissions to keep anyone else from reading it. For
+  example, first create a key::
+
+    dd if=/dev/urandom of=~/.borg-passphrase bs=1024 count=1


Perhaps use hex here as well, to avoid non-printables in the passphrase. Also, any NUL might terminate the passphrase, so there is a relatively good chance that this passphrase is only a few characters long.

enkore · 2017-07-17T07:00:37Z

docs/faq.rst

+
+  Then in an automated script one can put::
+
+    export BORG_PASSCOMMAND="cat ~/borg-passphrase"


~/ . b (missing dot after the slash)

v- Personally I'd avoid |project_bla| in new texts, since it makes for rather awkward reading of the source.

Are all those |project_name|s mostly remnants from the attic fork? I was just using what I saw in the rest of the docs.

I think it was once part of the sphinx quickstart.

lbeltrame · 2017-07-18T04:41:16Z

Note for docs: KWallet users can (assuming it's the KF5 based KWallet) use kwallet-query --read-password <entry name> <wallet name>. Unfortunately at the moment it outputs JSON, so it needs additional processing (via stdout) to extract the password.

milkey-mouse · 2017-07-19T06:23:13Z

kwallet-query ended up not working on my Kubuntu test VM(?) but kwalletcli works perfectly and should also have backwards compatibility with KDE 4 and earlier, so I ended up just using that.

rugk · 2017-07-19T10:01:37Z

docs/faq.rst

+    export BORG_PASSCOMMAND="security find-generic-password -a $USER -s borg-passphrase"
+
+Using ``BORG_PASSCOMMAND`` with GNOME Keyring (Ubuntu, Debian, Fedora)
+  GNOME has a keyring daemon similar to that of MacOS. However, it requires a bit more setup


Sounds biased… 😉

I.e. do not compare the keyrings and do not evaluate them.

rugk · 2017-07-19T10:03:29Z

docs/faq.rst

+
+    export BORG_PASSCOMMAND="security find-generic-password -a $USER -s borg-passphrase"
+
+Using ``BORG_PASSCOMMAND`` with GNOME Keyring (Ubuntu, Debian, Fedora)


The desktop environment does not depend on the distro used, so rather leave the "()" list out. Add "(Linux)" if you want as AFAIK GNOME only runs on Linux.

rugk · 2017-07-19T10:05:12Z

docs/faq.rst

+Using ``BORG_PASSCOMMAND`` with GNOME Keyring (Ubuntu, Debian, Fedora)
+  GNOME has a keyring daemon similar to that of MacOS. However, it requires a bit more setup
+  to get the login keyring to work. First ensure ``libpam-gnome-keyring`` is installed and
+  running on login (skip this step on Fedora, as it is installed by default)::


Mhh, I doubt Fedora is the only distro where this is the case. Maybe delete that sentence or make it more general ("In some ditros this is done by default.")

Or just change the wording in general: "If XY is not installed, then you have to install it first."

I put that there in the first place because it was kind of a PITA to get it working/get working instructions on Debian and Ubuntu (which don't have it installed by default), so I wanted to save the users some time. If I'm dropping all mentions of which distros have what DEs and what package managers they use I might as well drop this too, though; the remedy if it's not installed is only two commands.

rugk · 2017-07-19T10:06:07Z

docs/faq.rst

+  Then add a secret to the login keyring::
+
+    sudo apt install libsecret-tools  # Ubuntu, Debian
+    sudo yum install libsecret-tools  # Fedora, RHEL


New RHEL/Fedora-based distros should use "dnf". Please change it, the syntax stays the same.

Consider removing installation instructions for other software entirely - it's always going to change slightly and there will always be distros left out. Just saying what is needed should be sufficient to install it.

rugk · 2017-07-19T10:08:39Z

docs/faq.rst

+  directory and use permissions to keep anyone else from reading it. For
+  example, first create a key::
+
+    head -c 1024 /dev/urandom | xxd -p > ~/.borg-passphrase


Do you rally want to use binary stuff as your passphrase? IMHO the output should be filtered, so only ASCII (or similar) characters are used. At some day you may want to enter the passphrase manually.

If xxd is the thing doing this, then let's just say me that it is not installed by default for me. (Fedora 26 here) Better use a compatible command.

xxd should be converting it to hex here. I thought (mistakenly) that it was in coreutils and I could assume people would have it installed.

As for why I was using 30 chars, it was the boundary for a line break in xxd, and I was averse to having newlines in the password. Of course, I could have fixed it with a simple tr, but that would have complicated the instructions for not much benefit. In hindsight, I don't see why I was so dead-set on not having newlines in the password anyway...

I'll change that to use base64, which is actually in GNU coreutils (and seems to exist on Mac, too).

rugk · 2017-07-19T10:10:21Z

docs/faq.rst

+
+    sudo apt install libsecret-tools  # Ubuntu, Debian
+    sudo yum install libsecret-tools  # Fedora, RHEL
+    head -c 30 /dev/urandom | xxd -p | secret-tool store borg-repository repo-name --label="Borg Passphrase"


You may also mention that of course you can also do it with graphical tools (Seahorse in GNOME).

It's harder to write tutorials for how to do it in a GUI IMO. Also if they copy-paste these instructions the user can't accidentally use the wrong folder or anything (it will always put them in the defaults for secret-tool).

Yeah, but you could just mention that it is alos possible with the GUI, so users not liking the terminal don't get angry. 😉

Seriously, they should just know that it is possible. Mention the application name(s) as I made in my comment, e.g., if you want to give a hint how to do it. That's all.

rugk · 2017-07-19T10:11:06Z

docs/faq.rst

+    head -c 30 /dev/urandom | xxd -p | secret-tool store borg-repository repo-name --label="Borg Passphrase"
+
+  If a dialog box pops up prompting you to pick a password for a new keychain, use your
+  login password. If there is a checkbox for automatically unlocking on login, check it.


Maybe: "check it, if you ant that to be the case." OR "check it, if you want automatic updates in the background without interrupting you." or something similar.

rugk · 2017-07-19T10:17:58Z

docs/faq.rst

+__ https://github.com/borgbackup/borg/pull/2837#discussion_r127641330
+
+Using ``BORG_PASSCOMMAND`` with KWallet (Kubuntu, other KDE systems)
+  KDE also has a similar keychain feature in a program called KWallet. The command-line


Again this comparison… Just don't talk of "similar" here. (I could probably accept "also".) That does not matter for the user anyway – they do not want to know how/whether these things are similar, 😃

rugk · 2017-07-19T10:18:44Z

docs/faq.rst

+  passphrase and store it in your "wallet"::
+
+    sudo apt install kwalletcli  # might not be installed by default
+    head -c 30 /dev/urandom | xxd -p | kwalletcli -Pe borg-passphrase -f Passwords


rugk · 2017-07-19T10:19:51Z

docs/faq.rst

+
+    export BORG_PASSCOMMAND="kwalletcli -e borg-passphrase -f Passwords"
+
+Using keyfile-based encryption with a blank passphrase


I'd say this suggestion should be mentioned before all the keychain stuff as it is simple, general and something a user would appreciate/should think about before potentially getting into more difficult stuff.

I had the file-based option at the very beginning, which IMO is less hacky than the keyfile-based encryption, but on second thought it would make sense to have the keyfile option before the keychain stuff.

…backup#392)

milkey-mouse · 2017-07-19T21:21:57Z

collapsed changesets

ThomasWaldmann · 2017-07-19T22:30:08Z

@milkey-mouse it is good to collapse some changesets at the end (after all review is finished and at least one core dev approved), but if you do it in the middle of review, you require reviewers to re-read all the stuff just to find out whether the feedback got actually into the changeset. It easier to review incremental diffs, fixup changesets.

enkore · 2017-07-24T09:03:40Z

Thanks!

milkey-mouse changed the title ~~[WIP] Detail how to use macOS/GNOME keyrings for repo passwords (fixes #392)~~ [WIP] Detail how to use macOS/GNOME/KDE keyrings for repo passwords (fixes #392) Jul 17, 2017

enkore reviewed Jul 17, 2017

View reviewed changes

milkey-mouse mentioned this pull request Jul 19, 2017

update docs bounty (7) #2798

Closed

milkey-mouse force-pushed the fix392 branch from 6914606 to 6357e73 Compare July 19, 2017 06:19

milkey-mouse changed the title ~~[WIP] Detail how to use macOS/GNOME/KDE keyrings for repo passwords (fixes #392)~~ Detail how to use macOS/GNOME/KDE keyrings for repo passwords (fixes #392) Jul 19, 2017

rugk suggested changes Jul 19, 2017

View reviewed changes

milkey-mouse force-pushed the fix392 branch from f73fda3 to e4fa8cd Compare July 19, 2017 21:19

Detail how to use macOS/GNOME keyrings for repo passwords (fixes borg…

756dea7

…backup#392)

milkey-mouse force-pushed the fix392 branch from e4fa8cd to 756dea7 Compare July 19, 2017 21:20

enkore merged commit 77797a2 into borgbackup:master Jul 24, 2017

milkey-mouse deleted the fix392 branch July 25, 2017 05:05

Detail how to use macOS/GNOME/KDE keyrings for repo passwords (fixes #392) #2837

Detail how to use macOS/GNOME/KDE keyrings for repo passwords (fixes #392) #2837

milkey-mouse commented Jul 16, 2017

milkey-mouse commented Jul 16, 2017 •

edited

enkore Jul 17, 2017

milkey-mouse Jul 17, 2017

enkore Jul 17, 2017 •

edited

jkirk Apr 9, 2020 •

edited

enkore Jul 17, 2017 •

edited

enkore Jul 17, 2017 •

edited

milkey-mouse Jul 17, 2017

enkore Jul 17, 2017

lbeltrame commented Jul 18, 2017

milkey-mouse commented Jul 19, 2017 •

edited

rugk Jul 19, 2017

rugk Jul 19, 2017

rugk Jul 19, 2017

milkey-mouse Jul 19, 2017

rugk Jul 19, 2017

enkore Jul 19, 2017

rugk Jul 19, 2017

milkey-mouse Jul 19, 2017 •

edited

rugk Jul 19, 2017

milkey-mouse Jul 19, 2017 •

edited

rugk Jul 21, 2017

rugk Jul 19, 2017

rugk Jul 19, 2017

rugk Jul 19, 2017

rugk Jul 19, 2017

milkey-mouse Jul 19, 2017

milkey-mouse commented Jul 19, 2017 •

edited

ThomasWaldmann commented Jul 19, 2017

enkore commented Jul 24, 2017


		Then in an automated script one can put::

		export BORG_PASSCOMMAND="cat ~/borg-passphrase"


		export BORG_PASSCOMMAND="security find-generic-password -a $USER -s borg-passphrase"

		Using ``BORG_PASSCOMMAND`` with GNOME Keyring (Ubuntu, Debian, Fedora)


		export BORG_PASSCOMMAND="kwalletcli -e borg-passphrase -f Passwords"

		Using keyfile-based encryption with a blank passphrase

Detail how to use macOS/GNOME/KDE keyrings for repo passwords (fixes #392) #2837

Detail how to use macOS/GNOME/KDE keyrings for repo passwords (fixes #392) #2837

Conversation

milkey-mouse commented Jul 16, 2017

milkey-mouse commented Jul 16, 2017 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

enkore Jul 17, 2017 • edited

Choose a reason for hiding this comment

jkirk Apr 9, 2020 • edited

Choose a reason for hiding this comment

enkore Jul 17, 2017 • edited

Choose a reason for hiding this comment

enkore Jul 17, 2017 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

lbeltrame commented Jul 18, 2017

milkey-mouse commented Jul 19, 2017 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

milkey-mouse Jul 19, 2017 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

milkey-mouse Jul 19, 2017 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

milkey-mouse commented Jul 19, 2017 • edited

ThomasWaldmann commented Jul 19, 2017

enkore commented Jul 24, 2017

milkey-mouse commented Jul 16, 2017 •

edited

enkore Jul 17, 2017 •

edited

jkirk Apr 9, 2020 •

edited

enkore Jul 17, 2017 •

edited

enkore Jul 17, 2017 •

edited

milkey-mouse commented Jul 19, 2017 •

edited

milkey-mouse Jul 19, 2017 •

edited

milkey-mouse Jul 19, 2017 •

edited

milkey-mouse commented Jul 19, 2017 •

edited