LFCS 117 🐧 Remote Transfer — sftp - KandZ

⏱️ Estimated read: 10 min | |

The sftp command is the interactive file transfer client in the OpenSSH suite. It establishes an encrypted connection to a remote host and provides a command interface similar to the legacy ftp client. The LFCS exam tests the distinction between local and remote commands, the syntax for uploading and downloading files, and the batch mode used in scripts. The critical trap is the dual command set: cd, ls, pwd, and mkdir operate on the remote host, while lcd, lls, lpwd, and lmkdir operate on the local machine. Confusing the two leads to files being placed in the wrong location or commands failing silently.

Key point: sftp is an interactive session, not a one-shot command like scp. It connects to the remote host, presents a prompt, and accepts commands. The get command downloads a file; the put command uploads a file. The -b flag runs a batch file of commands without interaction, and the -r flag enables recursive transfers.

Why sftp exists and how it differs from scp

The interactive problem. scp is designed for single commands: copy this file to that location. It does not provide a session for browsing the remote filesystem, changing directories, or listing files before deciding what to transfer. sftp fills this gap. It opens a persistent connection and presents a prompt where the user can navigate both the local and remote filesystems, inspect file attributes, and transfer files interactively .

The dual-context problem. An sftp session has two current working directories: the remote directory (on the server) and the local directory (on the client). The pwd command shows the remote directory. The lpwd command shows the local directory. The cd command changes the remote directory. The lcd command changes the local directory. This symmetry is deliberate, but it is the most common source of confusion. A user who types cd /tmp expecting to change the local directory will instead change the remote directory and be surprised when the next put places the file in the remote /tmp instead of the local one .

The protocol problem. sftp uses the SSH File Transfer Protocol, a subsystem defined in sshd_config. The subsystem is typically internal-sftp or /usr/libexec/openssh/sftp-server. If the subsystem is not configured on the server, sftp fails to connect. The internal-sftp implementation is the modern default because it supports ChrootDirectory, which is used to confine users to a specific directory tree .

The batch problem. An interactive session is useful for humans but not for scripts. The -b flag reads commands from a file and executes them without prompting. The batch file contains the same commands as the interactive session: cd, put, get, bye. If any command fails, the batch aborts unless the command is prefixed with a hyphen (-rm), which suppresses the abort on error .

The trade-off. sftp is slower than scp for simple single-file transfers because it opens an interactive session and issues multiple protocol requests. It is not the right tool for a one-line copy in a script. It is the right tool for exploring a remote filesystem, transferring multiple files in a session, or scripting a sequence of transfers with the -b flag.

a. The interactive session and the dual command set

The sftp command connects to a remote host. The prompt appears after authentication. The prompt shows sftp>.

# Connect to a remote host
sftp user@server.example.com

# Connect to a specific port
sftp -P 2222 user@server.example.com

# Connect and change to a remote directory
sftp user@server.example.com:/var/log

The command set is divided into remote and local operations. The remote commands operate on the server. The local commands are prefixed with l and operate on the client machine.

Remote Command	Purpose	Local Equivalent
`cd`	Change remote directory	`lcd`
`pwd`	Print remote directory	`lpwd`
`ls`	List remote files	`lls`
`mkdir`	Create remote directory	`lmkdir`
`rmdir`	Remove remote directory	—
`rm`	Remove remote file	—
`chmod`	Change remote permissions	—
`chown`	Change remote owner	—
`get`	Download file	—
`put`	Upload file	—

The get command downloads a file from the remote host to the local machine. The put command uploads a file from the local machine to the remote host.

sftp> get /var/log/syslog
# Downloads syslog to the current local directory.

sftp> put report.pdf
# Uploads report.pdf to the current remote directory.

The -r flag enables recursive transfers. It is passed to get or put as an option, or to sftp on the command line for all subsequent operations.

sftp> get -r /var/log/nginx
# Downloads the nginx log directory recursively.

sftp> put -r ./project
# Uploads the project directory recursively.

b. Batch mode and scripting

The -b flag reads commands from a file. The file contains one command per line. The session executes the commands in order and exits.

# Create a batch file
cat > transfer.batch <<'EOF'
cd /var/www/html
put index.html
put style.css
bye
EOF

# Execute the batch
sftp -b transfer.batch user@server.example.com

The batch mode requires non-interactive authentication. Password prompts would hang the process. The authentication must be key-based, or the ssh-agent must be running with the key loaded. The -o BatchMode=yes option enforces this: it fails immediately if a prompt would be required .

# Batch mode with key authentication
sftp -b transfer.batch -o BatchMode=yes user@server.example.com

The -b flag implies quiet mode (-q), which suppresses the progress meter and diagnostic messages. The -N flag disables quiet mode if the output is needed for logging.

c. Connection options and jump hosts

The sftp command accepts the same SSH connection options as ssh and scp. The -P flag specifies the port. The -i flag specifies the identity file. The -J flag specifies a jump host.

# Connect through a bastion
sftp -J bastion.example.com internal.example.com

# Use a specific key
sftp -i ~/.ssh/work_key user@server

# Use an SSH config alias
sftp work

The -F flag specifies an alternative SSH configuration file. The -o flag passes an arbitrary SSH option. The -v flag increases the logging level, which is useful for diagnosing connection failures.

# Verbose connection for debugging
sftp -v user@server

# Pass an SSH option
sftp -o StrictHostKeyChecking=accept-new user@server

Complete Example Session

# ============================================
# PART 1: CONNECT TO THE REMOTE HOST
# ============================================

sftp user@server.example.com
# The prompt appears: sftp>

# ============================================
# PART 2: NAVIGATE THE REMOTE FILESYSTEM
# ============================================

sftp> pwd
# Remote working directory: /home/user
sftp> cd /var/log
sftp> ls
# Lists the log files on the server.

# ============================================
# PART 3: NAVIGATE THE LOCAL FILESYSTEM
# ============================================

sftp> lpwd
# Local working directory: /home/localuser
sftp> lcd /tmp
sftp> lls
# Lists the local files in /tmp.

# ============================================
# PART 4: DOWNLOAD A FILE
# ============================================

sftp> get syslog
# Downloads syslog to the local /tmp directory.

# ============================================
# PART 5: UPLOAD A FILE
# ============================================

sftp> put /tmp/report.pdf
# Uploads report.pdf to the remote /var/log directory.

# ============================================
# PART 6: RECURSIVE TRANSFER
# ============================================

sftp> get -r nginx
# Downloads the remote nginx directory recursively.

# ============================================
# PART 7: BATCH MODE
# ============================================

cat > upload.batch <<'EOF'
cd /var/www/html
put index.html
put style.css
bye
EOF

sftp -b upload.batch -o BatchMode=yes user@server
# Executes the batch without interaction.

# ============================================
# PART 8: CONNECT VIA JUMP HOST
# ============================================

sftp -J bastion.example.com internal.example.com
# Connects to the internal host through the bastion.

# ============================================
# PART 9: VERIFY AND EXIT
# ============================================

sftp> ls /var/www/html
# Confirms the uploaded files are present.
sftp> bye
# Session closed.

The nine parts trace the sftp workflow: connection, remote navigation, local navigation, download, upload, recursive transfer, batch mode, jump host, and verification.

Quick Reference

Interactive Commands

Command	Context	Purpose
`cd`	Remote	Change remote directory
`pwd`	Remote	Print remote directory
`ls`	Remote	List remote files
`mkdir`	Remote	Create remote directory
`rm`	Remote	Remove remote file
`rmdir`	Remote	Remove remote directory
`chmod`	Remote	Change remote permissions
`get`	Download	Fetch file from remote
`put`	Upload	Send file to remote
`lcd`	Local	Change local directory
`lpwd`	Local	Print local directory
`lls`	Local	List local files
`lmkdir`	Local	Create local directory
`bye`	Exit	Quit the session

Command-Line Options

Option	Purpose
`-P <port>`	SSH port
`-b <file>`	Batch file
`-r`	Recursive transfer
`-i <key>`	Identity file
`-J <host>`	Jump host
`-o <option>`	SSH option
`-v`	Verbose logging

Batch Mode

Setting	Effect
`-b file`	Read commands from file
`-o BatchMode=yes`	Fail if prompt required
`-rm`	Prefix to ignore error

Best Practices

✅ Do This:

sftp -b upload.batch -o BatchMode=yes user@server
<!-- Use batch mode with non-interactive auth -->     # ✅

sftp> lcd /tmp
<!-- Use lcd for local directory changes -->         # ✅

sftp -J bastion internal
<!-- Use -J for jump hosts -->                       # ✅

❌ Don’t Do This:

sftp> cd /tmp
# Expecting to change the local directory
<!-- cd changes the remote directory -->             # ❌

# Use sftp for a single file copy in a script
<!-- scp is simpler and faster -->                   # ❌

# Rely on password prompts in batch mode
<!-- The process will hang -->                       # ❌

Common Pitfalls

Pitfall	Why It Happens	Fix
File uploaded to wrong place	`cd` used instead of `lcd`	Use `lcd` for local
Batch mode hangs	Password prompt	Use key auth + `BatchMode=yes`
Recursive transfer fails	Missing `-r`	Add `-r` to `get`/`put`
Connection refused	Wrong port	Use `-P`
Subsystem not found	`sshd_config` missing sftp	Enable `internal-sftp`

Real-World Examples

1. Connect

sftp user@server

2. Connect on Port

sftp -P 2222 user@server

3. Navigate Remote

sftp> cd /var/log
sftp> pwd

4. Navigate Local

sftp> lcd /tmp
sftp> lpwd

5. Download

sftp> get syslog

6. Upload

sftp> put report.pdf

7. Recursive Download

sftp> get -r nginx

8. Batch Mode

sftp -b upload.batch user@server

9. Jump Host

sftp -J bastion internal

10. Exit

sftp> bye

Visual

Dual Context

┌──────────────────────────────────────────────┐
│  LOCAL MACHINE                               │
│  lpwd → /home/localuser                      │
│  lcd /tmp → /tmp                             │
│  lls → local files                           │
└──────────────────┬───────────────────────────┘
                   │
                   │ sftp session
                   ▼
┌──────────────────────────────────────────────┐
│  REMOTE SERVER                               │
│  pwd → /home/user                            │
│  cd /var/log → /var/log                      │
│  ls → remote files                           │
└──────────────────────────────────────────────┘

Transfer Flow

┌──────────────────────────────────────────────┐
│  get /remote/file                            │
└──────────────────┬───────────────────────────┘
                   │
                   ▼
┌──────────────────────────────────────────────┐
│  File downloaded to local working directory  │
└──────────────────────────────────────────────┘

┌──────────────────────────────────────────────┐
│  put /local/file                             │
└──────────────────┬───────────────────────────┘
                   │
                   ▼
┌──────────────────────────────────────────────┐
│  File uploaded to remote working directory   │
└──────────────────────────────────────────────┘

Summary

Item	Value
Connection	`sftp user@host`
Remote directory	`cd`, `pwd`, `ls`
Local directory	`lcd`, `lpwd`, `lls`
Download	`get <remote>`
Upload	`put <local>`
Recursive	`get -r` / `put -r`
Batch mode	`-b <file>`
Non-interactive	`-o BatchMode=yes`
Port	`-P <port>`
Jump host	`-J <host>`
Exit	`bye`

Key takeaways:

sftp is interactive, scp is one-shot. sftp opens a session for browsing and transferring multiple files. scp copies one file or directory per command .
The dual command set is the primary trap. cd, pwd, ls, and mkdir operate on the remote host. lcd, lpwd, lls, and lmkdir operate on the local machine .
get downloads, put uploads. The -r flag enables recursive transfers. sftp does not follow symbolic links during recursive traversal .
Batch mode is for scripts. The -b flag reads commands from a file. The -o BatchMode=yes option enforces non-interactive authentication, which is required for the batch to complete without hanging.
The server needs the sftp subsystem. The sshd_config must have Subsystem sftp internal-sftp (or the path to the sftp-server binary). Without it, the connection fails .

Remember: sftp is a session, not a command. The prompt is the boundary between the local and remote contexts. The l prefix is the local side. The absence of the prefix is the remote side. The get and put commands move files across the boundary. The bye command closes the session.

Was this helpful?

Stop using slow, ad-bloated tool sites! 🤮

🔎 Search “KandZ Tools” on Google to use many professional utilities for free.

KandZ.me is the ultimate minimalist hub for:
✅ Finance (Mortgage, Interest, Inflation)
✅ Tech (Base64, JSON, Dev Suite, IP)
✅ Health (BMI, BMR, TDEE)
✅ Productivity (Timer, Workspace, QR)

⚡️ Fast & Private
🔒 No data leaves your device
💎 100% Free

🔗 Use it now: https://tools.kandz.me
🔖 Bookmark it—you’ll need it later!