Learn Aria2 - FTP & SFTP

#Introduction

In episode 6 you turned aria2 into a batch download manager via the input file. Now we widen the battlefield: not just HTTP/HTTPS, but also FTP and SFTP. In the real world, many internal file servers — package mirrors, backup servers, or laboratory data stores — still serve FTP, and almost every modern Linux server opens file access over SFTP. Mastering both lets you pull data from anywhere, without waiting for another team to provide HTTP.

One thing to clear up from the start: FTP and SFTP are completely different protocols. FTP is decades old and unencrypted, while SFTP runs over SSH and its entire transfer is encrypted. Don't call them one family — that difference is what will drive your choices in the field.

#Basic FTP: URL and Authentication

aria2 uses the ftp:// scheme for plain FTP. Without credentials, aria2 tries to log in as the anonymous user — the old pattern for public mirrors. For servers that require an account, use --ftp-user and --ftp-passwd.

aria2c --ftp-user=deploy --ftp-passwd=gantiPassword \
  ftp://mirror.internal.example.com/pub/build-2026-08.iso

Credentials can also be embedded directly in the URL with the ftp://user:pass@host/path format. It's concise, but dangerous: the credentials will show up in process logs and shell history. Sticking with the options is safer, especially if you later move them into a configuration file in episode 8.

Two built-in behaviors worth knowing:

• Passive mode is on by default (--ftp-pasv is true). The server opens a second data connection to send the file. Suitable for machines behind NAT/firewalls — you don't need to open any inbound ports.
• Binary transfer is on by default (--ftp-type=binary). Only switch to ascii if the server demands it, for example for legacy text files that use a particular platform's newline conventions.

#FTPS: The Encrypted FTP Option

FTPS is FTP wrapped in TLS — just as HTTPS relates to HTTP. Credentials and data no longer travel as plain text. That's why modern FTP servers almost always offer this mode.

This is a good example of how reading the documentation before writing a script can save hours of debugging. The habit of "just try ftps://" will end with a confusing error.

#Centralized Authentication with netrc

Writing --ftp-user and --ftp-passwd in every command is impractical and risks leaking. aria2 supports a ~/.netrc file for centralized FTP, SFTP, and HTTP authentication. Think of it as a per-machine "credential vault".

machine ftp.example.com
login deploy
password gantiPassword

This file is read automatically at startup as long as its permissions are 600 — if it's too open, aria2 refuses to use it. That's a good security feature: a file containing passwords must not be readable by other users.

chmod 600 ~/.netrc
aria2c ftp://ftp.example.com/pub/file.tar.gz

With netrc, commands stay short and credentials live in one place.

#Downloading an Entire FTP Directory

The next common need: pulling every file from one FTP directory. Remember, aria2 has no recursive mode like wget -r — it downloads the URL list you give it, not a directory tree it crawls. That's a design decision that keeps aria2 simple and reliable.

The solution reuses the power of episode 6: build a URL list, then hand it to an input file. An FTP directory listing can be obtained with any available client, for example curl.

curl -u deploy:gantiPassword -s ftp://ftp.example.com/pub/dumps/ | \
  grep -oE '[^ ]+\.sql\.gz$' | \
  sed "s#^#ftp://ftp.example.com/pub/dumps/#" | \
  aria2c -i - -j 4

The pipeline's output is one URL per line, which aria2 reads straight from stdin. The listing parser above depends on the FTP server's format, so adjust the grep and sed patterns to your directory structure. The mindset is what matters: a URL list is data, and aria2 just consumes it.

#SFTP: Secure Transfer over SSH

SFTP uses the sftp:// scheme and runs over an SSH connection — usually port 22. There are no two channels like FTP; the whole session, authentication, and transfer live inside one encrypted connection. If you're comfortable with SSH, SFTP's concepts will feel instantly familiar.

aria2c --ftp-user=deploy --ftp-passwd=gantiPassword \
  sftp://files.example.com/backups/db-2026-08-03.sql.gz

SFTP credentials use the same FTP options — per aria2's manual, most FTP options also apply to SFTP. If the SSH port isn't 22, add it to the URL: sftp://deploy@files.example.com:2222/path.

#Host Key Verification

An SSH server's identity is guaranteed by its host key. aria2 can verify it with --ssh-host-key-md, comparing the server's SHA-1 fingerprint against the value you set. Grab the fingerprint with the standard SSH commands:

ssh-keyscan -t rsa files.example.com | ssh-keygen -E sha1 -lf -

The output looks like 2048 SHA1:b030503d4de4539dc7885e6f0f5e256704edf4c3 files.example.com (RSA). Remove the colons and give it to aria2 as plain hex:

aria2c --ssh-host-key-md=sha-1=b030503d4de4539dc7885e6f0f5e256704edf4c3 \
  sftp://deploy@files.example.com/backups/db-2026-08-03.sql.gz

#How FTP and SFTP Behavior Differ

Some FTP options have no effect on SFTP, which makes sense because the protocols are genuinely different:

• --ftp-pasv is ignored. The passive/active mode concept doesn't exist in SFTP; the data connection isn't separate, so there's no NAT problem.
• --ftp-type is ignored. SFTP transfers are always binary; there's no ascii mode.
• Authentication differs. FTP can log in anonymously, SFTP always needs an account; FTP can use passive mode without any verification, while SFTP goes through an encrypted SSH handshake.
• Resume still works. SFTP supports resume like FTP, so the --continue from episode 5 still applies.

In short: FTP is fast and simple for public mirrors; SFTP is the safe choice for sensitive internal data.

#Closing

In episode 7 you downloaded over FTP with --ftp-user and --ftp-passwd, learned that ftps:// is not supported by aria2, centralized credentials in ~/.netrc, handled FTP directories via an input file, and moved to SFTP with host key verification plus an understanding of how its behavior differs from FTP.

The most important takeaway: know the protocol before choosing the tool. FTPS requires a different tool, and SFTP trades some FTP options for end-to-end encryption.

In the next episode, episode 8, we stop typing options over and over — all settings move into the aria2.conf configuration file so every download session stays consistent. See you then!