fineFTP Server Documentation

Follow these steps to clone the repository, initialize submodules, and build the project using CMake.

1. Clone and initialize submodules:

   git clone https://github.com/eclipse-ecal/fineftp-server.git
   cd fineftp-server
   git submodule init
   git submodule update

2. Configure with CMake:

   mkdir _build
   cd _build
   cmake .. -DCMAKE_BUILD_TYPE=Debug -DCMAKE_INSTALL_PREFIX=_install

3. Build:

   • Linux: Run make.
   • Windows: Open _build\fineftp.sln in Visual Studio and build the example project.

To use fineFTP as an embedded library, instantiate a fineftp::FtpServer object with a desired port, configure users with specific permissions, and call start() with a thread-pool size.

Note: fineFTP does not support encryption. Use it only in trusted networks.

#include <fineftp/server.h>
#include <thread>
 
int main() {
  // Create an FTP Server on port 2121
  fineftp::FtpServer ftp_server(2121);
 
  // Add an anonymous user with full permissions to a specific path
  ftp_server.addUserAnonymous("C:\\", fineftp::Permission::All);
  
  // Start the FTP Server with a thread-pool size of 4
  ftp_server.start(4);
 
  // Prevent the application from exiting immediately
  for (;;) std::this_thread::sleep_for(std::chrono::milliseconds(100));
  return 0;
}

You can integrate fineFTP using two primary methods:

Option 1: Integrate as binaries

Download the release and add the installation directory to your CMAKE_PREFIX_PATH:

cmake your_command_line -DCMAKE_PREFIX_PATH=path/to/fineftp/install/dir

Option 2: Integrate as source

Add the repository as a git submodule or via FetchContent, then add it to your project:

Method A: Add top-level CMakeLists.txt (Inherits all options and builtin asio):

add_subdirectory(path/to/fineftp-server)

Method B: Add server subdirectory (Cleanest version, requires you to provide asio):

add_subdirectory(path/to/fineftp-server/server)

Linking

After adding the project, link against the fineftp::server target:

find_package(fineftp REQUIRED)
target_link_libraries(your_target PRIVATE fineftp::server)

Use the following CMake options to control the build process:

The fineftp::FtpServer class provides a simple interface to instantiate and run an FTP server. The typical workflow involves:

1. Instantiating the server: Specify the network interface (address) and the port. Use "0.0.0.0" to listen on all interfaces, or 0 to let the OS assign a free port.
2. Adding users: Define users with specific local root paths and fineftp::Permission bit-masks.
3. Starting the server: Call start() to begin accepting connections.

Note on Ports: If you use the default FTP port 21, your application may require root/administrator privileges. If you use port 0, you can retrieve the assigned port using getPort().

fineftp::FtpServer server(2121);
server.addUserAnonymous("C:\\", fineftp::Permission::All);
server.start();

To use the fineFTP library, instantiate a fineftp::FtpServer object with a specific port number. You can then configure users with different permission levels and root directories before starting the server with a specified number of worker threads.

Note that on Windows, the local_root path string must end with a backslash (e.g., "C:\\").

#include <fineftp/server.h>

// 1. Initialize server on port 2121
fineftp::FtpServer server(2121);

// 2. Configure users
// Anonymous user: username "anonymous" or "ftp", any password
server.addUserAnonymous("/path/to/root", fineftp::Permission::All);

// Normal user: specific credentials and permissions
server.addUser("MyUser", "MyPassword", "/path/to/root", fineftp::Permission::ReadOnly);

// 3. Start the server with 4 worker threads
server.start(4);

Use the following methods to control and monitor the running server:

• bool start(size_t thread_count = 1): Starts the server with a specified thread pool size. thread_count must be greater than 0. Returns true if started successfully.
• void stop(): Stops the server. All current operations are cancelled as quickly as possible. Note that clients are not explicitly informed of the shutdown.
• int getOpenConnectionCount() const: Returns the number of currently active connections.
• uint16_t getPort() const: Returns the control port. If the server was started with port 0, this returns the port assigned by the OS.
• std::string getAddress() const: Returns the IP address the server is listening on.

The fineftp::FtpServer class offers several constructors to control how the server binds to the network:

Key Parameters:

• address: Use "0.0.0.0" to accept connections from any IPv4 address. Use a specific IP to restrict access.
• port: Use 0 to let the operating system choose a free port. Use 21 for the standard FTP port.

You can manage access by adding users to the server instance before calling start().

addUser

Adds a standard user with credentials and filesystem access.

• username: The login name. Warning: "anonymous" and "ftp" are reserved. If used, the password will be ignored and any password will allow login.
• password: The user's password.
• local_root_path: The local directory that the user will see as their root.
• permissions: A bit-mask of fineftp::Permission flags.
• Returns: true if successful.

addUserAnonymous

Adds the special "anonymous" / "ftp" user used by clients for passwordless access.

• local_root_path: The local directory to expose.
• permissions: A bit-mask of fineftp::Permission flags.
• Returns: true if successful.

The fineftp::FtpServer class provides methods to manage user access and directory roots:

• addUserAnonymous(local_root, permission): Adds a well-known anonymous user. The user can log in using the username anonymous or ftp with any password.
• addUser(username, password, local_root, permission): Adds a standard user with specific credentials.

Permissions

Permissions are managed via the fineftp::Permission bitmask. Common flags include:

• fineftp::Permission::All: Full access.
• fineftp::Permission::ReadOnly: Read-only access.
• fineftp::Permission::DirList: Ability to list directory contents.
• fineftp::Permission::DirCreate: Ability to create directories.
• fineftp::Permission::FileWrite: Ability to write files.
• fineftp::Permission::FileAppend: Ability to append to files.