SSH Sink
Provided by: "Apache Software Foundation"
Support Level for this Kamelet is: "Stable"
Runs the text of each message as a command on a remote server over SSH, and returns what the command prints.
Use it to run a script or a maintenance command on a server when something happens, for example restart a service after a deployment or clear a cache when data changes. To run a fixed command on a schedule and read its output, use ssh-source; to run a command on the machine of the integration, use exec-sink.
Input: the body is the command to run, as text, such as systemctl restart myapp. It runs in the shell of username, so it can hold several commands separated by ;.
Output: the body afterwards is what the command printed on its standard output, as a stream. The CamelSshExitValue header holds the exit code of the command, and CamelSshStderr what it printed on its standard error, as a stream.
Good to know: it runs whatever command it receives, with the rights of username. Never send it messages from an untrusted source, and log in with an account that may do only what is needed. A command that ends with an exit code other than 0 does not fail the message: check CamelSshExitValue. Log in with password, or with a private key in privateKeyResource when the server does not take passwords; when a key is set, the password is not used. The key of the server is checked only when knownHostsResource is set; without it, any server is accepted. A server that is not listed in that file is still accepted, unless failOnUnknownHost is true.
Configuration Options
The following table summarizes the configuration options available for the ssh-sink Kamelet:
| Property | Name | Description | Type | Default | Example |
|---|---|---|---|---|---|
Connection Host | Required The host name or IP address of the SSH server, without a port. | string | server.example.com | ||
Connection Port | Required The port of the SSH server, usually 22. | string | 22 | ||
Username | Required The user to log in as. The commands run with the rights of this user. | string | |||
Connect Timeout | How long to wait for the connection, for the login and for the command to start, each in milliseconds. It does not limit how long the command runs. When it is not set, it is 30000, which is 30 seconds. | integer | 10000 | ||
Fail On Unknown Host | If true, a server that is not listed in | boolean | |||
Known Hosts Resource | A known_hosts file that holds the key of the server, starting with | string | file:/etc/ssh/known_hosts | ||
Password | The password of | string | |||
Private Key Passphrase | The passphrase of the key in | string | |||
Private Key Resource | A private key to log in with instead of a password, starting with | string | file:/etc/ssh-keys/id_ed25519 |
Dependencies
At runtime, the ssh-sink Kamelet relies upon the presence of the following dependencies:
-
camel:ssh
-
camel:gson
-
camel:kamelet
Camel JBang usage
Prerequisites
-
You’ve installed JBang.
-
You have executed the following command:
jbang app install camel@apache/camel Supposing you have a file named route.yaml with this content:
- route:
from:
uri: "kamelet:timer-source"
parameters:
period: 10000
message: 'test'
steps:
- to:
uri: "kamelet:ssh-sink" You can now run it directly through the following command
camel run route.yaml SSH Sink Kamelet Description
Secure Shell Integration
This Kamelet provides integration with SSH (Secure Shell) for executing remote commands and operations on remote systems over encrypted connections.
Remote Command Execution
The body of each message is run as a command in the shell of username, and the body afterwards is what the command printed on its standard output. The exit code is in the CamelSshExitValue header and the standard error in CamelSshStderr; an exit code other than 0 does not fail the message. The Kamelet runs whatever command it receives, so never place it after messages from an untrusted source.
Authentication Methods
The Kamelet logs in as username, either with password or with a private key in privateKeyResource. Use the key when the server does not take passwords. When a key is set, the password is not used.
-
privateKeyResourceis where to read the key from:file:followed by the path of the key file,classpath:,http:orhttps:. OpenSSH keys, such as those made withssh-keygen, and PEM keys can be read. The matching public key must be in theauthorized_keysfile ofusernameon the server. -
privateKeyPassphraseis the passphrase of the key, when it has one.
The key of the server is checked only when knownHostsResource is set; without it, any server is accepted. A server that is not listed in that file is still accepted, unless failOnUnknownHost is true. A server that is listed with another key is always refused. The lines of the file can be made with ssh-keyscan, such as ssh-keyscan -p 22 server.example.com > known_hosts.
connectTimeout is how long to wait for the connection, for the login and for the command to start, in milliseconds (30000 when it is not set). It does not limit how long the command runs.
Example with a Private Key
- route:
from:
uri: "kamelet:webhook-source"
parameters:
subpath: "restart"
steps:
- setBody:
constant: "systemctl restart myapp"
- to:
uri: "kamelet:ssh-sink"
parameters:
connectionHost: "server.example.com"
connectionPort: "22"
username: "deploy"
privateKeyResource: "file:/etc/ssh-keys/id_ed25519"
privateKeyPassphrase: "{{ssh.key.passphrase}}"
knownHostsResource: "file:/etc/ssh-keys/known_hosts"
failOnUnknownHost: true The command is fixed in the route, not taken from the request, so that callers of the webhook cannot choose what runs on the server.
Security Features
SSH provides comprehensive security features:
-
Strong encryption for all communications
-
Host key verification, when
knownHostsResourceis set -
Login with a private key, when
privateKeyResourceis set -
User authentication and authorization
-
Session integrity and confidentiality