ConnectorTypeSSH

class connector_types.connector_type_ssh.ConnectorTypeSSH

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

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
execution_id	int		The ID of the connection execution
files	dict		The names of the output files which were registered using #OUTPUT_FILE(path)
handler_report	str
message	str		The ended message for the connection. If the connection ended with an error, the message will contain information about what went wrong
report	str		The outputs your scripts produce on the remote systems
retcode	int
status	str		The ended status for the connection. Either "success" or "error".
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 ()

get_file (src, dst)

log (message)

one_of_inputs (options)

run ()

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['var']['HOSTNAME']
    username = outputs['var']['USERNAME']
    cpu = outputs['var']['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['var']['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')['var']['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['var']['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'