Documentation
This job is used to execute commands, programs and/or shell-scripts on a remote server by SSH.
For more information on SSH see:
How to use OpenSSH with JobScheduler
All related programs in JobScheduler use an implementation of Trilead on the client site. This requires to take some things into account.
Trilead requires a SSH protocol with at least version 3. All other versions are not supported.
SSH is a registered trademark of SSH Communications Security Corp in the United States and in certain other jurisdictions.
Authentication Methods
UserID and Password
This is the easiest and most popular method to authenticate a user. The user ID and a password is sent to the SSH server. Best of all, the password is encrypted before sending it to the server and decrypted at the server side. but, at the end, it is a password and if someone is able to decrypt he has opened the door to the server.
Note that the password authentication must be enabled in the SSH configuration file /etc/ssh/sshd_config:
PasswordAuthentication yes
Public and private Key
Passphrase: What it is and how to handle it
A passphrase is an additional protection of the key files, like a password. Every time you want to access a server by a passphrase protected key you have to enter the value of the passphrase as an additional authentication.
Note that the publickey authentication must be enabled in the /etc/ssh/sshd_config SSH configuration file:
PasswordAuthentication yes
In addition, the private SSH-Key must be in OpenSSH-Format.
Creating the public and private key
First we generate the key with ssh-keygen.
kb@wilma:~/.ssh> ssh-keygen -f my-key-set.id_dsa -t rsa
When ssh-keygen askes for a passphrase you can enter your passphrase to add it to the key. Or you can leave it blank. Remember, the longer and stronger you make your password, the harder it will be for any malicious h4x0r (or government agency) to decrypt it. Save the key to /home/username/.ssh/identity as recommended by the ssh-keygen program. You will also need to specify which encryption method (e.g. RSA, DSA) you want to use.
ssh-keygen generates an private OpenSSH key and a public key.
Generating public/private rsa1 key pair.
Enter file in which to save the key (/home/dave/.ssh/identity): /home/dave/.ssh/identity
Enter passphrase (empty for no passphrase): *enter your passphrase here*
Enter same passphrase again: *repeat your passphrase*
Your identification has been saved in
/home/dave/.ssh/identity.
Your public key has been saved in
/home/dave/.ssh/identity.pub.
The key fingerprint is:
24:bc:0b:fs:f5:06:1d:c0:05:3a:59:09:e3:07:8a:8d kb@wilma
The private key looks the the key in the lines below:
-----BEGIN RSA PRIVATE KEY----- Proc-Type: 4,ENCRYPTED DEK-Info: DES-EDE3-CBC,56C91DCFDF45E388 MxnhXdGMmnFlR2cmjtF690uIYKLZUlbfVcXWRYwgxH21k0K6zicRE2YUDiNGikCW GNjB97uObN8JEyykvbQaXFdu5UJKO5ydE7YmBk3n/I6WRo+gNCig9+ty0LIMOg0J NIsvCdUi3+2ldsz8TRSRYPY0uZ3ddymKjIzePDx2WiacTB3VAomx7s3HhoFIBuTA 7DwUJx0jDUsoF6vNs3LIZTOs/XuwRAttNRsKX2LFkAZpqRPjabohZ7HpQy2Y3yGF zv2kdAQXF769/YepaBzjEmt5OKx+NsWmi9DgaghhUsUZjPqZY+X/D8hXqCIMdSsB 5uPuKC/OjfuersZTiNK1hh288fuFD2phQ8aHu2RCfpFXB21Vh5A8Bg9ZO1pqHfU2 ngWrmdXOauOQxQ8+Pmh44N0dKPmmQ4sccpUgZe4aMplLKrarQOufcGX33JGAF0xc WyWjl14IZCpQdWbCO6rKEnWf6bgjuYyV9y2n6TjaIDgwMn3UV381LHCqxEsdERid X/at3BsPc2verLrN5qEDVpPJmdFr5WCghgds88DhuP8suQodbtlVidWj/rTd7fV+ 6RhsozJIkeCBwccQTJDJrMoTUi5eNwIO2g91Cjj7Fu2b3ir1lrOVg8OK5zsukFcY +Gcub8AJjOq8vRqNZ2o0SyXGcoORKIwqpMF9+IlaUGJ3n7THK4DbXwtzGeBIZiwH Gs4bzowFecPFh8PuvwUa1gIH+aPNsXZ0Jtkv72d3r9y9EBHNIkyh9KFDztFaFswY 2BdXcnDfNmsRbtVvH4kFb0h2R1M2aaXsJFl0mvCtaOM= -----END RSA PRIVATE KEY-----
If puTTYgen is used to create the priv/pub keys it is not an OpenSSH Key by default. To get an OpenSSH conform key you must export the private key to OpenSSH format.
If you want to use the private key in putty as well you have to convert the private key to the openSSH-format. This can be done with puTTYgen as well.
Moving the public key to the remote server
To be able to log in to remote systems using a pair of keys, you first have to add the public key on the remote server to the authorized_keys file in the .ssh/ directory in the home directory on the remote machine.
The Next action is to create a .ssh directory, and inside the .ssh/ directory create an authorized_keys file and add the public key to the file. Make sure the file is not readable for other users/groups. chmod 600 authorized_keys* does the trick.
[kb@wilma kb]$ mkdir .ssh
[kb@wilma kb]$ chmod 700 .ssh
[kb@wilma kb]$ cd .ssh
[kb@wilma .ssh]$ touch authorized_keys
[kb@wilma .ssh]$ chmod 600 authorized_keys
[kb@wilma .ssh]$ cat ../identity.pub >> authorized_keys
[kb@wilma .ssh]$ rm ../identity.pub
Further reading:
- http://www.oreilly.com/catalog/sshtdg/ SSH, The Secure Shell: The Definitive Guide written by Daniel J. Barret & Richard Silverman, published by O'Reilly
- http://www.openssh.org/manual.html OpenSSH manual
How to handle StdErr and ExitCode
The job knows some parameters to handle the stderr and the exit code. These are:
- ignore_stderr
- ignore_error
- ignore_exit_code
- raise_exception_on_error
As an example, we examine the command
ls _unknown_folder_; exit 5;
This command has a stderr = "ls: _unknown_folder_: No such file or directory" and the exit code 5.
| ignore_stdout | ignore_error | raise_exception_on_error | ExitCode of the command | ExitCode of the job's task | Order goes to... |
|---|---|---|---|---|---|
| false | false | true | 5 | 1 | error node |
| true | false | true | 5 | 1 | error node |
| false | true | true | 5 | 1 | error node |
| true | true | true | 5 | 0 | next node |
| false | false | false | 5 | 5 | next node |
| true | false | false | 5 | 5 | next node |
| false | true | false | 5 | 5 | next node |
| true | true | false | 5 | 0 | next node |
Further the job creates the parameters
- std_out_output
- std_err_output
- exit_code
If you use the job in a job chain then you can use these parameters in a next job of the job chain to handle the result.
Class
Name/ Title
JobSchedulerSSHJob Launch commands or executable files by SSH
Order Control
This job is triggered by orders or by standard job starts.
Script
- Language: java
- Name of Java Class: sos.scheduler.job.SOSSSHJob2JSAdapter
Configuration
Parameters
| Default | |||
|---|---|---|---|
| auth_file | [optional] | The value of this parameter specifies the path and name of a user's private key file used for authorisation on an SSH server. This parameter must be specified if the publickey authorization method has been specified in the auth_method parameter. Should the private key file be secured by a password, then this must be specified using the password parameter. | --- |
| auth_method | [optional] | publickey | |
| command | [optional] | This parameter specifies a command that is to be executed on the SSH server. Multiple commands can be separated by the command delimiter that is specified using the command_delimiter parameter. DataType: SOSOptionCommandString | --- |
| command_delimiter | [required] | %% | |
| command_script | [optional] | This parameter can be used as an alternative to command, command_delimiter and command_script_file. It contains scriptcode which will be transferred to the remote host as a file and will then be executed there. The script can access job and order parameters by environment variables. The names are in upper case and have "SCHEDULER_PARAM_" as a prefix. Order parameters with the same name overwrite task parameters. DataType: SOSOptionString | --- |
| command_script_file | [optional] | Script file name to Execute The value of this parameter contains the file-name (and path-name, if needed) of a local (script-)file, which will be transferred to the remote host and will then be executed there. The script can access job- and order-parameters by environment variables. The names of the environment variables are in upper case and have the string "SCHEDULER_PARAM_" as a prefix. Order parameters with the same name overwrite task parameters. This parameter can be used as an alternative to command, command_delimiter and command_script. ---- examples ---- example: usage of parameter command_script_file <job title="SSH example job" order="no"> <description > <include file="jobs/SOSSSHJob2JSAdapter.xml"/> </description> <params > <param name="host" value="wilma.sos"/> <param name="port" value="22"/> <param name="user" value="test"/> <param name="password" value="*****"/> <param name="auth_method" value="password"/> <param name="command_script_file" value="c:/temp/test.sh"/> </params> <script language="java" java_class="sos.scheduler.job.SOSSSHJob2JSAdapter"/> <run_time /> </job> <job title="SSH example job" order="no"> <description > <include file="jobs/SOSSSHJob2JSAdapter.xml"/> </description> <params > <param name="host" value="wilma.sos"/> <param name="port" value="22"/> <param name="user" value="test"/> <param name="password" value="*****"/> <param name="auth_method" value="password"/> <param name="command_script_file" value="c:/temp/test.sh"/> </params> <script language="java" java_class="sos.scheduler.job.SOSSSHJob2JSAdapter"/> <run_time /> </job> Die Parameter des SSH-Jobs sind in diesem Beispiel innerhalb des params-tags spezifiziert. Dabei ist für das auszuführende Skript ein Name einer Datei im lokalen Filesystem angegeben. Diese wird, falls vorhanden, zunächst auf den SSH-Host kopiert und dann dort ausgeführt. DataType: SOSOptionInFileName | --- |
| command_script_param | [optional] | This parameter contains a parameter string, which will be appended when calling the command_script or the command_script_file. | --- |
| host | [required] | Host-Name This parameter specifies the hostname (e.g. wilma.sos) or IP address (e.g. IPv4 192.168.0.1) of the (FTP, SFTP, SSH, SMTP, etc.) server to which a connection has to be made. DataType: SOSOptionHostName Alias: HostName | --- |
| port | [required] | Port-Number to be used for Data-Transfer Port by which files should be transferred. For FTP this is usually port 21, for SFTP this is usually port 22. DataType: SOSOptionPortNumber | 21 |
| ignore_error | [optional] | Should the value true be specified, then execution errors caused by commands on the SSH server are ignored. Otherwise such execution errors for jobs and orders are reported by the Job Scheduler. | false |
| ignore_exit_code | [optional] | This parameter configures one or more exit codes which will not be treated as errors. Multiple exit codes can be defined comma separated or using ranges. Examples: 255 2,3,4,100 4,50-60,210-220 | --- |
| ignore_hangup_signal | [required] | Ignore_Hangup_Signal With this parameter the behavior of the remote running job (Script, executable) will be influenced. If the job is killed by the JS-Operations-GUI, the running job will continue if the value of this parameter is set to true. http://en.wikipedia.org/wiki/Nohup and http://en.wikipedia.org/wiki/SIGHUP | true |
| ignore_signal | [optional] | Should the value true be specified, then on Unix systems all signals will be ignored that terminate the execution of a command on the SSH server - if for example a command is terminated using kill. Note that by default the Job Scheduler reports errors for commands that are terminated by signals. | false |
| ignore_stderr | [optional] | This job checks if any output to stderr has been created by a command that is being executed on the SSH server and reports this as an error. Should the value true be specified for this parameter, then output to stderr will not be reported as an error by the Job Scheduler. | false |
| raise_exception_on_error | [optional] | If any output to stderr has been created or the exit code is unequal 0 then the job usually throws an exception. Whenever the job throws an exception then its task ends with the exit code 1. If the job is started by an order and an exception is thrown then the order goes to the error node of the job chain. Should this value false be specified, then it prevents an exception is thrown, the task has the exit code of the command that is being executed on the SSH server and an order goes to the next node of the job chain. | true |
| password | [optional] | Password for UserID Password for authentication at the FTP/SFTP server. For SSH/SFTP connections that make use of public/private key authentication the password parameter is specified for the passphrase that optionally secures a private key. DataType: SOSOptionPassword | --- |
| proxy_host | [optional] | The value of this parameter is the host name or the IP address of a proxy used to create the connection to the SSH server. The use of a proxy is optional. | --- |
| proxy_password | [optional] | This parameter specifies the password for the proxy server user account, should a proxy be used to connect to the SSH server. | --- |
| proxy_port | [optional] | This parameter specifies the port number of the proxy, should a proxy be used to create the connection to the SSH server. | --- |
| proxy_user | [optional] | The value of this parameter specifies the user account for authorization by the proxy server should a proxy be used to connect to the SSH server. | --- |
| simulate_shell | [optional] | Should the value true be specified for this parameter, then a login to a shell is simulated to execute commands. Some scripts may cause problems if no shell is present. The parameter simulate_shell_prompt_trigger must be specified if this parameter is used. | false |
| simulate_shell_inactivity_timeout | [optional] | If no new characters are written to stdout or stderr after the given number of milliseconds, the job assumes that that the command has been carried out and the shell is waiting for commands. | --- |
| simulate_shell_login_timeout | [optional] | If no new characters are written to stdout or stderr after the given number of milliseconds, the job assumes that that the login has been carried out and the shell is waiting for commands. | |
| simulate_shell_prompt_trigger | [optional] | The expected command line prompt. Using this prompt the job tries to find out if commands may be entered or have been carried out. If no prompt can be configured, timeout parameters have to be used. | --- |
| user | [required] | UserID of user in charge User name for authentication at the (FTP/SFTP) server. DataType: SOSOptionUserName | anonymous |
| preCommand | [optional] | This parameter specifies the command to set an environmental variable on the remote host. default: 'export' | --- |
| postCommandRead | [optional] | This parameter specifies the command to read the content of a file on the remote host. The content will then be written to stdout of the remote host. The command reads return values from a temporary file. default: 'cat' | --- |
| postCommandDelete | [optional] | This parameter specifies the command to delete a file on the remote host. The command deletes a temporary file after proccessing. default: 'rm' | --- |
| ssh_job_kill_pid_command | [optional] | The os specific command to to kill a remote running pid. | --- |
| ssh_job_terminate_pid_command | [optional] | The os specific command to to terminate a remote running pid. | --- |
| ssh_job_get_pid_command | [optional] | The os specific command to get the PID of the active shell. | --- |
| ssh_job_get_active_processes_command | [optional] | The command to check if the given process is still running. | --- |
| ssh_job_get_child_processes_command | [optional] | The command to get the child processes related to the given pid. | --- |
| ssh_job_timeout_kill_after | [optional] | The timeout in seconds after which a kill signal will be send. | --- |
| runWithWatchdog | [optional] | This parameter activates ssh session management. | --- |
| create_environment_variables | [optional] | This parameter can be used to activate transmission of JobScheduler-parameters as ssh environment variables. | --- |
| cleanupJobchain | [optional] | This parameter is used to determine the name of the jobchain for cleanup. | --- |
Return Parameters
| Default | |||
|---|---|---|---|
| std_out_output | [optional] | Content of STDOUT The output of the process into STDOUT is reported as the value of this parameter. | --- |
| std_err_output | [optional] | Content of STDERR The output of the process into STDERR is reported as the value of this parameter. | --- |
| exit_code | [optional] | Job exit code The exit code of the process is the value of this parameter. The exit code is zero if the process ended without any error. DataType: SOSOptionString | --- |
Releases
1.0
Version 1.0 - 2010-07-01
2010-07-01
[Last Changes 2010-07-01]
Klaus Buttner kb@sos-berlin.com
Comment
Refactoring of former Version
Resources
| Filename | Type | OS | Comment | Source documentation | |
|---|---|---|---|---|---|
| com.sos.scheduler-*.jar | java | all | Source: scheduler (http://www.sos-berlin.com/doc/doxygen-docs/scheduler/html/index.html) | ||
| com.sos.spooler-*.jar | java | all | |||
| com.sos.util-*.jar | java | all | Classes SOSFile, SOSSchedulerLogger | Source: com.sos.util (http://www.sos-berlin.com/doc/doxygen-docs/com.sos.util/html/index.html) | |
| trilead-ssh2.jar | java | all | SSH2 library by Trilead: info@trilead.com, (www.trilead.com) |