When configuring SFTP with chroot (restricted access), users might fail to connect with errors like:

bash
$ sftp restricteduser@server.example.com
Connection closed

Or in the server logs:

bash
sshd[12345]: fatal: bad ownership or modes for chroot directory component "/home/restricteduser/"
sshd[12345]: Chroot directory /home/restricteduser must be owned by root and not writable by anyone else

Chroot SFTP restricts users to a specific directory tree, preventing them from accessing other parts of the filesystem. SSH is strict about directory requirements for security.

Understand Chroot Requirements

For a chroot directory to work, it must:

  1. 1.Be owned by root
  2. 2.Not be writable by group or others
  3. 3.Not be writable by the user
  4. 4.Have proper permissions on all parent directories

The user's files must be in a subdirectory that they own and can write to.

Check Current Configuration

First, see your current SSH configuration for the user:

bash
sudo grep -A 10 "Match User restricteduser" /etc/ssh/sshd_config

Or check the subsystem:

bash
sudo grep -i subsystem /etc/ssh/sshd_config

A typical chroot configuration looks like:

``` Subsystem sftp /usr/lib/openssh/sftp-server

Match User restricteduser ChrootDirectory /home/restricteduser ForceCommand internal-sftp AllowTcpForwarding no X11Forwarding no PermitTTY no ```

Fix Directory Ownership

The chroot directory must be owned by root:

bash
ls -ld /home/restricteduser

If it shows the user as owner:

bash
drwx------ 2 restricteduser restricteduser 4096 Apr 3 10:00 /home/restricteduser

Fix it:

bash
sudo chown root:root /home/restricteduser

Fix Directory Permissions

The directory must not be writable by anyone other than root:

bash
sudo chmod 755 /home/restricteduser

Or more restrictive:

bash
sudo chmod 750 /home/restricteduser

Verify:

bash
ls -ld /home/restricteduser

Should show:

bash
drwxr-xr-x 2 root root 4096 Apr  3 10:00 /home/restricteduser

Create User-Writable Subdirectory

Since the user can't write to the chroot root, create a subdirectory:

bash
sudo mkdir /home/restricteduser/files
sudo chown restricteduser:restricteduser /home/restricteduser/files
sudo chmod 755 /home/restricteduser/files

The user can now write to files/ which appears as /files/ inside their chroot.

Check Parent Directory Permissions

All parent directories must also have proper permissions:

bash
ls -ld /home

Must not be writable by group or others:

bash
drwxr-xr-x 5 root root 4096 Apr  3 10:00 /home

If /home has wrong permissions:

bash
sudo chmod 755 /home
sudo chown root:root /home

Use Internal-SFTP vs SFTP-Server

The internal-sftp is preferred for chroot:

bash
Match User restricteduser
    ChrootDirectory /home/restricteduser
    ForceCommand internal-sftp

This doesn't require a separate process and works better with chroot.

If using sftp-server, you need:

bash
Subsystem sftp /usr/lib/openssh/sftp-server -l INFO

But internal-sftp is simpler and recommended.

Configure for Group Chroot

To chroot multiple users to the same structure:

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

Create directories for each user:

bash
sudo mkdir -p /home/sftp/user1/files
sudo chown root:root /home/sftp/user1
sudo chown user1:user1 /home/sftp/user1/files

Handle Home Directory in Chroot

The chroot becomes the user's root, so paths change. The user sees /files/ instead of /home/restricteduser/files/.

If you want the user to land in their writable directory:

bash
Match User restricteduser
    ChrootDirectory /home/restricteduser
    ForceCommand internal-sftp -d /files

The -d option sets the starting directory within the chroot.

Test the Configuration

Test the SSH config syntax:

bash
sudo sshd -t

If errors exist, fix them before restarting.

Test the SFTP connection:

bash
sftp -v restricteduser@server.example.com

Look for:

bash
debug1: subsystem request for sftp
debug1: Received subsystem request for sftp

Inside the SFTP session:

bash
sftp> pwd
Remote working directory: /
sftp> ls
files
sftp> cd files
sftp> pwd
Remote working directory: /files

Common Chroot Directory Structures

Single User Chroot

bash
/home/restricteduser/    (root:root, 755)
    files/               (user:user, 755)
    uploads/             (user:user, 755)

Group-Based Chroot

bash
/home/sftp/              (root:root, 755)
    user1/               (root:root, 755)
        files/           (user1:user1, 755)
    user2/               (root:root, 755)
        files/           (user2:user2, 755)

Shared Upload Directory

bash
/home/sftpshared/        (root:root, 755)
    uploads/             (root:sftpgroup, 775)
    downloads/           (root:sftpgroup, 755)

Troubleshoot Connection Refused

If users can't connect at all:

bash
sudo journalctl -u sshd -f

Connect from another terminal and watch:

bash
Apr  3 10:15:22 server sshd[12345]: Connection from 192.168.1.50 port 22
Apr  3 10:15:22 server sshd[12345]: Accepted password for restricteduser
Apr  3 10:15:22 server sshd[12345]: fatal: bad ownership or modes for chroot directory

Fix ownership based on the log message.

Symbolic links in the chroot can cause issues. Don't use symlinks that point outside the chroot:

```bash # Bad - points outside chroot ln -s /var/www /home/restricteduser/www

# Good - within chroot ln -s files/uploads /home/restricteduser/uploads ```

SELinux Considerations

On SELinux systems, you need correct context:

bash
ls -ldZ /home/restricteduser

Set proper context:

bash
sudo semanage fcontext -a -t ssh_home_t "/home/restricteduser(/.*)?"
sudo restorecon -R -v /home/restricteduser

Or temporarily disable SELinux for testing:

bash
sudo setenforce 0

Debug Chroot Path Issues

If the chroot path has issues, SSH will reject it:

bash
fatal: directory "/home/restricteduser/files" is not a chroot directory

Remember: the chroot must be the parent of user-writable directories.

Resolution Checklist

  1. 1.Chroot directory owned by root: chown root:root /path
  2. 2.Chroot directory not writable: chmod 755 /path
  3. 3.User-writable subdirectory: mkdir /path/files; chown user:user /path/files
  4. 4.Parent directories also owned by root
  5. 5.Use internal-sftp not sftp-server
  6. 6.Test config: sshd -t
  7. 7.Test connection: sftp -v user@server
  8. 8.Check logs: journalctl -u sshd

Chroot directory errors are almost always ownership and permission issues. The strict requirements exist to prevent users from escaping their restricted environment. Follow the root-ownership rule exactly.