Wiki

Private downloads directory

The private downloads directory feature of SFTP Gateway allows you to send files to your individual users.

By configuring a user with a downloads directory, SFTP Gateway will create a downloads folder on S3 in the user's folder. You can upload files to this folder in S3 and they will eventually be synced to that user's downloads directory on the SFTP Gateway server. The user will then be able to retrieve these files from the downloads directory.

When using the downloads directory, some things to consider are:

There could be a delay of a few minutes until files get synced. You can adjust the scheduled task (crontab -e), but this will result in more frequent S3 API calls.
Keep an eye on available local storage (df -h). Running out of space will interfere with normal operation of SFTP Gateway.
By default the users will only have read access to this directory because the process that syncs this directory with the S3 content will overwrite the directory with any additions, modifications, or deletions that were made to the S3 folder since the last periodic sync.
To remove files from the downloads directory, they should be removed from the S3 folder, and the deletion should be allowed to propagate down to the server.
The sync operation does not clean up directories when files are removed from them. This is a known issue with the AWS S3 data model and the AWS CLI. For more information, see Remove empty folders after download sync

Configuring the private download directory

To configure a user with a private download folder:

Run sudo addsftpuser username
When the interactive wizard asks "Would you like setup a private S3 download directory for this user?", answer with y

By default, this will create a folder on S3:

s3://sftpgateway-i-0123456789abcde/username/downloads/

Note: If the user was configured with a custom S3 bucket location, the downloads folder will be created in that bucket (i.e. s3://custom-bucket/username/downloads/)

When the user connects to the server over SFTP, they will see the downloads directory.

/
  downloads/
  local/
  uploads/

Customize the downloads directory name

In some use cases, you may wish to present the user with a downloads directory that is names something other than downloads.

The default name of the downloads directory can be changed by editing the sftpgateway.downloaddir property in the /home/ec2-user/.sftpgateway/sftpgateway.properties file.

Once the properties file has been modified, any users that you add and configure to use the downloads, will have this name as their downloads directory.

If you want to apply the changes to existing users, you can rerun the sudo addsftpuser username command. This will create the downloads directory with the new name, but the old downloads directory will still be present. You will have to manually delete the old downloads directory with the command sudo rm -rf /home/username/home/username/downloads/.

CAUTION: the command sudo rm -rf will run as the root user and remove a directory with recursive force. Take care to ensure that the path you provide this command is correct.

Shared download directory

The shared directory feature of SFTP Gateway, is used to distribute files to all of your users at once.

When SFTP Gateway is setup, the default bucket is created, if it does not exist, and the shared folder is created in the root of the default bucket.

When you place a file in the shared folder in S3, it will eventually get synced down to the shared directory on the server.

The shared directory on the server is accessible to all users whom are configured to use it, and they can download the files from there.

When using the shared directory, some things to consider are:

There could be a delay of a few minutes until files get synced. You can adjust the scheduled task (crontab -e), but this will result in more frequent S3 API calls.
Keep an eye on available local storage (df -h). Running out of space will interfere with normal operation of SFTP i Gateway.
All users whom are configured to use the shared directory will have the same accessibility to the files in the shared directory.
By defualt the users will only have read access to this directory because the process that syncs this directory with the S3 content will overwrite the directory with any additions, modifications, or deletions that were made to the S3 folder since the last periodic sync.
To remove files from the shared directory, they should be removed from the S3 folder, and the deletion should be allowed to propagate down to the server.
The sync operation does not clean up directories when files are removed from them. This is a known issue with the AWS S3 data model and the AWS CLI. For more information, see Remove empty folders after download sync

Configure the shared directory

To configure users to have access to the shared downloads directory:

Run sudo addsftpuser username
When the interactive wizard asks "Would you like setup a shared S3 download directory for this user?", answer with y

This will create the user's shared directory in their home directory. Then, the server's shared directory (/opt/sftpgw/shared) is linked to the user's shared directory. Any files that get synced to the server's shared directory through the sync process, will be accessible to the user through the user's shared directory.

Note: Even if the user is configured to use a custom S3 bucket, the shared directory will always use the default S3 bucket.

When the user connects to the server over SFTP, they will see the shared directory.

/
   local/
   shared/
   uploads/

Configuring individual SFTP users to see their own uploaded files

The latest update to SFTP Gateway has configuration options that can be combined to support different scenarios. One common scenario is allowing SFTP users to view their own uploaded files.

To accomplish this, just point the user's custom S3 location to match the download path.

Run sudo addsftpuser username.

When prompted, set a custom S3 bucket and path:

Would you like to modify the current S3 location (s3://sftpgateway-i-0123456789abcde/username) for this user? 
[y/N]: y
Please enter the S3 bucket name to use for this user: sftpgateway-i-0123456789abcde
Please enter the S3 path to use for this user: username/downloads

Here, you set the custom path to match the downloads directory: username/downloads.

When prompted to setup a private s3 download directory, say yes:

Would you like to setup a private S3 download directory for this user? Only this user will be able to download 
S3 files from this directory. [y/N]: y

Now, when the user uploads a file via SFTP:

/uploads/test.txt

The same file will appear in the downloads directory:

/downloads/test.txt

Configuring multiple SFTP users with a common download directory

You can also configure SFTP Gateway so that each SFTP file upload can be viewed by multiple users. This can be useful if all your users work on the same team. This is accomplished by pointing every user's custom S3 location to the default bucket's shared directory.

Run sudo addsftpuser username.

When prompted, point the custom S3 bucket and path to the shared directory:

Would you like to modify the current S3 location (s3://sftpgateway-i-0123456789abcde/username) for this user? 
[y/N]: y
Please enter the S3 bucket name to use for this user: sftpgateway-i-0123456789abcde
Please enter the S3 path to use for this user: shared

When prompted to setup a shared s3 download directory, say yes:

Would you like to setup a shared S3 download directory for this user? All SFTP users will be able to download 
the same files from this shared S3 location. [y/N]: y

Repeat this process of pointing the custom S3 location to the shared directory for each user.

Now, when one user uploads a file via SFTP:

/uploads/common.txt

The same file will appear in each user's shared directory:

/shared/common.txt