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

Reply via email to