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:
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} | johndoe@linux:~$ |
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 |
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} | root@ |
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} | root@ |
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} | root@myserver:~# |
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} | root@ |
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 |