Chroot directories and home-directory mapping for SFTP, explained

If you give a partner SFTP access, you almost never want them to see anything except their own files. The mechanism that enforces that is a chroot (change root): the user is locked into one directory and, as far as they can tell, that directory is the whole filesystem. Here’s what it means and how it works in both classic and cloud setups.

What chroot does

Normally an SSH/SFTP user lands in a home directory but can navigate upward and around the filesystem subject to permissions. A chroot jail changes the apparent root for that user: their session is confined to a chosen directory, and paths above it simply don’t exist from their point of view. They can’t cd .. their way out, list other users’ folders, or read system files.

This is the foundation of safe multi-tenant SFTP: each partner is jailed to their own space.

On a traditional SFTP server

With OpenSSH, you set this up with ChrootDirectory in sshd_config, usually combined with ForceCommand internal-sftp so the user gets SFTP only, no shell:

Match Group sftpusers
    ChrootDirectory /srv/sftp/%u
    ForceCommand internal-sftp
    AllowTcpForwarding no

There are sharp edges: the chroot directory must be owned by root and not writable by the user, which is why you often see a structure where the jail root is read-only and an uploads/ subfolder inside it is writable. Getting the ownership and permissions wrong is a common cause of “permission denied” on otherwise-correct setups.

On object storage: a prefix is the jail

Cloud object storage has no directories to chroot into, but the same idea maps cleanly onto a key prefix. Each user is scoped to a prefix like clients/acme/, and the gateway refuses any operation outside it. From the user’s side it looks exactly like a chroot: they see their own folder as the root and nothing above it. Under the hood the gateway is just enforcing “every key this credential touches must start with clients/acme/.”

This is simpler and safer than the OpenSSH version, there are no filesystem ownership traps, just a prefix rule applied on every operation. See how an SFTP proxy works for the mechanics.

Home-directory mapping

“Home directory” for an SFTP user is just where they land on login. On a server it’s a path on disk; on a gateway it’s the prefix they’re jailed to. When you migrate from a server to a gateway, you keep partners’ workflows intact by mapping each user’s old home directory to the same prefix, so they log in and see the same folder layout they always did.

Why it matters

Path jailing (chroot, or its prefix equivalent) is the single most important containment control in multi-user SFTP. Without it, one partner’s credential can read or list everyone else’s files. With it, a leaked or misused credential is confined to one slice of your storage. It pairs with per-user credentials and an audit trail to form the core of SFTP security best practices.

In a managed gateway like Firepipe, every user is path-jailed to a prefix by construction, so this containment is on by default rather than something you have to configure correctly.