TodayTools

SSH File Transfer Protocol

How SFTP works

File transfer inside SSH

Donate
L7ApplicationPort 22TCP
What brings you here?

Watch it happen

How much detail

Omar downloads a zip of photos: SSH sets up a locked tunnel, then SFTP opens, reads and closes the file.

Omar's laptop
Home router
Internet
files.example.com
Wi-FiInternetEncrypted tunnelSetupRequestResponseDataControlCloseEncrypted

5 steps, 21 packets

First up: SSH connection. Press Play to watch it happen, one step at a time.

0 of 50/5

What is SFTP?

SFTP lets you list, upload, download, rename and delete files on a remote computer, all inside an SSH connection. Because SSH encrypts everything, your password and files are safe even on public Wi-Fi.

Despite the name, SFTP is not FTP with a lock added. It is a different, binary protocol with one connection, no separate data channel and no trouble with NAT. Each read and write names its offset in the file, which makes resuming a broken transfer easy.

Think of it like this. SFTP is like handling papers at a bank teller window behind thick glass. You first prove who you are (SSH login), then pass slips through the slot: open this file, give me pages 1 to 10, file this page at page 11. Nobody in the queue behind you can see what is on the slips.

Step by step

Normal

5 steps

Omar downloads a zip of photos: SSH sets up a locked tunnel, then SFTP opens, reads and closes the file.

  1. 1

    SSH connection

    TCP 22, keys, login

    SFTP starts as a normal SSH connection: a TCP handshake, a key exchange that sets up encryption, and a login with a key or password.

  2. 2

    Start SFTP

    Subsystem request, INIT, VERSION

    Instead of a shell, the client asks for the sftp subsystem. Then the two sides agree on SFTP version 3.

  3. 3

    Find and open

    REALPATH, OPEN, HANDLE

    The client asks where it is, then opens the file for reading. The server returns a handle, a short token that stands for the open file.

  4. 4

    Read in pieces

    READ at an offset, DATA back

    The client asks for 32 KB pieces at given offsets, and keeps many requests in flight so the line stays full. Because each read names its offset, pieces can come back in any order.

  5. 5

    End and close

    EOF status, CLOSE

    When a read starts past the end, the server answers with an end-of-file status. The client closes the handle and the file is saved.

Resume upload

4 steps

Omar's 1.2 GB video upload stops halfway when the Wi-Fi drops. He reconnects and continues from where it stopped.

  1. 1

    Uploading

    WRITE at growing offsets

    Uploads use OPEN with WRITE, CREAT and TRUNC, then WRITE requests that each name an offset in the file.

  2. 2

    Wi-Fi drops

    The connection dies

    At 640 MB the laptop loses the network. The SSH connection breaks and the server closes the half-written file. The 640 MB already sent stay on the server.

  3. 3

    Check what arrived

    Reconnect, then STAT

    Omar reconnects and runs reput video.mp4. The client first asks the server how big the remote file is.

  4. 4

    Carry on

    OPEN without TRUNC, WRITE from 640 MB

    The client opens the file for writing without emptying it and starts writing at offset 671088640. Only the missing part is sent.

Permission denied

3 steps

Omar tries to upload into a folder he is not allowed to write to, and the server says no.

  1. 1

    Connected

    SSH and SFTP ready

    The SSH login works, so Omar is who he says he is. What he may do is still decided file by file.

  2. 2

    Open for writing

    OPEN /var/www/index.html

    The client asks to create a file in a folder owned by another user.

  3. 3

    Refused

    STATUS code 3

    The server checks the normal file permissions of the account and answers SSH_FX_PERMISSION_DENIED. Nothing is written and the session goes on.

Myths and mix-ups

  • SFTP is not FTP over SSL; that is FTPS, a different protocol.
  • SFTP does not need its own port; it runs on SSH's port 22.
  • SFTP is not an official RFC; it is defined by an IETF draft that everyone implements.
  • A dropped SFTP upload does not have to start over; tools like reput continue from the last byte.

Try it yourself

Run these on your own computer to see SFTP at work.

  • Connect and see each step

    sftp -v omar@files.example.com

    Replace with a server you can log in to. -v shows the SSH key exchange and the subsystem request.

  • Resume a broken upload

    sftp> reput video.mp4

    Inside an sftp session. reget does the same for downloads.

  • Copy one file in one line

    sftp omar@files.example.com:/home/omar/photos-lisbon.zip .

    Downloads to the current folder and exits.

  • Check that SSH is listening

    nc -vz files.example.com 22

    If port 22 is open, SFTP will usually work too.

SFTP at a glance

Layer
Application (7), inside SSH
Port
22 (the SSH port)
Transport
TCP, one connection
Format
Binary messages with request ids
Version in use
3, from OpenSSH and most servers
Encryption
Always, provided by SSH
Standard
IETF draft only, never finished as an RFC

Defined indraft-ietf-secsh-filexfer (version 3, never an RFC)RFC 4251RFC 4254

Header fields

What SFTP puts in its messages, with example values from the stories above.

SFTP v3

Type
SSH_FXP_INIT (1)
Version
3Version 3 is what nearly every client and server uses.
Extensions
posix-rename@openssh.com, statvfs@openssh.com, limits@openssh.com, ...
Request id
1Replies carry the same id, so the client can have many requests in flight.
Path
.
Name
/home/omar
Flags
0x00000001 (READ)Other flags ask to WRITE, CREAT (create), TRUNC (empty the file first) or APPEND.
Handle
00000001Like a ticket number. Every READ and the final CLOSE name this handle.
Offset
0Where in the file to start. This is what makes resuming and parallel reads possible.
Length
32768

Test yourself

Question 1 of 5Score 0

Which port does SFTP normally use?

Questions people ask

What is the difference between SFTP and FTP?

FTP is the old, unencrypted protocol with separate command and data connections. SFTP runs inside SSH over one encrypted connection on port 22 and is a completely different protocol.

Is SFTP secure?

Yes. SSH encrypts the login and every file, and the host key check protects you from talking to a fake server. Use key-based login for the best safety.

What port does SFTP use?

Port 22 by default, the same as SSH. Some servers move SSH to another port, and SFTP moves with it.

Is SFTP an RFC standard?

No. SFTP is described in IETF drafts that were never finished. Almost everyone uses version 3, as implemented by OpenSSH.

How do I resume an interrupted SFTP transfer?

In the sftp command line use reput for uploads or reget for downloads. Many graphical apps also offer resume. They check the size already transferred and continue from there.

Donate