From 10e910cfedae54e07240a4b49c024ef0f813f3b2 Mon Sep 17 00:00:00 2001
From: Einar <me@ege.cx>
Date: Sat, 9 May 2026 23:33:36 +0200
Subject: [PATCH] Add SSH key authentication section to rclone guide

---
 rclone.md | 43 ++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 42 insertions(+), 1 deletion(-)

diff --git a/rclone.md b/rclone.md
index a3fd514..deed26d 100644
--- a/rclone.md
+++ b/rclone.md
@@ -42,7 +42,7 @@ backend type. For an SSH/SFTP server:
 - User: `god`
 - Port: `22` (default, just press Enter)
 - Password: leave blank if you use SSH key auth
-- Key file: leave blank to use your default `~/.ssh/` keys
+- Key file: set this explicitly — see SSH key authentication below
 
 Once saved, the remote is available by name in all rclone commands.
 
@@ -54,6 +54,47 @@ sudo mkdir -p /root/.config/rclone
 sudo cp ~/.config/rclone/rclone.conf /root/.config/rclone/rclone.conf
 ```
 
+## SSH key authentication
+
+rclone does not use the macOS SSH agent. It reads key files directly using
+its own SSH library, which only reliably supports the older PEM format —
+not the modern OpenSSH private key format that recent versions of ssh-keygen
+produce by default.
+
+If you point rclone at a standard modern key and it falls back to password
+auth with no clear error, this is why.
+
+### Generate a dedicated rclone key
+
+```bash
+ssh-keygen -t rsa -b 4096 -m PEM -f ~/.ssh/rclone_rsa -N "" -C "rclone"
+```
+
+No passphrase (`-N ""`), RSA 4096, explicitly PEM format. Keep this key
+separate from your main SSH key.
+
+### Add the public key to the remote host
+
+```bash
+ssh-copy-id -i ~/.ssh/rclone_rsa.pub user@host
+```
+
+### Set the key in your rclone remote config
+
+Either via `rclone config` (set the `key_file` field), or edit
+`~/.config/rclone/rclone.conf` directly:
+
+```ini
+[hetzner-vps]
+type = sftp
+host = vps-hetzner-01.warthog-rockhopper.ts.net
+user = egeidal
+key_file = ~/.ssh/rclone_rsa
+shell_type = unix
+md5sum_command = md5sum
+sha1sum_command = sha1sum
+```
+
 ## Core commands
 
 ### copy