Close All Connections

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.

Examples

Open Connection my.server.com
Open Connection build.local.net
# Do something with the connections
[Teardown] Close all connections

Close Connection

Closes the current connection.

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

Examples

Open Connection my.server.com
Login johndoe secretpasswd
Get File results.txt /tmp
Close Connection
# Do something with /tmp/results.txt

Create Local Ssh Tunnel

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

Argument Type Default value Description
local_portnull
remote_hostnull
remote_port22
bind_addressNone

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:

Open Connection remote.server.com prompt=$
Login johndoe secretpasswd
Create Local SSH Tunnel 9191 secure.server.com 80

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.

Examples

Create Local SSH Tunnel 9191 secure.server.com 80 bind_address=127.0.0.1

bind_address is new in SSHLibrary 3.3.0.

Directory Should Exist

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

Arguments

Argument Type Default value Description
pathnull

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

Examples

Directory Should Exist /usr/share/man
Directory Should Exist /usr/share/*

Note that symlinks are followed:

Directory Should Exist /usr/local/man # Points to /usr/share/man/

Directory Should Not Exist

Fails if the given path points to an existing directory.

Arguments

Argument Type Default value Description
pathnull

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

Examples

Directory Should Not Exist /non/existing
Directory Should Not Exist /non/*

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

Enable Ssh Logging

Enables logging of SSH protocol output to given logfile.

Arguments

Argument Type Default value Description
logfilenull

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.

Examples

Open Connection my.server.com # Not logged
Enable SSH Logging myserver.log
Login johndoe secretpasswd
Open Connection build.local.net # Logged
# Do something with the connections
# Check myserver.log for detailed debug information

Note: This keyword does not work when using Jython.

Execute Command

Executes command on the remote machine and returns its outputs.

Arguments

Argument Type Default value Description
commandnull
return_stdoutTrue
return_stderrFalse
return_rcFalse
sudoFalse
sudo_passwordNone
timeoutNone
output_during_executionFalse
output_if_timeoutFalse
invoke_subsystemFalse
forward_agentFalse

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:

${stdout}= Execute Command echo 'Hello John!'
Should Contain ${stdout} Hello John!

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:

${stdout} ${stderr}= Execute Command echo 'Hello John!' return_stderr=True
Should Be Empty ${stderr}

Often checking the return code is enough:

${rc}= Execute Command echo 'Hello John!' return_stdout=False return_rc=True
Should Be Equal As Integers ${rc} 0 # succeeded

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.

Execute Command pwd sudo=True sudo_password=test

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:

${pwd}= Execute Command pwd
Should Be Equal ${pwd} /home/johndoe
Execute Command cd /tmp
${pwd}= Execute Command pwd
Should Be Equal ${pwd} /home/johndoe

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.

Execute Command ssh-add -L forward_agent=True

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.

File Should Exist

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

Arguments

Argument Type Default value Description
pathnull

Supports wildcard expansions described in glob patterns.

Examples

File Should Exist /boot/initrd.img
File Should Exist /boot/*.img

Note that symlinks are followed:

File Should Exist /initrd.img # Points to /boot/initrd.img

File Should Not Exist

Fails if the given path points to an existing file.

Arguments

Argument Type Default value Description
pathnull

Supports wildcard expansions described in glob patterns.

Examples

File Should Not Exist /non/existing
File Should Not Exist /non/*

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

Get Connection

Returns information about the connection.

Arguments

Argument Type Default value Description
index_or_aliasNone
indexFalse
hostFalse
aliasFalse
portFalse
timeoutFalse
newlineFalse
promptFalse
term_typeFalse
widthFalse
heightFalse
encodingFalse
escape_ansiFalse

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:

Name Type Explanation
index integer Number of the connection. Numbering starts from 1.
host string Destination hostname.
alias string An optional alias given when creating the connection.
port integer Destination port.
timeout string Timeout length in textual representation.
newline string The line break sequence used by Write keyword. See newline.
prompt string Prompt character sequence for Read Until Prompt.
term_type string Type of the virtual terminal. See terminal settings.
width integer Width of the virtual terminal. See terminal settings.
height integer Height of the virtual terminal. See terminal settings.
path_separator string The path separator used on the remote host.
encoding string The encoding used for inputs and outputs.

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:

Open Connection far.server.com
Open Connection near.server.com prompt=>> # Current connection
${nearhost}= Get Connection
Should Be Equal ${nearhost.host} near.server.com
Should Be Equal ${nearhost.index} 2
Should Be Equal ${nearhost.prompt} >>
Should Be Equal ${nearhost.term_type} vt100 # From defaults

Getting connection information using an index:

Open Connection far.server.com
Open Connection near.server.com # Current connection
${farhost}= Get Connection 1
Should Be Equal ${farhost.host} far.server.com

Getting connection information using an alias:

Open Connection far.server.com alias=far
Open Connection near.server.com # Current connection
${farhost}= Get Connection far
Should Be Equal ${farhost.host} far.server.com
Should Be Equal ${farhost.alias} far

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.

Open Connection my.server.com alias=example
${host}= Get Connection host=True
Should Be Equal ${host} my.server.com
${host} ${alias}= Get Connection host=yes alias=please
Should Be Equal ${host} my.server.com
Should Be Equal ${alias} example

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.

Get Connections

Returns information about all the open connections.

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

Examples

Open Connection near.server.com timeout=10s
Open Connection far.server.com timeout=5s
${nearhost} ${farhost}= Get Connections
Should Be Equal ${nearhost.host} near.server.com
Should Be Equal As Integers ${nearhost.timeout} 10
Should Be Equal As Integers ${farhost.port} 22
Should Be Equal As Integers ${farhost.timeout} 5

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

Get Directory

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

Arguments

Argument Type Default value Description
sourcenull
destination.
recursiveFalse
scpOFF
scp_preserve_timesFalse

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:

Get Directory /var/logs /tmp
Get Directory /var/logs /tmp/non/existing
Get Directory /var/logs
Get Directory /var/logs recursive=True

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.

Get File

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

Arguments

Argument Type Default value Description
sourcenull
destination.
scpOFF
scp_preserve_timesFalse

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:

Get File /var/log/auth.log /tmp/
Get File /tmp/example.txt C:\\temp\\new_name.txt
Get File /path/to/*.txt

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.

Get Pre Login Banner

Returns the banner supplied by the server upon connect.

Arguments

Argument Type Default value Description
hostNone
port22

There are 2 ways of getting banner information.

1. Independent of any connection:

${banner} = Get Pre Login Banner ${HOST}
Should Be Equal ${banner} Testing pre-login banner

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

2. From the current connection:

Open Connection ${HOST} prompt=${PROMPT}
Login ${USERNAME} ${PASSWORD}
${banner} = Get Pre Login Banner
Should Be Equal ${banner} Testing pre-login banner

New in SSHLibrary 3.0.0.

Note: This keyword does not work when using Jython.

List Directories In Directory

A wrapper for List Directory that returns only directories.

Arguments

Argument Type Default value Description
pathnull
patternNone
absoluteFalse

List Directory

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

Arguments

Argument Type Default value Description
pathnull
patternNone
absoluteFalse

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):

@{items}= List Directory /home/johndoe
@{files}= List Files In Directory /tmp *.txt absolute=True

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

List Files In Directory

A wrapper for List Directory that returns only files.

Arguments

Argument Type Default value Description
pathnull
patternNone
absoluteFalse

Login

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

Arguments

Argument Type Default value Description
usernameNone
passwordNone
allow_agentFalse
look_for_keysFalse
delay0.5 seconds
proxy_cmdNone
read_configFalse
jumphost_index_or_aliasNone
keep_alive_interval0 seconds

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:

Open Connection linux.server.com
${output}= Login johndoe secretpasswd
Should Contain ${output} Last login at

Example that logs in and returns everything until the prompt:

Open Connection linux.server.com prompt=$
${output}= Login johndoe secretpasswd
Should Contain ${output} [email protected]:~$

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

Open Connection linux.server.com
${output}= Login johndoe secretpasswd proxy_cmd=ssh -l user -i keyfile -W linux.server.com:22 proxy.server.com
Should Contain ${output} Last login at

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

Open Connection linux.server.com
Login johndoe allow_agent=True

Login With Public Key

Logs into the SSH server using key-based authentication.

Arguments

Argument Type Default value Description
usernameNone
keyfileNone
password
allow_agentFalse
look_for_keysFalse
delay0.5 seconds
proxy_cmdNone
jumphost_index_or_aliasNone
read_configFalse
keep_alive_interval0 seconds

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:

Open Connection linux.server.com
${output}= Login With Public Key johndoe /home/johndoe/.ssh/id_rsa
Should Contain ${motd} Last login at

With locked private keys, the keyring password is required:

Open Connection linux.server.com
Login With Public Key johndoe /home/johndoe/.ssh/id_dsa keyringpasswd

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.

Open Connection

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

Arguments

Argument Type Default value Description
hostnull
aliasNone
port22
timeoutNone
newlineNone
promptNone
term_typeNone
widthNone
heightNone
path_separatorNone
encodingNone
escape_ansiNone
encoding_errorsNone

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:

${index}= Open Connection my.server.com

Non-standard port may be given as an argument:

${index}= Open Connection 192.168.1.1 port=23

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

Open Connection my.server.com alias=myserver
# Do something with my.server.com
Open Connection 192.168.1.1
Switch Connection myserver # Back to my.server.com

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

Open Connection 192.168.1.1 timeout=1 hour newline=CRLF
# Do something with the connection
Open Connection my.server.com # Default timeout # Default line breaks

The terminal settings are also configurable per connection:

Open Connection 192.168.1.1 term_type=ansi width=40

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

Host my_custom_hostname
Hostname my.server.com

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

Open connection my_custom_hostname

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

Put Directory

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

Arguments

Argument Type Default value Description
sourcenull
destination.
mode0744
newline
recursiveFalse
scpOFF
scp_preserve_timesFalse

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:

Put Directory /var/logs /tmp
Put Directory /var/logs /tmp/non/existing
Put Directory /var/logs
Put Directory /var/logs recursive=True
Put Directory /var/logs /home/groups/robot mode=0770
Put Directory | /var/logs | newline=CRLF       |Get File With SCP (transfer) And Preserve Time

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.

Put File

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

Arguments

Argument Type Default value Description
sourcenull
destination.
mode0744
newline
scpOFF
scp_preserve_timesFalse

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:

Put File /path/to/*.txt
Put File /path/to/*.txt /home/groups/robot mode=0770
Put File /path/to/*.txt /home/groups/robot mode=None
Put File /path/to/*.txt newline=CRLF

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.

Read

Consumes and returns everything available on the server output.

Arguments

Argument Type Default value Description
loglevelNone
delayNone

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.

Examples

Open Connection my.server.com
Login johndoe secretpasswd
Write sudo su -
${output}= Read delay=0.5s
Should Contain ${output} [sudo] password for johndoe:
Write secretpasswd
${output}= Read loglevel=WARN # Shown in the console due to loglevel
Should Contain ${output} [email protected]

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

Read Command Output

Returns outputs of the most recent started command.

Arguments

Argument Type Default value Description
return_stdoutTrue
return_stderrFalse
return_rcFalse
timeoutNone

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:

Start Command echo 'Hello John!'
${stdout}= Read Command Output
Should Contain ${stdout} Hello John!

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:

Start Command echo 'Hello John!'
${stdout} ${stderr}= Read Command Output return_stderr=True
Should Be Empty ${stderr}

Often checking the return code is enough:

Start Command echo 'Hello John!'
${rc}= Read Command Output return_stdout=False return_rc=True
Should Be Equal As Integers ${rc} 0 # succeeded

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:

Start Command echo 'HELLO'
Start Command echo 'SECOND'
${stdout}= Read Command Output
Should Contain ${stdout} 'SECOND'
${stdout}= Read Command Output
Should Contain ${stdout} 'HELLO'

This keyword logs the read command with log level INFO.

Read Until

Consumes and returns the server output until expected is encountered.

Arguments

Argument Type Default value Description
expectednull
loglevelNone

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.

Examples

Open Connection my.server.com
Login johndoe ${PASSWORD}
Write sudo su -
${output}= Read Until :
Should Contain ${output} [sudo] password for johndoe:
Write ${PASSWORD}
${output}= Read Until @
Should End With ${output} [email protected]

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

Read Until Prompt

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

Arguments

Argument Type Default value Description
loglevelNone
strip_promptFalse

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.

Examples

Open Connection my.server.com prompt=$
Login johndoe ${PASSWORD}
Write sudo su -
Write ${PASSWORD}
Set Client Configuration prompt=# # For root, the prompt is #
${output}= Read Until Prompt
Should End With ${output} [email protected]:~#

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.

Read Until Regexp

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

Arguments

Argument Type Default value Description
regexpnull
loglevelNone

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.

Examples

Open Connection my.server.com
Login johndoe ${PASSWORD}
Write sudo su -
${output}= Read Until Regexp \\[.*\\].*:
Should Contain ${output} [sudo] password for johndoe:
Write ${PASSWORD}
${output}= Read Until Regexp .*@
Should Contain ${output} [email protected]

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

Set Client Configuration

Update the configuration of the current connection.

Arguments

Argument Type Default value Description
timeoutNone
newlineNone
promptNone
term_typeNone
widthNone
heightNone
path_separatorNone
encodingNone
escape_ansiNone
encoding_errorsNone

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:

Open Connection my.server.com
Set Client Configuration prompt=$
${myserver}= Get Connection
Should Be Equal ${myserver.prompt} $

Using keyword does not affect the other connections:

Open Connection linux.server.com
Set Client Configuration prompt=$ # Only linux.server.com affected
Open Connection windows.server.com
Set Client Configuration prompt=> # Only windows.server.com affected
${linux} ${windows}= Get Connections
Should Be Equal ${linux.prompt} $
Should Be Equal ${windows.prompt} >

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

Open Connection 192.168.1.1
Set Client Configuration term_type=ansi width=40

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

Set Default Configuration

Update the default configuration.

Arguments

Argument Type Default value Description
timeoutNone
newlineNone
promptNone
loglevelNone
term_typeNone
widthNone
heightNone
path_separatorNone
encodingNone
escape_ansiNone
encoding_errorsNone

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 $:

Set Default Configuration prompt=$

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

Set Default Configuration newline=CRLF path_separator=\\

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

Set Default Configuration timeout=5 seconds
Open Connection local.server.com
Set Default Configuration timeout=20 seconds
Open Connection emea.server.com
Open Connection apac.server.com
${local} ${emea} ${apac}= Get Connections
Should Be Equal As Integers ${local.timeout} 5
Should Be Equal As Integers ${emea.timeout} 20
Should Be Equal As Integers ${apac.timeout} 20

Start Command

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

Arguments

Argument Type Default value Description
commandnull
sudoFalse
sudo_passwordNone
invoke_subsystemFalse
forward_agentFalse

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:

Start Command echo 'Hello John!'
${stdout}= Read Command Output
Should Contain ${stdout} Hello John!

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:

Start Command pwd
${pwd}= Read Command Output
Should Be Equal ${pwd} /home/johndoe
Start Command cd /tmp
Start Command pwd
${pwd}= Read Command Output
Should Be Equal ${pwd} /home/johndoe

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.

Start Command pwd sudo=True sudo_password=test

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.

Switch Connection

Switches the active connection by index or alias.

Arguments

Argument Type Default value Description
index_or_aliasnull

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.

Examples

${myserver}= Open Connection my.server.com
Login johndoe secretpasswd
Open Connection build.local.net alias=Build
Login jenkins jenkins
Switch Connection ${myserver} # Switch using index
${username}= Execute Command whoami # Executed on my.server.com
Should Be Equal ${username} johndoe
Switch Connection Build # Switch using alias
${username}= Execute Command whoami # Executed on build.local.net
Should Be Equal ${username} jenkins

Write

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

Arguments

Argument Type Default value Description
textnull
loglevelNone

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.

Examples

${written}= Write su
Should Contain ${written} su # Returns the consumed output
${output}= Read
Should Not Contain ${output} ${written} # Was consumed from the output
Should Contain ${output} Password:
Write invalidpasswd
${output}= Read
Should Contain ${output} su: Authentication failure

See also Write Bare.

Write Bare

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

Arguments

Argument Type Default value Description
textnull

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

Examples

Write Bare su\n
${output}= Read
Should Contain ${output} su # Was not consumed from output
Should Contain ${output} Password:
Write Bare invalidpasswd\n
${output}= Read
Should Contain ${output} su: Authentication failure

See also Write.

Write Until Expected Output

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

Arguments

Argument Type Default value Description
textnull
expectednull
timeoutnull
retry_intervalnull
loglevelNone

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:

Write Until Expected Output lsof -c python27\n expected=myscript.py timeout=5s retry_interval=0.5s