Using scponly To Allow SCP/SFTP Logins And Disable SSH Logins On Debian Squeeze

Version 1.0
Author: Falko Timme
Follow me on Twitter

scponly is an alternate shell that restricts users to SCP and SFTP logins, but disallows SSH logins. It is a wrapper to the OpenSSH suite of applications. With the help of scponly, you can allow your users to use clients such as WinSCP or FileZilla to upload/download files, but you refuse SSH logins (e.g. with PuTTY) so that your users cannot execute files/programs. This tutorial shows how to install and use scponly on Debian Squeeze.

I do not issue any guarantee that this will work for you!


1 Preliminary Note

I will show how to set up chrooted and non-chrooted accounts. Non-chrooted accounts can browse the whole file system, while chrooted accounts can browse only their home directory and can write(= upload) only to a specified subdirectory of their home directory. This is important so that the chrooted scponly user cannot subvert the .ssh configuration parameters.

Please note that you can modify existing users to use non-chrooted scponly, but it's not possible to modify an existing user to chrooted scponly. To use chrooted scponly, you must create a new user!


2 Installing scponly

scponly can be installed as follows:

apt-get install scponly

You will see the following question:

Install the chrooted binary /usr/sbin/scponlyc SUID root? <-- Yes

Afterwards, you will find two new tools on your system:

  • /usr/bin/scponly
  • /usr/sbin/scponlyc

/usr/bin/scponly is used for non-chrooted accounts, while /usr/sbin/scponlyc is used for chrooted accounts.


3 Setting Up Non-Chrooted Accounts

To make a user use scponly, all we have to do is change his login shell to /usr/bin/scponly. You can modify an existing user as follows:

usermod -s /usr/bin/scponly someuser

(Replace someuser with the real username.)

You can create a new user with the scponly shell as follows:

useradd -m -s /usr/bin/scponly someuser

(Again, replace someuser with the real username.)

Specify a password for the new user afterwards:

passwd someuser

That's it! Now you can use clients such as WinSCP or FileZilla to log in with that username, and you can use SCP or SFTP - both work fine.


4 Setting Up Chrooted Accounts

As I mentioned earlier, it is not possible to modify existing users to use chrooted SCP or SFTP with scponly - we have to create a new user. To do this, there is a (compressed) helper script called in the /usr/share/doc/scponly/setup_chroot directory. Let's uncompress the file first:

cd /usr/share/doc/scponly/setup_chroot

Now we can run the script as follows:


The script will ask you for the username and the home directory of the user. It will also ask for a subdirectory of the home directory to which scponly will allow write(= upload) permissions (write permissions cannot be granted to the home directory itself so that the chrooted scponly user cannot subvert the .ssh configuration parameters - the home directory can be read/browsed, though). In the end the script will ask for a password for the new user.

I want to create the user someuser with the home directory /home/someuser. I want to grant write permissions to the /home/someuser/www directory because the user has his web site in this directory (with the document root /home/someuser/www/web, the cgi-bin directory /home/someuser/www/cgi-bin, etc. all inside /home/someuser/www):

root@server1:/usr/share/doc/scponly/setup_chroot# sh

Next we need to set the home directory for this scponly user.
please note that the user's home directory MUST NOT be writeable
by the scponly user. this is important so that the scponly user
cannot subvert the .ssh configuration parameters.

for this reason, a writeable subdirectory will be created that
the scponly user can write into.

-en Username to install [scponly]

<-- someuser
-en home directory you wish to set for this user [/home/someuser]
<-- /home/someuser
-en name of the writeable subdirectory [incoming]
<-- www
creating  /home/someuser/www directory for uploading files

Your platform (Linux) does not have a platform specific setup script.
This install script will attempt a best guess.
If you perform customizations, please consider sending me your changes.
Look to the templates in build_extras/arch.
 - joe at sublimation dot org

please set the password for someuser:
Enter new UNIX password:
 <-- somepassword
Retype new UNIX password: <-- somepassword
passwd: password updated successfully
if you experience a warning with winscp regarding groups, please install
the provided hacked out fake groups program into your chroot, like so:
cp groups /home/someuser/bin/groups

Now take a look at the created directories:

ls -la /home/someuser/

root@server1:~# ls -la /home/someuser/
total 36
drwxr-xr-x 9 root     root     4096 Jul 25 13:29 .
drwxr-xr-x 6 root     root     4096 Jul 25 13:29 ..
drwxr-xr-x 2 root     root     4096 Jul 25 13:29 bin
drwxr-xr-x 2 root     root     4096 Jul 25 13:29 dev
drwxr-xr-x 2 root     root     4096 Jul 25 13:29 etc
drwxr-xr-x 2 root     root     4096 Jul 25 13:29 lib
drwxr-xr-x 2 root     root     4096 Jul 25 13:29 lib64
drwxr-xr-x 4 root     root     4096 Jul 25 13:29 usr
drwxr-xr-x 2 someuser someuser 4096 Jul 25 13:29 www

As you see, the script has created /home/someuser and all necessary directories/files for the chroot environment, and they are all owned by the user and group root, except for the www subdirectory which is owned by the user and group someuser (so that the user has write permissions to that directory).

Now you can use a client such as WinSCP or FileZilla to log in with that username, and you can use SCP or SFTP - both work fine.

If you get an error message like

Command 'groups'
failed with return code 1 and error message
/usr/bin/groups: cannot find name for group ID 1003.

please do the following:

cp /lib/libnss_* -av /home/someuser/lib/

On a 64bit system, also run the following command in addtition to the previous one:

cp /lib64/libnss_* -av /home/someuser/lib64/

Log in again, and the error should be gone.


Share this page:

3 Comment(s)

Add comment



You write "that your users cannot execute files/programs". This is only true if one also ensures that uploaded files cannot be executed by other means. A setup as you suggest it here is likely to also offer e.g. access through a web server and PHP. At least default configurations generally allow PHP to run programs. Moreover PHP is generally not confined to chrooted environments.

Though, the whole point of scponly and similar tools rarely is to avoid execution of programs because what it does is no more or less than plain FTP or other upload mechanisms, only the authentication and transport is encrypted.

From: Brent


Thanks for this. But it does not work (Or least in my testing). And the reason why I say is.

 I used to create my janedoe user.

/etc/passwd shows:


 If I use winscp and I *dont* specify SCP (i.e. sftp), I can still traverse the filesystem.



From: jack

hi, i was configured 

but client login, the error :

root@ubuntu:/tmp# sftp [email protected]

[email protected]'s password: 

Connection closed

root@ubuntu:/tmp# scp a.txt [email protected]:www/

[email protected]'s password: 

unknown user 513

lost connection