From 541e13b5bfd0ba6c185533c1f460efae233b6044 Mon Sep 17 00:00:00 2001
From: Matteo Carotta <matteo.carotta@gmail.com>
Date: Fri, 30 Jan 2026 07:08:11 +0100
Subject: [PATCH] chore: update troubleshooting SFTP documentation (#1094)

---
 docs/content/3.cookbooks/4.ssh-remote.md | 17 ++++++++++++++---
 1 file changed, 14 insertions(+), 3 deletions(-)

diff --git a/docs/content/3.cookbooks/4.ssh-remote.md b/docs/content/3.cookbooks/4.ssh-remote.md
index 144179a4..eab36d44 100644
--- a/docs/content/3.cookbooks/4.ssh-remote.md
+++ b/docs/content/3.cookbooks/4.ssh-remote.md
@@ -116,10 +116,21 @@ docker compose up -d --force-recreate
 
 ## Troubleshooting
 
-- **Connection Errors:** First, test your SSH connection from the host machine to isolate issues. This command uses the exact same configuration files that the container will use.
-  ```bash
+- **Connection Errors:**
+  First, test your SSH connection from the host machine to isolate issues. This command uses the exact same configuration files that the container will use.
+  ```bash host
   # This command should connect without asking for a password
-  ssh -F ./backrest/ssh/config backrest-remote
+  ssh -vF ./backrest/ssh/config -o UserKnownHostsFile=./backrest/ssh/known_hosts backrest-remote
+  # -o UserKnownHostsFile ensures that ssh uses ony the public keys passed to the backrest container instead of the global public keys of the host.
+  ```
+  Attempt connection to the server from the container and compare the results :
+  ```bash host
+  # From the host open a bash terminal to the backrest container
+  docker exec -it backrest bash
+  ```
+  ```bash container
+  # Attempt to connect to the server via ssh. If prompt abort the command, saved keys would be ephemeral.
+  ssh -vF /root/.ssh/config backrest-remote
   ```
 - **Permission Denied:**
   - Double-check the file permissions set in Step 5.