libftp

A cross-platform FTP/FTPS client library built on Boost.Asio.

Table of contents

1. Overview
2. Features
3. Examples
4. Integration
5. Building
6. References

Overview

This library implements the client-side functionality of the File Transfer Protocol (FTP), providing a flexible solution for transferring files between clients and servers.

Connections

FTP employs two separate connections to manage commands and file transfers.

• Control connection: A persistent connection for exchanging commands and replies between the client and server.
• Data connection: A temporary connection established solely for transferring files. It remains open only for the duration of the data transfer.

Transfer modes

The transfer mode determines how the data connection is established.

Active mode

• The client uses the control connection to send the server its own IP address and a port number where it will accept incoming data connections.
• The server uses this information to initiate and open a data connection to the client.

Passive mode

• The client uses the control connection to request the server's IP address and a port number where the server will accept incoming data connections.
• The client then uses this information to initiate and open a data connection to the server.

This mode is useful in scenarios where the client is unable to accept incoming connections, such as when operating behind a firewall or NAT.

Transfer types

The transfer type determines how data is transferred.

ASCII type

• The sender converts newline characters from system style to CRLF style, and the receiver performs the reverse conversion.
• Suitable for transferring text files between systems with different newline conventions.

Binary type

• Transfers files byte by byte without modifications.
• Ideal for binary files, including images, videos, and archives.

Features

• Windows, Linux and macOS are supported.
• Supports FTP and FTP over TLS/SSL (FTPS).
• Supports IPv4 and IPv6.
• Supports active and passive transfer modes.
• Supports ASCII and binary transfer types.

Examples

Download the README.TXT file from ftp.freebsd.org and output its contents to stdout:

#include <iostream>
#include <sstream>

#include <ftp/ftp.hpp>

int main(int argc, char *argv[])
{
    ftp::client client;

    client.connect("ftp.freebsd.org", 21, "anonymous");

    std::ostringstream oss;

    client.download_file(ftp::ostream_adapter(oss), "pub/FreeBSD/README.TXT");

    std::cout << oss.str();

    client.disconnect();

    return 0;
}

See more examples in the example folder.

Integration

This library can be integrated into a project via CMake's FetchContent, for example:

cmake_minimum_required(VERSION 3.14)
project(application)

include(FetchContent)
FetchContent_Declare(
        libftp
        GIT_REPOSITORY https://github.com/deniskovalchuk/libftp.git
        GIT_TAG        v1.4.1)
FetchContent_MakeAvailable(libftp)

add_executable(application main.cpp)
target_link_libraries(application ftp::ftp)

Building

Prerequisites

• A C++17-compliant compiler
• CMake 3.14 or newer
• Boost 1.70 or newer
• OpenSSL
• Python3 (only for tests)

Windows

Build and run tests:

tool/windows/build.ps1 [-BuildType Debug|Release] [-RunTest]

Clean the builds:

tool/windows/clean.ps1

Linux/macOS

Build and run tests:

tool/unix/build.sh [--debug | --release] [--test]

Clean the builds:

tool/unix/clean.sh

Custom environment

Build:

$ mkdir -p build
$ cd build
$ cmake ..
$ cmake --build .

To run tests, set the LIBFTP_TEST_SERVER_PATH environment variable to the path to the server.py file:

$ export LIBFTP_TEST_SERVER_PATH="/path/to/server.py"
$ cd test
$ ctest -V

References

• RFC 959 File Transfer Protocol (FTP). J. Postel, J. Reynolds. October 1985.
• RFC 2228 FTP Security Extensions. October 1997.
• RFC 2428 Extensions for IPv6, NAT, and Extended passive mode. September 1998.
• RFC 3659 Extensions to FTP. P. Hethmon. March 2007.
• RFC 4217 Securing FTP with TLS. October 2005.