components/camel-ssh/src/main/docs/ssh-component.adoc

= SSH Component
:doctitle: SSH
:shortname: ssh
:artifactid: camel-ssh
:description: Execute commands on remote hosts using SSH.
:since: 2.10
:supportlevel: Stable
:tabs-sync-option:
:component-header: Both producer and consumer are supported
//Manually maintained attributes
:camel-spring-boot-name: ssh

*Since Camel {since}*

*{component-header}*

The SSH component enables access to SSH servers such that you can send
an SSH command, and process the response.

Maven users will need to add the following dependency to their `pom.xml`
for this component:

[source,xml]
------------------------------------------------------------
<dependency>
    <groupId>org.apache.camel</groupId>
    <artifactId>camel-ssh</artifactId>
    <version>x.x.x</version>
    <!-- use the same version as your Camel core version -->
</dependency>
------------------------------------------------------------

== URI format

-----------------------------------------------
ssh:[username[:password]@]host[:port][?options]
-----------------------------------------------



// component-configure options: START

// component-configure options: END

// component options: START
include::partial$component-configure-options.adoc[]
include::partial$component-endpoint-options.adoc[]
// component options: END

// endpoint options: START

// endpoint options: END
// component headers: START
include::partial$component-endpoint-headers.adoc[]
// component headers: END

== Usage as a Producer endpoint

When the SSH Component is used as a Producer (`.to("ssh://...")`), it
will send the message body as the command to execute on the remote SSH
server.

Here is an example of this within the XML DSL. Note that the command has
an XML encoded newline (`+&#10;+`).

[source,xml]
----------------------------------------------
<route id="camel-example-ssh-producer">
  <from uri="direct:exampleSshProducer"/>
  <setBody>
    <constant>features:list&#10;</constant>
  </setBody>
  <to uri="ssh://karaf:karaf@localhost:8101"/>
  <log message="${body}"/>
</route>
----------------------------------------------

== Authentication

The SSH Component can authenticate against the remote SSH server using
one of two mechanisms: Public Key certificate or username/password.
Configuring how the SSH Component does authentication is based on how
and which options are set.

1.  First, it will look to see if the `certResource` option has been
set, and if so, use it to locate the referenced Public Key certificate
and use that for authentication.
2.  If `certResource` is not set, it will look to see if a
`keyPairProvider` has been set, and if so, it will use that for
certificate based authentication.
3.  If neither `certResource` nor `keyPairProvider` are set, it will use
the `username` and `password` options for authentication. Even though the `username` 
and `password` are provided in the endpoint configuration and headers set with 
`SshConstants.USERNAME_HEADER` (`CamelSshUsername`) and 
`SshConstants.PASSWORD_HEADER` (`CamelSshPassword`), the endpoint 
configuration is surpassed and credentials set in the headers are used.

The following route fragment shows an SSH polling consumer using a
certificate from the classpath.

In the XML DSL,

[source,xml]
-------------------------------------------------------------------------------------------------------------------------------------------------
<route>
  <from uri="ssh://scott@localhost:8101?certResource=classpath:test_rsa&amp;useFixedDelay=true&amp;delay=5000&amp;pollCommand=features:list%0A"/>
  <log message="${body}"/>
</route>
-------------------------------------------------------------------------------------------------------------------------------------------------

In the Java DSL,

[source,java]
-----------------------------------------------------------------------------------------------------------------------------
from("ssh://scott@localhost:8101?certResource=classpath:test_rsa&useFixedDelay=true&delay=5000&pollCommand=features:list%0A")
    .log("${body}");
-----------------------------------------------------------------------------------------------------------------------------

An example of using Public Key authentication is provided in
`examples/camel-example-ssh-security`.

[[SSH-CertificateDependencies]]
== Certificate Dependencies

You will need to add some additional runtime dependencies if you use
certificate based authentication. You may need to use later versions depending what version
of Camel you are using.

The component uses `sshd-core` library which is based on either `bouncycastle` or `eddsa` security providers. `camel-ssh` is picking explicitly `bouncycastle` as security provider.

[source,xml]
-----------------------------------------
<dependency>
  <groupId>org.apache.sshd</groupId>
  <artifactId>sshd-core</artifactId>
  <version>2.8.0</version>
</dependency>
<dependency>
  <groupId>org.bouncycastle</groupId>
  <artifactId>bcpg-jdk18on</artifactId>
  <version>1.71</version>
</dependency>
<dependency>
  <groupId>org.bouncycastle</groupId>
  <artifactId>bcpkix-jdk18on</artifactId>
  <version>1.71</version>
</dependency>
-----------------------------------------



include::spring-boot:partial$starter.adoc[]