Remote Access plugin

With this plugin, the CloudBees CD/RO server and securely connect to a remote host to remotely execute commands, transfer files, and run scripts.

Plugin version 2.0.0.2022072113

Revised on July 21, 2022

Supported operating systems

This plugin has been tested with the following Operating Systems on the Remote Host.

Ubuntu
Solaris
RHEL
Debian

The OS of the CloudBees CD/RO Server and Agent used to execute the plugin can be either Linux or Windows.

Document convention

All mandatory/required parameters in all procedures (including Configuration Procedure) are marked in bold italics.

Plugin configurations

Plugin configurations are sets of parameters that apply across some or all of the plugin procedures. They reduce repetition of common values, create predefined parameter sets for end users, and securely store credentials where needed. Each configuration is given a unique name that is entered in designated parameters on procedures that use them.

Creating plugin configurations

To create plugin configurations in CloudBees CD/RO, do these steps:

Go to Administration Plugins to open the Plugin Manager.
Find the EC-RemoteAccess-2.0.0.2022072113 row.
Click Configure to open the Configurations page.
Click Create Configuration as per the description of parameters below.

Configuration procedure parameters

Parameter Description

Parameter	Description
CloudBees CD/RO Information
Configuration:	Required. Unique name for the plugin configuration.
Description:	Description for the plugin configuration.
Log Level:	Obsolete field. Will be ignored. 'Debug level' is used instead
Remote Host Details
Host Address:	Required. Remote Host address.
Port:	Port for SSH connection.
OS:	Required. OS of the Remote Host. Currently, the only value supported is Linux.
Script Destination Directory:	Directory on remote machine where temporary script file created by the plugin will be transferred to. This file will be removed after its execution. This directory is required to have the correct permissions to enable both the Connection user and the Target user to use it.
Remote Action
Remote Action:	Required. Type of Remote action. Currently, the only value supported is Execute Command.
Connection Protocol
Protocol:	Required. Type of connection protocol. Currently, the only value supported is SSH.
File Transfer Type:	Required. Indicates the File Transfer Type used to transfer the plugin created temporary script file. Supported values are SFTP and SCP.
Connection Details
Connect With:	Type of User Authentication. Supported values are password, private key and private key file.
Connect Credential (Username and Password):	Username and password to connect.
Connect Credential (Username and Private Key):	Username and private key to connect.
Connect Credential (Username and Private Key File):	Username and private key file to connect.
Private Key Passphrase:	Passphrase used along with the private key. This parameter applies only when the connect uses a private key or a private key file.
Target User Information
Is Target User Same as Connection User?	If checked the plugin will execute commands as the Connection User. In this case, the plugin will not prefix SUDO or SU before executing the command. Default is Yes.
Target User Runas Identity:	Applies only when the Target User is not the same as Connection User. Plugin will add a prefix as follows before executing the command, based on the Value chosen for this parameter. If Value = SUDO, plugin will perform the following:`sudo [command]` If Value = SU, plugin will perform the following: `su -c [command]` If Value = SUDO WITH USERNAME, plugin will perform the following: `sudo -u [TargetUserName] [command]` If Value = SU WITH USERNAME, plugin will perform the following: `su - [TargetUserName] -c [command]`
Target Username	Applies only when "Is Target User Same as Connection User?" is 'false' and "Target User Runas Identity" is either "SUDO WITH USERNAME" or "SU WITH USERNAME".
Interactivity Information
Is Interactive Mode Enabled?	If Yes, plugin will look for prompts thrown in the standard output by the script that the plugin executes. For example the executing script could expect an argument supplied to it interactively during its execution. Default is No.
Prompt Pattern Type:	Applies only when Inter active mode is enabled. Indicates if the prompt thrown by the script is a Credential or Plain Text. If the prompt is a Credential values supplied to it would be considered a secret and will not be surfaced anywhere in CloudBees CD/RO (either in the UI or Logs). Default is Credential.
Prompt Pattern:	Applies only when Interactive mode is enabled. Can be either an exact string or a pattern the plugin will look for. For example password: or .[Pp]assword.:
Prompt Pattern Value (Credential):	Applies only when Interactive mode is enabled. The value that the plugin will supply to the prompt any time the prompt matches the Prompt Pattern parameter and the Prompt pattern type is Credential.
Prompt Pattern Value (Plain Text):	Applies only when Interactive mode is enabled. The value that the plugin will supply to the prompt any time the prompt matches the Prompt Pattern parameter and the Prompt pattern type is Plain Text.
Check Connection?	If checked, the connection endpoint and credentials entered as part of the configuration will be tested. If this option is checked, configuration will not be saved if the test fails.
Debug Level	This option sets debug level for logs. If info is selected, only summary information will be shown, for debug, there will be some debug information and for trace the whole requests and responses will be shown.

CloudBees CD/RO Information

Configuration:

Required. Unique name for the plugin configuration.

Description:

Description for the plugin configuration.

Log Level:

Obsolete field. Will be ignored. 'Debug level' is used instead

Remote Host Details

Host Address:

Required. Remote Host address.

Port:

Port for SSH connection.

OS:

Required. OS of the Remote Host. Currently, the only value supported is Linux.

Script Destination Directory:

Directory on remote machine where temporary script file created by the plugin will be transferred to. This file will be removed after its execution. This directory is required to have the correct permissions to enable both the Connection user and the Target user to use it.

Remote Action

Remote Action:

Required. Type of Remote action. Currently, the only value supported is Execute Command.

Connection Protocol

Protocol:

Required. Type of connection protocol. Currently, the only value supported is SSH.

File Transfer Type:

Required. Indicates the File Transfer Type used to transfer the plugin created temporary script file. Supported values are SFTP and SCP.

Connection Details

Connect With:

Type of User Authentication. Supported values are password, private key and private key file.

Connect Credential (Username and Password):

Username and password to connect.

Connect Credential (Username and Private Key):

Username and private key to connect.

Connect Credential (Username and Private Key File):

Username and private key file to connect.

Private Key Passphrase:

Passphrase used along with the private key. This parameter applies only when the connect uses a private key or a private key file.

Target User Information

Is Target User Same as Connection User?

If checked the plugin will execute commands as the Connection User. In this case, the plugin will not prefix SUDO or SU before executing the command. Default is Yes.

Target User Runas Identity:

Applies only when the Target User is not the same as Connection User. Plugin will add a prefix as follows before executing the command, based on the Value chosen for this parameter. If Value = SUDO, plugin will perform the following:`sudo [command]`

If Value = SU, plugin will perform the following: su -c [command]

If Value = SUDO WITH USERNAME, plugin will perform the following: sudo -u [TargetUserName] [command]

If Value = SU WITH USERNAME, plugin will perform the following: su - [TargetUserName] -c [command]

Target Username

Applies only when "Is Target User Same as Connection User?" is 'false' and "Target User Runas Identity" is either "SUDO WITH USERNAME" or "SU WITH USERNAME".

Interactivity Information

Is Interactive Mode Enabled?

If Yes, plugin will look for prompts thrown in the standard output by the script that the plugin executes. For example the executing script could expect an argument supplied to it interactively during its execution. Default is No.

Prompt Pattern Type:

Applies only when Inter active mode is enabled. Indicates if the prompt thrown by the script is a Credential or Plain Text. If the prompt is a Credential values supplied to it would be considered a secret and will not be surfaced anywhere in CloudBees CD/RO (either in the UI or Logs). Default is Credential.

Prompt Pattern:

Applies only when Interactive mode is enabled. Can be either an exact string or a pattern the plugin will look for. For example password: or .[Pp]assword.:

Prompt Pattern Value (Credential):

Applies only when Interactive mode is enabled. The value that the plugin will supply to the prompt any time the prompt matches the Prompt Pattern parameter and the Prompt pattern type is Credential.

Prompt Pattern Value (Plain Text):

Applies only when Interactive mode is enabled. The value that the plugin will supply to the prompt any time the prompt matches the Prompt Pattern parameter and the Prompt pattern type is Plain Text.

Check Connection?

If checked, the connection endpoint and credentials entered as part of the configuration will be tested. If this option is checked, configuration will not be saved if the test fails.

Debug Level

This option sets debug level for logs. If info is selected, only summary information will be shown, for debug, there will be some debug information and for trace the whole requests and responses will be shown.

Plugin procedures

Run Custom Command

Use this procedure to execute a command on a remote host.

Run Custom Command parameters

Parameter	Description
Configuration Name	Previously defined configuration for the plugin
Script:	Required. Enter either a single command or the contents of a script that needs to be executed. For example this could be a single command like hostname or a script as follows #!/bin/bash echo "Hello World" >> /tmp/test In both cases above, the plugin would transfer the contents as a script to be executed on the Remote Host.
Remote Path:	Path on the Remote Host where the plugin will execute the script. Default will be the default directory when connecting to remote machine by specific user. This directory is required to have the correct permissions to enable both the Connection user and the Target user to use it.
Result Property Path:	If provided command output, error output and exit value will be stored in properties whose names are remoteCommandOutput, remoteCommandErrorOutput and remoteCommandExitValue respectively.

Parameter

Description

Configuration Name

Previously defined configuration for the plugin

Script:

Required. Enter either a single command or the contents of a script that needs to be executed. For example this could be a single command like hostname or a script as follows

#!/bin/bash

echo "Hello World" >> /tmp/test

In both cases above, the plugin would transfer the contents as a script to be executed on the Remote Host.

Remote Path:

Path on the Remote Host where the plugin will execute the script. Default will be the default directory when connecting to remote machine by specific user. This directory is required to have the correct permissions to enable both the Connection user and the Target user to use it.

Result Property Path:

If provided command output, error output and exit value will be stored in properties whose names are remoteCommandOutput, remoteCommandErrorOutput and remoteCommandExitValue respectively.

Known issues

When the Run Custom Command procedure is executed in interactive mode, the plugin cannot distinguish between the command output versus errors in stdout. Consequently, both are reported in the remoteCommandOutput parameter and no warning is reported in the Job Summary if errors are returned in stdout when the command has otherwise succeeded.
During the connection check, if Interactivity information is specified incorrectly and a different Target User is used, it can lead to an endless connection check. In this case, a running job can be manually aborted.

Release notes

EC-RemoteAccess 2.0.0

Ported the plugin to PDK.
Added usage for new configurations.

EC-RemoteAccess 1.2.6

Updated logger

EC-RemoteAccess 1.2.5

Updated dependencies

EC-RemoteAccess 1.2.4

The documentation has been migrated to the main documentation site.

EC-RemoteAccess 1.2.3

Updated logger to slf4j.

EC-RemoteAccess 1.2.2

Renaming to "CloudBees".

EC-RemoteAccess 1.2.1

Fixed Plugin Dependency Management to work with Gateways.

EC-RemoteAccess 1.2.0

Add checking connection while creating/editing a configuration.
Fixed issues in the RunCustomCommand procedure when Flow Agent runs on Java 11.

EC-RemoteAccess 1.1.0

Provisioning of Binary Dependencies (for example Grape jars) in the agent resource, required by this plugin, is now delivered through a newly introduced mechanism called Plugin Dependency Management. Binary dependencies will now be seamlessly delivered to the agent resource from the Flow Server, any time a new version of a plugin is invoked the first time. Flow Repository set up is no longer required for this plugin.

EC-RemoteAccess 1.0.1

Renaming to "CloudBees CD/RO".

EC-RemoteAccess 1.0.0

First release.