Configuring SFTP for the document root

How To Configure SFTP for a Web Server Document Root

Last updated on

SFTP is the favourite these days because of its robust security model and easier setup than traditional FTP and FTPS. In this guide we will configure SFTP to allow users to upload to the web server document root.

Introduction

This guide assumes your web document root is the default for Apache and Nginx in /var/www/html. If you followed one of our previous guides on setting up virtual hosts, your document root may be located in /var/www/example.com/public_html. Just make sure you have the correct document root and update commands in this guide to match.

This guide was tested on Ubuntu Server 20.04, 18.04 and 16.04, though it should also work with other Debian-based distributions without issue. If you are using CentOS, just substitute www-data in this guide for apache or nginx. Any issues, please let me know in the comments.

I have provided two different methods in this guide for setting up SFTP access to your document root:

  • Method One is a simple setup where you just add your SFTP user to the www-data group.
  • Method Two is far more secure and recommend if you want to limit where www-data has write access. I have included a special section for WordPress users and best security practises. See step 5.5: WordPress and www-data.

Regardless of the method you choose, Step 1, 2 and 3 below are the same.

1. Install SSH

SFTP is built upon the SSH transport layer and should be installed on most Linux server distributions by default. If it isn’t , you can install with:

sudo apt install ssh

2. Configure SSH

Change the Subsystem to internal-sftp in sshd_config.

sudo nano /etc/ssh/sshd_config

Scroll to the bottom of the file and comment out the line Subsystem sftp by adding # before it and then add Subsystem sftp internal-sftp below it.

/etc/ssh/sshd_config
#Subsystem sftp /usr/lib/openssh/sftp-server 
Subsystem sftp internal-sftp

This tells sshd to use SFTP server code built into sshd instead of running sftp-server, which is now redundant and only kept for a backward compatibility.

Restart the sshd service for changes to take affect.

sudo service sshd restart

3. Create SFTP User

It’s not recommended that you use the root account or any account with sudo privileges to upload files to the web server document root. For this reason, you should create a new user that only has SFTP access to the document root.

In this guide, we are calling the SFTP user webdev – you can call this whatever you want. If you plan to give SFTP access to multiple users across different document roots, consider a naming scheme like username_domain_com. For example john_devanswers_co. This will make it easier to keep track of all your SFTP users.

For the purposes of this guide, we will name the SFTP user webdev.

sudo adduser webdev

Generate a password and press enter to accept all defaults.

Two SFTP Configuration Methods

I am providing two different methods in this guide because there are some people who just want a quick and easy method to access the document root with SFTP, and others who want a more advanced security setup (which I use). It might be worth reading through both methods to see which one suits your needs.

  • Method One: Quick Setup
    • You just want a quick and simple method to give one or multiple SFTP users access to the document root by adding them to the www-data group.
    • You already have a live, busy site running on the document root and don’t want to risk accidentally taking it down by setting restrictive permissions in Method Two.
    • You need to install a CMS from scratch such as WordPress before setting up more restrictive permissions in Method Two.
  • Method Two: Better Security and SFTP User Management
    • You want the best security possible for your document root.
    • You already have your CMS such as WordPress installed and running, and now want to lock it down.
    • You want to restrict where www-data can write to.
    • You have multiple developers that need write access to multiple document roots hosted on your server.

4. Method One: Quick Setup

Using this method with the least amount of configuration, we will create a Match User directive in the SSH config and add your SFTP user to the www-data group.

4.1. Add Match User Directive in SSH Config

Restrict the user webdev to the document root and also disable their SSH access – we only want them to be able to log in over SFTP. We can do this by adding a Match User directive in the SSH config file.

Begin by opening sshd_config.

sudo nano /etc/ssh/sshd_config

Scroll down to the bottom of the SSH config file and add your new Match User directive.

Make sure that ChrootDirectory is the directory above your document root. For example, if your document root is /var/www/html/, then the ChrootDirectory is /var/www/.

If you followed one of our previous guides on hosting multiple domains on Apache or Nginx, your document root may be located in /var/www/mydomain.com/public_html, in that case, your ChrootDirectory would be /var/www/mydomain.com/.

Note you can add multiple users here separated by a comma, e.g. Match User webdev, webdev2, webdev3

/etc/ssh/sshd_config
Match User webdev 
        ChrootDirectory /var/www/
        ForceCommand internal-sftp 
        X11Forwarding no 
        AllowTcpForwarding no 
        PasswordAuthentication yes

Save and exit (press CTRL + X, press Y and then press ENTER)

Test SSH config before restarting.

sudo sshd -t

If no errors, restart the sshd service for changes to take affect.

sudo service sshd restart

4.2. Add SFTP User to www-data

Add your SFTP user webdev to the www-data group.

sudo usermod -a -G www-data webdev

Note: Linux groups do not take affect until the user logs out and in again. If you are already logged in as this user in your FTP client, close the program completely and then log in again.

4.3. Set Document Root Permissions

Make sure the document root is set to 775.

sudo chmod 775 /var/www/html

Make sure that your document root and all contents are owned by www-data.

sudo chown -R www-data:www-data /var/www/html*

Change all directories in the document root to 775. This will allow both the owner (www-data) and its group (which SFTP users belong to) to read, write and execute folders.

sudo find /var/www/html/ -type d -exec chmod 775 {} \;

Change all files in the document root to 664, this will allow both the owner and the group to read, write and execute files.

sudo find /var/www/html/ -type f -exec chmod 664 {} \;

Make sure that any new files or folders created by SFTP users inherit the www-data group.

sudo find /var/www/html -type d -exec chmod g+s {} \;

Now log into SFTP with you preferred FTP client and make sure you can create, edit and delete files and folders.

4.4. Adding More SFTP Users

If you need to provide other SFTP users write access to the document root, simply add their usernames separated by a comma, e.g. Match User webdev, webdev2, webdev3 in sshd_config (step 4.1) and then add the SFTP user to the www-data group (Step 4.2) .

5. Method Two: Better Security and SFTP User Management

In this method we will set up more restrictive permissions for your document root and use Linux user groups to manage SFTP users. This is the method I personally use for managing multiple virtual hosts, WordPress installs, and SFTP users on the one server.

Even if you are only hosting one website on your server, I strongly recommend this setup if you want the best security for your website’s document root.

This method removes www-data write access to the entire document root. Consider a scenario where a PHP script or WordPress plugin is hacked, the attacker could gain write access to your entire document root. To mitigate this, we need to only give www-data (and thus WordPress) write access to the directories where it only needs it to function properly.

If you haven’t installed your CMS yet, you should first carry out Method One, upload and install your CMS, then follow Method Two to lock down the CMS.

5.1. Create a New Linux User Group

With this method we will create a Linux User Group with the necessary access to the document root and then add our SFTP users to that group.

If you are hosting multiple websites on the one server with Apache or Nginx, you should name these groups so they correspond to your domain name. For example, sftp_example1_com and sftp_example2_org. This will make it a lot easier to keep track of your groups should they grow over time.

However, for the purposes of this guide, we will just call the group sftp_users and restrict this group to the default document root /var/www/html.

Add new group:

sudo groupadd sftp_users

5.2. Add SFTP User to Group

Add your SFTP user webdev (or whatever you called it) to the sftp_users group.

sudo usermod -a -G sftp_users webdev

Note: Groups do not take affect until the user logs out and in again. If you are already logged in as this user in your FTP client, close the program completely and then log in again.

5.3. Add Match Group Directive in SSH Config

In Method One we used the Match User directive, but by using the Match Group directive, you can manage multiple users and document roots far more effectively.

This allows you to restrict an entire group to a particular document root, and then you just add your SFTP users to that group with no additional configuration. This can save you a lot of time.

Begin by opening sshd_config

sudo nano /etc/ssh/sshd_config

Scroll down to the bottom of the SSH config file and add your new Match Group directive.

Make sure that ChrootDirectory is the directory above your document root. For example, if your document root is /var/www/html/, then the ChrootDirectory is /var/www/.

If you followed one of our previous guides on setting up multiple domains, your document root may be located in /var/www/mydomain.com/public_html, in that case, your ChrootDirectory would be /var/www/mydomain.com/.

/etc/ssh/sshd_config
Match Group sftp_users 
        ChrootDirectory /var/www/
        ForceCommand internal-sftp 
        X11Forwarding no 
        AllowTcpForwarding no 
        PasswordAuthentication yes

Save and exit (press CTRL + X, press Y and then press ENTER)

Test SSH config before restarting.

sudo sshd -t

If no errors, restart the sshd service for changes to take affect.

sudo service sshd restart

5.4. Set Document Root Permissions

Make sure the document root is set to 775.

sudo chmod 775 /var/www/html

Make sure your document root and all contents are owned by root and the group sftp_users.

sudo chown -R root:sftp_users /var/www/html*

Change all directories in the document root to 775. This will allow the sftp_users group to read, write and execute folders.

sudo find /var/www/html/ -type d -exec chmod 775 {} \;

Change all files in the document root to 664, this will allow the sftp_users group to read, write and execute files.

sudo find /var/www/html/ -type f -exec chmod 664 {} \;

Make sure that any new files or folders created by the SFTP user inherit the group of the document root, in this example the sftp-users group.

sudo find /var/www/html -type d -exec chmod g+s {} \;

Now log into SFTP with you preferred FTP client and make sure you can create, edit and delete files and folders in the document root.

If you need to provide other SFTP users write access to the document root, simply add them to the sftp-users group (Step 5.2).

5.5. WordPress and www-data

www-data now has no write access to your document root, which is the preferred security setup. However, you may need to give www-data write access to certain files and directories in order for WordPress to function properly.

.htaccess and Apache

If you get an Apache error after setting permissions in the previous steps “You don’t have permission to access this resource. Server unable to read htaccess file, denying access to be safe”, you may need to give both www-data and the sftp-users group ownership of .htaccess.

sudo chown www-data:sftp_users /var/www/html/.htaccess

WordPress Uploads Directory

If your users need to upload files through the WordPress media library, you will need to give www-data write access to the uploads directory in /var/www/html/wp-content/uploads.

sudo chown -R www-data:sftp_users /var/www/html/wp-content/uploads*

This will give both WordPress and all your SFTP users write access to the uploads directory.

WordPress Cache Directory

If you are using a caching plugin such as W3 Total Cache plugin, you should give www-data write access to the cache directory in /var/www/html/wp-content/cache.

sudo chown -R www-data:sftp_users /var/www/html/wp-content/cache*

WordPress Updates and Installing/Updating Plugins

WordPress normally uses www-data in order to update itself and add/update plugins. This is the most common setup but it is not the most secure because any rogue plugin could compromise your entire WordPress install.

You should instead upload the SSH SFTP Updater Support plugin to your WordPress plugins directory and then activate it in WordPress.

Once activated, if you need to update WordPress or add/update plugins, you will be prompted for your SFTP username and password/SSH key. You can save this password or SSH key in your browser password manager so you don’t have to type it every time.

If the SSH SFTP Updater Support plugin isn’t prompting you to enter password when you try to update WordPress or alter plugins, add an entry in your wp-config.php file for define('FS_METHOD', 'ssh2'). Make sure there are no other entries for FS_METHOD in the config file.

But can WordPress update itself?

This is what some would consider a caveat of restricting where www-data can write to. If there is a critical security patch released, WordPress will not have the appropriate permissions to apply this patch on its own.

However, if you are serious about WordPress security, you should be proactively maintaining and updating your WordPress install frequently anyway. And in such eventuality where there is a critical security hole discovered in WordPress core, a hacker will still not be able to gain write access to your entire doc root.

You can be notified of critical WordPress and plugin security patches via email using a plugin such as WordFence and then update WordPress yourself using the SSH SFTP Updater Support plugin as previously mentioned. This is the method that I personally employ for all my WordPress installs.

1 Star2 Stars3 Stars4 Stars5 Stars 5.00 (7 votes)

Let me know if this helped. Follow me on Twitter, Facebook and YouTube, or 🍊 buy me a smoothie.

p.s. I increased my AdSense revenue by 68% using AI πŸ€–. Read my Ezoic review to find out how.

32 replies

avatar
  Subscribe  
newest oldest
Notify of
Zorann
Guest
Zorann
Zorann
16 hours ago

I was so happy when I made yesterday everything work, yet I encountered a serious problem. I had SFTP with multiple virtual hosts, and I was using FileZilla to copy files on each one. Yet i forgot to add sftp_users as owner to one of virtual hosts, and couple dozens mkdir could not be executed, and the transfer took a long while.
Meantime I was typing command on mu ubuntu server and keyboard suddenly stopped working. The underscore line was blinking whole time, but I wasn’t able to type anything. After few minutes I hit enter few times, typed shutdown (or reboot), press enter and wait… and the server executed the command!

Ok, I tought that everything is fine, but now I’m unable to connevt to sftp. Filezilla returns FATAL ERROR: Network error: Software caused connection abort.
I have no idea what to do now. I tried redo all the steps multiple times, checked virtual hosts settings and tried to redo them as well, nothing works. What can be the problem? I’d like to provide more informations or some logs, but I don’t know where could i get some. Can You help me?

Karim Hosein
Guest
Karim Hosein
Karim Hosein
1 month ago

It worked right up until I did the “match user” thing, then I started getting this message.

ssh_init: Name or service not known
Could not connect to server

So I removed the code block from the config, but it still gives this error. I cannot get back to how it was before, even after complete reboot.

Arvind Kumar
Guest
Arvind Kumar
Arvind Kumar
2 months ago

Could be a good guide but its “Generate a password and press enter to accept all defaults.” where it broke!

Andrew
Guest
Andrew
Andrew
3 months ago

Great!

Thank you very much!

This saves me a lot of time!

I was looking for how to install vsftpd… this was easier and better.

cakra
Guest
cakra
cakra
3 months ago

great and detail explanation
working at the first try.

Kudos for you mate!

thanks a lot

James
Guest
James
James
5 months ago

Amazing Tutorial!! Worked the first time πŸ™‚ Keep up the great work

James

Gary
Guest
Gary
Gary
6 months ago

So, normally I have had Apache:Apache as ownership in my web directory. Now a test file transferred to the web root is user:user. Will this be accessible to the website? Did I miss something?

Arvind Kumar
Guest
Arvind Kumar
Arvind Kumar
2 months ago

Did you find an answer, I face the same issue. If I change it to webdev my website breaks!

annas
Guest
annas
annas
6 months ago

Great explanation. I’ve also seen some posts disabling login for the ftp user…

usermod -s /usr/sbin/nologin myuser

K Tysinger
Guest
K Tysinger
K Tysinger
8 months ago

This is the finest LAMP tutorial I have ever read on the Internet. It actually works and it is clear that you spent a whole lot of time writing this. You are a master of LAMP. Thank you!

Yuri
Guest
Yuri
Yuri
9 months ago

At last! Clear and understandable instructions!

Hugo
Guest
Hugo
Hugo
11 months ago

Excellent guide. Finally I have found what I looking for (paraphrasing Its U2’s song…). You help me a lot!!!.
Many thanks and greetings from Argentina,

Hugo

Frank
Guest
Frank
Frank
11 months ago

Probably the best guide on the net about SSH setting …. incredible work!

Dave Smith
Guest
Dave Smith
Dave Smith
1 year ago

Something I don’t understand about your instructions, and I’m a learner so I don’t want to say YOU’VE GOT IT WRONG when it is much more likely that I’m misunderstanding something, so please correct me!
(By the way, having to exclude code from my feedback because with code, getting blocked by cloudflare)

But, as I understand it
SFTP protocol explicitly depends on the user having SSH. To be denied an SSH login is to be denied an SFTP login.

So Step 1.3 is to “(…) restrict the user (…) to the document root and also disable their SSH access – we only want them to be able to log in over SFTP.” and that contradicts what I understand about SFTP.

Experience bears this out; If I include the line (code broken up to allow without cloudflare having a hissy fit) Fo rc eC om ma nd inte rn al-sf tp in my file /e tc/ss h/s shd _con fig , I can’t log in with FileZilla. If I comment it out and reload sshd then filezilla works over sftp.

Dave Smith
Guest
Dave Smith
Dave Smith
1 year ago

Scratch all that, something else was preventing me from logging in.

Nick
Guest
Nick
Nick
1 year ago

I first followed this to try a single user with access to an experimental directory. It worked fine. Then I wanted to try adding a user to a group, and setting up the group access like you described in part 2. I was able to get the user to log in and navigate all through the folders down from the chroot, but I get a permissions denied message when trying to upload files to any of the directories.

James Pike
Guest
James Pike
James Pike
1 year ago

I followed this tut yesterday, and everything was working fine, except none of the users I created had access to upload anything to the server.

So after reading more about permissions and groups, I changed some permissions settings. Restarted the server, and now I can’t connect at all. Running FileZilla on the server computer, gives the error:
Error: Connection reset by peer
Error: Could not connect to server

From any of my other computers, I get:
Network Error: Software caused connection to abort.

Any ideas, what happened, an/or how to fix it?