ConnectorTypeSSH

class connector_types.connector_type_ssh.ConnectorTypeSSH

Connect to a remote host using SSH and execute a script.

note

Cancelling an active execution created by an SSH connector might not be possible if the third party system, that is running the script, doesn't respond. In this case Cloudomation sends the signal to cancel the process on the third party system but as long as the script is running on said system, the execution status will be shown a running in Cloudomation. To cancel the execution you have to kill the process directly in the non-responsive system.

Inputs

Name	Type	Default	Description
connect_timeout	Number	60	How long to wait for a response from the server. Only applies after a successful connection. If a connection is impossible the connection fails immediately.
connect_tries	Number	3	How many times to try to connect.
copy_files	set	None
encoding	str	utf-8	The character encoding used on the remote host.
hostkey	String		The content of the ssh known hosts file, whether [host] [type] [key] - or [type] [key], a [comment] may be present after the [key]. Can be False to disable host key checking
hostname	String
interpreter	str	/usr/bin/env bash -e
key	String	None	The content of the ssh private keyfile associated with the repository, currently only works with non-password protected keyfiles.
output_files	set	None
output_vars	set	None
password	String	None
port	Number	22
remove_ansi_escapes	bool	False
remove_cr	bool	True
script	String
script_timeout	int	60
temp_path	str	/tmp
use_shell	bool	False
username	String

Outputs

Name	Type	Default	Description
files	dict		The names of the output files which were registered using #OUTPUT_FILE(path)
handler_report	str
report	str		The outputs your scripts produce on the remote systems
retcode	int
vars	dict		The content of all variables which were registered using #OUTPUT_VAR(variable)
waiter_report	str

Constants

input_list = ['connect_timeout', 'connect_tries', 'copy_files', 'encoding', 'hostkey', 'hostname', 'interpreter', 'key', 'output_files', 'output_vars', 'password', 'port', 'remove_ansi_escapes', 'remove_cr', 'script', 'script_timeout', 'temp_path', 'use_shell', 'username'] output_list = ['files', 'handler_report', 'report', 'retcode', 'vars', 'waiter_report'] ssl_context_inputs = ['check_hostname', 'client_cert', 'client_key', 'server_ca'] version = 1

Methods

execute

details

get_file

details

log

details

one_of_inputs

details

run

details

Example

import flow_api

def handler(system: flow_api.System, this: flow_api.Execution):
    # Authenticate using private key
    info_child = this.connect(
        connector_type='SSH',
        # public accessible name or IP
        hostname='my-ssh-server',
        # key to check host identity.
        # can be read with "$ ssh-keyscan -t rsa <my-ssh-server>"
        hostkey='ssh-rsa AAAAB3NzaC1yc2E...',
        username='kevin',
        key='-----BEGIN RSA PRIVATE KEY-----\nMII...',
        script=(
            '''
            HOSTNAME=$(hostname)
            USERNAME=$(id -un)
            CPU=$(uname -p)
            #OUTPUT_VAR(HOSTNAME)
            #OUTPUT_VAR(USERNAME)
            #OUTPUT_VAR(CPU)
            '''
        ),
    )

    outputs = info_child.get('output_value')
    hostname = outputs['vars']['HOSTNAME']
    username = outputs['vars']['USERNAME']
    cpu = outputs['vars']['CPU']

    this.log(f'info_child was running on {hostname} using {cpu} as {username}')

    # Authenticate using password
    uptime_child = this.connect(
        connector_type='SSH',
        hostname='my-ssh-server',
        hostkey='ssh-rsa AAAAB3NzaC1yc2E...',
        username='kevin',
        password='***',
        script=(
            '''
            UPTIME=$(uptime -s)
            #OUTPUT_VAR(UPTIME)
            '''
        ),
    )

    outputs = uptime_child.get('output_value')
    uptime = outputs['vars']['UPTIME']

    this.log(f'{hostname} is up since {uptime}')

    return this.success('all done')

More

Output variables

There are two ways how to define "output variables":

• from the flow starting the connection, in the output_vars field of the input dictionary
• from inside the connection, in the script field of the input dictionary

Output variables in output_vars

You can register shell variables as "output variables" in the output_vars field of the input dictionary, e.g.:

child_execution = this.connect(
    connector_type='SSH',
    hostname='my-ssh-server',
    hostkey='ssh-rsa AAAAB3NzaC1yc2E...',
    username='kevin',
    key='-----BEGIN RSA PRIVATE KEY-----\nMII...',
    script='''
        VALUE=foo
        ''',
    name='output_var',
    output_vars=['VALUE'],
)
assert child_execution.get('output_value')['vars']['VALUE'] == 'foo'

Output variables in script

You can register shell variables as "output variables" using #OUTPUT_VAR(variable_name):

VARIABLE="some content"
#OUTPUT_VAR(VARIABLE)

The value of registered variables is available to the calling flow script in the var dictionary of the connection outputs:

outputs = connect(...).get('output_value')
variable = outputs['vars']['VARIABLE']
# `variable` contains "some content"

Output files

There are two ways how to define "output files":

• from the flow starting the connection, in the output_files field of the input dictionary
• from inside the connection, in the script field of the input dictionary

Output files in output_files

You can register files as "output files" in the output_files field of the input dictionary, e.g.:

child_execution = this.connect(
    connector_type='SSH',
    hostname='my-ssh-server',
    hostkey='ssh-rsa AAAAB3NzaC1yc2E...',
    username='kevin',
    key='-----BEGIN RSA PRIVATE KEY-----\nMII...',
    script='''
        echo -n "spam" > file.txt
        ''',
    name='output_var',
    output_files=['file.txt'],
)
assert 'file.txt' in child_execution.get('output_value')['files']
assert system.file('file.txt').get_text_content() == 'spam'

Output files in script

You can register files as "output files" using #OUTPUT_FILE(filename):

child_execution = this.connect(
    connector_type='SSH',
    hostname='my-ssh-server',
    hostkey='ssh-rsa AAAAB3NzaC1yc2E...',
    username='kevin',
    key='-----BEGIN RSA PRIVATE KEY-----\nMII...',
    script='''
        echo -n "egg" > file2.txt
        #OUTPUT_FILE(file2.txt)
        ''',
    name='output_var',
)
assert 'file2.txt' in child_execution.get('output_value')['files']
assert system.file('file2.txt').get_text_content() == 'egg'