This is an automated email from the ASF dual-hosted git repository.
davsclaus 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 bd562ef39360 CAMEL-23806: Split mina-sftp docs into focused sub-pages
bd562ef39360 is described below
commit bd562ef39360aadf7862f33216f9b2c6c755192c
Author: Claus Ibsen <[email protected]>
AuthorDate: Sun Jun 21 07:39:59 2026 +0200
CAMEL-23806: Split mina-sftp docs into focused sub-pages
Split the large mina-sftp-component.adoc (3,176 lines) into focused
sub-pages: authentication methods, SSH security hardening, and JSch
migration guide. Main page reduced to 602 lines (58% reduction).
Co-Authored-By: Claude Opus 4.6 <[email protected]>
---
.../src/main/docs/mina-sftp-authentication.adoc | 208 ++
.../src/main/docs/mina-sftp-component.adoc | 2935 ++------------------
.../src/main/docs/mina-sftp-migration.adoc | 173 ++
.../src/main/docs/mina-sftp-security.adoc | 346 +++
docs/components/modules/others/nav.adoc | 3 +
.../others/pages/mina-sftp-authentication.adoc | 1 +
.../modules/others/pages/mina-sftp-migration.adoc | 1 +
.../modules/others/pages/mina-sftp-security.adoc | 1 +
8 files changed, 914 insertions(+), 2754 deletions(-)
diff --git
a/components/camel-mina-sftp/src/main/docs/mina-sftp-authentication.adoc
b/components/camel-mina-sftp/src/main/docs/mina-sftp-authentication.adoc
new file mode 100644
index 000000000000..e7c36c9053a8
--- /dev/null
+++ b/components/camel-mina-sftp/src/main/docs/mina-sftp-authentication.adoc
@@ -0,0 +1,208 @@
+= MINA SFTP Authentication
+:tabs-sync-option:
+
+xref:ROOT:mina-sftp-component.adoc[Back to MINA SFTP Component]
+
+The MINA SFTP component supports multiple authentication methods.
+
+== Password Authentication
+
+[source,java]
+----
+from("mina-sftp://admin@host/path?password=secret";)
+ .to("file:local");
+----
+
+== Public Key Authentication
+
+=== Using Private Key File
+
+[source,java]
+----
+from("mina-sftp://user@host/path?privateKeyFile=/home/user/.ssh/id_rsa";)
+ .to("file:local");
+----
+
+=== Using Private Key from Classpath
+
+[source,java]
+----
+from("mina-sftp://user@host/path?privateKeyUri=classpath:keys/id_rsa";)
+ .to("file:local");
+----
+
+=== Using Encrypted Private Key
+
+[source,java]
+----
+from("mina-sftp://user@host/path?privateKeyFile=/path/to/encrypted_key&privateKeyPassphrase=mypassphrase";)
+ .to("file:local");
+----
+
+=== Using Direct KeyPair Object
+
+[source,java]
+----
+KeyPairGenerator keyGen = KeyPairGenerator.getInstance("RSA");
+keyGen.initialize(2048);
+KeyPair keyPair = keyGen.generateKeyPair();
+
+MinaSftpEndpoint endpoint = context.getEndpoint(
+ "mina-sftp://user@host/path";, MinaSftpEndpoint.class);
+MinaSftpConfiguration config = (MinaSftpConfiguration)
endpoint.getConfiguration();
+config.setKeyPair(keyPair);
+----
+
+== Authentication Priority
+
+When both password and public key authentication are configured, the component
tries public key first and falls back to password. This matches the JSch-based
sftp component.
+
+== Preferred Authentication Methods
+
+Customize the authentication order using `preferredAuthentications`:
+
+[source,java]
+----
+from("mina-sftp://user@host/path?password=secret&privateKeyFile=/path/to/key&preferredAuthentications=password,publickey";)
+ .to("file:local");
+----
+
+[cols="2,4"]
+|===
+| Method | Description
+
+| `publickey`
+| Public key or certificate-based authentication
+
+| `password`
+| Password-based authentication
+
+| `keyboard-interactive`
+| Keyboard-interactive authentication (multi-factor scenarios)
+|===
+
+If not specified, the default order from Apache MINA SSHD is used: publickey,
keyboard-interactive, password.
+
+== Public Key Accepted Algorithms
+
+Restrict which public key algorithms are accepted using
`publicKeyAcceptedAlgorithms`:
+
+[source,java]
+----
+from("mina-sftp://user@host/path?privateKeyFile=/path/to/key&publicKeyAcceptedAlgorithms=ssh-ed25519,rsa-sha2-256,rsa-sha2-512";)
+ .to("file:local");
+----
+
+[cols="2,4"]
+|===
+| Algorithm | Description
+
+| `ssh-ed25519`
+| Ed25519 algorithm (modern, recommended)
+
+| `rsa-sha2-256`
+| RSA with SHA-256 signature (recommended)
+
+| `rsa-sha2-512`
+| RSA with SHA-512 signature (recommended)
+
+| `ecdsa-sha2-nistp256`
+| ECDSA with NIST P-256 curve
+
+| `ecdsa-sha2-nistp384`
+| ECDSA with NIST P-384 curve
+
+| `ecdsa-sha2-nistp521`
+| ECDSA with NIST P-521 curve
+
+| `ssh-rsa`
+| Legacy RSA with SHA-1 (avoid if possible)
+
+| `ssh-dss`
+| DSA algorithm (deprecated)
+|===
+
+== Supported Key Formats
+
+The component supports all key formats natively supported by Apache MINA SSHD:
+
+* **PEM formats**: PKCS#1, PKCS#8, OpenSSH format
+* **OpenSSH native format**
+* **Encrypted keys**: Supported (PKCS#8 encrypted requires BouncyCastle)
+
+Supported key algorithms: RSA (all key sizes), ECDSA (P-256, P-384, P-521),
Ed25519, DSA.
+
+== Client Certificate Authentication
+
+The mina-sftp component supports OpenSSH certificate-based authentication,
which provides centralized key management through a Certificate Authority (CA).
This is a MINA SSHD-specific feature not available in the JSch-based sftp
component.
+
+OpenSSH certificates bind a public key to identity information and are signed
by a trusted CA. They provide centralized key revocation, time-limited access
without key rotation, and principal-based authorization.
+
+=== Certificate Options
+
+[cols="2,3,1"]
+|===
+| Option | Description | Priority
+
+| `certBytes`
+| Certificate content as byte array (for programmatic loading from secret
managers)
+| 1 (highest)
+
+| `certUri`
+| URI to certificate file (classpath:, file:, etc.)
+| 2
+
+| `certFile`
+| Path to certificate file on filesystem
+| 3 (lowest)
+|===
+
+The first non-empty option wins. This matches the priority order used for
private key options (`privateKey` > `privateKeyUri` > `privateKeyFile`).
+
+=== Certificate Format Requirements
+
+* Certificates must be in OpenSSH format (as generated by `ssh-keygen -s`)
+* Only USER type certificates are supported (for client authentication)
+* The certificate must correspond to the configured private key
+* Certificate file typically has a `-cert.pub` suffix (e.g., `id_rsa-cert.pub`)
+
+=== Example: Certificate from File
+
+[source,java]
+----
+from("direct:start")
+
.to("mina-sftp://user@host/path?privateKeyFile=/path/to/id_rsa&certFile=/path/to/id_rsa-cert.pub";);
+----
+
+=== Example: Certificate from Classpath
+
+[source,java]
+----
+from("direct:start")
+
.to("mina-sftp://user@host/path?privateKeyUri=classpath:keys/id_rsa&certUri=classpath:keys/id_rsa-cert.pub";);
+----
+
+=== Example: Certificate from Byte Array
+
+[source,java]
+----
+// Load certificate from external secret manager
+byte[] certBytes = secretManager.getCertificate("sftp-cert");
+byte[] keyBytes = secretManager.getPrivateKey("sftp-key");
+
+MinaSftpEndpoint endpoint = context.getEndpoint(
+ "mina-sftp://user@host/path";, MinaSftpEndpoint.class);
+MinaSftpConfiguration config = (MinaSftpConfiguration)
endpoint.getConfiguration();
+config.setCertBytes(certBytes);
+config.setPrivateKey(keyBytes);
+----
+
+=== Certificate Validation
+
+The component validates certificates before use:
+
+* **Type check**: Only USER certificates are accepted (not HOST certificates)
+* **Validity period**: Certificate must be currently valid (not expired, not
before valid-from date)
+* **Private key requirement**: A corresponding private key must be configured
+
+Invalid certificates result in clear error messages indicating the issue.
diff --git a/components/camel-mina-sftp/src/main/docs/mina-sftp-component.adoc
b/components/camel-mina-sftp/src/main/docs/mina-sftp-component.adoc
index 986133326a49..c574abf5eb14 100644
--- a/components/camel-mina-sftp/src/main/docs/mina-sftp-component.adoc
+++ b/components/camel-mina-sftp/src/main/docs/mina-sftp-component.adoc
@@ -36,6 +36,14 @@ include::partial$component-endpoint-headers.adoc[]
// endpoint options: START
// endpoint options: END
+== Sub-Pages
+
+For detailed documentation on specific topics, see:
+
+* xref:others:mina-sftp-authentication.adoc[Authentication] - Password, public
key, certificates, and authentication priority
+* xref:others:mina-sftp-security.adoc[SSH Security] - Host key verification,
ciphers, key exchange protocols, and algorithm recommendations
+* xref:others:mina-sftp-migration.adoc[Migration from JSch] - Migration guide,
behavioral differences, deprecated parameters, and logging
+
== Username Resolution
When no username is specified in the URI, the mina-sftp component follows the
same username resolution order as the JSch-based camel-sftp component, matching
standard SSH client behavior.
@@ -157,11 +165,9 @@ This username resolution behavior is identical to the
JSch-based camel-sftp comp
* Fall back to `~/.ssh/config` if no username in URI
* Fall back to OS username if SSH config exists but has no `User` directive
-== Authentication
-
-The MINA SFTP component supports multiple authentication methods:
+== Examples
-=== Password Authentication
+=== Upload Files
[tabs]
====
@@ -169,8 +175,8 @@ Java::
+
[source,java]
----
-from("mina-sftp://admin@host/path?password=secret";)
- .to("file:local");
+from("file:inbox")
+ .to("mina-sftp://[email protected]/upload?password=secret";);
----
XML::
@@ -178,8 +184,8 @@ XML::
[source,xml]
----
<route>
- <from uri="mina-sftp://admin@host/path?password=secret"/>
- <to uri="file:local"/>
+ <from uri="file:inbox"/>
+ <to uri="mina-sftp://[email protected]/upload?password=secret"/>
</route>
----
@@ -189,18 +195,16 @@ YAML::
----
- route:
from:
- uri: mina-sftp://admin@host/path
- parameters:
- password: secret
+ uri: file:inbox
steps:
- to:
- uri: file:local
+ uri: mina-sftp://[email protected]/upload
+ parameters:
+ password: secret
----
====
-=== Public Key Authentication
-
-==== Using Private Key File
+=== Download Files
[tabs]
====
@@ -208,8 +212,8 @@ Java::
+
[source,java]
----
-from("mina-sftp://user@host/path?privateKeyFile=/home/user/.ssh/id_rsa";)
- .to("file:local");
+from("mina-sftp://[email protected]/download?password=secret&delete=true";)
+ .to("file:outbox");
----
XML::
@@ -217,8 +221,8 @@ XML::
[source,xml]
----
<route>
- <from
uri="mina-sftp://user@host/path?privateKeyFile=/home/user/.ssh/id_rsa"/>
- <to uri="file:local"/>
+ <from
uri="mina-sftp://[email protected]/download?password=secret&delete=true"/>
+ <to uri="file:outbox"/>
</route>
----
@@ -228,16 +232,17 @@ YAML::
----
- route:
from:
- uri: mina-sftp://user@host/path
+ uri: mina-sftp://[email protected]/download
parameters:
- privateKeyFile: /home/user/.ssh/id_rsa
+ password: secret
+ delete: true
steps:
- to:
- uri: file:local
+ uri: file:outbox
----
====
-==== Using Private Key from Classpath
+=== Poll and Move
[tabs]
====
@@ -245,7 +250,7 @@ Java::
+
[source,java]
----
-from("mina-sftp://user@host/path?privateKeyUri=classpath:keys/id_rsa";)
+from("mina-sftp://user@host/inbox?password=secret&move=.done";)
.to("file:local");
----
@@ -254,7 +259,7 @@ XML::
[source,xml]
----
<route>
- <from uri="mina-sftp://user@host/path?privateKeyUri=classpath:keys/id_rsa"/>
+ <from uri="mina-sftp://user@host/inbox?password=secret&move=.done"/>
<to uri="file:local"/>
</route>
----
@@ -265,16 +270,17 @@ YAML::
----
- route:
from:
- uri: mina-sftp://user@host/path
+ uri: mina-sftp://user@host/inbox
parameters:
- privateKeyUri: "classpath:keys/id_rsa"
+ password: secret
+ move: .done
steps:
- to:
uri: file:local
----
====
-==== Using Encrypted Private Key
+=== Filter by Extension
[tabs]
====
@@ -282,8 +288,8 @@ Java::
+
[source,java]
----
-from("mina-sftp://user@host/path?privateKeyFile=/path/to/encrypted_key&privateKeyPassphrase=mypassphrase";)
- .to("file:local");
+from("mina-sftp://user@host/data?password=secret&antInclude=*.csv";)
+ .to("direct:process-csv");
----
XML::
@@ -291,8 +297,8 @@ XML::
[source,xml]
----
<route>
- <from
uri="mina-sftp://user@host/path?privateKeyFile=/path/to/encrypted_key&privateKeyPassphrase=mypassphrase"/>
- <to uri="file:local"/>
+ <from uri="mina-sftp://user@host/data?password=secret&antInclude=*.csv"/>
+ <to uri="direct:process-csv"/>
</route>
----
@@ -302,43 +308,19 @@ YAML::
----
- route:
from:
- uri: mina-sftp://user@host/path
+ uri: mina-sftp://user@host/data
parameters:
- privateKeyFile: /path/to/encrypted_key
- privateKeyPassphrase: mypassphrase
+ password: secret
+ antInclude: "*.csv"
steps:
- to:
- uri: file:local
+ uri: direct:process-csv
----
====
-==== Using Direct KeyPair Object
-
-._Java-only: programmatic `KeyPairGenerator` and endpoint configuration_
-[source,java]
-----
-KeyPairGenerator keyGen = KeyPairGenerator.getInstance("RSA");
-keyGen.initialize(2048);
-KeyPair keyPair = keyGen.generateKeyPair();
-
-MinaSftpEndpoint endpoint = context.getEndpoint(
- "mina-sftp://user@host/path";, MinaSftpEndpoint.class);
-MinaSftpConfiguration config = (MinaSftpConfiguration)
endpoint.getConfiguration();
-config.setKeyPair(keyPair);
-----
-
-=== Authentication Priority
-
-When both password and public key authentication are configured, the component
will:
-
-1. Try public key authentication first
-2. Fall back to password authentication if public key fails
-
-This behavior matches the JSch-based sftp component.
-
-=== Preferred Authentication Methods
+== Error Handling
-You can customize the authentication order using the
`preferredAuthentications` option:
+=== Connection Retry
[tabs]
====
@@ -346,7 +328,7 @@ Java::
+
[source,java]
----
-from("mina-sftp://user@host/path?password=secret&privateKeyFile=/path/to/key&preferredAuthentications=password,publickey";)
+from("mina-sftp://user@host/path?password=secret&maximumReconnectAttempts=5&reconnectDelay=2000";)
.to("file:local");
----
@@ -355,7 +337,7 @@ XML::
[source,xml]
----
<route>
- <from
uri="mina-sftp://user@host/path?password=secret&privateKeyFile=/path/to/key&preferredAuthentications=password,publickey"/>
+ <from
uri="mina-sftp://user@host/path?password=secret&maximumReconnectAttempts=5&reconnectDelay=2000"/>
<to uri="file:local"/>
</route>
----
@@ -369,2424 +351,227 @@ YAML::
uri: mina-sftp://user@host/path
parameters:
password: secret
- privateKeyFile: /path/to/key
- preferredAuthentications: "password,publickey"
+ maximumReconnectAttempts: 5
+ reconnectDelay: 2000
steps:
- to:
uri: file:local
----
====
-==== Available Authentication Methods
+=== Error Messages
-[cols="2,4"]
-|===
-| Method | Description
+The component provides clear error messages for common failure scenarios:
-| `publickey`
-| Public key or certificate-based authentication
+==== Connection Errors
+* **Host unreachable**: `Cannot connect to \{host\}:\{port\}`
+* **Connection timeout**: `Connection timed out after \{timeout\}ms`
-| `password`
-| Password-based authentication
+==== Authentication Errors
+* **Authentication failure**: `Authentication failed: \{reason\}`
+* **Authentication timeout**: `Authentication timed out after \{timeout\}ms`
-| `keyboard-interactive`
-| Keyboard-interactive authentication (multi-factor scenarios)
-|===
+==== Configuration Errors
+* **Invalid chmod**: `Invalid chmod value: '999'. Must be a valid octal number
(e.g., 644, 755)`
+* **Invalid cipher**: `Unknown or unsupported cipher: xxx. Available ciphers:
[aes128-ctr, aes256-ctr, ...]`
+* **Invalid key exchange**: `Unknown or unsupported key exchange protocol:
xxx. Available protocols: [curve25519-sha256, ...]`
+* **Invalid host key algorithm**: `Unknown or unsupported server host key
algorithm: xxx. Available algorithms: [ssh-ed25519, ...]`
+
+==== Host Key Verification Errors
+* **Unknown host**: `Host key verification failed: server 'hostname:port' is
not in the known_hosts file`
+* **Key mismatch**: `Host key verification failed: the host key for
'hostname:port' has changed!`
+* **Expired certificate**: `Host certificate has expired. Valid until <date>,
current time: <date>`
-If `preferredAuthentications` is not specified, the default order from Apache
MINA SSHD is used: publickey, keyboard-interactive, password.
+==== Unsupported Features
+* **Proxy**: `Proxy not supported in mina-sftp, use sftp component`
-=== Public Key Accepted Algorithms
+The error messages include available options where applicable, making it
easier to correct configuration issues.
-You can restrict which public key algorithms are accepted for authentication
using the `publicKeyAcceptedAlgorithms` option:
+== Compression
+
+The mina-sftp component supports SSH data compression to reduce bandwidth
usage for large file transfers over slow or metered connections.
+
+To enable compression, set the `compression` option to a value between 1 and
10:
-[tabs]
-====
-Java::
-+
[source,java]
----
-from("mina-sftp://user@host/path?privateKeyFile=/path/to/key&publicKeyAcceptedAlgorithms=ssh-ed25519,rsa-sha2-256,rsa-sha2-512";)
+from("mina-sftp://user@host/path?password=secret&compression=5";)
.to("file:local");
----
-XML::
-+
-[source,xml]
-----
-<route>
- <from
uri="mina-sftp://user@host/path?privateKeyFile=/path/to/key&publicKeyAcceptedAlgorithms=ssh-ed25519,rsa-sha2-256,rsa-sha2-512"/>
- <to uri="file:local"/>
-</route>
-----
-
-YAML::
-+
-[source,yaml]
-----
-- route:
- from:
- uri: mina-sftp://user@host/path
- parameters:
- privateKeyFile: /path/to/key
- publicKeyAcceptedAlgorithms: "ssh-ed25519,rsa-sha2-256,rsa-sha2-512"
- steps:
- - to:
- uri: file:local
-----
-====
+When compression is enabled, the component configures the following algorithms
in order of preference:
-==== Available Public Key Algorithms
+1. `[email protected]` (OpenSSH delayed compression - preferred for security)
+2. `zlib` (standard zlib compression)
+3. `none` (fallback if server doesn't support compression)
-[cols="2,4"]
-|===
-| Algorithm | Description
+If the server does not support compression, the connection falls back to
uncompressed transfer and logs a WARNING.
-| `ssh-ed25519`
-| Ed25519 algorithm (modern, recommended)
+NOTE: Unlike the JSch-based `sftp` component which requires manually adding a
zlib JAR to the classpath, Apache MINA SSHD includes built-in compression
support. No additional dependencies are needed.
-| `rsa-sha2-256`
-| RSA with SHA-256 signature (recommended)
+By default (`compression=0`), compression is disabled to minimize CPU overhead.
-| `rsa-sha2-512`
-| RSA with SHA-512 signature (recommended)
+== Connection Keep-Alive
-| `ecdsa-sha2-nistp256`
-| ECDSA with NIST P-256 curve
+The component supports SSH keep-alive (heartbeat) functionality to prevent
connections from being dropped during long idle periods and to detect
unresponsive servers.
-| `ecdsa-sha2-nistp384`
-| ECDSA with NIST P-384 curve
+=== Configuration Options
-| `ecdsa-sha2-nistp521`
-| ECDSA with NIST P-521 curve
+[cols="1,1,1,3"]
+|===
+| Option | Default | Type | Description
-| `ssh-rsa`
-| Legacy RSA with SHA-1 (avoid if possible)
+| `serverAliveInterval`
+| `0`
+| int (ms)
+| Interval in milliseconds between keep-alive messages. Set to `0` to disable
(default).
-| `ssh-dss`
-| DSA algorithm (deprecated)
+| `serverAliveCountMax`
+| `1`
+| int
+| Maximum number of consecutive unanswered keep-alive messages before the
connection is terminated.
|===
-==== Example: Modern Algorithms Only
-
-For security-conscious deployments, restrict to modern algorithms only:
+=== Preventing Connection Drops
-[tabs]
-====
-Java::
-+
[source,java]
----
-from("mina-sftp://user@host/path?privateKeyFile=/path/to/key&publicKeyAcceptedAlgorithms=ssh-ed25519,rsa-sha2-256,rsa-sha2-512,ecdsa-sha2-nistp256";)
+// Send keep-alive every 30 seconds, terminate after 3 unanswered (90s max
detection time)
+from("mina-sftp://user@host/path?password=secret&serverAliveInterval=30000&serverAliveCountMax=3";)
.to("file:local");
----
-XML::
-+
-[source,xml]
-----
-<route>
- <from
uri="mina-sftp://user@host/path?privateKeyFile=/path/to/key&publicKeyAcceptedAlgorithms=ssh-ed25519,rsa-sha2-256,rsa-sha2-512,ecdsa-sha2-nistp256"/>
- <to uri="file:local"/>
-</route>
-----
+=== Behavioral Difference: serverAliveCountMax with Zero or Negative Values
-YAML::
-+
-[source,yaml]
-----
-- route:
- from:
- uri: mina-sftp://user@host/path
- parameters:
- privateKeyFile: /path/to/key
- publicKeyAcceptedAlgorithms:
"ssh-ed25519,rsa-sha2-256,rsa-sha2-512,ecdsa-sha2-nistp256"
- steps:
- - to:
- uri: file:local
-----
-====
+IMPORTANT: There is a behavioral difference between `mina-sftp` and `sftp`
components when `serverAliveCountMax` is set to `0` or a negative value.
+
+[cols="1,2,2"]
+|===
+| Value | mina-sftp (MINA SSHD) | sftp (JSch)
-If `publicKeyAcceptedAlgorithms` is not specified, the default list from
Apache MINA SSHD is used.
+| `> 0`
+| Terminate connection after N unanswered heartbeats
+| Terminate connection after N unanswered heartbeats
+
+| `= 0`
+| *Fire-and-forget mode*: heartbeats sent but no reply expected
+| No keep-alive messages are sent
+
+| `< 0`
+| Same as `0` (fire-and-forget mode)
+| No keep-alive messages are sent
+|===
-=== Supported Key Formats
+Always use positive values for `serverAliveCountMax` for consistent behavior
when migrating.
-The component supports all key formats natively supported by Apache MINA SSHD:
+== Local Interface Binding
-* **PEM formats**: PKCS#1, PKCS#8, OpenSSH format
-* **OpenSSH native format**
-* **Encrypted keys**: Supported (PKCS#8 encrypted requires BouncyCastle)
+In multi-homed environments (servers with multiple network interfaces),
specify which local network interface the SFTP connection should use:
-=== Supported Key Algorithms
+[source,java]
+----
+from("mina-sftp://user@host/path?password=secret&bindAddress=192.168.1.100";)
+ .to("file:local");
+----
-* RSA (all key sizes)
-* ECDSA (P-256, P-384, P-521)
-* Ed25519
-* DSA
+=== Bind Address Formats
-=== Client Certificate Authentication
+[cols="2,2,2"]
+|===
+| Format | Example | Description
-The mina-sftp component supports OpenSSH certificate-based authentication,
which provides centralized key management through a Certificate Authority (CA).
This is a MINA SSHD-specific feature not available in the JSch-based sftp
component.
+| IPv4 address
+| `192.168.1.100`
+| Bind to IP, ephemeral port
-OpenSSH certificates bind a public key to identity information and are signed
by a trusted CA. They provide:
+| IPv4 with port
+| `192.168.1.100:5000`
+| Bind to IP and specific port
-* Centralized key revocation
-* Time-limited access without key rotation
-* Principal-based authorization
+| IPv6 address
+| `::1`
+| Bind to IPv6, ephemeral port
-==== Certificate Options
+| IPv6 with port
+| `[::1]:5000`
+| Bind to IPv6 and port (bracketed notation)
-[cols="2,3,1"]
+| Hostname
+| `localhost`
+| Bind to hostname, ephemeral port
|===
-| Option | Description | Priority
-| `certBytes`
-| Certificate content as byte array (for programmatic loading from secret
managers)
-| 1 (highest)
+NOTE: Port specification is a mina-sftp enhancement not available in the
JSch-based `sftp` component.
-| `certUri`
-| URI to certificate file (classpath:, file:, etc.)
-| 2
+When `bindAddress` is not specified, the operating system's routing table
determines which local interface is used.
-| `certFile`
-| Path to certificate file on filesystem
-| 3 (lowest)
-|===
+== SFTP Buffer Size Configuration
+
+Configure buffer sizes for SFTP read and write operations to optimize file
transfer performance:
+
+[source,java]
+----
+// Configure 64KB read buffer and 32KB write buffer
+from("mina-sftp://user@host/path?password=secret&readBufferSize=65536&writeBufferSize=32768";)
+ .to("file:local");
+----
-==== Option Priority Order
+[cols="2,1,3"]
+|===
+| Option | Default | Description
-When multiple certificate options are configured, the component uses this
priority order:
+| `readBufferSize`
+| MINA default
+| Buffer size in bytes for reading data from SFTP connections
-1. `certBytes` - checked first (highest priority)
-2. `certUri` - checked second
-3. `certFile` - checked last (lowest priority)
+| `writeBufferSize`
+| MINA default
+| Buffer size in bytes for writing data to SFTP connections
+|===
-The first non-empty option wins. This matches the priority order used for
private key options (`privateKey` > `privateKeyUri` > `privateKeyFile`).
+IMPORTANT: The maximum recommended buffer size is `126976` bytes (~124KB).
Larger values may cause data corruption in Apache MINA SSHD.
-==== Certificate Format Requirements
+The deprecated `bulkRequests` parameter is still accepted for backward
compatibility but new configurations should use `readBufferSize` and
`writeBufferSize` directly.
-* Certificates must be in OpenSSH format (as generated by `ssh-keygen -s`)
-* Only USER type certificates are supported (for client authentication)
-* The certificate must correspond to the configured private key
-* Certificate file typically has a `-cert.pub` suffix (e.g., `id_rsa-cert.pub`)
+== File and Directory Permissions (chmod)
-==== Example: Certificate from File
+Set POSIX file permissions on uploaded files and created directories:
-[tabs]
-====
-Java::
-+
[source,java]
----
-from("direct:start")
-
.to("mina-sftp://user@host/path?privateKeyFile=/path/to/id_rsa&certFile=/path/to/id_rsa-cert.pub";);
+// Set file permissions to rw-r--r-- (644) and directory permissions to
rwxr-xr-x (755)
+from("file:/data/outbound")
+
.to("mina-sftp://user@host/uploads?password=secret&chmod=644&chmodDirectory=755";);
----
-XML::
-+
-[source,xml]
-----
-<route>
- <from uri="direct:start"/>
- <to
uri="mina-sftp://user@host/path?privateKeyFile=/path/to/id_rsa&certFile=/path/to/id_rsa-cert.pub"/>
-</route>
-----
-
-YAML::
-+
-[source,yaml]
-----
-- route:
- from:
- uri: direct:start
- steps:
- - to:
- uri: mina-sftp://user@host/path
- parameters:
- privateKeyFile: /path/to/id_rsa
- certFile: /path/to/id_rsa-cert.pub
-----
-====
-
-==== Example: Certificate from Classpath
-
-[tabs]
-====
-Java::
-+
-[source,java]
-----
-from("direct:start")
-
.to("mina-sftp://user@host/path?privateKeyUri=classpath:keys/id_rsa&certUri=classpath:keys/id_rsa-cert.pub";);
-----
-
-XML::
-+
-[source,xml]
-----
-<route>
- <from uri="direct:start"/>
- <to
uri="mina-sftp://user@host/path?privateKeyUri=classpath:keys/id_rsa&certUri=classpath:keys/id_rsa-cert.pub"/>
-</route>
-----
-
-YAML::
-+
-[source,yaml]
-----
-- route:
- from:
- uri: direct:start
- steps:
- - to:
- uri: mina-sftp://user@host/path
- parameters:
- privateKeyUri: "classpath:keys/id_rsa"
- certUri: "classpath:keys/id_rsa-cert.pub"
-----
-====
-
-==== Example: Certificate from Byte Array
-
-._Java-only: programmatic endpoint configuration with byte arrays from secret
manager_
-[source,java]
-----
-// Load certificate from external secret manager
-byte[] certBytes = secretManager.getCertificate("sftp-cert");
-byte[] keyBytes = secretManager.getPrivateKey("sftp-key");
-
-MinaSftpEndpoint endpoint = context.getEndpoint(
- "mina-sftp://user@host/path";, MinaSftpEndpoint.class);
-MinaSftpConfiguration config = (MinaSftpConfiguration)
endpoint.getConfiguration();
-config.setCertBytes(certBytes);
-config.setPrivateKey(keyBytes);
-----
-
-==== Certificate Validation
-
-The component validates certificates before use:
-
-* **Type check**: Only USER certificates are accepted (not HOST certificates)
-* **Validity period**: Certificate must be currently valid (not expired, not
before valid-from date)
-* **Private key requirement**: A corresponding private key must be configured
-
-Invalid certificates result in clear error messages indicating the issue.
-
-== Examples
-
-=== Upload Files
-
-[tabs]
-====
-Java::
-+
-[source,java]
-----
-from("file:inbox")
- .to("mina-sftp://[email protected]/upload?password=secret";);
-----
-
-XML::
-+
-[source,xml]
-----
-<route>
- <from uri="file:inbox"/>
- <to uri="mina-sftp://[email protected]/upload?password=secret"/>
-</route>
-----
-
-YAML::
-+
-[source,yaml]
-----
-- route:
- from:
- uri: file:inbox
- steps:
- - to:
- uri: mina-sftp://[email protected]/upload
- parameters:
- password: secret
-----
-====
-
-=== Download Files
-
-[tabs]
-====
-Java::
-+
-[source,java]
-----
-from("mina-sftp://[email protected]/download?password=secret&delete=true";)
- .to("file:outbox");
-----
-
-XML::
-+
-[source,xml]
-----
-<route>
- <from
uri="mina-sftp://[email protected]/download?password=secret&delete=true"/>
- <to uri="file:outbox"/>
-</route>
-----
-
-YAML::
-+
-[source,yaml]
-----
-- route:
- from:
- uri: mina-sftp://[email protected]/download
- parameters:
- password: secret
- delete: true
- steps:
- - to:
- uri: file:outbox
-----
-====
-
-=== Poll and Move
-
-[tabs]
-====
-Java::
-+
-[source,java]
-----
-from("mina-sftp://user@host/inbox?password=secret&move=.done";)
- .to("file:local");
-----
-
-XML::
-+
-[source,xml]
-----
-<route>
- <from uri="mina-sftp://user@host/inbox?password=secret&move=.done"/>
- <to uri="file:local"/>
-</route>
-----
-
-YAML::
-+
-[source,yaml]
-----
-- route:
- from:
- uri: mina-sftp://user@host/inbox
- parameters:
- password: secret
- move: .done
- steps:
- - to:
- uri: file:local
-----
-====
-
-=== Filter by Extension
-
-[tabs]
-====
-Java::
-+
-[source,java]
-----
-from("mina-sftp://user@host/data?password=secret&antInclude=*.csv";)
- .to("direct:process-csv");
-----
-
-XML::
-+
-[source,xml]
-----
-<route>
- <from uri="mina-sftp://user@host/data?password=secret&antInclude=*.csv"/>
- <to uri="direct:process-csv"/>
-</route>
-----
-
-YAML::
-+
-[source,yaml]
-----
-- route:
- from:
- uri: mina-sftp://user@host/data
- parameters:
- password: secret
- antInclude: "*.csv"
- steps:
- - to:
- uri: direct:process-csv
-----
-====
-
-== Migration from JSch SFTP
-
-Users migrating from the JSch-based `sftp` component can switch by changing
only the URI scheme:
-
-.Before (JSch)
-
-[tabs]
-====
-Java::
-+
-[source,java]
-----
-from("sftp://user@host/path?password=secret";)
- .to("file:local");
-----
-
-XML::
-+
-[source,xml]
-----
-<route>
- <from uri="sftp://user@host/path?password=secret"/>
- <to uri="file:local"/>
-</route>
-----
-
-YAML::
-+
-[source,yaml]
-----
-- route:
- from:
- uri: sftp://user@host/path
- parameters:
- password: secret
- steps:
- - to:
- uri: file:local
-----
-====
-
-.After (MINA SSHD)
-
-[tabs]
-====
-Java::
-+
-[source,java]
-----
-from("mina-sftp://user@host/path?password=secret";)
- .to("file:local");
-----
-
-XML::
-+
-[source,xml]
-----
-<route>
- <from uri="mina-sftp://user@host/path?password=secret"/>
- <to uri="file:local"/>
-</route>
-----
-
-YAML::
-+
-[source,yaml]
-----
-- route:
- from:
- uri: mina-sftp://user@host/path
- parameters:
- password: secret
- steps:
- - to:
- uri: file:local
-----
-====
-
-All standard configuration options remain the same for supported features.
-
-=== Features Not Supported
-
-The following features from the JSch component are *not* supported by
mina-sftp:
-
-* **Proxy support**: HTTP proxy, SOCKS4, SOCKS5 proxy connections
-* **GSSAPI/Kerberos authentication**
-
-If you require these features, continue using the JSch-based `sftp` component.
-
-If you configure an unsupported feature, the component will throw a clear
error message indicating the feature is not supported.
-
-=== Behavioral Differences
-
-While the mina-sftp component aims for compatibility with the sftp component,
there are some behavioral differences due to the underlying SSH libraries.
-
-==== Comparison Table
-
-[cols="2,3,3"]
-|===
-| Feature | mina-sftp (Apache MINA SSHD) | sftp (JSch)
-
-| **License**
-| Apache License 2.0
-| BSD-style license
-
-| **Compression**
-| Built-in support, no extra JARs needed
-| Requires manually adding jsch-zlib JAR to classpath
-
-| **Ciphers**
-| Modern algorithms (ChaCha20-Poly1305, AES-GCM); validates cipher names
before connection
-| Limited algorithms; errors at connection time for invalid ciphers
-
-| **Key Exchange Protocols**
-| Modern algorithms (Curve25519, ECDH, post-quantum ready); validates protocol
names before connection
-| Limited algorithms; uses JSch.setConfig("kex", ...)
-
-| **Server Host Keys**
-| Modern algorithms (Ed25519, RSA-SHA2, ECDSA); validates algorithm names
before connection
-| Limited algorithms; uses session.setConfig("server_host_key", ...)
-
-| **Known Hosts Port Matching**
-| Strict OpenSSH semantics: `hostname` matches port 22 only; `[hostname]:port`
required for non-standard ports
-| Lenient: `hostname` matches any port
-
-| **serverAliveCountMax=0**
-| Fire-and-forget mode: heartbeats sent with `wantReply=false`, connection
never terminated
-| Keep-alive disabled, no heartbeats sent
-
-| **serverAliveCountMax < 0**
-| Same as `0` (fire-and-forget mode)
-| Keep-alive disabled
-
-| **Host Key Verification**
-| Apache MINA SSHD ServerKeyVerifier with certificate support
-| JSch-specific HostKeyRepository
-
-| **Algorithm Support**
-| Modern algorithms including Ed25519, ECDSA (all curves), ChaCha20-Poly1305
-| Limited algorithm support, requires workarounds for modern algorithms
-
-| **Proxy Support**
-| Not supported
-| HTTP, SOCKS4, SOCKS5 proxy support
-
-| **GSSAPI/Kerberos**
-| Not supported
-| Supported
-
-| **Logging Configuration**
-| Uses SLF4J natively; `loggingLevel` and `serverMessageLoggingLevel`
parameters not supported - use standard logging framework configuration instead
-| Requires `loggingLevel` parameter to bridge JSch internal logging to SLF4J;
`serverMessageLoggingLevel` for server messages
-|===
-
-==== Known Hosts Port Matching
-
-The mina-sftp component follows **strict OpenSSH semantics** for known_hosts
port matching, while the sftp component is more lenient.
-
-**OpenSSH known_hosts format:**
-
-* `hostname` - matches the hostname on **port 22 only**
-* `[hostname]:port` - matches the hostname on the specified non-standard port
-
-**Example:** If your known_hosts file contains:
-[source]
-----
-myserver.example.com ssh-rsa AAAAB3NzaC1yc2E...
-----
-
-* **sftp component**: This entry matches connections to `myserver.example.com`
on **any port**
-* **mina-sftp component**: This entry matches connections to
`myserver.example.com` on **port 22 only**
-
-**For non-standard ports with mina-sftp**, you must use the bracketed format:
-[source]
-----
-[myserver.example.com]:2222 ssh-rsa AAAAB3NzaC1yc2E...
-----
-
-This difference is important when migrating from the sftp component and using
`strictHostKeyChecking=yes` with servers running on non-standard ports.
-
-=== Migration Checklist
-
-When migrating from `sftp` to `mina-sftp`, verify the following:
-
-. **URI Scheme**: Change `sftp://` to `mina-sftp://`
-. **Proxy Usage**: If using proxy (HTTP, SOCKS4, SOCKS5), stay with `sftp` -
proxy is not supported in mina-sftp
-. **Kerberos/GSSAPI**: If using GSSAPI authentication, stay with `sftp`
-. **Known Hosts on Non-Standard Ports**: Update known_hosts entries to use
`[hostname]:port` format for non-standard ports
-. **serverAliveCountMax**: If using `serverAliveCountMax=0`, note the
behavioral difference (fire-and-forget vs disabled)
-. **Compression**: Remove any manual zlib JAR additions - mina-sftp has
built-in compression support
-. **Deprecated Parameters**: Remove JSch-specific parameters (`loggingLevel`,
`serverMessageLoggingLevel`, `existDirCheckUsingLs`) - they are accepted but
log warnings (see <<Deprecated JSch Parameters (Migration from sftp)>>)
-. **Logging Configuration**: Configure logging via log4j/logback instead of
URI parameters (see <<Logging Configuration>>)
-. **Test Authentication**: Verify public key and password authentication work
correctly
-. **Test Host Key Verification**: If using `strictHostKeyChecking=yes`, verify
known_hosts entries match
-
-== Error Handling
-
-=== Connection Retry
-
-[tabs]
-====
-Java::
-+
-[source,java]
-----
-from("mina-sftp://user@host/path?password=secret&maximumReconnectAttempts=5&reconnectDelay=2000";)
- .to("file:local");
-----
-
-XML::
-+
-[source,xml]
-----
-<route>
- <from
uri="mina-sftp://user@host/path?password=secret&maximumReconnectAttempts=5&reconnectDelay=2000"/>
- <to uri="file:local"/>
-</route>
-----
-
-YAML::
-+
-[source,yaml]
-----
-- route:
- from:
- uri: mina-sftp://user@host/path
- parameters:
- password: secret
- maximumReconnectAttempts: 5
- reconnectDelay: 2000
- steps:
- - to:
- uri: file:local
-----
-====
-
-=== Error Messages
-
-The component provides clear error messages for common failure scenarios:
-
-==== Connection Errors
-* **Host unreachable**: `Cannot connect to \{host\}:\{port\}`
-* **Connection timeout**: `Connection timed out after \{timeout\}ms`
-
-==== Authentication Errors
-* **Authentication failure**: `Authentication failed: \{reason\}`
-* **Authentication timeout**: `Authentication timed out after \{timeout\}ms`
-
-==== Configuration Errors
-* **Invalid chmod**: `Invalid chmod value: '999'. Must be a valid octal number
(e.g., 644, 755)`
-* **Invalid cipher**: `Unknown or unsupported cipher: xxx. Available ciphers:
[aes128-ctr, aes256-ctr, ...]`
-* **Invalid key exchange**: `Unknown or unsupported key exchange protocol:
xxx. Available protocols: [curve25519-sha256, ...]`
-* **Invalid host key algorithm**: `Unknown or unsupported server host key
algorithm: xxx. Available algorithms: [ssh-ed25519, ...]`
-
-==== Host Key Verification Errors
-* **Unknown host**: `Host key verification failed: server 'hostname:port' is
not in the known_hosts file`
-* **Key mismatch**: `Host key verification failed: the host key for
'hostname:port' has changed!`
-* **Expired certificate**: `Host certificate has expired. Valid until <date>,
current time: <date>`
-
-==== Unsupported Features
-* **Proxy**: `Proxy not supported in mina-sftp, use sftp component`
-
-The error messages include available options where applicable, making it
easier to correct configuration issues.
-
-== Compression
-
-The mina-sftp component supports SSH data compression to reduce bandwidth
usage for large file transfers over slow or metered connections.
-
-=== Enabling Compression
-
-To enable compression, set the `compression` option to a value between 1 and
10:
-
-[tabs]
-====
-Java::
-+
-[source,java]
-----
-from("mina-sftp://user@host/path?password=secret&compression=5";)
- .to("file:local");
-----
-
-XML::
-+
-[source,xml]
-----
-<route>
- <from uri="mina-sftp://user@host/path?password=secret&compression=5"/>
- <to uri="file:local"/>
-</route>
-----
-
-YAML::
-+
-[source,yaml]
-----
-- route:
- from:
- uri: mina-sftp://user@host/path
- parameters:
- password: secret
- compression: 5
- steps:
- - to:
- uri: file:local
-----
-====
-
-The compression level is advisory; the actual compression behavior depends on
the SSH library's implementation. When compression is enabled, the component
configures the following algorithms in order of preference:
-
-1. `[email protected]` (OpenSSH delayed compression - preferred for security)
-2. `zlib` (standard zlib compression)
-3. `none` (fallback if server doesn't support compression)
-
-=== No Additional Dependencies Required
-
-NOTE: Unlike the JSch-based `sftp` component which requires manually adding a
zlib JAR to the classpath, Apache MINA SSHD includes built-in compression
support. No additional dependencies are needed.
-
-=== Compression Fallback Behavior
-
-If compression is enabled but the server does not support any compression
algorithms, the connection automatically falls back to uncompressed transfer
and logs a WARNING message:
-
-[source]
-----
-WARN Compression was requested (level=5) but server does not support
compression. Falling back to uncompressed transfer.
-----
-
-This allows the connection to proceed without manual intervention while
alerting administrators to the configuration mismatch.
-
-=== Default Behavior
-
-By default (`compression=0`), compression is disabled to minimize CPU overhead
and maintain backward compatibility. Enable compression only when bandwidth
savings outweigh the CPU cost of compression/decompression.
-
-=== Compression Algorithm Details
-
-When compression is enabled, the component offers the following algorithms
during SSH negotiation:
-
-[cols="1,3"]
-|===
-| Algorithm | Description
-
-| `[email protected]`
-| OpenSSH "delayed" compression. Compression starts only after authentication
completes. This is preferred for security as it prevents potential
compression-related attacks during the authentication phase.
-
-| `zlib`
-| Standard zlib compression. Compression is active immediately, including
during authentication. Use only if the server doesn't support delayed
compression.
-
-| `none`
-| No compression (fallback). Used when the server doesn't support any
compression.
-|===
-
-The algorithm negotiation follows SSH protocol standards - the first mutually
supported algorithm from the client's preference list is selected.
-
-== Cipher Configuration
-
-The mina-sftp component allows you to specify which SSH cipher algorithms to
use for encrypted data transfer.
-
-=== Configuring Ciphers
-
-To specify a custom list of ciphers, use the `ciphers` option with a
comma-separated list of cipher names:
-
-[tabs]
-====
-Java::
-+
-[source,java]
-----
-from("mina-sftp://user@host/path?password=secret&ciphers=aes256-ctr,[email protected]";)
- .to("file:local");
-----
-
-XML::
-+
-[source,xml]
-----
-<route>
- <from
uri="mina-sftp://user@host/path?password=secret&ciphers=aes256-ctr,[email protected]"/>
- <to uri="file:local"/>
-</route>
-----
-
-YAML::
-+
-[source,yaml]
-----
-- route:
- from:
- uri: mina-sftp://user@host/path
- parameters:
- password: secret
- ciphers: "aes256-ctr,[email protected]"
- steps:
- - to:
- uri: file:local
-----
-====
-
-Ciphers are offered to the server in the order specified. The first mutually
supported cipher will be used.
-
-=== Available Ciphers
-
-The following ciphers are supported by Apache MINA SSHD:
-
-[cols="2,1,1,3"]
-|===
-| Cipher Name | Algorithm | Mode | Notes
-
-| `aes128-ctr`
-| AES-128
-| CTR
-| Standard, widely supported
-
-| `aes192-ctr`
-| AES-192
-| CTR
-| Standard
-
-| `aes256-ctr`
-| AES-256
-| CTR
-| Recommended for high security
-
-| `[email protected]`
-| AES-128
-| GCM
-| Authenticated encryption
-
-| `[email protected]`
-| AES-256
-| GCM
-| Recommended - authenticated encryption
-
-| `[email protected]`
-| ChaCha20
-| AEAD
-| Modern, fast on CPUs without AES-NI
-
-| `aes128-cbc`
-| AES-128
-| CBC
-| Legacy, avoid if possible
-
-| `aes192-cbc`
-| AES-192
-| CBC
-| Legacy
-
-| `aes256-cbc`
-| AES-256
-| CBC
-| Legacy, avoid if possible
-
-| `3des-cbc`
-| Triple DES
-| CBC
-| Deprecated, use only for compatibility
-
-| `blowfish-cbc`
-| Blowfish
-| CBC
-| Legacy
-|===
-
-=== Cipher Security Recommendations
-
-For security-hardened environments, use only modern authenticated encryption
modes:
-
-[tabs]
-====
-Java::
-+
-[source,java]
-----
-// Recommended secure configuration
-from("mina-sftp://user@host/path?password=secret&[email protected],[email protected],aes256-ctr";)
- .to("file:local");
-----
-
-XML::
-+
-[source,xml]
-----
-<!-- Recommended secure configuration -->
-<route>
- <from
uri="mina-sftp://user@host/path?password=secret&[email protected],[email protected],aes256-ctr"/>
- <to uri="file:local"/>
-</route>
-----
-
-YAML::
-+
-[source,yaml]
-----
-# Recommended secure configuration
-- route:
- from:
- uri: mina-sftp://user@host/path
- parameters:
- password: secret
- ciphers:
"[email protected],[email protected],aes256-ctr"
- steps:
- - to:
- uri: file:local
-----
-====
-
-=== Default Cipher Behavior
-
-If `ciphers` is not specified, Apache MINA SSHD's default cipher list is used,
which includes a secure selection of modern algorithms.
-
-NOTE: Unlike the JSch-based `sftp` component, Apache MINA SSHD supports modern
algorithms like ChaCha20-Poly1305 and AES-GCM that are not available in JSch.
Additionally, invalid cipher names are validated before attempting to connect,
providing clearer error messages.
-
-== Key Exchange Protocol Configuration
-
-The mina-sftp component allows you to specify which SSH key exchange
algorithms to use for deriving the shared session key.
-
-=== Configuring Key Exchange Protocols
-
-To specify a custom list of key exchange protocols, use the
`keyExchangeProtocols` option with a comma-separated list:
-
-[tabs]
-====
-Java::
-+
-[source,java]
-----
-from("mina-sftp://user@host/path?password=secret&keyExchangeProtocols=curve25519-sha256,ecdh-sha2-nistp256";)
- .to("file:local");
-----
-
-XML::
-+
-[source,xml]
-----
-<route>
- <from
uri="mina-sftp://user@host/path?password=secret&keyExchangeProtocols=curve25519-sha256,ecdh-sha2-nistp256"/>
- <to uri="file:local"/>
-</route>
-----
-
-YAML::
-+
-[source,yaml]
-----
-- route:
- from:
- uri: mina-sftp://user@host/path
- parameters:
- password: secret
- keyExchangeProtocols: "curve25519-sha256,ecdh-sha2-nistp256"
- steps:
- - to:
- uri: file:local
-----
-====
-
-Key exchange protocols are offered to the server in the order specified. The
first mutually supported algorithm will be used.
-
-=== Available Key Exchange Protocols
-
-The following key exchange protocols are supported by Apache MINA SSHD:
-
-[cols="2,3,1"]
-|===
-| Protocol Name | Description | Recommended
-
-| `curve25519-sha256`
-| Modern Curve25519 elliptic curve with SHA-256
-| Yes
-
-| `[email protected]`
-| Curve25519 (libssh.org variant)
-| Yes
-
-| `curve448-sha512`
-| Curve448 with SHA-512 (stronger)
-| Yes
-
-| `ecdh-sha2-nistp256`
-| ECDH with NIST P-256 curve
-| Yes
-
-| `ecdh-sha2-nistp384`
-| ECDH with NIST P-384 curve
-| Yes
-
-| `ecdh-sha2-nistp521`
-| ECDH with NIST P-521 curve
-| Yes
-
-| `diffie-hellman-group14-sha256`
-| DH Group14 (2048-bit) with SHA-256
-| Yes
-
-| `diffie-hellman-group15-sha512`
-| DH Group15 (3072-bit) with SHA-512
-| Yes
-
-| `diffie-hellman-group16-sha512`
-| DH Group16 (4096-bit) with SHA-512
-| Yes
-
-| `diffie-hellman-group17-sha512`
-| DH Group17 (6144-bit) with SHA-512
-| Yes
-
-| `diffie-hellman-group18-sha512`
-| DH Group18 (8192-bit) with SHA-512
-| Yes
-
-| `diffie-hellman-group-exchange-sha256`
-| DH Group Exchange with SHA-256
-| Yes
-
-| `diffie-hellman-group14-sha1`
-| DH Group14 with SHA-1
-| Deprecated
-
-| `diffie-hellman-group1-sha1`
-| DH Group1 (1024-bit) with SHA-1
-| Deprecated
-
-| `diffie-hellman-group-exchange-sha1`
-| DH Group Exchange with SHA-1
-| Deprecated
-|===
-
-=== Default Key Exchange Behavior
-
-If `keyExchangeProtocols` is not specified, Apache MINA SSHD's default list is
used, which prioritizes modern, secure algorithms.
-
-== Server Host Key Configuration
-
-The mina-sftp component allows you to specify which server host key algorithms
are accepted for verifying the identity of the SSH server.
-
-=== Configuring Server Host Keys
-
-To specify a custom list of server host key algorithms, use the
`serverHostKeys` option with a comma-separated list:
-
-[tabs]
-====
-Java::
-+
-[source,java]
-----
-from("mina-sftp://user@host/path?password=secret&serverHostKeys=ssh-ed25519,rsa-sha2-512";)
- .to("file:local");
-----
-
-XML::
-+
-[source,xml]
-----
-<route>
- <from
uri="mina-sftp://user@host/path?password=secret&serverHostKeys=ssh-ed25519,rsa-sha2-512"/>
- <to uri="file:local"/>
-</route>
-----
-
-YAML::
-+
-[source,yaml]
-----
-- route:
- from:
- uri: mina-sftp://user@host/path
- parameters:
- password: secret
- serverHostKeys: "ssh-ed25519,rsa-sha2-512"
- steps:
- - to:
- uri: file:local
-----
-====
-
-Server host key algorithms are offered to the server in the order specified.
The first mutually supported algorithm will be used for server authentication.
-
-=== Available Server Host Key Algorithms
-
-The following server host key algorithms are supported by Apache MINA SSHD:
-
-[cols="2,3,1"]
-|===
-| Algorithm Name | Description | Recommended
-
-| `ssh-ed25519`
-| EdDSA Ed25519 (modern, fast)
-| Yes
-
-| `rsa-sha2-512`
-| RSA with SHA-512 (2048+ bit keys)
-| Yes
-
-| `rsa-sha2-256`
-| RSA with SHA-256 (2048+ bit keys)
-| Yes
-
-| `ecdsa-sha2-nistp256`
-| ECDSA with NIST P-256 curve
-| Yes
-
-| `ecdsa-sha2-nistp384`
-| ECDSA with NIST P-384 curve
-| Yes
-
-| `ecdsa-sha2-nistp521`
-| ECDSA with NIST P-521 curve
-| Yes
-
-| `ssh-rsa`
-| RSA with SHA-1
-| Deprecated
-
-| `ssh-dss`
-| DSA
-| Deprecated
-|===
-
-=== Certificate Variants
-
-Apache MINA SSHD also supports OpenSSH certificate-based host key verification:
-
-* `[email protected]`
-* `[email protected]`
-* `[email protected]`
-* `[email protected]`
-* `[email protected]`
-* `[email protected]`
-
-=== Default Server Host Key Behavior
-
-If `serverHostKeys` is not specified, Apache MINA SSHD's default list is used,
which includes all supported algorithms with modern ones prioritized.
-
-== Algorithm Security Recommendations
-
-For security-hardened environments, configure only modern, recommended
algorithms:
-
-=== Recommended Configuration
-
-[tabs]
-====
-Java::
-+
-[source,java]
-----
-from("mina-sftp://user@host/path?password=secret&keyExchangeProtocols=curve25519-sha256,ecdh-sha2-nistp256,diffie-hellman-group16-sha512&serverHostKeys=ssh-ed25519,rsa-sha2-512,ecdsa-sha2-nistp256&[email protected],[email protected],aes256-ctr";)
- .to("file:local");
-----
-
-XML::
-+
-[source,xml]
-----
-<route>
- <from
uri="mina-sftp://user@host/path?password=secret&keyExchangeProtocols=curve25519-sha256,ecdh-sha2-nistp256,diffie-hellman-group16-sha512&serverHostKeys=ssh-ed25519,rsa-sha2-512,ecdsa-sha2-nistp256&[email protected],[email protected],aes256-ctr"/>
- <to uri="file:local"/>
-</route>
-----
-
-YAML::
-+
-[source,yaml]
-----
-- route:
- from:
- uri: mina-sftp://user@host/path
- parameters:
- password: secret
- keyExchangeProtocols:
"curve25519-sha256,ecdh-sha2-nistp256,diffie-hellman-group16-sha512"
- serverHostKeys: "ssh-ed25519,rsa-sha2-512,ecdsa-sha2-nistp256"
- ciphers:
"[email protected],[email protected],aes256-ctr"
- steps:
- - to:
- uri: file:local
-----
-====
-
-=== Algorithms to Avoid
-
-The following algorithms are deprecated and should be avoided for new
deployments:
-
-[cols="1,2"]
-|===
-| Algorithm | Reason
-
-| `diffie-hellman-group1-sha1`
-| 1024-bit DH is too weak; SHA-1 is deprecated
-
-| `diffie-hellman-group14-sha1`
-| SHA-1 is deprecated
-
-| `diffie-hellman-group-exchange-sha1`
-| SHA-1 is deprecated
-
-| `ssh-rsa`
-| Uses SHA-1 for signatures (deprecated)
-
-| `ssh-dss`
-| DSA is deprecated
-|===
-
-=== Compliance Considerations
-
-For environments requiring compliance with security standards (e.g., FIPS,
PCI-DSS):
-
-* Use only NIST-approved curves (P-256, P-384, P-521) for ECDH and ECDSA
-* Use RSA with SHA-256 or SHA-512 (rsa-sha2-256, rsa-sha2-512)
-* Use AES-128 or AES-256 in CTR or GCM mode
-* Avoid Curve25519/Ed25519 if strict FIPS compliance is required (not
NIST-approved)
-
-== Connection Keep-Alive
-
-The component supports SSH keep-alive (heartbeat) functionality to prevent
connections from being dropped during long idle periods and to detect
unresponsive servers.
-
-=== Configuration Options
-
-[cols="1,1,1,3"]
-|===
-| Option | Default | Type | Description
-
-| `serverAliveInterval`
-| `0`
-| int (ms)
-| Interval in milliseconds between keep-alive messages. Set to `0` to disable
(default).
-
-| `serverAliveCountMax`
-| `1`
-| int
-| Maximum number of consecutive unanswered keep-alive messages before the
connection is terminated.
-|===
-
-These option names follow the standard OpenSSH client configuration naming
(`ServerAliveInterval` and `ServerAliveCountMax`) and are identical to the
JSch-based `sftp` component for seamless migration.
-
-NOTE: Under the hood, these settings are mapped to Apache MINA SSHD's
`CoreModuleProperties.HEARTBEAT_INTERVAL` and
`CoreModuleProperties.HEARTBEAT_NO_REPLY_MAX` properties.
-
-=== Preventing Connection Drops
-
-For routes with long idle periods between file transfers, configure keep-alive
to prevent firewalls or servers from terminating the connection:
-
-[tabs]
-====
-Java::
-+
-[source,java]
-----
-// Send keep-alive every 30 seconds
-from("mina-sftp://user@host/path?password=secret&serverAliveInterval=30000";)
- .to("file:local");
-----
-
-XML::
-+
-[source,xml]
-----
-<!-- Send keep-alive every 30 seconds -->
-<route>
- <from
uri="mina-sftp://user@host/path?password=secret&serverAliveInterval=30000"/>
- <to uri="file:local"/>
-</route>
-----
-
-YAML::
-+
-[source,yaml]
-----
-# Send keep-alive every 30 seconds
-- route:
- from:
- uri: mina-sftp://user@host/path
- parameters:
- password: secret
- serverAliveInterval: 30000
- steps:
- - to:
- uri: file:local
-----
-====
-
-=== Detecting Unresponsive Servers
-
-Configure `serverAliveCountMax` to control how quickly the component detects
an unresponsive server:
-
-[tabs]
-====
-Java::
-+
-[source,java]
-----
-// Terminate connection after 3 unanswered keep-alives (90 seconds max)
-from("mina-sftp://user@host/path?password=secret&serverAliveInterval=30000&serverAliveCountMax=3";)
- .to("file:local");
-----
-
-XML::
-+
-[source,xml]
-----
-<!-- Terminate connection after 3 unanswered keep-alives (90 seconds max) -->
-<route>
- <from
uri="mina-sftp://user@host/path?password=secret&serverAliveInterval=30000&serverAliveCountMax=3"/>
- <to uri="file:local"/>
-</route>
-----
-
-YAML::
-+
-[source,yaml]
-----
-# Terminate connection after 3 unanswered keep-alives (90 seconds max)
-- route:
- from:
- uri: mina-sftp://user@host/path
- parameters:
- password: secret
- serverAliveInterval: 30000
- serverAliveCountMax: 3
- steps:
- - to:
- uri: file:local
-----
-====
-
-With this configuration:
-
-* Keep-alive messages are sent every 30 seconds
-* If 3 consecutive messages go unanswered, the connection is terminated
-* Maximum detection time: 90 seconds (30s × 3)
-
-=== Default Behavior
-
-By default (`serverAliveInterval=0`), no keep-alive messages are sent. This
matches the JSch-based `sftp` component behavior.
-
-NOTE: Negative values for `serverAliveInterval` are treated the same as `0`
(keep-alive disabled). This behavior is consistent between `mina-sftp` and
`sftp` components.
-
-=== Behavioral Difference: serverAliveCountMax with Zero or Negative Values
-
-IMPORTANT: There is a behavioral difference between `mina-sftp` and `sftp`
components when `serverAliveCountMax` is set to `0` or a negative value.
-
-[cols="1,2,2"]
-|===
-| Value | mina-sftp (MINA SSHD) | sftp (JSch)
-
-| `> 0`
-| Terminate connection after N unanswered heartbeats
-| Terminate connection after N unanswered heartbeats
-
-| `= 0`
-| *Fire-and-forget mode*: heartbeats are sent but no reply is expected,
connection is never terminated due to unanswered heartbeats
-| No keep-alive messages are sent
-
-| `< 0`
-| *Fire-and-forget mode*: same as `0`
-| No keep-alive messages are sent
-|===
-
-This difference stems from the underlying libraries:
-
-* **Apache MINA SSHD**: When `HEARTBEAT_NO_REPLY_MAX <= 0`, heartbeats are
sent with `wantReply=false` (fire-and-forget mode)
-* **JSch**: When `serverAliveCountMax <= 0`, keep-alive functionality is
effectively disabled
-
-==== Recommendation
-
-To ensure consistent behavior when migrating from `sftp` to `mina-sftp`:
-
-* Always use positive values for `serverAliveCountMax` (default is `1`)
-* If you want to disable connection termination on unresponsive servers but
still send heartbeats, `mina-sftp` with `serverAliveCountMax=0` provides this
capability (not available in `sftp`)
-
-== Host Key Verification
-
-The MINA SFTP component supports comprehensive host key verification to
protect against Man-in-the-Middle (MITM) attacks.
-
-=== Strict Host Key Checking
-
-When `strictHostKeyChecking=yes`, the server's host key must match an entry in
the known hosts source. If the key is unknown or mismatches, the connection is
rejected.
-
-[tabs]
-====
-Java::
-+
-[source,java]
-----
-from("mina-sftp://user@host/path?password=secret&strictHostKeyChecking=yes";)
- .to("file:local");
-----
-
-XML::
-+
-[source,xml]
-----
-<route>
- <from
uri="mina-sftp://user@host/path?password=secret&strictHostKeyChecking=yes"/>
- <to uri="file:local"/>
-</route>
-----
-
-YAML::
-+
-[source,yaml]
-----
-- route:
- from:
- uri: mina-sftp://user@host/path
- parameters:
- password: secret
- strictHostKeyChecking: "yes"
- steps:
- - to:
- uri: file:local
-----
-====
-
-=== Known Hosts Sources (Priority Order)
-
-The component checks for known hosts in this priority order:
-
-1. **Byte array** (`knownHosts`): Directly configured as byte array
-2. **URI/Classpath** (`knownHostsUri`): Loaded from classpath or file URI
-3. **File path** (`knownHostsFile`): Loaded from filesystem
-4. **User default** (`useUserKnownHostsFile=true`): Uses `~/.ssh/known_hosts`
-
-==== Using Custom Known Hosts File
-
-[tabs]
-====
-Java::
-+
-[source,java]
-----
-from("mina-sftp://user@host/path?password=secret&strictHostKeyChecking=yes&knownHostsFile=/path/to/known_hosts";)
- .to("file:local");
-----
-
-XML::
-+
-[source,xml]
-----
-<route>
- <from
uri="mina-sftp://user@host/path?password=secret&strictHostKeyChecking=yes&knownHostsFile=/path/to/known_hosts"/>
- <to uri="file:local"/>
-</route>
-----
-
-YAML::
-+
-[source,yaml]
-----
-- route:
- from:
- uri: mina-sftp://user@host/path
- parameters:
- password: secret
- strictHostKeyChecking: "yes"
- knownHostsFile: /path/to/known_hosts
- steps:
- - to:
- uri: file:local
-----
-====
-
-==== Using Known Hosts from Classpath
-
-[tabs]
-====
-Java::
-+
-[source,java]
-----
-from("mina-sftp://user@host/path?password=secret&strictHostKeyChecking=yes&knownHostsUri=classpath:ssh/known_hosts";)
- .to("file:local");
-----
-
-XML::
-+
-[source,xml]
-----
-<route>
- <from
uri="mina-sftp://user@host/path?password=secret&strictHostKeyChecking=yes&knownHostsUri=classpath:ssh/known_hosts"/>
- <to uri="file:local"/>
-</route>
-----
-
-YAML::
-+
-[source,yaml]
-----
-- route:
- from:
- uri: mina-sftp://user@host/path
- parameters:
- password: secret
- strictHostKeyChecking: "yes"
- knownHostsUri: "classpath:ssh/known_hosts"
- steps:
- - to:
- uri: file:local
-----
-====
-
-==== Using User's Default Known Hosts
-
-By default, `useUserKnownHostsFile=true` which uses `~/.ssh/known_hosts`:
-
-[tabs]
-====
-Java::
-+
-[source,java]
-----
-from("mina-sftp://user@host/path?password=secret&strictHostKeyChecking=yes";)
- .to("file:local");
-----
-
-XML::
-+
-[source,xml]
-----
-<route>
- <from
uri="mina-sftp://user@host/path?password=secret&strictHostKeyChecking=yes"/>
- <to uri="file:local"/>
-</route>
-----
-
-YAML::
-+
-[source,yaml]
-----
-- route:
- from:
- uri: mina-sftp://user@host/path
- parameters:
- password: secret
- strictHostKeyChecking: "yes"
- steps:
- - to:
- uri: file:local
-----
-====
-
-=== Auto-Create Known Hosts File (Development Only)
-
-For development environments, you can enable automatic trust-on-first-use:
-
-[tabs]
-====
-Java::
-+
-[source,java]
-----
-from("mina-sftp://user@host/path?password=secret&autoCreateKnownHostsFile=true&knownHostsFile=/tmp/dev_known_hosts";)
- .to("file:local");
-----
-
-XML::
-+
-[source,xml]
-----
-<route>
- <from
uri="mina-sftp://user@host/path?password=secret&autoCreateKnownHostsFile=true&knownHostsFile=/tmp/dev_known_hosts"/>
- <to uri="file:local"/>
-</route>
-----
-
-YAML::
-+
-[source,yaml]
-----
-- route:
- from:
- uri: mina-sftp://user@host/path
- parameters:
- password: secret
- autoCreateKnownHostsFile: true
- knownHostsFile: /tmp/dev_known_hosts
- steps:
- - to:
- uri: file:local
-----
-====
-
-CAUTION: Auto-create is only recommended for development environments. It
weakens security by automatically trusting new hosts.
-
-=== Disable Host Key Checking (Testing Only)
-
-[tabs]
-====
-Java::
-+
-[source,java]
-----
-from("mina-sftp://user@localhost/test?password=secret&strictHostKeyChecking=no&useUserKnownHostsFile=false";)
- .to("mock:result");
-----
-
-XML::
-+
-[source,xml]
-----
-<route>
- <from
uri="mina-sftp://user@localhost/test?password=secret&strictHostKeyChecking=no&useUserKnownHostsFile=false"/>
- <to uri="mock:result"/>
-</route>
-----
-
-YAML::
-+
-[source,yaml]
-----
-- route:
- from:
- uri: mina-sftp://user@localhost/test
- parameters:
- password: secret
- strictHostKeyChecking: "no"
- useUserKnownHostsFile: false
- steps:
- - to:
- uri: mock:result
-----
-====
-
-CAUTION: Disabling host key checking is insecure and should only be used for
testing.
-
-=== Certificate-Based Host Verification
-
-For enterprise environments using OpenSSH host certificates, you can use
`@cert-authority` entries in your known_hosts file to verify server
certificates instead of maintaining individual host keys.
-
-==== Using @cert-authority Entries
-
-The standard OpenSSH known_hosts format supports `@cert-authority` entries
that define trusted CA public keys for certificate verification:
-
-[source]
-----
-# Trust this CA for all hosts in example.com domain
-@cert-authority *.example.com ssh-rsa AAAAB3NzaC1yc2E... Production CA
-
-# Trust this CA for a specific host
-@cert-authority server.example.com ssh-ed25519 AAAAC3NzaC1lZDI1NTE5...
Specific CA
-----
-
-==== Example Configuration
-
-[tabs]
-====
-Java::
-+
-[source,java]
-----
-from("mina-sftp://[email protected]/path?password=secret&strictHostKeyChecking=yes&knownHostsFile=/path/to/known_hosts";)
- .to("file:local");
-----
-
-XML::
-+
-[source,xml]
-----
-<route>
- <from
uri="mina-sftp://[email protected]/path?password=secret&strictHostKeyChecking=yes&knownHostsFile=/path/to/known_hosts"/>
- <to uri="file:local"/>
-</route>
-----
-
-YAML::
-+
-[source,yaml]
-----
-- route:
- from:
- uri: mina-sftp://[email protected]/path
- parameters:
- password: secret
- strictHostKeyChecking: "yes"
- knownHostsFile: /path/to/known_hosts
- steps:
- - to:
- uri: file:local
-----
-====
-
-Where the known_hosts file contains:
-[source]
-----
-# Regular host key entry
-server1.example.com ssh-rsa AAAAB3NzaC1yc2E...
-
-# CA for certificate-based verification
-@cert-authority *.example.com ssh-rsa AAAAB3NzaC1yc2E... Enterprise CA
-----
-
-==== Certificate vs Known Hosts Priority
-
-When both `@cert-authority` entries and regular host key entries are present:
-
-* If the server presents a certificate AND a matching `@cert-authority` entry
exists: Certificate verification takes precedence
-* If certificate verification fails: Connection is rejected (does NOT fall
back to regular known_hosts entries)
-* If server presents a plain public key (not certificate): Regular known hosts
verification is used
-
-This ensures that servers configured for certificate authentication maintain
their security guarantees.
-
-=== Custom ServerKeyVerifier
-
-For advanced use cases, you can provide a custom `ServerKeyVerifier`
implementation to handle host key verification. This allows integration with
enterprise key management systems or implementing custom verification logic.
-
-==== Using Custom Verifier via Bean Reference
-
-._Java-only: `ServerKeyVerifier` lambda and registry bean binding_
-[source,java]
-----
-// Register custom verifier in Camel registry
-ServerKeyVerifier myVerifier = (session, remoteAddress, serverKey) -> {
- // Custom verification logic
- return verifyAgainstEnterpriseKeyStore(serverKey);
-};
-context.getRegistry().bind("myVerifier", myVerifier);
-----
-
-[tabs]
-====
-Java::
-+
-[source,java]
-----
-from("mina-sftp://user@host/path?password=secret&serverKeyVerifier=#myVerifier";)
- .to("file:local");
-----
-
-XML::
-+
-[source,xml]
-----
-<route>
- <from
uri="mina-sftp://user@host/path?password=secret&serverKeyVerifier=#myVerifier"/>
- <to uri="file:local"/>
-</route>
-----
-
-YAML::
-+
-[source,yaml]
-----
-- route:
- from:
- uri: mina-sftp://user@host/path
- parameters:
- password: secret
- serverKeyVerifier: "#myVerifier"
- steps:
- - to:
- uri: file:local
-----
-====
-
-==== Using Custom Verifier Programmatically
-
-._Java-only: programmatic endpoint configuration with `ServerKeyVerifier`
lambda_
-[source,java]
-----
-MinaSftpEndpoint endpoint = context.getEndpoint(
- "mina-sftp://user@host/path?password=secret";, MinaSftpEndpoint.class);
-MinaSftpConfiguration config = (MinaSftpConfiguration)
endpoint.getConfiguration();
-
-config.setServerKeyVerifier((session, remoteAddress, serverKey) -> {
- // Custom verification logic
- return true;
-});
-----
-
-==== Custom Verifier Precedence
-
-When a custom `ServerKeyVerifier` is provided:
-
-* The custom verifier is used **exclusively** for host key verification
-* All other host key options are ignored (`strictHostKeyChecking`,
`knownHostsFile`, `knownHostsUri`, etc.)
-* The user takes full responsibility for security decisions
-
-This precedence ensures predictable behavior - when you provide a custom
verifier, only your verification logic runs.
-
-=== Host Key Verification Error Messages
-
-The component provides clear error messages for different failure scenarios:
-
-* **Unknown host**: `Host key verification failed: server 'hostname:port' is
not in the known_hosts file.`
-* **Key mismatch**: `Host key verification failed: the host key for
'hostname:port' has changed! This may indicate a man-in-the-middle attack.`
-* **Untrusted CA**: `Certificate is signed by untrusted CA. Add
@cert-authority entry to known_hosts file.`
-* **Expired certificate**: `Host certificate has expired. Valid until <date>,
current time: <date>.`
-* **Principal mismatch**: `Hostname '<hostname>' is not listed in certificate
principals.`
-
-== Local Interface Binding
-
-In multi-homed environments (servers with multiple network interfaces), you
may need to specify which local network interface the SFTP connection should
use.
-
-=== Configuring Bind Address
-
-Use the `bindAddress` option to specify the local IP address or hostname to
bind the outgoing connection:
-
-[tabs]
-====
-Java::
-+
-[source,java]
-----
-from("mina-sftp://user@host/path?password=secret&bindAddress=192.168.1.100";)
- .to("file:local");
-----
-
-XML::
-+
-[source,xml]
-----
-<route>
- <from
uri="mina-sftp://user@host/path?password=secret&bindAddress=192.168.1.100"/>
- <to uri="file:local"/>
-</route>
-----
-
-YAML::
-+
-[source,yaml]
-----
-- route:
- from:
- uri: mina-sftp://user@host/path
- parameters:
- password: secret
- bindAddress: "192.168.1.100"
- steps:
- - to:
- uri: file:local
-----
-====
-
-=== Bind Address Formats
-
-The mina-sftp component supports multiple formats for `bindAddress`:
-
-[cols="2,2,2"]
-|===
-| Format | Example | Description
-
-| IPv4 address
-| `192.168.1.100`
-| Bind to IP, ephemeral port
-
-| IPv4 with port
-| `192.168.1.100:5000`
-| Bind to IP and specific port
-
-| IPv6 address
-| `::1`
-| Bind to IPv6, ephemeral port
-
-| IPv6 with port
-| `[::1]:5000`
-| Bind to IPv6 and port (bracketed notation)
-
-| Hostname
-| `localhost`
-| Bind to hostname, ephemeral port
-
-| Hostname with port
-| `localhost:5000`
-| Bind to hostname and specific port
-|===
-
-NOTE: The ability to specify a local port is a **mina-sftp specific feature**
not available in the JSch-based `sftp` component. See
<<bindaddress-difference>> for details.
-
-=== Use Cases
-
-[cols="2,3"]
-|===
-| Scenario | Configuration
-
-| Multi-homed server
-| `bindAddress=10.0.0.50` (use internal network interface)
-
-| Firewall compliance
-| `bindAddress=172.16.0.1` (use DMZ interface)
-
-| Fixed source port (strict firewall)
-| `bindAddress=10.0.0.50:5000` (specific interface and port)
-
-| Default routing
-| Omit `bindAddress` (OS decides based on routing table)
-|===
-
-=== Default Behavior
-
-When `bindAddress` is not specified (default), the operating system's routing
table determines which local interface is used for the connection. This is the
standard behavior for most use cases.
-
-When a port is not specified (e.g., `bindAddress=192.168.1.100`), an ephemeral
port is automatically assigned by the operating system.
-
-=== Error Handling
-
-If an invalid or unavailable bind address is specified, the connection will
fail with a clear error message:
-
-[source]
-----
-Invalid bind address: 192.168.99.99. Supported formats: host, host:port,
[ipv6], [ipv6]:port
-----
-
-[[bindaddress-difference]]
-=== Difference from JSch SFTP Component
-
-The mina-sftp component's `bindAddress` parameter has an enhanced format
compared to the JSch-based `sftp` component:
-
-[cols="1,2,2"]
-|===
-| Feature | mina-sftp | sftp (JSch)
-
-| **IP/hostname binding**
-| Supported
-| Supported
-
-| **Port specification**
-| Supported (`host:port` format)
-| Not supported (always ephemeral)
-
-| **IPv6 with port**
-| Supported (`[ipv6]:port` format)
-| Not supported
-
-| **Implementation**
-| Native MINA SSHD API (`SshClient.connect()` with local address)
-| Custom SocketFactory workaround
-|===
-
-==== Migration Note
-
-If you are migrating from the `sftp` component to `mina-sftp`, your existing
`bindAddress` configurations will work without changes. The port specification
is an optional enhancement.
-
-._Java-only: bindAddress configuration values_
-[source,java]
-----
-// Works in both sftp and mina-sftp
-bindAddress=192.168.1.100
-
-// Only works in mina-sftp (port specification)
-bindAddress=192.168.1.100:5000
-----
-
-== SFTP Buffer Size Configuration
-
-The mina-sftp component allows you to configure buffer sizes for SFTP read and
write operations to optimize file transfer performance.
-
-=== Configuring Buffer Sizes
-
-Use `readBufferSize` and `writeBufferSize` to control the buffer allocation
for SFTP transfers:
-
-[tabs]
-====
-Java::
-+
-[source,java]
-----
-// Configure 64KB read buffer and 32KB write buffer
-from("mina-sftp://user@host/path?password=secret&readBufferSize=65536&writeBufferSize=32768";)
- .to("file:local");
-
-// Configure symmetric buffer sizes for balanced transfers
-from("mina-sftp://user@host/path?password=secret&readBufferSize=65536&writeBufferSize=65536";)
- .to("file:local");
-----
-
-XML::
-+
-[source,xml]
-----
-<!-- Configure 64KB read buffer and 32KB write buffer -->
-<route>
- <from
uri="mina-sftp://user@host/path?password=secret&readBufferSize=65536&writeBufferSize=32768"/>
- <to uri="file:local"/>
-</route>
-
-<!-- Configure symmetric buffer sizes for balanced transfers -->
-<route>
- <from
uri="mina-sftp://user@host/path?password=secret&readBufferSize=65536&writeBufferSize=65536"/>
- <to uri="file:local"/>
-</route>
-----
-
-YAML::
-+
-[source,yaml]
-----
-# Configure 64KB read buffer and 32KB write buffer
-- route:
- from:
- uri: mina-sftp://user@host/path
- parameters:
- password: secret
- readBufferSize: 65536
- writeBufferSize: 32768
- steps:
- - to:
- uri: file:local
-
-# Configure symmetric buffer sizes for balanced transfers
-- route:
- from:
- uri: mina-sftp://user@host/path
- parameters:
- password: secret
- readBufferSize: 65536
- writeBufferSize: 65536
- steps:
- - to:
- uri: file:local
-----
-====
-
-=== Buffer Size Options
-
-[cols="2,1,3"]
-|===
-| Option | Default | Description
-
-| `readBufferSize`
-| MINA default
-| Buffer size in bytes for reading data from SFTP connections
-
-| `writeBufferSize`
-| MINA default
-| Buffer size in bytes for writing data to SFTP connections
-|===
-
-=== Performance Tuning Guidelines
-
-[cols="2,2,3"]
-|===
-| Buffer Size | Memory Usage | Use Case
-
-| `32768` (32KB)
-| Low
-| Memory-constrained environments, slow connections
-
-| `65536` (64KB)
-| Medium
-| Balanced performance (recommended starting point)
-
-| `98304` (96KB)
-| Medium-High
-| High-throughput connections
-
-| `126976` (124KB)
-| High
-| Maximum recommended - higher values may cause issues
-|===
-
-=== Important Considerations
-
-IMPORTANT: The maximum recommended buffer size is `126976` bytes
(approximately 124KB). Buffer sizes larger than this may cause data corruption
issues in Apache MINA SSHD due to server read request size limits.
-
-=== Default Behavior
-
-When buffer sizes are not specified, Apache MINA SSHD uses its internal
defaults, which are suitable for most use cases. Configure explicit buffer
sizes only when you need to optimize for specific network conditions or memory
constraints.
-
-=== Migration from bulkRequests (Deprecated)
-
-If you are migrating from a configuration using the deprecated `bulkRequests`
parameter, use the following conversion:
-
-[cols="1,2,2"]
-|===
-| bulkRequests | Equivalent Buffer Size | Configuration
-
-| `1`
-| 32KB
-| `readBufferSize=32768&writeBufferSize=32768`
-
-| `2`
-| 64KB
-| `readBufferSize=65536&writeBufferSize=65536`
-
-| `4`
-| 128KB (capped to 124KB)
-| `readBufferSize=126976&writeBufferSize=126976`
-
-| `8+`
-| 124KB (maximum)
-| `readBufferSize=126976&writeBufferSize=126976`
-|===
-
-The `bulkRequests` parameter is still supported for backward compatibility but
is deprecated. New configurations should use `readBufferSize` and
`writeBufferSize` directly as they map directly to Apache MINA SSHD's native
buffer properties.
-
-NOTE: In the original JSch-based `sftp` component, `bulkRequests` controlled
how many 32KB packets could be in-flight simultaneously. In Apache MINA SSHD,
there is no direct equivalent, so the mina-sftp component approximates this
behavior using buffer sizes. For fine-grained control over transfer
characteristics, use `readBufferSize` and `writeBufferSize`.
-
-== File and Directory Permissions (chmod)
-
-The mina-sftp component supports setting POSIX file permissions on uploaded
files and created directories.
-
-=== Setting File Permissions
-
-Use the `chmod` option to set permissions on files after they are uploaded:
-
-[tabs]
-====
-Java::
-+
-[source,java]
-----
-// Set file permissions to rw-r--r-- (644)
-from("file:/data/outbound")
- .to("mina-sftp://user@host/uploads?password=secret&chmod=644";);
-
-// Set file permissions to rw------- (600) for sensitive files
-from("file:/data/secrets")
- .to("mina-sftp://user@host/secure?password=secret&chmod=600";);
-----
-
-XML::
-+
-[source,xml]
-----
-<!-- Set file permissions to rw-r--r-- (644) -->
-<route>
- <from uri="file:/data/outbound"/>
- <to uri="mina-sftp://user@host/uploads?password=secret&chmod=644"/>
-</route>
-
-<!-- Set file permissions to rw------- (600) for sensitive files -->
-<route>
- <from uri="file:/data/secrets"/>
- <to uri="mina-sftp://user@host/secure?password=secret&chmod=600"/>
-</route>
-----
-
-YAML::
-+
-[source,yaml]
-----
-# Set file permissions to rw-r--r-- (644)
-- route:
- from:
- uri: file:/data/outbound
- steps:
- - to:
- uri: mina-sftp://user@host/uploads
- parameters:
- password: secret
- chmod: "644"
-
-# Set file permissions to rw------- (600) for sensitive files
-- route:
- from:
- uri: file:/data/secrets
- steps:
- - to:
- uri: mina-sftp://user@host/secure
- parameters:
- password: secret
- chmod: "600"
-----
-====
-
-=== Setting Directory Permissions
-
-Use the `chmodDirectory` option to set permissions on directories when they
are created:
-
-[tabs]
-====
-Java::
-+
-[source,java]
-----
-// Set directory permissions to rwxr-xr-x (755)
-from("file:/data/outbound")
- .to("mina-sftp://user@host/uploads?password=secret&chmodDirectory=755";);
-
-// Combine with chmod for complete control
-from("file:/data/outbound")
-
.to("mina-sftp://user@host/uploads?password=secret&chmod=644&chmodDirectory=755";);
-----
-
-XML::
-+
-[source,xml]
-----
-<!-- Set directory permissions to rwxr-xr-x (755) -->
-<route>
- <from uri="file:/data/outbound"/>
- <to
uri="mina-sftp://user@host/uploads?password=secret&chmodDirectory=755"/>
-</route>
-
-<!-- Combine with chmod for complete control -->
-<route>
- <from uri="file:/data/outbound"/>
- <to
uri="mina-sftp://user@host/uploads?password=secret&chmod=644&chmodDirectory=755"/>
-</route>
-----
-
-YAML::
-+
-[source,yaml]
-----
-# Set directory permissions to rwxr-xr-x (755)
-- route:
- from:
- uri: file:/data/outbound
- steps:
- - to:
- uri: mina-sftp://user@host/uploads
- parameters:
- password: secret
- chmodDirectory: "755"
-
-# Combine with chmod for complete control
-- route:
- from:
- uri: file:/data/outbound
- steps:
- - to:
- uri: mina-sftp://user@host/uploads
- parameters:
- password: secret
- chmod: "644"
- chmodDirectory: "755"
-----
-====
-
-=== Permission Format
-
-Permissions are specified as octal strings, just like the Unix `chmod` command:
+Common permission values:
[cols="1,2,3"]
|===
| Value | Permissions | Description
-| `777`
-| `rwxrwxrwx`
-| Full access for everyone (not recommended)
-
| `755`
| `rwxr-xr-x`
| Owner full, group/others read+execute
-| `750`
-| `rwxr-x---`
-| Owner full, group read+execute, others none
-
-| `700`
-| `rwx------`
-| Owner only
-
| `644`
| `rw-r--r--`
| Owner read+write, group/others read-only
-| `640`
-| `rw-r-----`
-| Owner read+write, group read-only, others none
-
| `600`
| `rw-------`
| Owner read+write only
|===
-=== Platform Considerations
-
-IMPORTANT: The `chmod` and `chmodDirectory` options only work on
POSIX-compatible SFTP servers (Linux, macOS, Unix). Windows SFTP servers that
don't support POSIX permissions may ignore these settings or return an error.
-
-=== Configuration Validation
-
-The `chmod` and `chmodDirectory` values are validated at endpoint startup.
Invalid values will cause the endpoint to fail during initialization with a
clear error message:
-
-[source]
-----
-Invalid chmod value: '999'. Must be a valid octal number (e.g., 644, 755).
-The value contains non-octal characters (valid: 0-7).
-
-Invalid chmodDirectory value: '888'. Must be an octal number between 000 and
7777 (e.g., 644, 755).
-----
+Values are validated at endpoint startup. Invalid values cause a clear error
message.
-This early validation helps catch configuration errors before any file
operations are attempted.
+IMPORTANT: The `chmod` and `chmodDirectory` options only work on
POSIX-compatible SFTP servers. Windows SFTP servers may ignore these settings.
== Symbolic Links
-The mina-sftp component supports reading and writing through symbolic links on
SFTP servers that support them.
-
-=== Consumer Behavior
-
-When consuming files, the consumer follows symbolic links to their target
files:
-
-[tabs]
-====
-Java::
-+
-[source,java]
-----
-// Will consume files through symlinks
-from("mina-sftp://user@host/data?password=secret";)
- .to("file:local");
-----
-
-XML::
-+
-[source,xml]
-----
-<!-- Will consume files through symlinks -->
-<route>
- <from uri="mina-sftp://user@host/data?password=secret"/>
- <to uri="file:local"/>
-</route>
-----
-
-YAML::
-+
-[source,yaml]
-----
-# Will consume files through symlinks
-- route:
- from:
- uri: mina-sftp://user@host/data
- parameters:
- password: secret
- steps:
- - to:
- uri: file:local
-----
-====
-
-=== Producer Behavior
-
-When producing files, you can write to paths that are symbolic links. The file
will be written to the symlink's target:
-
-[tabs]
-====
-Java::
-+
-[source,java]
-----
-// Can write to symlink targets
-from("file:local")
- .to("mina-sftp://user@host/upload-link?password=secret";);
-----
-
-XML::
-+
-[source,xml]
-----
-<!-- Can write to symlink targets -->
-<route>
- <from uri="file:local"/>
- <to uri="mina-sftp://user@host/upload-link?password=secret"/>
-</route>
-----
-
-YAML::
-+
-[source,yaml]
-----
-# Can write to symlink targets
-- route:
- from:
- uri: file:local
- steps:
- - to:
- uri: mina-sftp://user@host/upload-link
- parameters:
- password: secret
-----
-====
-
-=== Symlink Limitations
+The consumer follows symbolic links to their target files. The producer writes
to symlink targets.
-NOTE: **Absolute symlinks in chroot environments**: If the SFTP server uses a
chroot jail (common with OpenSSH `ChrootDirectory`), absolute symlinks may not
resolve correctly because the absolute path gets prepended with the chroot
directory. Use **relative symlinks** for maximum compatibility in chroot
environments.
+NOTE: **Absolute symlinks in chroot environments**: If the SFTP server uses a
chroot jail, absolute symlinks may not resolve correctly. Use **relative
symlinks** for maximum compatibility.
[source,bash]
----
@@ -2801,375 +586,17 @@ ln -s /home/user/actual-data/file.txt data/link.txt
The mina-sftp component handles thread safety internally. The underlying MINA
SSHD session and SFTP client are not thread-safe, so the component uses
internal locking to ensure safe concurrent access.
-=== Concurrent Access
-
-Multiple Camel routes can safely share the same SFTP endpoint. The component
serializes access to the underlying SFTP connection:
-
-[tabs]
-====
-Java::
-+
-[source,java]
-----
-from("timer:upload1?period=5000")
- .setBody(constant("data1"))
- .to("mina-sftp://user@host/uploads?password=secret";);
-
-from("timer:upload2?period=5000")
- .setBody(constant("data2"))
- .to("mina-sftp://user@host/uploads?password=secret";);
-----
-
-XML::
-+
-[source,xml]
-----
-<route>
- <from uri="timer:upload1?period=5000"/>
- <setBody>
- <constant>data1</constant>
- </setBody>
- <to uri="mina-sftp://user@host/uploads?password=secret"/>
-</route>
-
-<route>
- <from uri="timer:upload2?period=5000"/>
- <setBody>
- <constant>data2</constant>
- </setBody>
- <to uri="mina-sftp://user@host/uploads?password=secret"/>
-</route>
-----
-
-YAML::
-+
-[source,yaml]
-----
-- route:
- from:
- uri: timer:upload1
- parameters:
- period: 5000
- steps:
- - setBody:
- constant: data1
- - to:
- uri: mina-sftp://user@host/uploads
- parameters:
- password: secret
-
-- route:
- from:
- uri: timer:upload2
- parameters:
- period: 5000
- steps:
- - setBody:
- constant: data2
- - to:
- uri: mina-sftp://user@host/uploads
- parameters:
- password: secret
-----
-====
-
-=== Connection Pooling
-
-Each endpoint maintains its own connection. For high-throughput scenarios with
many concurrent operations, consider using multiple endpoints or connection
pooling strategies at the route level.
+Multiple Camel routes can safely share the same SFTP endpoint. Each endpoint
maintains its own connection. For high-throughput scenarios, consider using
multiple endpoints.
== Filename Encoding
-The mina-sftp component allows you to specify the character encoding used for
filenames when communicating with the SFTP server.
-
-=== When to Use
-
-By default, MINA SSHD uses UTF-8 encoding for filenames, which is the standard
for modern SFTP servers. However, some legacy servers may use different
regional encodings:
-
-- **GBK** or **GB2312** - Chinese servers
-- **Shift-JIS** or **EUC-JP** - Japanese servers
-- **ISO-8859-1** - Western European legacy systems
-- **Windows-1252** - Windows legacy systems
-
-=== Configuration
-
-Use the `filenameEncoding` option to specify the charset:
+By default, MINA SSHD uses UTF-8 encoding for filenames. For legacy servers
using different regional encodings, configure the `filenameEncoding` option:
-[tabs]
-====
-Java::
-+
[source,java]
----
// Connect to a legacy server using GBK encoding for Chinese filenames
from("mina-sftp://user@host/path?password=secret&filenameEncoding=GBK";)
.to("file:local");
-
-// Connect to a Japanese server
-from("mina-sftp://user@host/path?password=secret&filenameEncoding=Shift-JIS";)
- .to("file:local");
-----
-
-XML::
-+
-[source,xml]
-----
-<!-- Connect to a legacy server using GBK encoding for Chinese filenames -->
-<route>
- <from
uri="mina-sftp://user@host/path?password=secret&filenameEncoding=GBK"/>
- <to uri="file:local"/>
-</route>
-
-<!-- Connect to a Japanese server -->
-<route>
- <from
uri="mina-sftp://user@host/path?password=secret&filenameEncoding=Shift-JIS"/>
- <to uri="file:local"/>
-</route>
-----
-
-YAML::
-+
-[source,yaml]
-----
-# Connect to a legacy server using GBK encoding for Chinese filenames
-- route:
- from:
- uri: mina-sftp://user@host/path
- parameters:
- password: secret
- filenameEncoding: GBK
- steps:
- - to:
- uri: file:local
-
-# Connect to a Japanese server
-- route:
- from:
- uri: mina-sftp://user@host/path
- parameters:
- password: secret
- filenameEncoding: Shift-JIS
- steps:
- - to:
- uri: file:local
-----
-====
-
-=== Default Behavior
-
-When `filenameEncoding` is not specified, UTF-8 is used (the MINA SSHD
default). This is correct for most modern SFTP servers.
-
-== Deprecated JSch Parameters (Migration from sftp)
-
-The following parameters from the JSch-based `sftp` component are accepted for
**backward compatibility** but are ignored. When used, they log a deprecation
warning to help you identify configurations that need updating.
-
-=== Accepted but Ignored Parameters
-
-[cols="2,3,2"]
-|===
-| Parameter | Description | Recommendation
-
-| `existDirCheckUsingLs`
-| JSch-specific workaround for Windows compatibility. MINA SSHD uses `stat()`
instead.
-| Remove from URI
-
-| `jschLoggingLevel`
-| Controlled JSch internal logging verbosity.
-| Configure via log4j/logback (see <<Logging Configuration>>)
-
-| `serverMessageLoggingLevel`
-| Controlled SSH server message logging.
-| Configure via log4j/logback (see <<Logging Configuration>>)
-|===
-
-=== Example Warning Messages
-
-When these deprecated parameters are used, warnings like the following are
logged:
-
-[source]
-----
-WARN The 'existDirCheckUsingLs' parameter is specific to the JSch-based sftp
component
- and is ignored by mina-sftp. MINA SSHD uses stat() for directory
existence checks
- which is more reliable.
-
-WARN The 'jschLoggingLevel' parameter is specific to the JSch-based sftp
component
- and is ignored by mina-sftp. MINA SSHD uses SLF4J natively - configure
logging
- via your logging framework (log4j, logback) instead.
-----
-
-=== Migration Example
-
-._Java-only: before and after migration from JSch-specific parameters_
-[source,java]
-----
-// Before (sftp component with JSch-specific parameters)
-from("sftp://user@host/path?existDirCheckUsingLs=false&jschLoggingLevel=WARN";)
-
-// After (mina-sftp component) - remove JSch-specific parameters
-from("mina-sftp://user@host/path";)
-----
-
-The deprecated parameters will continue to work (without effect) to ease
migration, but you should remove them to avoid the warning messages.
-
-== Logging Configuration
-
-=== Difference from JSch SFTP Component
-
-The JSch-based `sftp` component provides two logging-related configuration
options:
-
-* `loggingLevel` (also known as `jschLoggingLevel`) - Controls the verbosity
of JSch library internal logging
-* `serverMessageLoggingLevel` - Controls the log level for SSH server messages
(banners, interactive messages)
-
-**These options are NOT available in the mina-sftp component** because Apache
MINA SSHD handles logging differently:
-
-[cols="2,3,3"]
-|===
-| Aspect | sftp (JSch) | mina-sftp (Apache MINA SSHD)
-
-| **Logging Framework**
-| JSch has its own `com.jcraft.jsch.Logger` interface that must be bridged to
SLF4J
-| Uses SLF4J natively - no bridge needed
-
-| **Library Logging Control**
-| Requires `loggingLevel` parameter to control JSch verbosity
-| Controlled via standard SLF4J configuration (log4j.properties, logback.xml)
-
-| **Server Messages**
-| `serverMessageLoggingLevel` controls `showMessage()` callback output
-| Server messages (banners) are handled internally and logged via SLF4J
-|===
-
-=== Configuring MINA SSHD Logging
-
-To control the verbosity of Apache MINA SSHD logging, configure your logging
framework directly.
-
-==== Log4j Configuration
-
-[source,properties]
-----
-# log4j.properties
-
-# Set MINA SSHD logging level (equivalent to loggingLevel in sftp component)
-log4j.logger.org.apache.sshd=WARN
-
-# For more verbose debugging during development
-log4j.logger.org.apache.sshd=DEBUG
-
-# Fine-grained control over specific MINA SSHD components
-log4j.logger.org.apache.sshd.client=DEBUG
-log4j.logger.org.apache.sshd.common.channel=WARN
-log4j.logger.org.apache.sshd.sftp=DEBUG
-
-# To see SSH channel window operations (very verbose)
-log4j.logger.org.apache.sshd.common.channel.Window=TRACE
-
-# To see key exchange details
-log4j.logger.org.apache.sshd.common.kex=DEBUG
-
-# To see authentication details
-log4j.logger.org.apache.sshd.client.auth=DEBUG
-----
-
-==== Log4j2 Configuration
-
-[source,xml]
-----
-<!-- log4j2.xml -->
-<Configuration>
- <Loggers>
- <!-- Set MINA SSHD logging level -->
- <Logger name="org.apache.sshd" level="WARN"/>
-
- <!-- For debugging SFTP operations -->
- <Logger name="org.apache.sshd.sftp" level="DEBUG"/>
-
- <!-- For debugging authentication -->
- <Logger name="org.apache.sshd.client.auth" level="DEBUG"/>
-
- <!-- For debugging key exchange -->
- <Logger name="org.apache.sshd.common.kex" level="DEBUG"/>
- </Loggers>
-</Configuration>
-----
-
-==== Logback Configuration
-
-[source,xml]
-----
-<!-- logback.xml -->
-<configuration>
- <!-- Set MINA SSHD logging level (equivalent to loggingLevel in sftp
component) -->
- <logger name="org.apache.sshd" level="WARN"/>
-
- <!-- For debugging during development -->
- <logger name="org.apache.sshd" level="DEBUG"/>
-
- <!-- Fine-grained control -->
- <logger name="org.apache.sshd.client" level="DEBUG"/>
- <logger name="org.apache.sshd.sftp" level="DEBUG"/>
- <logger name="org.apache.sshd.client.auth" level="DEBUG"/>
- <logger name="org.apache.sshd.common.kex" level="DEBUG"/>
-
- <!-- Very verbose channel window logging -->
- <logger name="org.apache.sshd.common.channel.Window" level="TRACE"/>
-</configuration>
-----
-
-=== Common Logging Scenarios
-
-[cols="2,3"]
-|===
-| Scenario | Logger Configuration
-
-| **Reduce noise in production**
-| `org.apache.sshd=WARN` or `org.apache.sshd=ERROR`
-
-| **Debug connection issues**
-| `org.apache.sshd.client=DEBUG`
-
-| **Debug authentication failures**
-| `org.apache.sshd.client.auth=DEBUG`
-
-| **Debug file transfer issues**
-| `org.apache.sshd.sftp=DEBUG`
-
-| **Debug host key verification**
-| `org.apache.sshd.client.keyverifier=DEBUG`
-
-| **Full verbose debugging**
-| `org.apache.sshd=TRACE` (warning: very verbose)
-|===
-
-=== Migration Note
-
-If you are migrating from the `sftp` component and were using `loggingLevel`
or `serverMessageLoggingLevel`:
-
-1. These parameters are accepted for backward compatibility but will log a
deprecation warning
-2. Remove these parameters from your endpoint URI to avoid the warning messages
-3. Add the equivalent logging configuration to your `log4j.properties`,
`log4j2.xml`, or `logback.xml`
-4. The standard SLF4J approach provides more flexibility and follows Java
logging best practices
-
-.Before (JSch sftp component)
-
-._Java-only: JSch sftp component with logging parameters_
-[source,java]
-----
-from("sftp://user@host/path?password=secret&loggingLevel=DEBUG&serverMessageLoggingLevel=INFO";)
- .to("file:local");
----
-.After (MINA SSHD mina-sftp component)
-
-._Java-only: mina-sftp component with logging parameters removed_
-[source,java]
-----
-// Remove logging parameters from URI
-from("mina-sftp://user@host/path?password=secret";)
- .to("file:local");
-----
-
-And add to your logging configuration:
-[source,properties]
-----
-# log4j.properties
-log4j.logger.org.apache.sshd=DEBUG
-----
+Supported encodings include GBK, GB2312, Shift-JIS, EUC-JP, ISO-8859-1, and
Windows-1252.
diff --git a/components/camel-mina-sftp/src/main/docs/mina-sftp-migration.adoc
b/components/camel-mina-sftp/src/main/docs/mina-sftp-migration.adoc
new file mode 100644
index 000000000000..9e23136ba0f1
--- /dev/null
+++ b/components/camel-mina-sftp/src/main/docs/mina-sftp-migration.adoc
@@ -0,0 +1,173 @@
+= MINA SFTP Migration from JSch
+:tabs-sync-option:
+
+xref:ROOT:mina-sftp-component.adoc[Back to MINA SFTP Component]
+
+Users migrating from the JSch-based `sftp` component can switch by changing
only the URI scheme from `sftp://` to `mina-sftp://`:
+
+[source,java]
+----
+// Before (JSch)
+from("sftp://user@host/path?password=secret";).to("file:local");
+
+// After (MINA SSHD)
+from("mina-sftp://user@host/path?password=secret";).to("file:local");
+----
+
+All standard configuration options remain the same for supported features.
+
+== Features Not Supported
+
+The following JSch features are *not* supported by mina-sftp:
+
+* **Proxy support**: HTTP proxy, SOCKS4, SOCKS5 proxy connections
+* **GSSAPI/Kerberos authentication**
+
+If you require these features, continue using the JSch-based `sftp` component.
Configuring an unsupported feature throws a clear error message.
+
+== Behavioral Differences
+
+[cols="2,3,3"]
+|===
+| Feature | mina-sftp (Apache MINA SSHD) | sftp (JSch)
+
+| **License**
+| Apache License 2.0
+| BSD-style license
+
+| **Compression**
+| Built-in, no extra JARs
+| Requires jsch-zlib JAR
+
+| **Ciphers**
+| Modern (ChaCha20-Poly1305, AES-GCM); validates before connection
+| Limited; errors at connection time
+
+| **Key Exchange**
+| Modern (Curve25519, ECDH); validates before connection
+| Limited; uses JSch.setConfig()
+
+| **Server Host Keys**
+| Modern (Ed25519, RSA-SHA2, ECDSA); validates before connection
+| Limited; uses session.setConfig()
+
+| **Known Hosts Port Matching**
+| Strict OpenSSH: `hostname` = port 22 only; `[hostname]:port` for non-standard
+| Lenient: `hostname` matches any port
+
+| **serverAliveCountMax=0**
+| Fire-and-forget: heartbeats sent, never terminates
+| Keep-alive disabled
+
+| **Host Key Verification**
+| MINA SSHD ServerKeyVerifier with certificate support
+| JSch HostKeyRepository
+
+| **Proxy Support**
+| Not supported
+| HTTP, SOCKS4, SOCKS5
+
+| **GSSAPI/Kerberos**
+| Not supported
+| Supported
+
+| **Logging**
+| SLF4J natively; configure via log4j/logback
+| Requires `loggingLevel` parameter to bridge
+|===
+
+=== Known Hosts Port Matching
+
+The mina-sftp component follows **strict OpenSSH semantics**: `hostname`
matches port 22 only, while `[hostname]:port` matches non-standard ports.
+
+If your known_hosts contains `myserver.example.com ssh-rsa AAAA...`:
+* **sftp**: matches on **any port**
+* **mina-sftp**: matches on **port 22 only**
+
+For non-standard ports, use: `[myserver.example.com]:2222 ssh-rsa AAAA...`
+
+== Migration Checklist
+
+. **URI Scheme**: Change `sftp://` to `mina-sftp://`
+. **Proxy Usage**: If using proxy, stay with `sftp`
+. **Kerberos/GSSAPI**: If using GSSAPI, stay with `sftp`
+. **Known Hosts on Non-Standard Ports**: Update entries to `[hostname]:port`
format
+. **serverAliveCountMax**: If using `=0`, note behavioral difference
+. **Compression**: Remove manual zlib JAR additions
+. **Deprecated Parameters**: Remove `loggingLevel`,
`serverMessageLoggingLevel`, `existDirCheckUsingLs` (see <<Deprecated JSch
Parameters>>)
+. **Logging**: Configure via log4j/logback instead of URI parameters (see
<<Logging Configuration>>)
+. **Test Authentication**: Verify public key and password work correctly
+. **Test Host Key Verification**: Verify known_hosts entries match
+
+== Deprecated JSch Parameters
+
+These JSch parameters are accepted for backward compatibility but ignored with
a deprecation warning:
+
+[cols="2,3,2"]
+|===
+| Parameter | Description | Recommendation
+
+| `existDirCheckUsingLs`
+| JSch workaround for Windows. MINA SSHD uses `stat()`.
+| Remove from URI
+
+| `jschLoggingLevel`
+| Controlled JSch logging verbosity.
+| Configure via log4j/logback
+
+| `serverMessageLoggingLevel`
+| Controlled SSH server message logging.
+| Configure via log4j/logback
+|===
+
+[source,java]
+----
+// Before (sftp with JSch-specific parameters)
+from("sftp://user@host/path?existDirCheckUsingLs=false&jschLoggingLevel=WARN";)
+
+// After (mina-sftp) - remove JSch-specific parameters
+from("mina-sftp://user@host/path";)
+----
+
+== Logging Configuration
+
+Apache MINA SSHD uses SLF4J natively — no logging parameters needed in the
URI. Configure your logging framework directly:
+
+[source,properties]
+----
+# log4j.properties - common configurations
+log4j.logger.org.apache.sshd=WARN # production
+log4j.logger.org.apache.sshd.client=DEBUG # debug connections
+log4j.logger.org.apache.sshd.client.auth=DEBUG # debug authentication
+log4j.logger.org.apache.sshd.sftp=DEBUG # debug file transfers
+----
+
+[source,xml]
+----
+<!-- logback.xml -->
+<configuration>
+ <logger name="org.apache.sshd" level="WARN"/>
+ <logger name="org.apache.sshd.client.auth" level="DEBUG"/>
+ <logger name="org.apache.sshd.sftp" level="DEBUG"/>
+</configuration>
+----
+
+[cols="2,3"]
+|===
+| Scenario | Logger
+
+| Reduce production noise
+| `org.apache.sshd=WARN`
+
+| Debug connections
+| `org.apache.sshd.client=DEBUG`
+
+| Debug authentication
+| `org.apache.sshd.client.auth=DEBUG`
+
+| Debug file transfers
+| `org.apache.sshd.sftp=DEBUG`
+
+| Debug host key verification
+| `org.apache.sshd.client.keyverifier=DEBUG`
+|===
diff --git a/components/camel-mina-sftp/src/main/docs/mina-sftp-security.adoc
b/components/camel-mina-sftp/src/main/docs/mina-sftp-security.adoc
new file mode 100644
index 000000000000..8ed427ab53be
--- /dev/null
+++ b/components/camel-mina-sftp/src/main/docs/mina-sftp-security.adoc
@@ -0,0 +1,346 @@
+= MINA SFTP SSH Security
+:tabs-sync-option:
+
+xref:ROOT:mina-sftp-component.adoc[Back to MINA SFTP Component]
+
+This page covers SSH security configuration for the MINA SFTP component,
including host key verification, cipher selection, key exchange protocols, and
algorithm security recommendations.
+
+== Host Key Verification
+
+The MINA SFTP component supports comprehensive host key verification to
protect against Man-in-the-Middle (MITM) attacks.
+
+=== Strict Host Key Checking
+
+When `strictHostKeyChecking=yes`, the server's host key must match an entry in
the known hosts source:
+
+[source,java]
+----
+from("mina-sftp://user@host/path?password=secret&strictHostKeyChecking=yes";)
+ .to("file:local");
+----
+
+=== Known Hosts Sources (Priority Order)
+
+The component checks for known hosts in this priority order:
+
+1. **Byte array** (`knownHosts`): Directly configured as byte array
+2. **URI/Classpath** (`knownHostsUri`): Loaded from classpath or file URI
+3. **File path** (`knownHostsFile`): Loaded from filesystem
+4. **User default** (`useUserKnownHostsFile=true`): Uses `~/.ssh/known_hosts`
+
+[source,java]
+----
+// Custom known hosts file
+from("mina-sftp://user@host/path?password=secret&strictHostKeyChecking=yes&knownHostsFile=/path/to/known_hosts";)
+ .to("file:local");
+
+// Known hosts from classpath
+from("mina-sftp://user@host/path?password=secret&strictHostKeyChecking=yes&knownHostsUri=classpath:ssh/known_hosts";)
+ .to("file:local");
+----
+
+=== Auto-Create Known Hosts File (Development Only)
+
+For development environments, enable automatic trust-on-first-use:
+
+[source,java]
+----
+from("mina-sftp://user@host/path?password=secret&autoCreateKnownHostsFile=true&knownHostsFile=/tmp/dev_known_hosts";)
+ .to("file:local");
+----
+
+CAUTION: Auto-create weakens security by automatically trusting new hosts.
Only use for development.
+
+=== Disable Host Key Checking (Testing Only)
+
+[source,java]
+----
+from("mina-sftp://user@localhost/test?password=secret&strictHostKeyChecking=no&useUserKnownHostsFile=false";)
+ .to("mock:result");
+----
+
+CAUTION: Disabling host key checking is insecure. Only use for testing.
+
+=== Certificate-Based Host Verification
+
+For enterprise environments using OpenSSH host certificates, use
`@cert-authority` entries in your known_hosts file:
+
+[source]
+----
+# Trust this CA for all hosts in example.com domain
+@cert-authority *.example.com ssh-rsa AAAAB3NzaC1yc2E... Production CA
+
+# Trust this CA for a specific host
+@cert-authority server.example.com ssh-ed25519 AAAAC3NzaC1lZDI1NTE5...
Specific CA
+----
+
+When both `@cert-authority` entries and regular host key entries are present:
+
+* Certificate verification takes precedence if the server presents a
certificate and a matching CA exists
+* If certificate verification fails, the connection is rejected (does NOT fall
back to regular entries)
+* If the server presents a plain public key, regular known hosts verification
is used
+
+=== Custom ServerKeyVerifier
+
+For advanced use cases, provide a custom `ServerKeyVerifier` for enterprise
key management integration:
+
+[source,java]
+----
+ServerKeyVerifier myVerifier = (session, remoteAddress, serverKey) -> {
+ return verifyAgainstEnterpriseKeyStore(serverKey);
+};
+context.getRegistry().bind("myVerifier", myVerifier);
+----
+
+[source,java]
+----
+from("mina-sftp://user@host/path?password=secret&serverKeyVerifier=#myVerifier";)
+ .to("file:local");
+----
+
+When a custom verifier is provided, it is used **exclusively** — all other
host key options are ignored.
+
+=== Host Key Verification Error Messages
+
+* **Unknown host**: `Host key verification failed: server 'hostname:port' is
not in the known_hosts file.`
+* **Key mismatch**: `Host key verification failed: the host key for
'hostname:port' has changed!`
+* **Untrusted CA**: `Certificate is signed by untrusted CA.`
+* **Expired certificate**: `Host certificate has expired.`
+* **Principal mismatch**: `Hostname '<hostname>' is not listed in certificate
principals.`
+
+== Cipher Configuration
+
+Specify which SSH cipher algorithms to use with the `ciphers` option:
+
+[source,java]
+----
+from("mina-sftp://user@host/path?password=secret&[email protected],[email protected],aes256-ctr";)
+ .to("file:local");
+----
+
+Ciphers are offered to the server in the order specified. The first mutually
supported cipher is used.
+
+=== Available Ciphers
+
+[cols="2,1,1,3"]
+|===
+| Cipher Name | Algorithm | Mode | Notes
+
+| `aes128-ctr`
+| AES-128
+| CTR
+| Standard, widely supported
+
+| `aes192-ctr`
+| AES-192
+| CTR
+| Standard
+
+| `aes256-ctr`
+| AES-256
+| CTR
+| Recommended for high security
+
+| `[email protected]`
+| AES-128
+| GCM
+| Authenticated encryption
+
+| `[email protected]`
+| AES-256
+| GCM
+| Recommended - authenticated encryption
+
+| `[email protected]`
+| ChaCha20
+| AEAD
+| Modern, fast on CPUs without AES-NI
+
+| `aes128-cbc`
+| AES-128
+| CBC
+| Legacy, avoid if possible
+
+| `aes192-cbc`
+| AES-192
+| CBC
+| Legacy
+
+| `aes256-cbc`
+| AES-256
+| CBC
+| Legacy, avoid if possible
+
+| `3des-cbc`
+| Triple DES
+| CBC
+| Deprecated
+
+| `blowfish-cbc`
+| Blowfish
+| CBC
+| Legacy
+|===
+
+NOTE: Unlike JSch, Apache MINA SSHD supports modern algorithms like
ChaCha20-Poly1305 and AES-GCM. Invalid cipher names are validated before
connecting.
+
+== Key Exchange Protocol Configuration
+
+Specify key exchange algorithms with the `keyExchangeProtocols` option:
+
+[source,java]
+----
+from("mina-sftp://user@host/path?password=secret&keyExchangeProtocols=curve25519-sha256,ecdh-sha2-nistp256";)
+ .to("file:local");
+----
+
+=== Available Key Exchange Protocols
+
+[cols="2,3,1"]
+|===
+| Protocol Name | Description | Recommended
+
+| `curve25519-sha256`
+| Modern Curve25519 with SHA-256
+| Yes
+
+| `[email protected]`
+| Curve25519 (libssh.org variant)
+| Yes
+
+| `curve448-sha512`
+| Curve448 with SHA-512
+| Yes
+
+| `ecdh-sha2-nistp256`
+| ECDH with NIST P-256
+| Yes
+
+| `ecdh-sha2-nistp384`
+| ECDH with NIST P-384
+| Yes
+
+| `ecdh-sha2-nistp521`
+| ECDH with NIST P-521
+| Yes
+
+| `diffie-hellman-group14-sha256`
+| DH Group14 (2048-bit) with SHA-256
+| Yes
+
+| `diffie-hellman-group16-sha512`
+| DH Group16 (4096-bit) with SHA-512
+| Yes
+
+| `diffie-hellman-group18-sha512`
+| DH Group18 (8192-bit) with SHA-512
+| Yes
+
+| `diffie-hellman-group-exchange-sha256`
+| DH Group Exchange with SHA-256
+| Yes
+
+| `diffie-hellman-group14-sha1`
+| DH Group14 with SHA-1
+| Deprecated
+
+| `diffie-hellman-group1-sha1`
+| DH Group1 (1024-bit) with SHA-1
+| Deprecated
+
+| `diffie-hellman-group-exchange-sha1`
+| DH Group Exchange with SHA-1
+| Deprecated
+|===
+
+== Server Host Key Configuration
+
+Specify accepted server host key algorithms with `serverHostKeys`:
+
+[source,java]
+----
+from("mina-sftp://user@host/path?password=secret&serverHostKeys=ssh-ed25519,rsa-sha2-512";)
+ .to("file:local");
+----
+
+=== Available Server Host Key Algorithms
+
+[cols="2,3,1"]
+|===
+| Algorithm Name | Description | Recommended
+
+| `ssh-ed25519`
+| EdDSA Ed25519 (modern, fast)
+| Yes
+
+| `rsa-sha2-512`
+| RSA with SHA-512
+| Yes
+
+| `rsa-sha2-256`
+| RSA with SHA-256
+| Yes
+
+| `ecdsa-sha2-nistp256`
+| ECDSA with NIST P-256
+| Yes
+
+| `ecdsa-sha2-nistp384`
+| ECDSA with NIST P-384
+| Yes
+
+| `ecdsa-sha2-nistp521`
+| ECDSA with NIST P-521
+| Yes
+
+| `ssh-rsa`
+| RSA with SHA-1
+| Deprecated
+
+| `ssh-dss`
+| DSA
+| Deprecated
+|===
+
+OpenSSH certificate variants are also supported (e.g.,
`[email protected]`, `[email protected]`).
+
+== Algorithm Security Recommendations
+
+=== Recommended Secure Configuration
+
+[source,java]
+----
+from("mina-sftp://user@host/path?password=secret";
+ +
"&keyExchangeProtocols=curve25519-sha256,ecdh-sha2-nistp256,diffie-hellman-group16-sha512"
+ + "&serverHostKeys=ssh-ed25519,rsa-sha2-512,ecdsa-sha2-nistp256"
+ +
"&[email protected],[email protected],aes256-ctr")
+ .to("file:local");
+----
+
+=== Algorithms to Avoid
+
+[cols="1,2"]
+|===
+| Algorithm | Reason
+
+| `diffie-hellman-group1-sha1`
+| 1024-bit DH is too weak; SHA-1 is deprecated
+
+| `diffie-hellman-group14-sha1`
+| SHA-1 is deprecated
+
+| `ssh-rsa`
+| Uses SHA-1 for signatures
+
+| `ssh-dss`
+| DSA is deprecated
+|===
+
+=== Compliance Considerations
+
+For FIPS/PCI-DSS compliance:
+
+* Use only NIST-approved curves (P-256, P-384, P-521) for ECDH and ECDSA
+* Use RSA with SHA-256 or SHA-512
+* Use AES-128 or AES-256 in CTR or GCM mode
+* Avoid Curve25519/Ed25519 if strict FIPS compliance is required
diff --git a/docs/components/modules/others/nav.adoc
b/docs/components/modules/others/nav.adoc
index dc45abedebf9..46a16218fc7b 100644
--- a/docs/components/modules/others/nav.adoc
+++ b/docs/components/modules/others/nav.adoc
@@ -57,6 +57,9 @@
** xref:microprofile-config.adoc[Microprofile Config]
** xref:microprofile-fault-tolerance.adoc[Microprofile Fault Tolerance]
** xref:microprofile-health.adoc[Microprofile Health]
+** xref:mina-sftp-authentication.adoc[MINA SFTP Authentication]
+** xref:mina-sftp-migration.adoc[MINA SFTP Migration from JSch]
+** xref:mina-sftp-security.adoc[MINA SFTP SSH Security]
** xref:oauth.adoc[Oauth]
** xref:observability-services.adoc[Observability Services]
** xref:openai-providers.adoc[OpenAI - Compatible Providers]
diff --git a/docs/components/modules/others/pages/mina-sftp-authentication.adoc
b/docs/components/modules/others/pages/mina-sftp-authentication.adoc
new file mode 120000
index 000000000000..d1c7b2f3df07
--- /dev/null
+++ b/docs/components/modules/others/pages/mina-sftp-authentication.adoc
@@ -0,0 +1 @@
+../../../../../components/camel-mina-sftp/src/main/docs/mina-sftp-authentication.adoc
\ No newline at end of file
diff --git a/docs/components/modules/others/pages/mina-sftp-migration.adoc
b/docs/components/modules/others/pages/mina-sftp-migration.adoc
new file mode 120000
index 000000000000..598e2eac4b02
--- /dev/null
+++ b/docs/components/modules/others/pages/mina-sftp-migration.adoc
@@ -0,0 +1 @@
+../../../../../components/camel-mina-sftp/src/main/docs/mina-sftp-migration.adoc
\ No newline at end of file
diff --git a/docs/components/modules/others/pages/mina-sftp-security.adoc
b/docs/components/modules/others/pages/mina-sftp-security.adoc
new file mode 120000
index 000000000000..ff5ec8b85797
--- /dev/null
+++ b/docs/components/modules/others/pages/mina-sftp-security.adoc
@@ -0,0 +1 @@
+../../../../../components/camel-mina-sftp/src/main/docs/mina-sftp-security.adoc
\ No newline at end of file
