sftp icon

SFTP

Version: latest

When you want to send and receive a large amount of files via the AS2 Gateway, using an integration mechanism is a must. SFTP is one such integration mechanisms currently supported by the AS2 Gateway.

What is SFTP?

SFTP, which stands for SSH File Transfer Protocol, or Secure File Transfer Protocol, is a separate protocol packaged with SSH that works in a similar way over a secure connection. The advantage is the ability to leverage a secure connection to transfer files and traverse the filesystem on both the local and remote system.

The AS2 Gateway runs an SFTP server and once the SFTP setup is done, users can login to the AS2 Gateway’s SFTP server to download received files and upload files to be sent.

If you enable SFTP integration, messages in your web interface will be only retained for a maximum period of 60 days.
Attachments placed into SFTP are not guaranteed to be available beyond 48 hours; hence it is recommended to fetch the received files at least within 24 hours, and delete each file from AS2 Gateway SFTP space as soon as it is retrieved. AS2 Gateway SFTP space must not be used for long-term storage of your attachments/files.

Setup SFTP with AS2 Gateway

Lets start with setting up SFTP for your account. First go to the SFTP view using the "SFTP" icon on the left navigation menu. Alternatively click on the link https://console.as2gateway.com/sftp to navigate to the SFTP view.

sftp menu

One you navigate to the SFTP view, if you haven’t already done the SFTP setup, a form will be shown with a username and a password field.

Please provide a user name and a password and click on Setup SFTP to initiate the SFTP setup.

Username should start from a lowercase character and it can only include numbers 0-9, hyphen and underscore. Uppercase characters are not allowed.

Minimum length for the password field is 5 characters.

Once you click on the "Setup SFTP" button, what happens in the background is that a key-based authentication for SFTP will be setup for you and your private key will be available for you to download after the setup. Note that the password which you provided during the setup will be the passphrase for your private key.

If you are already subscribed and paying for the Personal package: once SFTP is activated, make sure to inform AS2 Gateway Team to get your subscription updated.

Logging in to AS2 Gateway SFTP Space

Once the SFTP setup is complete, you should be able to use any of the SFTP clients and connect to the AS2 Gateway server. After the setup the SFTP view will show the instructions on connecting to the AS2 Gateway SFTP server via the command line for Linux and MacOS users. In this documentation we will cover steps on configuring connectivity using several SFTP clients including OpenSSL command line client and File Zilla and WinSCP.

A complete listing of SFTP clients can be found at https://www.sftp.net/clients

To ensure fair usage, AS2 Gateway throttles its SFTP connections as follows:

  • Up to 20 new connections per minute can be made from a single IP address.

  • A total of up to 20 concurrent live connections can be maintained per IP address.

To save processing and bandwidth on both ends, it is recommended to:

  • poll the inbox with a considerably large time period; e.g. checking for new messages once every 10 minutes.

  • not maintain persistent or long-lived connections, except if/when uploading or downloading a long batch of files at a steady rate.

SFTP Folder Structure

Once logged in, you will be inside your own SFTP space, containing the following:

  • as2gateway: base folder containing AS2 folder/attachment hierarchy

  • id_rsa_<username>, id_rsa_<username>.pub: your SFTP private/public keys

  • .ssh: folder containing your SFTP login configurations

Within as2gateway, you can find folder path combinations for all your trading stations and partners:

<station AS2 identifier>/<partner AS2 identifier>

Under each path, there are 3 folders:

  • inbox: attachments from incoming AS2 messages

  • outbox: folder to place attachments in order to send them out as AS2 messages

  • failed: send-out attachments (from outbox) that could not be enqueued for delivery, due to some reason (error)

For more details and examples, refer to the SFTP folder structure reference.

Sending and Receiving files via SFTP

Receiving files (AS2 message attachments) via partner inbox

When a new AS2 message is received, AS2 Gateway will persist its attachments into SFTP, under your <recipient station ID>/<sender partner ID>/inbox folder.

The file saving path depends on the receiving trading station’s inbox folder structure config.

In each case, you can fetch the file using the SFTP get command. Make sure that you also delete the fetched files, to preserve your storage quota. Deletion also eliminates the need to skip/keep track of already fetched files on your end.

cd as2gateway/<station ID>/<partner ID>/inbox/<timestamp>-<random number>/
get <filename> /local/file/store/path
rm <filename>
cd ..
rmdir <timestamp>-<random number>/

Recursively fetching and removing all inbox content, despite being simple, can be risky - as it may:

  • fetch (and then discard) files that are still being written to the SFTP filesystem (i.e. those related to messages that were received right before or during the SFTP get invocation)

  • delete (lose) files for messages that were received after the recursive list/fetch was invoked (these files will not get included in the recursive fetch, but will still get deleted during the recursive removal)

Hence, when accessing SFTP programmatically, it is recommended to:

  • list all files/directories in the inbox that are older than a certain time threshold (e.g. 1 minute from now)

  • fetch and delete, explicitly, the content returned in the list - either as a batch (preferred), or by iterating each

Sending files (messages) out via partner outbox

There are two modes of sending files out:

  • To send a single file as an AS2 message, simply upload the file to the respective outbox. AS2 Gateway will pick it up and queue it for delivery, within a maximum of 30 seconds.

    put <local path>/<filename> as2gateway/<station ID>/<partner ID>/outbox/
  • To send multiple files in a single AS2 message (multiple-attachment mode),

    • create a folder inside the outbox, and

    • place all files into it.

      cd as2gateway/<station ID>/<partner ID>/outbox/
      mkdir <a unique folder name; say "20200101101035">
      cd 20200101101035/
      put <file 1>
      put <file 2>
      ...
      put <file n>
      You can add up to 10 files per message, adding up to a total size of 10 MB.

In the latter case, AS2 Gateway will process and enqueue the folder content, two (2) minutes after the last file is uploaded. Hence, make sure that you do not leave a gap of more than 2 minutes between two consecutive file uploads.

Resetting SFTP

If you wish to stop using SFTP, or completely reset the SFTP space with a new keypair and clean (empty) folder structure,

SFTP integration details pane

After reset, any previously downloaded SFTP access keys would no longer work.

If you only want to change your SFTP keypair or key passphrase, DO NOT use the reset option; instead, contact AS2 Gateway Team.
If you are already subscribed and paying for the Personal package: if you do not wish to use SFTP again after the reset, make sure to inform AS2 Gateway Team to get your subscription downgraded accordingly.
In this topic
In this topic