Closes all open connections.

This keyword is ought to be used either in test or suite teardown to make sure all the connections are closed before the test execution finishes.

After this keyword, the connection indices returned by Open Connection are reset and start from 1.

Usage

Closes the current connection.

No other connection is made active by this keyword. Manually use Switch Connection to switch to another connection.

Usage

The keyword uses the existing connection to set up local port forwarding (the openssh -L option) from a local port through a tunneled connection to a destination reachable from the SSH server machine.

Arguments

The example below illustrates the forwarding from the local machine, of the connection on port 80 of an inaccessible server (secure.server.com) by connecting to a remote SSH server (remote.server.com) that has access to the secure server, and makes it available locally, on the port 9191:

The tunnel is active as long as the connection is open.

The default remote_port is 22.

By default, anyone can connect on the specified port on the SSH client because the local machine listens on all interfaces. Access can be restricted by specifying a bind_address. Setting bind_address does not work with Jython.

Usage

bind_address is new in SSHLibrary 3.3.0.

Fails if the given path does not point to an existing directory.

Arguments

Supports wildcard expansions described in glob patterns, but only on the current directory.

Usage

Note that symlinks are followed:

Fails if the given path points to an existing directory.

Arguments

Supports wildcard expansions described in glob patterns, but only on the current directory.

Usage

Note that this keyword follows symlinks. Thus the example fails if /non/existing is a link that points to an existing directory.

Enables logging of SSH protocol output to given logfile.

Arguments

All the existing and upcoming connections are logged onwards from the moment the keyword was called.

logfile is path to a file that is writable by the current local user. If the file already exists, it will be overwritten.

Usage

Note: This keyword does not work when using Jython.

Executes command on the remote machine and returns its outputs.

Arguments

This keyword executes the command and returns after the execution has been finished. Use Start Command if the command should be started in the background.

By default, only the standard output is returned:

Arguments return_stdout, return_stderr and return_rc are used to specify, what is returned by this keyword. If several arguments evaluate to a true value (see Boolean arguments), multiple values are returned.

If errors are needed as well, set the respective argument value to true:

Often checking the return code is enough:

Arguments sudo and sudo_password are used for executing commands within a sudo session. Due to different permission elevation in Cygwin, these two arguments will not work when using it.

The command is always executed in a new shell. Thus possible changes to the environment (e.g. changing working directory) are not visible to the later keywords:

Write and Read can be used for running multiple commands in the same shell. See interactive shells section for more information.

This keyword logs the executed command and its exit status with log level INFO.

If the timeout expires before the command is executed, this keyword fails.

invoke_subsystem will request a subsystem on the server, given by the command argument. If the server allows it, the channel will then be directly connected to the requested subsystem.

forward_agent determines whether to forward the local SSH Agent process to the process being executed. This assumes that there is an agent in use (i.e. eval $(ssh-agent)). Setting forward_agent does not work with Jython.

invoke_subsystem and forward_agent are new in SSHLibrary 3.4.0.

output_during_execution enable logging the output of the command as it is generated, into the console.

output_if_timeout if the executed command doesn't end before reaching timeout, the parameter will log the output of the command at the moment of timeout.

output_during_execution and output_if_timeout are not working with Jython. New in SSHLibrary 3.5.0.

Fails if the given path does NOT point to an existing file.

Arguments

Supports wildcard expansions described in glob patterns.

Usage

Note that symlinks are followed:

Fails if the given path points to an existing file.

Arguments

Supports wildcard expansions described in glob patterns.

Usage

Note that this keyword follows symlinks. Thus the example fails if /non/existing is a link that points an existing file.

Returns information about the connection.

Arguments

Connection is not changed by this keyword, use Switch Connection to change the active connection.

If index_or_alias is not given, the information of the current connection is returned. If there exists more connections with the same alias the keyword will return last opened connection that has that alias.

This keyword returns an object that has the following attributes:

If there is no connection, an object having index and host as None is returned, rest of its attributes having their values as configuration defaults.

If you want the information for all the open connections, use Get Connections.

Getting connection information of the current connection:

Getting connection information using an index:

Getting connection information using an alias:

This keyword can also return plain connection attributes instead of the whole connection object. This can be adjusted using the boolean arguments index, host, alias, and so on, that correspond to the attribute names of the object. If such arguments are given, and they evaluate to true (see Boolean arguments), only the respective connection attributes are returned. Note that attributes are always returned in the same order arguments are specified in the signature.

Getting only certain attributes is especially useful when using this library via the Remote library interface. This interface does not support returning custom objects, but individual attributes can be returned just fine.

This keyword logs the connection information with log level INFO.

Returns information about all the open connections.

This keyword returns a list of objects that are identical to the ones returned by Get Connection.

Usage

This keyword logs the information of connections with log level INFO.

Downloads a directory, including its content, from the remote machine to the local machine.

Arguments

source is a path on the remote machine. Both absolute paths and paths relative to the current working directory are supported.

destination is the target path on the local machine. Both absolute paths and paths relative to the current working directory are supported.

recursive specifies whether to recursively download all subdirectories inside source. Subdirectories are downloaded if the argument value evaluates to true (see Boolean arguments).

scp enables the use of scp (secure copy protocol) for the file transfer. See Transfer files with SCP for more details.

scp_preserve_times preserve modification time and access time of transferred files and directories. It is ignored when running with Jython.

Examples:

The local destination is created as following:

1. If destination is an existing path on the local machine, source directory is downloaded into it.

2. If destination does not exist on the local machine, it is created and the content of source directory is downloaded into it.

3. If destination is not given, source directory is downloaded into the current working directory on the local <machine. This is typically the directory where the test execution was started and thus accessible using the built-in ${EXECDIR} variable.

See also Get File.

scp_preserve_times is new in SSHLibrary 3.6.0.

Downloads file(s) from the remote machine to the local machine.

Arguments

source is a path on the remote machine. Both absolute paths and paths relative to the current working directory are supported. If the source contains wildcards explained in glob patterns, all files matching it are downloaded. In this case destination must always be a directory.

destination is the target path on the local machine. Both absolute paths and paths relative to the current working directory are supported.

scp enables the use of scp (secure copy protocol) for the file transfer. See Transfer files with SCP for more details.

scp_preserve_times preserve modification time and access time of transferred files and directories. It is ignored when running with Jython.

Examples:

The local destination is created using the rules explained below:

1. If the destination is an existing file, the source file is downloaded over it.

2. If the destination is an existing directory, the source file is downloaded into it. Possible file with the same name is overwritten.

3. If the destination does not exist and it ends with the path separator of the local operating system, it is considered a directory. The directory is then created and the source file is downloaded into it. Possible missing intermediate directories are also created.

4. If the destination does not exist and does not end with the local path separator, it is considered a file. The source file is downloaded and saved using that file name, and possible missing intermediate directories are also created.

5. If destination is not given, the current working directory on the local machine is used as the destination. This is typically the directory where the test execution was started and thus accessible using built-in ${EXECDIR} variable.

See also Get Directory.

scp_preserve_times is new in SSHLibrary 3.6.0.

Returns the banner supplied by the server upon connect.

Arguments

There are 2 ways of getting banner information.

1. Independent of any connection:

The argument host is mandatory for getting banner key without an open connection.

2. From the current connection:

New in SSHLibrary 3.0.0.

Note: This keyword does not work when using Jython.

A wrapper for List Directory that returns only directories.

Arguments

Returns and logs items in the remote path, optionally filtered with pattern.

Arguments

path is a path on the remote machine. Both absolute paths and paths relative to the current working directory are supported. If path is a symlink, it is followed.

Item names are returned in case-sensitive alphabetical order, e.g. ['A Name', 'Second', 'a lower case name', 'one more']. Implicit directories . and .. are not returned. The returned items are automatically logged.

By default, the item names are returned relative to the given remote path (e.g. file.txt). If you want them be returned in the absolute format (e.g. /home/johndoe/file.txt), set the absolute argument to any non-empty string.

If pattern is given, only items matching it are returned. The pattern is a glob pattern and its syntax is explained in the Pattern matching section.

Examples (using also other List Directory variants):

If you are only interested in directories or files, use List Files In Directory or List Directories In Directory, respectively.

A wrapper for List Directory that returns only files.

Arguments

Logs into the SSH server with the given username and password.

Arguments

Connection must be opened before using this keyword.

This keyword reads, returns and logs the server output after logging in. If the prompt is set, everything until the prompt is read. Otherwise the output is read using the Read keyword with the given delay. The output is logged using the default log level.

proxy_cmd is used to connect through a SSH proxy.

jumphost_index_or_alias is used to connect through an intermediary SSH connection that has been assigned an Index or Alias. Note that this requires a Connection that has been logged in prior to use.

Note: proxy_cmd and jumphost_index_or_alias are mutually exclusive SSH features. If you wish to use them both, create the jump-host's Connection using the proxy_cmd first, then use jump-host for secondary Connection.

allow_agent enables the connection to the SSH agent.

look_for_keys enables the searching for discoverable private key files in ~/.ssh/.

read_config reads or ignores entries from ~/.ssh/config file. This parameter will read the hostname, port number, username and proxy command.

read_config is new in SSHLibrary 3.7.0.

keep_alive_interval is used to specify after which idle interval of time a keepalive packet will be sent to remote host. By default keep_alive_interval is set to 0, which means sending the keepalive packet is disabled.

keep_alive_interval is new in SSHLibrary 3.7.0.

Note: allow_agent, look_for_keys, proxy_cmd, jumphost_index_or_alias, read_config and keep_alive_interval do not work when using Jython.

Example that logs in and returns the output:

Example that logs in and returns everything until the prompt:

Example that logs in a remote server (linux.server.com) through a proxy server (proxy.server.com)

Example usage of SSH Agent: First, add the key to the authentication agent with: ssh-add /path/to/keyfile.

Logs into the SSH server using key-based authentication.

Arguments

Connection must be opened before using this keyword.

username is the username on the remote machine.

keyfile is a path to a valid OpenSSH private key file on the local filesystem.

password is used to unlock the keyfile if needed. If the keyfile is invalid a username-password authentication will be attempted.

proxy_cmd is used to connect through a SSH proxy.

jumphost_index_or_alias is used to connect through an intermediary SSH connection that has been assigned an Index or Alias. Note that this requires a Connection that has been logged in prior to use.

Note: proxy_cmd and jumphost_index_or_alias are mutually exclusive SSH features. If you wish to use them both, create the jump-host's Connection using the proxy_cmd first, then use jump-host for secondary Connection.

This keyword reads, returns and logs the server output after logging in. If the prompt is set, everything until the prompt is read. Otherwise the output is read using the Read keyword with the given delay. The output is logged using the default log level.

Example that logs in using a private key and returns the output:

With locked private keys, the keyring password is required:

allow_agent enables the connection to the SSH agent. look_for_keys enables the searching for discoverable private key files in ~/.ssh/.

read_config reads or ignores entries from ~/.ssh/config file. This parameter will read the hostname, port number, username, identity file and proxy command.

read_config is new in SSHLibrary 3.7.0.

keep_alive_interval is used to specify after which idle interval of time a keepalive packet will be sent to remote host. By default keep_alive_interval is set to 0, which means sending the keepalive packet is disabled.

keep_alive_interval is new in SSHLibrary 3.7.0.

Note: allow_agent, look_for_keys, proxy_cmd, jumphost_index_or_alias, read_config and keep_alive_interval do not work when using Jython.

Opens a new SSH connection to the given host and port.

Arguments

The new connection is made active. Possible existing connections are left open in the background.

Note that on Jython this keyword actually opens a connection and will fail immediately on unreachable hosts. On Python the actual connection attempt will not be done until Login is called.

This keyword returns the index of the new connection which can be used later to switch back to it. Indices start from 1 and are reset when Close All Connections is used.

Optional alias can be given for the connection and can be used for switching between connections, similarly as the index. Multiple connections with the same alias are allowed. See Switch Connection for more details.

Connection parameters, like timeout and newline are documented in configuration. If they are not defined as arguments, the library defaults are used for the connection.

All the arguments, except host, alias and port can be later updated with Set Client Configuration.

Port 22 is assumed by default:

Non-standard port may be given as an argument:

Aliases are handy, if you need to switch back to the connection later:

Settings can be overridden per connection, otherwise the ones set on library importing or with Set Default Configuration are used:

The terminal settings are also configurable per connection:

Starting with version 3.3.0, SSHLibrary understands Host entries from ~/.ssh/config. For instance, if the config file contains:

The connection to the server can also be made like this:

Host entries are not read from config file when running with Jython.

Uploads a directory, including its content, from the local machine to the remote machine.

Arguments

source is the path on the local machine. Both absolute paths and paths relative to the current working directory are supported.

destination is the target path on the remote machine. Both absolute paths and paths relative to the current working directory are supported.

mode can be used to set the target file permission. Numeric values are accepted. The default value is 0744 (-rwxr--r--).

newline can be used to force the line break characters that are written to the remote files. Valid values are LF and CRLF. Does not work if scp is enabled.

recursive specifies whether to recursively upload all subdirectories inside source. Subdirectories are uploaded if the argument value evaluates to true (see Boolean arguments).

scp enables the use of scp (secure copy protocol) for the file transfer. See Transfer files with SCP for more details.

scp_preserve_times preserve modification time and access time of transferred files and directories. It is ignored when running with Jython.

Examples:

The remote destination is created as following:

1. If destination is an existing path on the remote machine, source directory is uploaded into it.

2. If destination does not exist on the remote machine, it is created and the content of source directory is uploaded into it.

3. If destination is not given, source directory is typically uploaded to user's home directory on the remote machine.

See also Put File.

scp_preserve_times is new in SSHLibrary 3.6.0.

Uploads file(s) from the local machine to the remote machine.

Arguments

source is the path on the local machine. Both absolute paths and paths relative to the current working directory are supported. If the source contains wildcards explained in glob patterns, all files matching it are uploaded. In this case destination must always be a directory.

destination is the target path on the remote machine. Both absolute paths and paths relative to the current working directory are supported.

mode can be used to set the target file permission. Numeric values are accepted. The default value is 0744 (-rwxr--r--). If None value is provided, setting modes will be skipped.

newline can be used to force the line break characters that are written to the remote files. Valid values are LF and CRLF. Does not work if scp is enabled.

scp enables the use of scp (secure copy protocol) for the file transfer. See Transfer files with SCP for more details.

scp_preserve_times preserve modification time and access time of transferred files and directories. It is ignored when running with Jython.

Examples:

The remote destination is created as following:

1. If destination is an existing file, source file is uploaded over it.

2. If destination is an existing directory, source file is uploaded into it. Possible file with same name is overwritten.

3. If destination does not exist and it ends with the path separator, it is considered a directory. The directory is then created and source file uploaded into it. Possibly missing intermediate directories are also created.

4. If destination does not exist and it does not end with the path separator, it is considered a file. If the path to the file does not exist, it is created.

5. If destination is not given, the user's home directory on the remote machine is used as the destination.

See also Put Directory.

scp_preserve_times is new in SSHLibrary 3.6.0.

Consumes and returns everything available on the server output.

Arguments

If delay is given, this keyword waits that amount of time and reads output again. This wait-read cycle is repeated as long as further reads return more output or the default timeout expires. delay must be given in Robot Framework's time format.

This keyword is most useful for reading everything from the server output, thus clearing it.

The read output is logged. loglevel can be used to override the default log level.

Usage

See interactive shells for more information about writing and reading in general.

Returns outputs of the most recent started command.

Arguments

At least one command must have been started using Start Command before this keyword can be used.

By default, only the standard output of the started command is returned:

Arguments return_stdout, return_stderr and return_rc are used to specify, what is returned by this keyword. If several arguments evaluate to a true value (see Boolean arguments), multiple values are returned.

If errors are needed as well, set the argument value to true:

Often checking the return code is enough:

Using Start Command and Read Command Output follows LIFO (last in, first out) policy, meaning that Read Command Output operates on the most recent started command, after which that command is discarded and its output cannot be read again.

If several commands have been started, the output of the last started command is returned. After that, a subsequent call will return the output of the new last (originally the second last) command:

This keyword logs the read command with log level INFO.

Consumes and returns the server output until expected is encountered.

Arguments

Text up until and including the expected will be returned.

If the timeout expires before the match is found, this keyword fails.

The read output is logged. loglevel can be used to override the default log level.

Usage

See also Read Until Prompt and Read Until Regexp keywords. For more details about reading and writing in general, see the Interactive shells section.

Consumes and returns the server output until the prompt is found.

Arguments

Text up and until prompt is returned. The prompt must be set before this keyword is used.

If the timeout expires before the match is found, this keyword fails.

This keyword is useful for reading output of a single command when output of previous command has been read and that command does not produce prompt characters in its output.

The read output is logged. loglevel can be used to override the default log level.

Usage

See also Read Until and Read Until Regexp keywords. For more details about reading and writing in general, see the Interactive shells section.

If you want to exclude the prompt from the returned output, set strip_prompt to a true value (see Boolean arguments). If your prompt is a regular expression, make sure that the expression spans the whole prompt, because only the part of the output that matches the regular expression is stripped away.

strip_prompt argument is new in SSHLibrary 3.2.0.

Consumes and returns the server output until a match to regexp is found.

Arguments

regexp can be a regular expression pattern or a compiled regular expression object. See the Regular expressions section for more details about the syntax.

Text up until and including the regexp will be returned.

If the timeout expires before the match is found, this keyword fails.

The read output is logged. loglevel can be used to override the default log level.

Usage

See also Read Until and Read Until Prompt keywords. For more details about reading and writing in general, see the Interactive shells section.

Update the configuration of the current connection.

Arguments

Only parameters whose value is other than None are updated.

In the following example, prompt is set for the current connection. Other settings are left intact:

Using keyword does not affect the other connections:

Multiple settings are possible. This example updates the terminal settings of the current connection:

Note: Setting width and height does not work when using Jython.

Update the default configuration.

Arguments

Please note that using this keyword does not affect the already opened connections. Use Set Client Configuration to configure the active connection.

Only parameters whose value is other than None are updated.

This example sets prompt to $:

This example sets newline and path separator to the ones known by Windows:

Sometimes you might want to use longer timeout for all the subsequent connections without affecting the existing ones:

Starts execution of the command on the remote machine and returns immediately.

Arguments

This keyword returns nothing and does not wait for the command execution to be finished. If waiting for the output is required, use Execute Command instead.

This keyword does not return any output generated by the started command. Use Read Command Output to read the output:

The command is always executed in a new shell, similarly as with Execute Command. Thus possible changes to the environment (e.g. changing working directory) are not visible to the later keywords:

Arguments sudo and sudo_password are used for executing commands within a sudo session. Due to different permission elevation in Cygwin, these two arguments will not when using it.

Write and Read can be used for running multiple commands in the same shell. See interactive shells section for more information.

This keyword logs the started command with log level INFO.

invoke_subsystem argument behaves similarly as with Execute Command keyword.

forward_agent argument behaves similarly as with Execute Command keyword.

invoke_subsystem is new in SSHLibrary 3.4.0.

Switches the active connection by index or alias.

Arguments

index_or_alias is either connection index (an integer) or alias (a string). Index is got as the return value of Open Connection. Alternatively, both index and alias can queried as attributes of the object returned by Get Connection. If there exists more connections with the same alias the keyword will switch to the last opened connection that has that alias.

This keyword returns the index of the previous active connection, which can be used to switch back to that connection later.

Usage

Writes the given text on the remote machine and appends a newline.

Arguments

Appended newline can be configured.

This keyword returns and consumes the written text (including the appended newline) from the server output. See the Interactive shells section for more information.

The written text is logged. loglevel can be used to override the default log level.

Usage

See also Write Bare.

Writes the given text on the remote machine without appending a newline.

Arguments

Unlike Write, this keyword returns and consumes nothing. See the Interactive shells section for more information.

Usage

See also Write.

Writes the given text repeatedly until expected appears in the server output.

Arguments

This keyword returns nothing.

text is written without appending a newline and is consumed from the server output before expected is read. See more information on the Interactive shells section.

If expected does not appear in output within timeout, this keyword fails. retry_interval defines the time before writing text again. Both timeout and retry_interval must be given in Robot Framework's time format.

The written text is logged. loglevel can be used to override the default log level.

This example will write lsof -c python27\n (list all files currently opened by Python 2.7), until myscript.py appears in the output. The command is written every 0.5 seconds. The keyword fails if myscript.py does not appear in the server output in 5 seconds: