< Home

Add and configure users

Before you continue, make sure you've provisioned an instance of SFTP Gateway, and logged in as the ec2-user. Refer to the initial setup instructions if necessary.

Create a new user

Create a new user with the following command:

sudo addsftpuser <username>

You will be asked a series of questions to configure your user.

Note: If you want to modify a user's configuration, just run addsftpuser on the same user again.

Note: Usernames must be between 1-32 characters long, and contain alphanumeric characters. Do not user special characters or email addresses.

Configure SSH Key

You'll first be asked whether to create a new SSH key. Key-based authentication is recommended, because it's secure and there's no passwords to remember.

Would you like to create a new SSH key for user mytestuser? [y/N]: y

Note: If you want to use a traditional password, refer to this wiki page.

Please use a valid email address in order to receive the private key.

Enter email address to receive private key: mytestuser@example.com
Key mailed to mytestuser@example.com

The email is likely to end up in your spam folder. This is because public IP addresses for EC2 are temporary, and could be on a spam filter gray-list.

If the email is blocked (e.g. due to a corporate firewall), you can retrieve the SFTP user's private key from /opt/sftpgw/keys.

Configure server-side encryption

The next question relates to encryption at rest while being stored on S3. We recommend that you choose option 1, which is Server Side Encryption (SSE-S3).

Please select an option for Server Side Encryption. If you are not sure, we recommend 
that you choose option 1. Only choose option 4 if you are positive you do not want any encryption whatsoever. 
Refer to our wiki for more information - 
https://bitbucket.org/thorntechnologies/sftpgateway-public/wiki/SSE 
   1. I want Amazon S3 to manage Server Side Encryption for me (SSE-S3). 
   2. I have an AWS KMS Key ARN that I want to use for Server Side Encryption (SSE KMS) 
   3. I have a base64-encoded AES-256 encryption key string that I can copy and paste (SSE-C). 
   4. I do not want to use server side encryption. 
   5. Skip this and do not change anything. 
[1-5]: 1
Amazon S3-managed encyption keys (SSE-S3) will be used for server side encryption. 

Here are your options:

• SSE-S3: With SSE-S3, your objects are encrypted when stored on S3. There is no additional cost, performance impact, nor key management overhead. You basically get some security compliance with no drawbacks.
• KMS: You use the AWS key-managed service for encryption. This is similar to SSE-S3, but requires some configuration on your part.
• SSE-C: You take full responsibility of managing keys. A lost key results in data loss, so choose this for compliance reasons only.
• No server side encryption: This is a good option if your S3 bucket is open to the public. Otherwise, it's best to take advantage of SSE-S3.

Customize S3 bucket and path

By default, SFTP Gateway uses a default bucket and path.

Would you like to modify the current S3 location (sftpgateway-i-123456789abcde/testuser/uploads/) for this user? [y/N]: n

• Bucket: This uses the convention sftpgateway-i-123456789abcde, based on your EC2 instance ID
• Path: This defaults to <username>/uploads/

However, you can specify a custom bucket name and path:

Would you like to modify the current S3 location (sftpgateway-i-123456789abcde/testuser/uploads/) for this user? [y/N]: y

Please enter the S3 bucket name to use for this user: mycustombucket
Please enter the S3 path to use for this user: my/custom/path

The custom S3 bucket will be created for you if it does not exist, or you can point it to an existing bucket that you own. The user's files will be uploaded to s3://mycustombucket/my/custom/path/

Caution: If you point it to a bucket that has already been created by someone else using S3, the bucket creation will fail.

Private download directory

A private download directory lets you drop files into S3 that can be picked by a single SFTP user.

For more information on private download folders, see this page.

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

This creates an S3 folder with the following default location:

s3://sftpgateway-i-123456789abcde/testuser/downloads/

Any file uploaded to this S3 location will get synced to the SFTP user's downloads folder:

/home/testuser/home/testuser/downloads/

You can think of the downloads and uploads folders like an inbox and outbox.

Note: The sync process happens once every five minutes. You can reduce this duration by running sudo crontab -l.

Shared download directory

For more information on shared download folders, see this page.

A shared directory is similar to a downloads folder, except multiple SFTP users have access.

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

By default, the shared directory location is:

s3://sftpgateway-i-123456789abcde/shared/

Note: Even if you configure each user with a custom S3 bucket, the shared directory will still use the default S3 bucket.

User directory structure

On the filesystem, users are configured with the following directory structure:

/home/testuser/home/testuser/

The first set of /home/testuser/ is a convention in Linux. Users will never see this, because shell access is disabled for SFTP users.

The second set of /home/testuser/ is what users see from their SFTP client.

Within the user's SFTP home directory, there are four folders:

• uploads: Files dropped here are uploaded to S3
• local: Files dropped here remain local to the server
• downloads: Files from the S3 downloads location are synced to this folder. The user does not have write access to this location.
• shared: Files from the S3 shared location are synced to this folder. The user does not have write access to this location.

Users do not have permission to modify or delete at the SFTP home directory level. Instead, they should use the folders provided.

User provided SSH public keys

Some user may wish to use their own SSH key pairs. They can send you a public key that you can add to their /home/username/.ssh/aurhorized_keys file.

create the user:

sudo addsftpuser <username>

You will be asked if you would like to create an SSH key for that user.

Would you like to create a new SSH key for user <username>? [y/N]: N

Finish configuring the user as directed above.

Once user creation is complete create an ssh folder for that user:

sudo mkdir /home/<username>/.ssh

Then create a file called authorized_keys:

sudo nano /home/<username>/.ssh/authorized_keys

That user can now SFTP to SFTP Gateway.

Public key format

SFTP Gateway uses a standard implementation of OpenSSH for all SSH and SFTP connections. The OpenSSH sshd service will authenticates the user by checking that user's /home/username/.ssh/authorized_keys file for the public key that matchs the private key the user provided in the connection. The sshd service will look through each entry in the authorized keys file untill it finds a public key that matches. Sshd is expecting these entries to be in OpenSSH format. The format for OpenSSH public keys is a single key per line that consists of 3 segments separated by a single whitespace character.

keyType encodedKey               comment(optional)
--------------------------------------------------
ssh-rsa AAAAB3NzaC1yc2EAAAADA... bobtest

If a user provided you a key that does not appear in this format, you can adjust the format of the key by uploading the key to the server. Then running the command

ssh-keygen -i -f otherformat.pub > openssh.pub