This is an automated email from the ASF dual-hosted git repository.
Croway pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/camel.git
The following commit(s) were added to refs/heads/main by this push:
new 5a5520744459 camel-ftp: docs - what soTimeout and the SFTP keep-alive
bound on a silent server, throwExceptionOnConnectFailed for the health check,
and tempPrefix for broken uploads
5a5520744459 is described below
commit 5a5520744459dd89a4fca00d17c256032c8ca963
Author: croway <[email protected]>
AuthorDate: Sun Nov 15 16:58:40 2026 +0100
camel-ftp: docs - what soTimeout and the SFTP keep-alive bound on a silent
server, throwExceptionOnConnectFailed for the health check, and tempPrefix for
broken uploads
---
.../apache/camel/catalog/docs/ftp-component.adoc | 54 ++++++++++++++++++----
.../apache/camel/catalog/docs/sftp-component.adoc | 26 +++++++++++
.../camel-ftp/src/main/docs/ftp-component.adoc | 54 ++++++++++++++++++----
.../camel-ftp/src/main/docs/sftp-component.adoc | 26 +++++++++++
4 files changed, 144 insertions(+), 16 deletions(-)
diff --git
a/catalog/camel-catalog/src/generated/resources/org/apache/camel/catalog/docs/ftp-component.adoc
b/catalog/camel-catalog/src/generated/resources/org/apache/camel/catalog/docs/ftp-component.adoc
index 23a2866e4912..702cbf71401e 100644
---
a/catalog/camel-catalog/src/generated/resources/org/apache/camel/catalog/docs/ftp-component.adoc
+++
b/catalog/camel-catalog/src/generated/resources/org/apache/camel/catalog/docs/ftp-component.adoc
@@ -322,14 +322,52 @@ Camel sets the following exchange properties
=== About timeouts
-The two sets of libraries (see top) have different API for setting
-timeout. You can use the `connectTimeout` option for both of them to set
-a timeout in millis to establish a network connection. An individual
-`soTimeout` can also be set on the FTP/FTPS, which corresponds to using
-`ftpClient.soTimeout`. Notice SFTP will automatically use
-`connectTimeout` as its `soTimeout`. The `timeout` option only applies
-for FTP/FTPS as the data timeout, which corresponds to the
-`ftpClient.dataTimeout` value. All timeout values are in millis.
+FTP and FTPS use Apache Commons Net and SFTP uses JSch, so the same options
map to different settings of each
+library. All timeout values are in milliseconds.
+
+[cols="1,1,4"]
+|===
+| Option | Default | What it bounds
+
+| `connectTimeout` | 10 seconds | Opening the connection to the server (FTP,
FTPS and SFTP).
+
+| `soTimeout` | 5 minutes | FTP/FTPS: each read on the control connection,
that is the wait for the reply to every
+command (login, `NOOP`, changing directory, listing, the end of each
transfer). It corresponds to `ftpClient.soTimeout`.
+For SFTP, see xref:sftp-component.adoc#_timeouts_and_dead_connections[Timeouts
and dead connections].
+
+| `timeout` | 30 seconds | FTP/FTPS only: each read on the data connection
(downloads and directory listings). It
+corresponds to `ftpClient.dataTimeout`. It does not bound an upload, which
only writes to the data connection.
+|===
+
+==== Noticing a dead or silent server
+
+A server that stops answering without closing the connection (the host is
gone, or a firewall or NAT drops the
+packets) is noticed only when one of these timeouts expires. With the
defaults, every command on such a connection
+waits up to 5 minutes for its reply, for example the `NOOP` that the producer
sends before each upload to check the
+connection (`sendNoop=true`). These durations are how the client libraries
behave, approximately, not guarantees of
+Camel. Lower `soTimeout` to a little more than your server needs to answer a
command:
+
+[source,text]
+----
+ftp://[email protected]/inbox?password=RAW(tiger)&connectTimeout=5000&soTimeout=30000&throwExceptionOnConnectFailed=true
+----
+
+By default, a consumer that cannot connect or log in logs a WARN once and
skips the poll, which counts as a
+successful poll: its xref:manual::health-check.adoc[health check] stays UP for
the whole outage. With
+`throwExceptionOnConnectFailed=true` the failed connection fails the poll, so
the health check reports the consumer
+DOWN and the `pollStrategy` gets the error. This applies to FTP, FTPS and SFTP.
+
+==== Uploads interrupted by a broken connection
+
+When the connection breaks during an upload, the server usually keeps the part
it received under the name of the
+file, and the producer does not remove it: a consumer on the other side can
pick up a truncated file. Upload under a
+temporary name with `tempPrefix` or `tempFileName`. The producer renames the
file to its final name only once the
+upload is complete, and a redelivery replaces the temporary file left by the
failed attempt.
+
+==== Transfer mode
+
+FTP and FTPS transfer files in ASCII mode by default (`binary=false`), which
converts line endings and so corrupts any
+file that is not text. Set `binary=true` for such files.
=== Using Local Work Directory
diff --git
a/catalog/camel-catalog/src/generated/resources/org/apache/camel/catalog/docs/sftp-component.adoc
b/catalog/camel-catalog/src/generated/resources/org/apache/camel/catalog/docs/sftp-component.adoc
index 11169ab95760..5403f09654d1 100644
---
a/catalog/camel-catalog/src/generated/resources/org/apache/camel/catalog/docs/sftp-component.adoc
+++
b/catalog/camel-catalog/src/generated/resources/org/apache/camel/catalog/docs/sftp-component.adoc
@@ -459,6 +459,32 @@ consumer is created, also with `poll` and `pollEnrich`,
with `IllegalArgumentExc
The `readLock` option is not checked when a custom `exclusiveReadLockStrategy`
or `processStrategy`
is set, as it does not apply then.
+=== Timeouts and dead connections
+
+The SFTP endpoint opens the connection with `connectTimeout` (10 seconds) and
uses `soTimeout` (5 minutes) as the read
+timeout of the JSch session. When nothing arrives from the server for
`soTimeout`, JSch sends a keep-alive message and
+waits once more; it drops the session after `serverAliveCountMax` (1 by
default) keep-alive messages without an answer.
+A connection that went silent (the host is gone, or a firewall or NAT drops
the packets) is therefore noticed after
+about twice `soTimeout`: about 10 minutes with the defaults, during which the
consumer or producer using it waits.
+These durations are how JSch behaves, approximately, not guarantees of Camel.
+
+Lower `soTimeout` to notice it sooner; `soTimeout=15000` notices it after
about 30 seconds. As a server that is alive
+answers the keep-alive message, a command that takes longer than `soTimeout`
does not drop the session.
+
+[source,text]
+----
+sftp://[email protected]/inbox?password=RAW(tiger)&connectTimeout=5000&soTimeout=15000&throwExceptionOnConnectFailed=true
+----
+
+When `serverAliveInterval` is set, it replaces `soTimeout` as the read timeout
of the session: the session is then
+dropped after about `serverAliveInterval` × (`serverAliveCountMax` + 1)
without data from the server.
+
+As with FTP, set `throwExceptionOnConnectFailed=true` so that a consumer that
cannot connect fails its poll and its
+health check reports it DOWN, and upload under a temporary name (`tempPrefix`
or `tempFileName`) so that a broken
+upload does not leave a truncated file under its final name. See
+xref:ftp-component.adoc#_noticing_a_dead_or_silent_server[Noticing a dead or
silent server] and
+xref:ftp-component.adoc#_uploads_interrupted_by_a_broken_connection[Uploads
interrupted by a broken connection].
+
=== Checking whether a file exists
The `sftp` component checks whether a remote file exists with a single `lstat`
request, whatever the number of files
diff --git a/components/camel-ftp/src/main/docs/ftp-component.adoc
b/components/camel-ftp/src/main/docs/ftp-component.adoc
index 23a2866e4912..702cbf71401e 100644
--- a/components/camel-ftp/src/main/docs/ftp-component.adoc
+++ b/components/camel-ftp/src/main/docs/ftp-component.adoc
@@ -322,14 +322,52 @@ Camel sets the following exchange properties
=== About timeouts
-The two sets of libraries (see top) have different API for setting
-timeout. You can use the `connectTimeout` option for both of them to set
-a timeout in millis to establish a network connection. An individual
-`soTimeout` can also be set on the FTP/FTPS, which corresponds to using
-`ftpClient.soTimeout`. Notice SFTP will automatically use
-`connectTimeout` as its `soTimeout`. The `timeout` option only applies
-for FTP/FTPS as the data timeout, which corresponds to the
-`ftpClient.dataTimeout` value. All timeout values are in millis.
+FTP and FTPS use Apache Commons Net and SFTP uses JSch, so the same options
map to different settings of each
+library. All timeout values are in milliseconds.
+
+[cols="1,1,4"]
+|===
+| Option | Default | What it bounds
+
+| `connectTimeout` | 10 seconds | Opening the connection to the server (FTP,
FTPS and SFTP).
+
+| `soTimeout` | 5 minutes | FTP/FTPS: each read on the control connection,
that is the wait for the reply to every
+command (login, `NOOP`, changing directory, listing, the end of each
transfer). It corresponds to `ftpClient.soTimeout`.
+For SFTP, see xref:sftp-component.adoc#_timeouts_and_dead_connections[Timeouts
and dead connections].
+
+| `timeout` | 30 seconds | FTP/FTPS only: each read on the data connection
(downloads and directory listings). It
+corresponds to `ftpClient.dataTimeout`. It does not bound an upload, which
only writes to the data connection.
+|===
+
+==== Noticing a dead or silent server
+
+A server that stops answering without closing the connection (the host is
gone, or a firewall or NAT drops the
+packets) is noticed only when one of these timeouts expires. With the
defaults, every command on such a connection
+waits up to 5 minutes for its reply, for example the `NOOP` that the producer
sends before each upload to check the
+connection (`sendNoop=true`). These durations are how the client libraries
behave, approximately, not guarantees of
+Camel. Lower `soTimeout` to a little more than your server needs to answer a
command:
+
+[source,text]
+----
+ftp://[email protected]/inbox?password=RAW(tiger)&connectTimeout=5000&soTimeout=30000&throwExceptionOnConnectFailed=true
+----
+
+By default, a consumer that cannot connect or log in logs a WARN once and
skips the poll, which counts as a
+successful poll: its xref:manual::health-check.adoc[health check] stays UP for
the whole outage. With
+`throwExceptionOnConnectFailed=true` the failed connection fails the poll, so
the health check reports the consumer
+DOWN and the `pollStrategy` gets the error. This applies to FTP, FTPS and SFTP.
+
+==== Uploads interrupted by a broken connection
+
+When the connection breaks during an upload, the server usually keeps the part
it received under the name of the
+file, and the producer does not remove it: a consumer on the other side can
pick up a truncated file. Upload under a
+temporary name with `tempPrefix` or `tempFileName`. The producer renames the
file to its final name only once the
+upload is complete, and a redelivery replaces the temporary file left by the
failed attempt.
+
+==== Transfer mode
+
+FTP and FTPS transfer files in ASCII mode by default (`binary=false`), which
converts line endings and so corrupts any
+file that is not text. Set `binary=true` for such files.
=== Using Local Work Directory
diff --git a/components/camel-ftp/src/main/docs/sftp-component.adoc
b/components/camel-ftp/src/main/docs/sftp-component.adoc
index 11169ab95760..5403f09654d1 100644
--- a/components/camel-ftp/src/main/docs/sftp-component.adoc
+++ b/components/camel-ftp/src/main/docs/sftp-component.adoc
@@ -459,6 +459,32 @@ consumer is created, also with `poll` and `pollEnrich`,
with `IllegalArgumentExc
The `readLock` option is not checked when a custom `exclusiveReadLockStrategy`
or `processStrategy`
is set, as it does not apply then.
+=== Timeouts and dead connections
+
+The SFTP endpoint opens the connection with `connectTimeout` (10 seconds) and
uses `soTimeout` (5 minutes) as the read
+timeout of the JSch session. When nothing arrives from the server for
`soTimeout`, JSch sends a keep-alive message and
+waits once more; it drops the session after `serverAliveCountMax` (1 by
default) keep-alive messages without an answer.
+A connection that went silent (the host is gone, or a firewall or NAT drops
the packets) is therefore noticed after
+about twice `soTimeout`: about 10 minutes with the defaults, during which the
consumer or producer using it waits.
+These durations are how JSch behaves, approximately, not guarantees of Camel.
+
+Lower `soTimeout` to notice it sooner; `soTimeout=15000` notices it after
about 30 seconds. As a server that is alive
+answers the keep-alive message, a command that takes longer than `soTimeout`
does not drop the session.
+
+[source,text]
+----
+sftp://[email protected]/inbox?password=RAW(tiger)&connectTimeout=5000&soTimeout=15000&throwExceptionOnConnectFailed=true
+----
+
+When `serverAliveInterval` is set, it replaces `soTimeout` as the read timeout
of the session: the session is then
+dropped after about `serverAliveInterval` × (`serverAliveCountMax` + 1)
without data from the server.
+
+As with FTP, set `throwExceptionOnConnectFailed=true` so that a consumer that
cannot connect fails its poll and its
+health check reports it DOWN, and upload under a temporary name (`tempPrefix`
or `tempFileName`) so that a broken
+upload does not leave a truncated file under its final name. See
+xref:ftp-component.adoc#_noticing_a_dead_or_silent_server[Noticing a dead or
silent server] and
+xref:ftp-component.adoc#_uploads_interrupted_by_a_broken_connection[Uploads
interrupted by a broken connection].
+
=== Checking whether a file exists
The `sftp` component checks whether a remote file exists with a single `lstat`
request, whatever the number of files