Modern Extensible FTP Server

Common errors

• Error: listen EADDRINUSE: address already in use :::21

  cause The specified port (e.g., 21 for FTP) is already being used by another application or a previously terminated instance of the FTP server that hasn't fully released the port.
  fix Change the `port` in the `url` option to an available port, or ensure no other process is listening on the desired port before starting `ftp-srv`. On Linux, you can use `lsof -i :<port>` to find the process.

• 530 Not logged in. Invalid username or password.

  cause This error is returned to the FTP client when the provided username and/or password do not pass the validation logic within your `ftpServer.on('login')` event handler.
  fix Review your `login` event handler to ensure it correctly resolves credentials. Verify that the username and password being sent by the FTP client match the expected values defined in your server-side logic.

• FTP client hangs during PASV data transfer or directory listing (e.g., after 'PASV' command).

  cause This issue typically arises from an incorrect passive mode (`PASV`) configuration, often due to Network Address Translation (NAT), firewalls, or an improperly set `pasv_url` option, preventing the client from connecting to the server's data port.
  fix Configure the `pasv_url` option with your server's external (WAN) IP address and ensure that the port range specified by `pasv_min` and `pasv_max` is open and accessible through your firewall.

Warnings

• breaking Version 4.3.4 introduced a critical security fix to disallow PORT connections to alternate hosts. Running older versions (prior to 4.3.4) exposes the server to potential security vulnerabilities (GHSA-jw37-5gqr-cf9j).
  Fix: Upgrade to `ftp-srv@4.3.4` or newer immediately to mitigate the vulnerability and ensure secure operation.
• gotcha When deploying `ftp-srv` behind a NAT or firewall, the `pasv_url` option is crucial for passive mode connections. It must be correctly configured with the external (WAN) IP address; otherwise, external clients may hang when attempting data transfers.
  Fix: Set `pasv_url` to your server's static external IP address or provide a resolver function that returns the correct external IP based on the client's connection. Example: `new FtpSrv({ pasv_url: 'YOUR_EXTERNAL_IP' });`
• gotcha The `url` option's hostname (e.g., `ftp://127.0.0.1:21`) must be `0.0.0.0` or the specific external IP address of the server to accept connections from outside the local machine. Using `127.0.0.1` will restrict client connections to localhost only.
  Fix: To allow external connections, configure the `url` option to listen on all available network interfaces using `url: "ftp://0.0.0.0:21"`.
• breaking `ftp-srv` requires Node.js version 12 or higher. Deployments on older Node.js runtimes will fail to start or operate correctly due to reliance on newer language features and APIs.
  Fix: Ensure your Node.js environment is updated to version 12 or newer. The `engines` field in the package's `package.json` specifies this minimum requirement.

Install

• npm install ftp-srv npm
• yarn add ftp-srv yarn
• pnpm add ftp-srv pnpm

Imports

• FtpSrv
  wrong:

  const FtpSrv = require('ftp-srv');

  correct:

  import { FtpSrv } from 'ftp-srv';

  While CommonJS `require` is shown in older examples, ESM `import` is the preferred pattern for modern Node.js applications and TypeScript projects using this library, which ships with type definitions.
• errors
  wrong:

  const { errors } = require('ftp-srv');

  correct:

  import { errors } from 'ftp-srv';

  The `errors` object, containing custom error types like `GeneralError`, is a named export from the library, useful for standardized error handling within the `login` event and other handlers.
• FtpSrvOptions

  import { FtpSrv, type FtpSrvOptions } from 'ftp-srv';

  For TypeScript users, the `FtpSrvOptions` interface provides type definitions for the configuration object passed to the `FtpSrv` constructor, ensuring type safety and autocomplete.

Quickstart

Demonstrates how to initialize an FTP server, handle anonymous logins, and specify a root directory. It includes basic error handling and prepares a dummy `ftp_root` directory in the current working directory, making it fully runnable out of the box.

import { FtpSrv, errors } from 'ftp-srv';
import path from 'path';
import { promises as fs } from 'fs'; // For creating the dummy ftp_root directory

const port = 21;
const ftpServer = new FtpSrv({
    url: `ftp://0.0.0.0:${port}`,
    anonymous: true
});

ftpServer.on('login', ({ connection, username, password }, resolve, reject) => {
    // In a real application, you would validate credentials against a database
    // For this example, 'anonymous' allows access to a specific root path
    if (username === 'anonymous' && password === 'anonymous') {
        const userRoot = path.join(process.cwd(), 'ftp_root');
        // A real scenario might dynamically create/select a user's directory
        return resolve({ root: userRoot });
    }
    return reject(new errors.GeneralError('Invalid username or password', 401));
});

ftpServer.listen().then(() => {
    console.log(`FTP server started on ftp://0.0.0.0:${port}`);
    console.log('Connect with anonymous:anonymous to access', path.join(process.cwd(), 'ftp_root'));
}).catch((err: Error) => {
    console.error('Failed to start FTP server:', err);
    process.exit(1);
});

// Helper to ensure the FTP root directory exists and contains a sample file
async function ensureFtpRootDirectory() {
    const rootPath = path.join(process.cwd(), 'ftp_root');
    try {
        await fs.mkdir(rootPath, { recursive: true });
        const welcomeFilePath = path.join(rootPath, 'welcome.txt');
        await fs.writeFile(welcomeFilePath, 'Welcome to the ftp-srv server!\nThis is a sample file.', { flag: 'wx' }); // 'wx' to only write if file doesn't exist
        console.log(`Ensured FTP root directory at ${rootPath}`);
    } catch (error: any) {
        if (error.code !== 'EEXIST') { // Ignore if directory/file already exists
            console.error('Error setting up FTP root directory:', error);
        }
    }
}
ensureFtpRootDirectory();