Skip to content

ftp://

RFC 959 FTP endpoint, backed by github.com/jlaffaye/ftp. Reuses pkg/component/file/ for filtering, sorting, read-locks (changed / rename / markerFile / idempotent*), idempotent dedup, and on-completion strategies — so user-visible semantics stay identical between local and remote endpoints.

For TLS-wrapped FTP, see ftps://. For SSH-based remote file transfer, see sftp:// (distinct wire protocol).

URI shape

ftp://host:21/path?username=...&password=...&passiveMode=true&binary=true

host:port is the FTP server. Port defaults to 21. /path is the starting directory on the remote.

Parameters

The full surface lives in paramDescriptors("ftp") in pkg/component/ftp/describe.go. It composes three groups (common remote, FTP-specific, inherited from file://); the canonical list is the function output. Sections below highlight the ftp-specific knobs.

Connection & auth (common to ftp/ftps/sftp)

Param Type Default Description
username string anonymous (FTP) Login username.
password string anonymous@ (FTP) Login password.
binary boolean false FTP TYPE I (binary).
connectTimeout duration 10s Initial TCP handshake timeout.
soTimeout duration 5m Socket read timeout for long ops (e.g. hanging LIST).
timeout duration — Alias / fallback for soTimeout.
disconnect boolean false Disconnect socket after every operation.
disconnectOnBatchComplete boolean false Disconnect after a producer batch.
maximumReconnectAttempts integer 3 Reconnect attempts on loss.
reconnectDelay duration 1s Delay between reconnect attempts.
throwExceptionOnConnectFailed boolean false Throw at startup vs WARN-and-retry-on-poll.
stepwise boolean true CWD-per-level (default) vs absolute paths.
autoCreate boolean true Auto-create missing directories before writes.
bufferSize integer 131072 I/O buffer size.
sendNoop boolean true Send NOOP before each write to detect dead sockets.
ignoreFileNotFoundOrPermissionError boolean false Silently skip 550/553 scan errors.
fastExistsCheck boolean false Use MDTM/SIZE instead of LIST for existence check.
chmod string — POSIX file perms after upload (octal). Best-effort via SITE CHMOD.

Consumer-side extras

Param Type Default Description
resumeDownload boolean false Byte-offset resume via REST. Requires localWorkDirectory and binary=true.
streamDownload boolean false Hand a *exchange.StreamBody to the route instead of buffering. Requires stepwise=false.
download boolean true Actually transfer the body (false = list-only).
localWorkDirectory string — Local spool dir for resume / safe atomic writes.

FTP-specific

Param Type Default Description
passiveMode boolean true PASV (client opens data conn — NAT-friendly) vs PORT/EPRT.
dataTimeout duration 30s Data-channel read timeout.
separator enum Auto Path separator hint for cross-platform LIST. Auto / UNIX / Windows.

Inherited from file://

The full filter / sort / read-lock / idempotent / scheduler / producer surface from file:// is honoured — see that page for the parameter list. Two defaults differ on remote endpoints:

Param Remote default Local default
readLockCheckInterval 5s 1s
readLockTimeout 20s 10s

readLock=fileLock is rejected on remote endpoints (OS flock has no remote equivalent).

Body shape

Consumer

For each polled file:

  • In body — file bytes (or a *exchange.StreamBody when streamDownload=true).
  • In headers — CamelFileName, CamelFileNameOnly, CamelFileAbsolute, CamelFileLength, CamelFileLastModified, Content-Type (when probeContentType=true).

Producer

Writes the In body to a file under the URI's path. fileName URI param or CamelFileName header chooses the target name.

Examples

Poll an FTP server every 30 seconds, archive after success:

- id: pull-bank-statements
  from: ftp://ftp.bank.example.com:21/outbox?username=user&password=secret&delay=30s&binary=true&move=.done/${file:name}
  steps:
    - to: direct://parse-statement

Upload to FTP with atomic temp-rename:

- to: ftp://uploads.example.com/inbox?username=user&password=secret&tempPrefix=.tmp&binary=true

Stream-download a multi-GB file without buffering:

- from: ftp://ftp.example.com/archive?username=u&password=p&streamDownload=true&stepwise=false&binary=true

Behavior notes

  • NAT-friendly default. passiveMode=true works through most firewalls; switch to PORT mode only when the server requires it.
  • stepwise. Default true issues CWD per path level (compatible with the broadest range of servers). stepwise=false uses absolute paths — required by streamDownload=true.
  • Read-lock strategies. changed is the safest default for pulling files that may still be uploading; rename requires the producer to atomic-rename into place; markerFile waits for a companion file. fileLock is rejected on remote.
  • SITE CHMOD is best-effort: not every server honours it. SFTP has fully-supported chmod.
  • Reconnect & retries. A failed poll WARNs and retries on the next cycle; throwExceptionOnConnectFailed=true flips that to a hard startup error.

Source

  • pkg/component/ftp/ftp.go — Component, Endpoint, multi-scheme registry.
  • pkg/component/ftp/describe.go — exhaustive parameter descriptor list.
  • pkg/component/ftp/{producer,consumer,op_ftp,remote}.go — wire I/O.
  • pkg/component/ftp/{config,lock_remote,checksum}.go — config parsing, read-locks, checksum.

See also