This is an OpenSSH-based remote file system protocol that allows for encrypted transfers and lower-level file I/O calls against the server (for example, open/read/write/close, opendir/readdir/closedir, unlink, rename, and symlink). Secure File Transfer Protocol is also more comprehensive than Secure Copy (SCP)—which it has largely superseded—in that you can manage your content beyond simple data transfers.

Prerequisites before using SFTP with NetStorage

• SSH keys. You need to apply a secure SSH key to an upload account.
• Domain name prefix. Prepend your domain name prefix to the upload domain.
• Upload domain. <Domain name prefix>.sftp.upload.akamai.com
• Username. All secure connections use sshacs as the username.

Example domain: This example uses an example domain name prefix of nsmediadocs and the sftp.upload.akamai.com upload domain to give a fully-qualified upload domain of: sshacs@nsmediadocs.sftp.upload.akamai.com

If you are using OpenSSH, you should also meet these requirements:

• OpenSSH version 7.2 or later. For multi-threading and higher window sizes.
• High Performance Network Patches. Apply these patches to remove a networking bottleneck that exists in the base OpenSSH code. View the FAQ for additional details.
• Reduce client CPU spikes. Spikes are unlikely if you are using a wide-area network, but if it happens, you can use the multi-threaded AES-CTR cipher if that meets your security needs. This is discussed in the FAQ above.

SFTP connection command format

Values displayed in “< >” represent variables and you should replace them with the actual options.

sftp [-Cv] [-B <buffer_size>] [-b <batchfile>] [-F <ssh_config>][-o <ssh_option] [-P <sftp_server_path>] [-R <#_of_requests>][-S <program>] [-s <subsystem | sftp_server>] hostsftp [[user@]host[:file [file]]]sftp [[user@]host[:dir[/]]]sftp -b <batchfile> [user@]host

Example SFTP commands using an OpenSSH client

Create an SFTP connection

This example uses the OpenSSH SFTP client from a command line. It uses an example domain name prefix of nsmediadocs and the sftp.upload.akamai.com upload domain to give a fully-qualified upload domain of: sshacs@nsmediadocs.sftp.upload.akamai.com

# SFTP connection command format
# Values displayed in “< >” represent variables. The “< >” characters are not used in the input.
sftp [-Cv] [-B <buffer_size>] [-b <batchfile>] [-F <ssh_config>][-o <ssh_option] [-P <sftp_server_path>] [-R <#_of_requests>][-S <program>] [-s <subsystem | sftp_server>] hostsftp [[user@]host[:file [file]]]sftp [[user@]host[:dir[/]]]sftp -b <batchfile> [user@]host

sftp -i <private key> sshacs@nsmediadocs.sftp.upload.akamai.com

Connected to sshacs@nsmediadocs.sftp.upload.akamai.com.

Display the local working directory

This example uses the lpwd command to display the present working directory on your local machine.

sftp> lpwd
Local working directory: C:\files

Display the remote working directory

This example uses the pwd command to display the present working directory on the server.

sftp> pwd
Remote working directory: /movies

List the local working directory

This example uses the lls command to perform a local directory list on your local machine.

sftp> lls
Directory of C:\files
06/05/2020  01:52 PM    <DIR>          .
06/05/2020  01:52 PM    <DIR>          ..
06/05/2020  11:50 AM            41,392 movie.mp4
1 File(s)         41,392 bytes
2 Dir(s)  38,636,281,856 bytes free

Upload a single file

This example uploads the local movie.mp4 file to the remote /movies directory by using the put command.

sftp> put movie.mp4
Uploading movie.mp4 to /movies/movie.mp4
movie.mp4            100%   40KB  40.4KB/s   00:00

List the remote working directory

This example performs a directory list ls -l on your remote server.

sftp> ls -l
-rw-rw-r--    0 writingteam storage     41392 Jun  5 18:39 movie.mp4

Don't include hidden dot files

By default, the ls command doesn't show hidden dotfiles.

sftp> ls -l movies
-rw-rw-r--    0 writingteam storage     41392 Jun  5 18:39 movie.mp4

Include hidden dot files

Use the ls -a command option to include hidden dotfiles.

sftp> ls -a -l movies
-rw-rw-r--    0 writingteam storage         0 Jun  5 18:52 .dotfile
-rw-rw-r--    0 writingteam storage     41392 Jun  5 18:39 movie.mp4

Use PuTTY as an SFTP client

PSFTP is the Secure File Transfer Protocol client of PuTTY.

Use these variables during the connection process:

• <Username>. When providing the username, the value sshacs must be used. (This is the case for all secure access methods in NetStorage.)
• <private key>. Apply your private SSH key for this upload account.
• <Domain Name Prefix>. This value followed by .sftp.upload.akamai.com represents your full upload domain name. You set up your domain name during creation of the target storage group.

Example SFTP commands using the PuTTY client client

Example PuTTY SFTP connection

This example uses the PuTTY SFTP client from a command line. It uses an example domain name prefix of nsmediadocs and the sftp.upload.akamai.com upload domain.

psftp -i <private key>.ppk sshacs@nsmediadocs.sftp.upload.akamai.com
Connected to sshacs@nsmediadocs.sftp.upload.akamai.com.

Display the local working directory

This example uses the lpwd command to display the present working directory on your local machine.

psftp> lpwd
Current local directory is C:\files

Display the remote working directory

This example uses the pwd command to display the present working directory on the server.

psftp> pwd
Remote directory is /movies

Upload a single file

This example uploads the local subtitle.srt file to the remote /movies directory by using the put command.

psftp> put subtitle.srt
local:subtitle.srt => remote:/movies/subtitle.srt

List the remote working directory

This example performs a directory list ls on your remote server. This includes hidden dotfiles by default.

psftp> ls
Listing directory /movies
-rw-rw-r--    0 writingteam storage         0 Jun  5 18:52 .dotfile
-rw-rw-r--    0 writingteam storage     41392 Jun  9 23:28 movie.mp4
-rw-rw-r--    0 writingteam storage      5029 Jun  9 21:58 subtitle.srt
drwxrwxr-x    0 writingteam storage         0 Jun  9 22:20 tmp

Differences between PuTTY PSFTP and OpenSSH SFTP

The PuTTY PSFTP client offers a subset of OpenSSH SFTP commands, and is compatible with NetStorage. PuTTY's PSCP client has an -sftp backend mode of operation that works likes PSFTP. There are differences between the PuTTY and OpenSSH SFTP clients:

• Limited globbing support: The PuTTY PSFTP client doesn't support “globbing” (wildcard characters) as fully as the OpenSSH client; this also affects PSCP in the -sftp backend mode.
• Limited constructs and commands: The PuTTY PSFTP client doesn't support these constructs or commands in either interactive usage or “batch” mode:
  • Leading # characters aren't treated as comments as they are with the OpenSSH client; they are treated as syntax errors.
  • Globbing expressions (wildcard characters) are not supported.
  • The get and put commands have no option to preserve transferred files’ permission and access time attributes. There is no [-P] option like there is with the OpenSSH client.
  • There is no symlink command.
  • These PuTTY PSFTP commands aren't present in the OpenSSH SFTP client, and aren't supported with NetStorage:
    • reget (resume download): The client tells the server to seek to the position corresponding to the end of the portion of the file on the client, and to transfer the remaining bytes.
    • reput (resume upload): The client queries to see how much of the file exists on the server, and then only uploads the remaining portion of the file. Note: When performed on NetStorage, reput will always result in a full upload.

Use WinSCP as an SFTP client

SFTP provides opendir/readdir/closedir interfaces, which are suitable for browsing support.

You can use WinSCP as an SFTP client. The popular OpenSSH and PuTTY SFTP clients provide rudimentary filesystem browsing support, but WinSCP, an open-source SCP/SFTP client, offers a graphical user interface.

WinSCP requirements for SFTP

NetStorage only supports the SFTP backend protocol. Specific requirements apply to the use and configuration of WinSCP:

• SFTP Backend Protocol, Only. Configure WinSCP to use the SFTP backend protocol.
• Enable transfer resume. Set to this option to disable.

🚧

The “Allow SCP fallback” option in WinSCP will not work with NetStorage.

Use the “Pageant” Agent vs. Direct Configuration in WinSCP

WinSCP offers two options when incorporating the private key file for access.

You can incorporate the key while setting the Login Configuration, or you can incorporate the PuTTY “Pageant” agent to call out the private key.

• Using Direct Configuration. During this one-time login configuration process, you simply navigate to the private key file on your local system and include it in the configuration. However, if you have incorporated a passphrase for added security, you will have to provide this value every time you attempt access, because WinSCP can not save this value within a Stored Session.
• Using Pageant. You launch the agent separately, navigate to the private key file and, if applicable provide the associated passphrase. You can come and go from an individual login configuration, and leave Pageant running, with your private key(s) loaded. For example, you won’t have to provide the passphrase each time you use the login configuration.

Both options have their merits, and can be incorporated to best meet your needs -- If you have a single NetStorage upload account (or one that you use primarily), it might be best to just apply the private key via the direct configuration method, and mark it as a saved session. You would then only need to provide the passphrase (if applicable) each time you login. However, if you use several upload accounts, and their private keys all exist on your local system, you would leave the private key out of the individual login configurations, and instead load all of them into a single instance of Pageant. As an end result, you could log in and out between the associated login configurations, and Pageant would sync with WinSCP -- no need to provide a passphrase each time.

📘

WinSCP does not support providing the passphrase from the command line or by other means that utilize automation. Therefore, the Pageant Method (below) must be used in this case.

Direct configuration method

This method requires that you provide the applicable private SSH key.

Pageant method

Pageant is included with WinSCP, and it can be accessed as follows to load private key files:

1. Launch WinSCP.
2. In the WinSCP Login window, click “Stored sessions” in the tree.
3. Click Tools... to reveal a drop-down, and select Pageant from the drop-down.
4. A monitor icon will appear in the system tray. Double-click it.
5. In the interface that appears, click Add Key.
6. Navigate to the private key file on your local system, select it and click Open.
7. If applicable, enter the appropriate passphrase, and click OK.
8. Repeat Steps 5 - 7 to add additional private keys (if applicable).

WinSCP will now sync with Pageant to use the private key(s) when you login.

Connection command options

This table covers the command options available for use during the connection process.

📘

This list of commands and options are specific to the OpenSSH SFTP client and can vary depending on the client used. For example, the PuTTY PSFTP client adds options (e.g., recursive directory traversal) not available to the OpenSSH client.

SFTP limitations and considerations with NetStorage

When using SFTP to interact with a storage group, these limitations apply:

Don't confuse SFTP with FTP

Despite its name, don't confuse SFTP with the following unrelated, FTP-based protocols (that may also use their own form of security):

• Simple File Transfer Protocol (RFC 913)
• File Transfer Protocol (RFC 959)
• FTP over SSH. This is FTP encapsulated inside an SSH session (this method is not supported for use with NetStorage).
• FTP-TLS (FTPS). This is FTP encapsulated inside an SSL/TLS session

Considerations when using OpenSSH as an SFTP client

Use the “ls <path>” command with OpenSSH

The OpenSSH SFTP client is fully interoperable with NetStorage. The points that follow offer notes about the directory listing command (ls ) when using OpenSSH versions 3.4p1 and earlier.

• Output is unsorted (version 3.5p1 introduced sorting).
• The . and .. entries are always displayed (version 3.5p1 introduced the filtering of “hidden” dotfiles, as well as a new -a option that displays these entries).
• The command’s argument must be a directory (version 3.5p1 removed this restriction so the command can also be used on other object types such as files and symbolic links).