{"id":7685,"library":"robotframework-sshlibrary","title":"Robot Framework SSHLibrary","description":"Robot Framework SSHLibrary is a test library for SSH and SFTP operations. It provides keywords for executing commands, interacting with interactive shells, transferring files and directories via SFTP, and asserting the existence of files and directories on remote machines. The library is operating system independent and currently supports Python 3.6 or newer (older versions like 3.8.0 also supported Python 2.7 and 3.4+). It maintains an active release cadence with regular updates and enhancements.","status":"active","version":"3.8.0","language":"en","source_language":"en","source_url":"https://github.com/robotframework/SSHLibrary","tags":["robot framework","ssh","sftp","testing","automation","paramiko"],"install":[{"cmd":"pip install robotframework-sshlibrary","lang":"bash","label":"Install for Python"},{"cmd":"apk add gcc make openssl-dev musl-dev libffi-dev && pip install robotframework-sshlibrary","lang":"bash","label":"Install for Alpine Linux (Docker)"}],"dependencies":[{"reason":"Core dependency for SSH communication in Python.","package":"paramiko","optional":false},{"reason":"Core dependency for SCP/SFTP file transfers in Python.","package":"scp","optional":false},{"reason":"Required by Paramiko for cryptographic operations (or PyCrypto for older Paramiko versions).","package":"cryptography","optional":false},{"reason":"Required for creating SSH tunnels (version > 1.2).","package":"robotbackgroundlogger","optional":true},{"reason":"Required when using SSHLibrary with Jython.","package":"Trilead SSH library","optional":false},{"reason":"Required on Windows operating systems when using Python versions older than 3.0.","package":"win_inet_pton","optional":true}],"imports":[{"note":"Robot Framework libraries are imported using the 'Library' setting in the Settings section of a .robot file, not with Python-style 'from import'.","wrong":"from SSHLibrary import SSHLibrary","symbol":"SSHLibrary","correct":"*** Settings ***\nLibrary    SSHLibrary"}],"quickstart":{"code":"*** Settings ***\nDocumentation    Demonstrates SSHLibrary connection and command execution.\nLibrary          SSHLibrary\n\n*** Variables ***\n${SSH_HOST}      ${OS_ENVIRONMENT_SSH_HOST}\n${SSH_PORT}      ${OS_ENVIRONMENT_SSH_PORT}\n${SSH_USERNAME}  ${OS_ENVIRONMENT_SSH_USERNAME}\n${SSH_PASSWORD}  ${OS_ENVIRONMENT_SSH_PASSWORD}\n\n*** Test Cases ***\nExecute Remote Command\n    [Tags]    SSH\n    Open Connection    ${SSH_HOST}    port=${SSH_PORT}\n    Login              ${SSH_USERNAME}    ${SSH_PASSWORD}\n    ${output}=         Execute Command    ls -l /tmp\n    Log To Console     Command Output: ${output}\n    Should Contain     ${output}          total\n    Close Connection\n","lang":"robotframework","description":"This example connects to a remote SSH server using environment variables for credentials, executes a simple `ls -l /tmp` command, logs the output, asserts a part of the output, and then closes the connection. Set `SSH_HOST`, `SSH_PORT`, `SSH_USERNAME`, and `SSH_PASSWORD` environment variables before running."},"warnings":[{"fix":"Ensure your Python environment matches the SSHLibrary version's requirements. Upgrade SSHLibrary and Python if necessary.","message":"SSHLibrary 3.0.0 introduced Python 3 support (Python 2.7, 3.4+). Older versions of SSHLibrary may not be compatible with newer Python 3 versions, and newer SSHLibrary versions (e.g., 3.8.0 onwards) officially support Python 3.6+.","severity":"breaking","affected_versions":"< 3.0.0 for Python 3; < 3.8.0 for Python 3.6+"},{"fix":"Update calls to `Login with Public Key` to use named arguments for `delay`.","message":"In SSHLibrary 3.0.0, the `Login with Public Key` keyword arguments changed. Specifically, the `delay` argument must now be provided as a named argument (e.g., `delay=1s`).","severity":"breaking","affected_versions":">= 3.0.0"},{"fix":"If using string boolean arguments (e.g., 'True', 'False', 'yes', 'no'), ensure to upgrade to SSHLibrary 3.1.0 or newer for correct boolean evaluation, especially for 'no'/'none' values.","message":"Prior to SSHLibrary 3.1.0, all non-empty strings, including 'no' and 'none', were considered `True` for boolean arguments. This behavior was aligned with Robot Framework 3.0.3, where 'none' is considered `False`.","severity":"breaking","affected_versions":"< 3.1.0"},{"fix":"Explicitly set timeouts. Use `Library SSHLibrary    timeout=30s` during import, `Open Connection    host=${HOST}    timeout=1min`, `Login    username=${USER}    password=${PASS}    delay=1s`, and `Execute Command    command    timeout=30s`.","message":"Connections or command executions can hang or time out (e.g., 'SSHLibrary Exception: Timeout opening tunnel') due to insufficient default timeouts or network latency.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Configure the `path_separator` during library import or using `Set Default Configuration` or `Open Connection`: `Library    SSHLibrary    path_separator=\\\\\\` or `Open Connection    ${HOST}    path_separator=\\\\\\`.","message":"The `path_separator` argument (used by keywords like `Get File`, `Put Directory`) defaults to '/' (Unix-like). On Windows SSH servers, this may need to be explicitly set to '\\\\' (doubled backslash in Robot Framework data) if the server uses backslashes.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Increase the timeout values for both library import and the `Open Connection` keyword. Example: `Library SSHLibrary    30s` and `Open Connection    ${HOST}    port=${PORT}    timeout=60s`.","cause":"The SSH connection could not be established or the tunnel creation timed out within the default or specified timeout period, often due to network issues or slow server response.","error":"SSHLibrary Exception: Timeout opening tunnel"},{"fix":"Double-check credentials. If using public key, verify key path and permissions. For password-less root logins, consider trying `pip uninstall paramiko` then `pip install paramiko-ng` as a workaround (as `paramiko` sometimes has issues with this specific scenario). Ensure the correct login keyword (`Login` vs. `Login With Public Key`) is used.","cause":"Incorrect username/password, invalid public key, server configuration issues (e.g., password-less login not working as expected), or incompatible Paramiko version.","error":"Authentication failed for user 'username'"},{"fix":"Ensure `Open Connection` and `Login` keywords are called successfully before any connection-dependent keywords. For example, `Open Connection    ${HOST}` followed by `Login    ${USERNAME}    ${PASSWORD}`.","cause":"Attempting to use SSHLibrary keywords that require an active connection (e.g., `Execute Command`, `Put File`) before a successful `Login` has occurred, or after a connection has been explicitly closed.","error":"Connection not open."},{"fix":"Verify the hostname is correct and reachable from the test runner machine. Use an IP address instead of a hostname if DNS resolution is problematic. Check network configuration and DNS settings.","cause":"The hostname provided to `Open Connection` cannot be resolved to an IP address by the system's DNS resolver.","error":"gaierror: [Errno -2] Name or service not known"},{"fix":"Robot Framework uses multiple spaces as a separator for arguments. Change `Open Connection    ${HOST},port=${PORT}` to `Open Connection    ${HOST}    port=${PORT}`.","cause":"Incorrect syntax when specifying the port argument in `Open Connection`. Using a comma instead of spaces between arguments.","error":"Logging into 'host,port=XXXX:22' as 'user'"}]}