Root Level Folders

Overview

This article covers the four main folders that an SFTP user will see when logging in.

Behind the scenes, these folders are located on the Linux file system:

/home/robtest/home/robtest/downloads/
/home/robtest/home/robtest/local/
/home/robtest/home/robtest/shared/
/home/robtest/home/robtest/uploads/

SFTP users are chrooted to:

/home/robtest/home/robtest/

So from the SFTP user's perspective, these folders reside at the root of the filesystem.

sftp> pwd
Remote working directory: /

sftp> ls -la
drwxr-xr-x    6 root     root         4096 Oct 25 19:59 .
drwxr-xr-x    6 root     root         4096 Oct 25 19:59 ..
drwxr-xr-x    2 root     root         4096 Oct 25 20:00 downloads
drwxr-xr-x    2 100001   100001       4096 Oct 25 19:59 local
drwxr-xr-x    2 root     root         4096 Oct 25 20:00 shared
drwxr-xr-x    2 100001   100001       4096 Oct 25 20:02 uploads

SFTP Gateway uses OpenSSH for SFTP. And by default, SFTP users are not allowed to write to their chroot directory. This is why SFTP Gateway has to create these folders for you.

Uploads

SFTP users typically drop files into the uploads directory. Each file is copied to S3, and then deleted from the Linux file system. The S3 destination is:

s3://<default bucket>/robtest/uploads

Since the file is deleted after getting copied to S3, the SFTP user will not be able to see the files they upload. So the uploads folder is similar to a drop box, or one of those outdoor USPS blue collection boxes. This is by design, because the idea is to move data to S3, which is a durable storage layer.

As a side note, there's a troubleshooting benefit. If files remain stuck in the uploads folder, this is your way of determining which files are failing to get copied to S3.

Behind the scenes, we use a file event service. When a file is done transferring via SFTP, a file event is triggered. Then a command is queued to copy the file to S3.

Local

The local folder behaves similar to a traditional SFTP server. This means you can create, move, and delete files. This is useful if you need read-write access.

The main drawback is that files in the local folder are not copied to S3.

An ideal use case for the local folder is if you need to send files to an external vendor. You can share the same SFTP account, and the vendor can delete your file after downloading it.

Downloads

The following S3 location:

s3://<default bucket>/robtest/downloads

gets synced (one-way) to the SFTP user's downloads folder on the Linux file system.

Behind the scenes, there's a cron job (running every 5 minutes) that executes an s3sync command, which performs the sync operation.

Since we're using a one-way sync, you can't write to this folder (any changes will be lost anyway).

So the only way to get files into this folder is to drop them into the S3 storage location (i.e. robtest/downloads). You can do this from the S3 service in the AWS management console.

The downloads folder is an optional setting, and can be configured on a per-user basis.

Shared

The shared folder behaves similarly to the downloads folder. This folder is a sync target, and it's configured on a per-user basis.

The main difference is that the shared folder can be seen by multiple users.

The following S3 location:

s3://<default bucket>/shared

gets synced (one-way) to the /opt/sftpgw/shared folder on the Linux file system.

Whenever an SFTP user is configured with the shared setting, SFTP Gateway creates a hard-link between /opt/sftpgw/shared and the user's shared directory.