DEV Community

Cover image for Your SFTP Client Should Not Assume "/" - Lessons From a Home Router
Sasha Kosobutsky
Sasha Kosobutsky

Posted on Originally published at m-apps.net

Your SFTP Client Should Not Assume "/" - Lessons From a Home Router

I am building SyncGallery, an Android gallery with configurable cloud sync. This post comes from one user report and the changes we made after reading it.

A user plugged a USB disk into their Keenetic router, turned on its built-in SFTP server, and pointed their computers at it. Sync worked. Then they added the same server to SyncGallery on their phone.

The login succeeded. Choosing a folder failed at once with "Permission denied".

The router was fine. Our app was asking the wrong question.

1. "Permission denied" is a precise answer

In SFTP, SSH_FX_PERMISSION_DENIED does not mean the login failed. The protocol draft returns it "when the authenticated user does not have sufficient permissions to perform the operation". One request was refused, and nothing else.

The refused request was "list the contents of /".

On Keenetic routers, SFTP shows the real file system. A USB disk is mounted deep inside it:

/tmp/mnt/<disk id or label>/<your folder>
Enter fullscreen mode Exit fullscreen mode

Users on Keenetic's community forum report the same thing: some apps try to open the root folder, get refused, and drop the connection. FileZilla on a desktop connects and lands straight in the right folder.

The difference is where each client starts.

2. Ask the server where to start

The SFTP draft already answers this. Relative paths are relative to "the user's default directory (home directory)", and SSH_FXP_REALPATH turns any path into an absolute one. Ask for the real path of . and the server tells you where you are supposed to be.

The reference clients do exactly that:

  • OpenSSH sftp requests the real path of . at startup and uses it as the start folder (source).
  • PuTTY psftp returns to "your home directory on the server" on cd with no argument (manual).
  • Go's pkg/sftp, used by rclone, implements its working-directory call as a real-path request for . (source).

A client that assumes everything starts at / skips this step. On most servers that is harmless, because / can be listed. On a server that refuses /, it is the whole bug.

3. Routers are not the only ones

Once we knew the pattern, we found it documented in other common setups:

Server What you see
OpenSSH with ChrootDirectory The jail root must be root-owned and not writable by others; after the chroot, sshd moves you to your home folder (sshd_config)
OpenSSH sftp-server -d An "alternate starting directory" that only a client asking the server will find (sftp-server)
Hetzner Storage Box "Only the directory /home/ is writable"; relative paths recommended (docs)
Windows built-in OpenSSH Paths carry the drive letter, like /C:/... (Win32-OpenSSH #730, curl commit)
Synology NAS SFTP shows shared folders at the top; a /volume1/... path copied from SSH does not exist over SFTP (restic forum, TrueNAS report)

The lesson: / is not a safe default. It is just the most common one.

4. Create folders from the bottom up

Fixing the browser was not enough. Before an upload, SyncGallery made sure the target folder existed by walking the path from / and creating each level. On this router, that meant asking about /tmp and /tmp/mnt - folders the user may not touch.

An SFTP MKDIR creates exactly one folder and fails if it already exists. Creating missing parents is the client's job, and the order matters.

Now SyncGallery checks the target first, climbs up only while folders are missing, then creates the missing ones on the way back down:

/tmp/mnt/disk/Photos/2026/Camera   missing
/tmp/mnt/disk/Photos/2026          missing
/tmp/mnt/disk/Photos               exists -> stop climbing
create  .../Photos/2026
create  .../Photos/2026/Camera
Enter fullscreen mode Exit fullscreen mode

It never looks above the first folder that exists. If a create fails, it checks once more and accepts the folder if it is now there, since another rule may have just made it. Climbing stops at / and at Windows drive roots like /C:. This is the same order rclone's SFTP backend uses.

A side benefit: uploading into a folder that already exists now costs one check instead of one request per path level.

5. Let people type the path

The other half of the fix was in the account editor. The start folder could only be picked with Browse, and Browse opened at /. There was no way to enter a long path by hand.

Now:

  • The folder browser lists / if it can, and otherwise opens at the real path of .. For FTP, PWD plays the same role (RFC 959).
  • The start directory is a text field for SFTP and FTP. When you finish typing, the app opens that folder and tells you whether it does not exist or access was denied.
  • Adding an SFTP, FTP or SMB account is split into steps: Connect, then Start directory (SMB adds Share). Saving lists the chosen folder, so a wrong path shows up now, not during the first sync.
  • If a saved start folder later stops working, the Files tab offers Change start directory next to the error.

6. Bonus: do not trust the first address

While testing this case we hit an unrelated problem. A router behind a dynamic DNS name can have both IPv4 and IPv6 addresses, and on some networks the IPv6 route goes nowhere - for example, when the router forwards SSH over IPv4 only. Phones that prefer IPv6 waited until the connection timed out, while the numeric IPv4 address worked.

RFC 6724 says applications "SHOULD NOT simply use the first address returned". RFC 8305 (Happy Eyeballs) adds that clients should interleave address families.

SFTP, FTP and SMB connections in SyncGallery now try every resolved address, alternating IPv6 and IPv4. They move on only when the network fails - a wrong password is not retried at another address - and remember the address that answered while the app runs. Attempts run one after another rather than overlapping, which matters less for a backup connection than for opening a web page.

What I took away

  1. A refused / is a normal server configuration, not an error state.
  2. Ask the server for its start folder with REALPATH "." (or PWD on FTP) instead of assuming one.
  3. Create missing folders from the deepest existing one downward, never from the root.
  4. Let users type a path and validate it immediately.
  5. Try every address a hostname resolves to.

None of this was new. The SFTP drafts, the OpenSSH client, and rclone all handle it already. We only found it because one user sent a clear report with the exact path that worked in other tools.

If you have shipped an SFTP or FTP client, I would love to hear which server layout surprised you the most.


This article was edited with AI assistance and reviewed for technical accuracy by the author.

Top comments (0)