Australian cloud for business software — built and run in Sydney since 2002

NetLeverage
NetLeverage

SFTP "bad ownership or modes for chroot directory": every path component must be root-owned and not group or world writable

Technical article
Troubleshooting

About this article: This article is reviewed against the cited sources. This is source research, not lab validation. Check the stated versions and your own requirements before making changes.

An SFTP login that closes at once, with sshd logging bad ownership or modes for chroot directory, means the ChrootDirectory path failed sshd's safety check. The sshd_config manual says sshd "checks that all components of the pathname are root-owned directories which are not writable by group or others". Make the chroot directory and each directory above it owned by root and not writable by group or others. Put a user-owned folder inside it for the files.

What the error means

ChrootDirectory makes sshd call chroot(2) after authentication, so the user sees the chosen directory as the root of the filesystem. A user who could change that directory could escape the jail, so sshd checks the whole path when the session starts.

In the OpenSSH portable source (session.c), the check walks the path one component at a time, starting at /. For each component it reads the owner and mode and stops when st.st_uid != 0 || (st.st_mode & 022) != 0. It then ends the session with a message in one of two forms:

  • For a parent directory: bad ownership or modes for chroot directory component "/srv/sftp/". The component shown ends with a slash.
  • For the last element, the chroot directory itself: bad ownership or modes for chroot directory "/srv/sftp/alice".

The source also checks that each component is a directory, with a separate message.

The mask 022 is octal for write permission for group (020) plus write permission for others (002). A mode passes only if none of those bits is set:

  • Mode 0755 AND 022 = 0, so it passes.
  • Mode 0775 AND 022 = 020 (group write is set), so it fails.
  • Mode 0777 AND 022 = 022, so it fails.

Because the check runs at session start, sshd -t will not find it. The manual describes -t as checking "the validity of the configuration file and sanity of the keys", and it does not test directories.

Likely causes

Cause What you see How to confirm
The chroot directory is the user's home directory, owned by the user Message without the word "component" naming the chroot path namei -l shows the user as owner of the last element
A parent directory is group-writable Message with "component" naming the parent, ending with a slash The mode of that component shows w in the group or other position
A parent directory is owned by a non-root account Message with "component" naming it The owner column is not root
ChrootDirectory uses %h or %u and expands to a different path than expected The failing path is not the one in your notes sshd -T -C user=name shows the value as configured, with %h or %u still unexpanded (the sshd manual does not say whether sshd -T expands these tokens); substitute the user's home directory or name yourself and check that path with namei -l
A path component is not a directory A separate message naming a path "is not a directory" namei -l shows another file type letter

Prove the cause before changing anything

All of these are read-only.

1. Read the sshd log line. The path in the message is the one sshd checked. If it ends with a slash and the word "component" is present, the problem is that parent, not the final directory. Read the log your system keeps for sshd. The unit name on systemd hosts is explained in "Changed sshd_config and now SSH says "Connection refused" on port 22: prevent it and recover".

2. Show the configured setting for the user.

sshd -T -C user=alice,host=client.example.com,addr=203.0.113.20

The sshd manual says -T prints the effective configuration and applies Match rules if you give connection parameters with -C; the keywords include addr, user and host. Look at the chrootdirectory line; if it still shows %h or %u, work out the real path yourself and use that in step 3.

3. Show owner and mode for every component.

namei -l /srv/sftp/alice

The namei manual describes -l as the long format, the same as -m -o -v: modes, owners, and the vertical layout. Each path component appears on its own line. A good component shows root root and no w in the group or other position. A bad one shows a different owner, or w there.

4. Save the numeric view.

stat -c '%U %G %a %n' /srv /srv/sftp /srv/sftp/alice

The stat manual defines %U as the owner's name, %G the group name, %a the octal permission bits and %n the file name. Write the output to a dated note such as /root/chroot-state-2026-11-20.txt. The note is your back-out.

Fix

Do this from a session that is not itself using the chroot, and on a tree reserved for SFTP users. A dedicated tree such as /srv/sftp/alice is easier to fix than a real home directory, whose files belong to the user.

Disruptive step: changing ownership and mode applies at once. The manual says the check runs at session startup, so new logins use the new rules. If the same path is the user's normal home directory, the user loses write access to it. Save the state first, as above.

Make the path safe

For each failing component, from the top down, set the owner to root and remove group and other write:

chown root:root /srv/sftp/alice
chmod 755 /srv/sftp/alice

Mode 755 passes the check by the arithmetic above. If a parent such as /srv/sftp also failed, apply the same two commands to it. If the failing parent is a shared system directory such as /home, /var or /, do not change it, because the change affects every other user of that directory; move the chroot to a dedicated tree instead.

To back out, read your saved note and run chown with the owner and group it recorded and chmod with the octal mode it recorded, for each path. For example, if the note held alice alice 775 /srv/sftp/alice, the commands are chown alice:alice /srv/sftp/alice and chmod 775 /srv/sftp/alice.

Give the user somewhere to write

A root-owned chroot directory is read-only to the user, so sftp can list it but cannot upload. Create a subdirectory and give it to the user. Risk: this adds a folder and changes its owner. To back out, run ls -A /srv/sftp/alice/upload (the ls manual describes -A as "do not list implied . and ..") to confirm the folder is empty, then rmdir /srv/sftp/alice/upload; the rmdir manual says it removes the directory "if they are empty".

mkdir /srv/sftp/alice/upload
chown alice:alice /srv/sftp/alice/upload
chmod 755 /srv/sftp/alice/upload

The user logs in, changes into upload, and writes there.

Make the account's home directory exist inside the jail

The sshd_config manual says: "After the chroot, sshd(8) changes the working directory to the user's home directory." If alice still has /home/alice as her home and the chroot is /srv/sftp/alice, sshd tries to change into /srv/sftp/alice/home/alice, which does not exist. In session.c the missing-home warning is suppressed for the chroot case ("Suppress missing homedir warning for chroot case"), so the login is not refused, but the session does not start in the folder you intended. To start it in the upload folder, set her home to /upload, which is /srv/sftp/alice/upload from outside the jail. First save her current entry:

getent passwd alice > /root/alice-passwd-2026-11-20.txt

Disruptive step: usermod -d changes the home directory recorded for the account for every use, not only SFTP. The usermod manual says to make sure the user is not executing any processes when the home directory is changed, so run it when alice has no session open. The -d, --home HOME_DIR option sets "The user's new login directory"; without -m it does not move any files. The sshd_config manual says the AuthorizedKeysFile path, by default .ssh/authorized_keys .ssh/authorized_keys2, is "taken to be an absolute path or one relative to the user's home directory", so a key login would look for /upload/.ssh/authorized_keys after the change.

If she logs in with a key, do this first. The manual says AuthorizedKeysFile accepts the tokens %h, %U and %u. Disruptive step: this edits sshd_config, and a wrong value stops her key logins. Save the configuration and her key file, then copy her key file to a path that does not depend on her home (the first command creates the directory if it does not already exist):

cp -a /etc/ssh/sshd_config /etc/ssh/sshd_config.2026-11-20
cp -a /home/alice/.ssh/authorized_keys /root/alice-authorized_keys-2026-11-20
mkdir -p /etc/ssh/authorized_keys
cp -a /home/alice/.ssh/authorized_keys /etc/ssh/authorized_keys/alice

Then add AuthorizedKeysFile /etc/ssh/authorized_keys/%u inside a Match User alice block, so no other account is affected, run sshd -t, and reload sshd with your distribution's service command. Check that a new key login works before you change the home. If that check fails, the home has not been changed yet, so back out here: copy /etc/ssh/sshd_config.2026-11-20 back over /etc/ssh/sshd_config, run sshd -t, reload sshd, and remove the new copy with rm /etc/ssh/authorized_keys/alice. Her original key file was only copied, so it is unchanged.

Then change the home:

usermod -d /upload alice
getent passwd alice

To back out after the home has changed, undo the two changes in reverse order. First set the home directory shown in the saved note, usermod -d /home/alice alice, and run getent passwd alice again to compare it with the note. Only then, if you also changed AuthorizedKeysFile, restore sshd_config as above. In the other order, sshd would look for her key under /upload/.ssh/authorized_keys and her key login would fail.

If you change sshd_config

A change to ChrootDirectory or the Match block edits the configuration file. Disruptive step: a bad configuration file can stop new SSH connections. First copy the file, for example cp -a /etc/ssh/sshd_config /etc/ssh/sshd_config.2026-11-20, then edit, then run sshd -t. Only after that, reload sshd using your distribution's service command. The sshd manual says sshd rereads its file when it receives SIGHUP. To back out, copy the saved file over sshd_config, run sshd -t, and reload.

A block can use the user name token. The manual says ChrootDirectory accepts the tokens in its TOKENS section, which lists %h and %u:

Match User alice
    ChrootDirectory /srv/sftp/%u
    ForceCommand internal-sftp

The manual says ForceCommand internal-sftp forces an in-process SFTP server "that requires no support files when used with ChrootDirectory".

Example (illustrative): sftp01 hosts a feed for a supplier. The supplier's user alice has her home at /home/alice, owned by alice, and ChrootDirectory /home/alice. After a change request, logins close immediately and the log shows bad ownership or modes for chroot directory "/home/alice". namei -l shows alice as the owner of the last element. The administrator saves stat output, creates /srv/sftp/alice owned by root with mode 755, adds /srv/sftp/alice/upload owned by alice, and saves getent passwd alice. Because her home is still /home/alice and she signs in with a password, the administrator runs usermod -d /upload alice while she is logged out. Last, the administrator points ChrootDirectory at /srv/sftp/%u after copying and testing the configuration.

Confirm the fix

  1. namei -l on the chroot path shows root as the owner and no group or other write bit for every component.
  2. A new SFTP login succeeds and lands in the jail, in the folder the account's home directory points to (getent passwd alice shows it).
  3. The user can upload into the upload folder and cannot write in the jail's top directory.
  4. The sshd log no longer shows the message.

What to watch afterwards

  • Packages and deploy scripts may reset ownership. After an update, run namei -l again.
  • A group-writable parent added for a shared drop folder brings the error back for every user under it.

Risks and limits

  • These commands have not been run or lab-tested.
  • The message text is from the OpenSSH portable session.c on the master branch. The text can differ by version, and distributions may patch it.
  • The manual warns that "Misconfiguration can lead to unsafe environments which sshd(8) cannot detect", so the ownership check does not make the jail safe by itself.
  • The steps are for SFTP with internal-sftp only; shell sessions in a chroot have further requirements.

Sources

  • sshd_config(5) — OpenBSD manual page, OpenBSD-current, October 30, 2026, accessed 20 November 2026
  • sshd(8) — OpenBSD manual page, OpenBSD-current, September 2, 2026, accessed 20 November 2026
  • OpenSSH portable: session.c — OpenSSH project source, master branch, version stamp 2026/10/30 (revision 1.354), accessed 20 November 2026
  • namei(1) — util-linux 2.43.devel-739, 2026-05-24, accessed 20 November 2026
  • stat(1) — GNU coreutils 9.11, April 2026, accessed 20 November 2026
  • chown(1) — GNU coreutils 9.11, April 2026, accessed 20 November 2026
  • chmod(1) — GNU coreutils 9.11, April 2026, accessed 20 November 2026
  • mkdir(1) — GNU coreutils 9.11, April 2026, accessed 20 November 2026
  • rmdir(1) — GNU coreutils 9.11, April 2026, accessed 20 November 2026
  • ls(1) — GNU coreutils 9.11, April 2026, accessed 20 November 2026
  • usermod(8) — shadow-utils 4.19.0, 08/04/2026, accessed 20 November 2026
  • getent(1) — Linux man-pages 6.19, 2026-02-08, accessed 20 November 2026
  • cp(1) — GNU coreutils 9.11, April 2026, accessed 20 November 2026