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 Blob storage, and then deleted from the Linux file system. The Blob destination is:

Storage Account > Default Container > robtest/uploads

Since the file is deleted after getting copied to Blob, 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 Blob, 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 Blob.

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 Blob.

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 Blob.

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 Blob location:

Storage Account > Default Container > 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 AzCopy 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 Blob storage location (i.e. robtest/downloads). You can do this using Azure Storage Explorer.

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 Blob location:

Storage Account > Default Container > 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.