SSH

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

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

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_port		null
remote_host		null
remote_port		22
bind_address		None

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.

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

Arguments

Argument	Type	Default value	Description
path		null

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/

Fails if the given path points to an existing directory.

Arguments

Argument	Type	Default value	Description
path		null

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.

Enables logging of SSH protocol output to given logfile.

Arguments

Argument	Type	Default value	Description
logfile		null

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.

Executes command on the remote machine and returns its outputs.

Arguments

Argument	Type	Default value	Description
command		null
return_stdout		True
return_stderr		False
return_rc		False
sudo		False
sudo_password		None
timeout		None
output_during_execution		False
output_if_timeout		False
invoke_subsystem		False
forward_agent		False

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.

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

Arguments

Argument	Type	Default value	Description
path		null

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

Fails if the given path points to an existing file.

Arguments

Argument	Type	Default value	Description
path		null

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.

Returns information about the connection.

Arguments

Argument	Type	Default value	Description
index_or_alias		None
index		False
host		False
alias		False
port		False
timeout		False
newline		False
prompt		False
term_type		False
width		False
height		False
encoding		False
escape_ansi		False

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.

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.

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

Arguments

Argument	Type	Default value	Description
source		null
destination		.
recursive		False
scp		OFF
scp_preserve_times		False

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.

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

Arguments

Argument	Type	Default value	Description
source		null
destination		.
scp		OFF
scp_preserve_times		False

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.

Returns the banner supplied by the server upon connect.

Arguments

Argument	Type	Default value	Description
host		None
port		22

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.

A wrapper for List Directory that returns only directories.

Arguments

Argument	Type	Default value	Description
path		null
pattern		None
absolute		False

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

Arguments

Argument	Type	Default value	Description
path		null
pattern		None
absolute		False

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.

A wrapper for List Directory that returns only files.

Arguments

Argument	Type	Default value	Description
path		null
pattern		None
absolute		False

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

Arguments

Argument	Type	Default value	Description
username		None
password		None
allow_agent		False
look_for_keys		False
delay		0.5 seconds
proxy_cmd		None
read_config		False
jumphost_index_or_alias		None
keep_alive_interval		0 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

Logs into the SSH server using key-based authentication.

Arguments

Argument	Type	Default value	Description
username		None
keyfile		None
password
allow_agent		False
look_for_keys		False
delay		0.5 seconds
proxy_cmd		None
jumphost_index_or_alias		None
read_config		False
keep_alive_interval		0 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.

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

Arguments

Argument	Type	Default value	Description
host		null
alias		None
port		22
timeout		None
newline		None
prompt		None
term_type		None
width		None
height		None
path_separator		None
encoding		None
escape_ansi		None
encoding_errors		None

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.

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

Arguments

Argument	Type	Default value	Description
source		null
destination		.
mode		0744
newline
recursive		False
scp		OFF
scp_preserve_times		False

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.

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

Arguments

Argument	Type	Default value	Description
source		null
destination		.
mode		0744
newline
scp		OFF
scp_preserve_times		False

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.

Consumes and returns everything available on the server output.

Arguments

Argument	Type	Default value	Description
loglevel		None
delay		None

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.

Returns outputs of the most recent started command.

Arguments

Argument	Type	Default value	Description
return_stdout		True
return_stderr		False
return_rc		False
timeout		None

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.

Consumes and returns the server output until expected is encountered.

Arguments

Argument	Type	Default value	Description
expected		null
loglevel		None

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.

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

Arguments

Argument	Type	Default value	Description
loglevel		None
strip_prompt		False

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.

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

Arguments

Argument	Type	Default value	Description
regexp		null
loglevel		None

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.

Update the configuration of the current connection.

Arguments

Argument	Type	Default value	Description
timeout		None
newline		None
prompt		None
term_type		None
width		None
height		None
path_separator		None
encoding		None
escape_ansi		None
encoding_errors		None

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.

Update the default configuration.

Arguments

Argument	Type	Default value	Description
timeout		None
newline		None
prompt		None
loglevel		None
term_type		None
width		None
height		None
path_separator		None
encoding		None
escape_ansi		None
encoding_errors		None

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

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

Arguments

Argument	Type	Default value	Description
command		null
sudo		False
sudo_password		None
invoke_subsystem		False
forward_agent		False

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.

Switches the active connection by index or alias.

Arguments

Argument	Type	Default value	Description
index_or_alias		null

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

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

Arguments

Argument	Type	Default value	Description
text		null
loglevel		None

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.

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

Arguments

Argument	Type	Default value	Description
text		null

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.

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

Arguments

Argument	Type	Default value	Description
text		null
expected		null
timeout		null
retry_interval		null
loglevel		None

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