The File Transfer Protocol (FTP) is a standard communication protocol used for the transfer of computer files from a server to a client. The SSH File Transfer Protocol (SFTP) is similar but operates over SSH for added security.
The Weble universal gateway FTP driver acts as an FTP/SFTP client that connects to a remote file server. It maps the remote file system to gateway addresses, allowing files and directories to be browsed, uploaded, downloaded, created, and deleted directly from the gateway interface. File metadata (size, timestamps, type) is automatically retrieved and exposed as address properties.
The driver is useful for:
- Retrieving files from remote servers (e.g. configuration files, data exports, logs).
- Uploading data generated by other drivers (e.g. CSV exports, reports).
- Monitoring file changes on a remote server with automatic polling.
- Managing files through the gateway interface (create, rename, delete directories and files).
A common use case is to combine the FTP driver with the CSV driver: the CSV driver generates data export files, and the FTP driver uploads them to a remote server for collection or archival.
¶ 1. Getting started
¶ 1.1 Gateway configuration
Create a new gateway and select the FTP driver. Configure the connection to the remote FTP or SFTP server:
- Protocol: select
ftp(port 21) orsftp(port 22, recommended for security). - Host: the IP address or domain name of the remote server.
- Port: the TCP port (default:
22for SFTP,21for FTP). - Username / Password: credentials for the remote server.
- Directory: the initial remote directory to browse (default:
/).
¶ 1.2 Browsing files
Once the gateway is started, it connects to the remote server and lists the contents of the configured base directory. The root directory address %ftp/ is automatically created.
To explore the file system, right-click on a directory and select Read directory to list its contents. Each file and directory discovered is created as a gateway address in a tree structure. You can also select Read directory recursive to list all contents including subdirectories.
¶ 1.3 File operations
All file operations are accessible via the right-click context menu on addresses:
¶ On directories
| Action | Description |
|---|---|
| Read directory | Lists the immediate contents of the directory. |
| Read directory recursive | Lists all contents including all subdirectories. |
| Create file | Creates a new empty file in the directory (prompts for file name). |
| Create directory | Creates a new subdirectory (prompts for directory name). |
| Remove dir. | Removes an empty directory. |
| Remove dir. recursive | Removes a directory and all its contents. |
| Download zip | Downloads the entire directory as a ZIP archive. |
| Upload zip | Uploads and extracts a ZIP archive into the directory. |
| Upload file | Uploads a single file into the directory. |
| Refresh | Refreshes the file metadata (size, timestamps). |
¶ On files
| Action | Description |
|---|---|
| Remove file | Deletes the file from the remote server. |
| Download | Downloads the file to your computer. |
| Upload | Uploads a replacement file (overwrites the existing file). |
| Refresh | Refreshes the file metadata. |
¶ 2. Gateway parameters
| Label | JSON Key | Description |
|---|---|---|
| Name | name | A descriptive name for this FTP gateway instance. |
| Cluster ID | cluster | Cluster identifier (integer). Use 0 for single-gateway setups. |
| Description | description | Optional description for this gateway. |
| Protocol | protocol | Transfer protocol: ftp (standard FTP, port 21) or sftp (SSH File Transfer Protocol, port 22). SFTP is recommended for secure transfers. Default: sftp. |
| Host | host | IP address or domain name of the remote FTP/SFTP server. Default: localhost. |
| Port | port | TCP port of the remote server. Default: 22 (SFTP). Use 21 for standard FTP. |
| Username | user | Username for authentication on the remote server. |
| Password | pwd | Password for authentication on the remote server. |
| Directory | basedir | Initial remote directory to browse. Default: /. All addresses will be relative to this base directory. |
| Connection State | connectionManagement | Connection persistence mode: Keeps it open (maintains a permanent connection to the server) or Opens it when needed (connects only when a file operation is requested, then disconnects after a short idle period). Default: Keeps it open. |
¶ 2.1 Gateway JSON example
SFTP connection:
{
"protocol": "sftp",
"host": "192.168.1.50",
"port": 22,
"user": "datauser",
"pwd": "securePassword",
"basedir": "/home/datauser/exports",
"connectionManagement": "Keeps it open"
}
FTP connection with on-demand connection:
{
"protocol": "ftp",
"host": "ftp.example.com",
"port": 21,
"user": "ftpuser",
"pwd": "ftpPassword",
"basedir": "/",
"connectionManagement": "Opens it when needed"
}
¶ 3. Addresses
¶ 3.1 Address format
FTP addresses use the prefix %ftp followed by the file or directory path:
%ftp/— the root directory (base directory configured on the gateway)%ftp/data— a subdirectory named "data"%ftp/data/report.csv— a file in the "data" subdirectory%ftp/logs/2024/january.log— nested path
The address tree mirrors the remote file system structure. Directories and files are distinguished by their type metadata (d for directory, - for file).
A special address %ftp_logs is automatically created to receive driver log messages (connection events, transfer progress, errors).
¶ 3.2 Address parameters
The following parameters are available on each address. They can be edited directly in the grid columns:
| Column | JSON Key | Description |
|---|---|---|
| Insert | insert | Directories only. Controls automatic discovery of directory contents: manual (contents listed only via right-click), children (automatically lists immediate children), or descendents (automatically lists all nested contents recursively). |
| Delete | delete | Controls what happens when a file is deleted on the remote server: manual (address remains, marked as deleted) or auto (address is automatically removed from the gateway). |
| Del. old files | deleteOldFiles | Duration after which old files are automatically deleted (in milliseconds). Leave empty to disable. |
| Refresh | refresh | Controls automatic metadata refresh: manual (refresh only via right-click) or auto (automatically refreshes file metadata). |
| Polling | polling | Polling interval in milliseconds for automatic refresh. Only effective when Refresh is not set to manual. |
| Log | log | Logging mode: never, on update, always, or a duration in milliseconds. |
¶ 3.3 File metadata
Each address stores file metadata in the json.meta property, visible in the grid columns:
| Column | Description |
|---|---|
| Type | Directory or File. |
| Size | File size in bytes (displayed in human-readable format). |
| AccessTime | Last access timestamp. |
| ModifyTime | Last modification timestamp. |
¶ 3.4 Reading and writing
Reading a file address retrieves a preview of the file content (limited to ~1500 bytes by default). Reading a directory address retrieves the directory listing and updates the child addresses.
Writing to a file address supports several commands via a JSON object with a cmd property:
| Command | Target | Description |
|---|---|---|
ls |
Directory | Lists the directory contents (one level). |
ls -r |
Directory | Lists the directory contents recursively. |
mkdir "name" |
Directory | Creates a subdirectory with the given name. |
touch "name" |
Directory | Creates an empty file with the given name. |
rmdir |
Directory | Removes an empty directory. |
rm -r |
Directory | Removes a directory and all its contents recursively. |
rm |
File | Deletes the file. |
These commands are used internally by the context menu actions but can also be triggered programmatically via routes.
¶ 3.5 File transfer (streaming)
Files can be uploaded and downloaded through the gateway's streaming API:
- Download:
GET /peers/gateways/<id>/streaming?address=%ftp/path/file.txt - Upload:
POST /peers/gateways/<id>/streaming?address=%ftp/path/file.txt
For directories, add &options={"zip":1} to download as a ZIP archive or upload a ZIP to be extracted.
¶ 4. Connection management
¶ 4.1 Keep open mode
When Connection State is set to Keeps it open, the driver maintains a permanent connection to the FTP/SFTP server. This is the fastest mode for frequent file operations but uses a persistent network connection.
If the connection is lost, the driver will automatically attempt to reconnect.
¶ 4.2 On-demand mode
When set to Opens it when needed, the driver connects only when a file operation is requested (directory listing, file read, upload, etc.). After a short idle period (~5 seconds with no pending operations), the connection is closed.
This mode is useful when connecting to servers that limit concurrent connections or when file operations are infrequent.