csit/libraries/SSHKeywords.robot

   1 *** Settings ***
   2 Documentation     Resource enhancing SSHLibrary with Keywords used in multiple suites.
   3 ...
   4 ...               Copyright (c) 2015 Cisco Systems, Inc. and others. All rights reserved.
   5 ...
   6 ...               This program and the accompanying materials are made available under the
   7 ...               terms of the Eclipse Public License v1.0 which accompanies this distribution,
   8 ...               and is available at http://www.eclipse.org/legal/epl-v10.html
   9 ...
  10 ...
  11 ...               Some suites evolved utility Keywords re-usable with other suites.
  12 ...               When the Keywords assume a SSH session is active,
  13 ...               and if the Keywords do not fit into a more specific Resource,
  14 ...               you can place them here.
  15 Library           SSHLibrary
  16 Resource          ${CURDIR}/Utils.robot
  17 Resource          ../variables/Variables.robot
  18
  19 *** Variables ***
  20 ${SSHKeywords__current_remote_working_directory}    .
  21 ${SSHKeywords__current_venv_path}    /tmp/defaultvenv
  22
  23 *** Keywords ***
  24 Open_Connection_To_ODL_System
  25     [Arguments]    ${ip_address}=${ODL_SYSTEM_IP}    ${timeout}=10s
  26     [Documentation]    Open a connection to the ODL system at ${ip_address} and return its identifier.
  27     ${odl_connection} =    SSHLibrary.Open_Connection    ${ip_address}    prompt=${ODL_SYSTEM_PROMPT}    timeout=${timeout}
  28     Flexible_Controller_Login
  29     [Return]    ${odl_connection}
  30
  31 Open_Connection_To_Tools_System
  32     [Arguments]    ${ip_address}=${TOOLS_SYSTEM_IP}    ${timeout}=10s
  33     [Documentation]    Open a connection to the tools system at ${ip_address} and return its identifier.
  34     ${tools_connection} =    SSHLibrary.Open_Connection    ${ip_address}    prompt=${TOOLS_SYSTEM_PROMPT}    timeout=${timeout}
  35     Flexible_Mininet_Login
  36     [Return]    ${tools_connection}
  37
  38 Restore_Current_Ssh_Connection_From_Index
  39     [Arguments]    ${connection_index}
  40     [Documentation]    Restore active SSH connection in SSHLibrary to given index.
  41     ...
  42     ...    Restore the currently active connection state in
  43     ...    SSHLibrary to match the state returned by "Switch
  44     ...    Connection" or "Get Connection". More specifically makes
  45     ...    sure that there will be no active connection when the
  46     ...    \${connection_index} reported by these means is None.
  47     ...
  48     ...    There is a misfeature in SSHLibrary: Invoking "SSHLibrary.Switch_Connection"
  49     ...    and passing None as the "index_or_alias" argument to it has exactly the
  50     ...    same effect as invoking "Close Connection".
  51     ...    https://github.com/robotframework/SSHLibrary/blob/master/src/SSHLibrary/library.py#L560
  52     ...
  53     ...    We want to have Keyword which will "switch out" to previous
  54     ...    "no connection active" state without killing the background one.
  55     ...
  56     ...    As some suites may hypothetically rely on non-writability of active connection,
  57     ...    workaround is applied by opening and closing temporary connection.
  58     ...    Unfortunately this will fail if run on Jython and there is no SSH server
  59     ...    running on localhost, port 22 but there is nothing easy that can be done about it.
  60     BuiltIn.Run Keyword And Return If    ${connection_index} is not None    SSHLibrary.Switch Connection    ${connection_index}
  61     # The background connection is still current, bury it.
  62     SSHLibrary.Open Connection    127.0.0.1
  63     SSHLibrary.Close Connection
  64
  65 Run_Keyword_Preserve_Connection
  66     [Arguments]    ${keyword_name}    @{args}    &{kwargs}
  67     [Documentation]    Store current connection index, run keyword returning its result, restore connection in teardown.
  68     ...    Note that in order to avoid "got positional argument after named arguments", it is safer to use positional (not named) arguments on call.
  69     ${current_connection}=    SSHLibrary.Get_Connection
  70     BuiltIn.Run_Keyword_And_Return    ${keyword_name}    @{args}    &{kwargs}
  71     # Resource name has to be prepended, as KarafKeywords still contains a redirect.
  72     [Teardown]    SSHKeywords.Restore_Current_SSH_Connection_From_Index    ${current_connection.index}
  73
  74 Run_Keyword_With_Ssh
  75     [Arguments]    ${ip_address}    ${keyword_name}    @{args}    &{kwargs}
  76     [Documentation]    Open temporary connection to given IP address, run keyword, close connection, restore previously active connection, return result.
  77     Run_Keyword_Preserve_Connection    Run_Unsafely_Keyword_Over_Temporary_Odl_Session    ${ip_address}    ${keyword_name}    @{args}    &{kwargs}
  78
  79 Run_Unsafely_Keyword_Over_Temporary_Odl_Session
  80     [Arguments]    ${ip_address}    ${keyword_name}    @{args}    &{kwargs}
  81     [Documentation]    Open connection to given IP address, run keyword, close connection, return result.
  82     ...    This is unsafe in the sense that previously active session will be switched out off, but safe in the sense only the temporary connection is closed.
  83     Open_Connection_To_ODL_System    ${ip_address}
  84     # Not using Teardown, to avoid a call to close if the previous line fails.
  85     ${status}    ${result} =    BuiltIn.Run_Keyword_And_Ignore_Error    ${keyword_name}    @{args}    &{kwargs}
  86     SSHLibrary.Close_Connection
  87     BuiltIn.Return_From_Keyword_If    "${status}" == "PASS"    ${result}
  88     BuiltIn.Fail    ${result}
  89
  90 Log_Command_Results
  91     [Arguments]    ${stdout}    ${stderr}    ${rc}
  92     [Documentation]    Log everything returned by SSHLibrary.Execute_Command
  93     BuiltIn.Log    ${stdout}
  94     BuiltIn.Log    ${stderr}
  95     BuiltIn.Log    ${rc}
  96
  97 Execute_Command_Passes
  98     [Arguments]    ${command}    ${return_success_only}=True    ${log_on_success}=False    ${log_on_failure}=True    ${stderr_must_be_empty}=False
  99     [Documentation]    Execute command via the active SSH connection. For success, rc has to be zero and optionally stderr has to be empty.
 100     ...    Log everything, depending on arguments and success. Return either success string or stdout.
 101     ...    TODO: Do we want to support customizing return values the same way as SSHLibrary.Execute_Command does?
 102     ${stdout}    ${stderr}    ${rc} =    SSHLibrary.Execute_Command    ${command}    return_stderr=True    return_rc=True
 103     ${emptiness_status}    ${result} =    BuiltIn.Run_Keyword_And_Ignore_Error    BuiltIn.Should_Be_Empty    ${stderr}
 104     ${success} =    BuiltIn.Set_Variable_If    (${rc} == 0) and (("${emptiness_status}" == "PASS") or not ${stderr_must_be_empty})    True    False
 105     BuiltIn.Run_Keyword_If    (${log_on_success} and ${success}) or (${log_on_failure} and not ${success})    Log_Command_Results    ${stdout}    ${stderr}    ${rc}
 106     BuiltIn.Return_From_Keyword_If    ${return_success_only}    ${success}
 107     BuiltIn.Return_From_Keyword_If    ${success}    ${stdout}
 108     BuiltIn.Fail    Got rc: ${rc} or stderr was not empty: ${stderr}
 109
 110 Execute_Command_Should_Pass
 111     [Arguments]    ${command}    ${log_on_success}=True    ${log_on_failure}=True    ${stderr_must_be_empty}=False
 112     [Documentation]    A wrapper for Execute_Command_Passes with return_success_only=False
 113     ...    Also, log_on_success defaults to True (but is customizable, unlike return_success_only)..
 114     BuiltIn.Run_Keyword_And_Return    Execute_Command_Passes    ${command}    return_success_only=False    log_on_success=${log_on_success}    log_on_failure=${log_on_failure}    stderr_must_be_empty=${stderr_must_be_empty}
 115
 116 Execute_Command_At_Path_Should_Pass
 117     [Arguments]    ${command}    ${path}=None    ${log_on_success}=True    ${log_on_failure}=True    ${stderr_must_be_empty}=False
 118     [Documentation]    A keyword similar to Execute_Command_Should_Pass which performs "cd" to ${path} before executing the ${command}.
 119     ...    This is useful when rewriting bash scripts, as series of SSHLibrary.Execute_Command do not share current working directory.
 120     ...    TODO: Perhaps a Keyword which sets up environment variables would be useful as well.
 121     ${cd_and_command} =    BuiltIn.Set_Variable    cd '${path}' && ${command}
 122     BuiltIn.Run_Keyword_And_Return    Execute_Command_Passes    ${cd_and_command}    return_success_only=False    log_on_success=${log_on_success}    log_on_failure=${log_on_failure}    stderr_must_be_empty=${stderr_must_be_empty}
 123
 124 Set_Cwd
 125     [Arguments]    ${path}
 126     [Documentation]    Set \${SSHKeywords__current_remote_working_directory} variable to ${path}. If SSH default is desired, use dot.
 127     BuiltIn.Set_Suite_Variable    \${SSHKeywords__current_remote_working_directory}    ${path}
 128
 129 Execute_Command_At_Cwd_Should_Pass
 130     [Arguments]    ${command}    ${log_on_success}=True    ${log_on_failure}=True    ${stderr_must_be_empty}=True
 131     [Documentation]    Run Execute_Command_At_Path_Should_Pass with previously set CWD as path.
 132     BuiltIn.Run_Keyword_And_Return    Execute_Command_At_Path_Should_Pass    command=${command}    path=${SSHKeywords__current_remote_working_directory}    log_on_success=${log_on_success}    log_on_failure=${log_on_failure}    stderr_must_be_empty=${stderr_must_be_empty}
 133
 134 Require_Python
 135     [Documentation]    Verify current SSH connection leads to machine with python working. Fatal fail otherwise.
 136     ${passed} =    Execute_Command_Passes    python --help
 137     BuiltIn.Return_From_Keyword_If    ${passed}
 138     BuiltIn.Fatal_Error    Python is not installed!
 139
 140 Assure_Library_Ipaddr
 141     [Arguments]    ${target_dir}=.
 142     [Documentation]    Tests whether ipaddr module is present on ssh-connected machine, Puts ipaddr.py to target_dir if not.
 143     ${passed} =    Execute_Command_Passes    bash -c 'cd "${target_dir}" && python -c "import ipaddr"'
 144     BuiltIn.Return_From_Keyword_If    ${passed}
 145     SSHLibrary.Put_File    ${CURDIR}/ipaddr.py    ${target_dir}/
 146
 147 Assure_Library_Counter
 148     [Arguments]    ${target_dir}=.
 149     [Documentation]    Tests whether Counter is present in collections on ssh-connected machine, Puts Counter.py to workspace if not.
 150     ${passed} =    Execute_Command_Passes    bash -c 'cd "${target_dir}" && python -c "from collections import Counter"'
 151     # TODO: Move the bash-cd wrapper to separate keyword?
 152     BuiltIn.Return_From_Keyword_If    ${passed}
 153     SSHLibrary.Put_File    ${CURDIR}/Counter.py    ${target_dir}/
 154
 155 Count_Port_Occurences
 156     [Arguments]    ${port}    ${state}    ${name}
 157     [Documentation]    Run 'netstat' on the remote machine and count occurences of given port in the given state connected to process with the given name.
 158     ${output} =    SSHLibrary.Execute_Command    netstat -natp 2> /dev/null | grep -E ":${port} .+ ${state} .+${name}" | wc -l
 159     [Return]    ${output}
 160
 161 Virtual_Env_Set_Path
 162     [Arguments]    ${venv_path}
 163     [Documentation]    Set \${SSHKeywords__current_venv_path} variable to ${venv_path}. Path should be absolute.
 164     BuiltIn.Set_Global_Variable    \${SSHKeywords__current_venv_path}    ${venv_path}
 165
 166 Virtual_Env_Create
 167     [Documentation]    Creates virtual env. If not to use the default name, use Virtual_Env_Set_Path kw. Returns stdout.
 168     Execute_Command_At_Cwd_Should_Pass    virtualenv ${SSHKeywords__current_venv_path}
 169     BuiltIn.Run_Keyword_And_Return    Virtual_Env_Run_Cmd_At_Cwd    pip install --upgrade pip
 170
 171 Virtual_Env_Delete
 172     [Documentation]    Deletes a directory with virtual env.
 173     Execute_Command_At_Cwd_Should_Pass    rm -rf ${SSHKeywords__current_venv_path}
 174
 175 Virtual_Env_Run_Cmd_At_Cwd
 176     [Arguments]    ${cmd}    ${log_on_success}=True    ${log_on_failure}=True    ${stderr_must_be_empty}=True
 177     [Documentation]    Runs given command within activated virtual env and returns stdout.
 178     BuiltIn.Run_Keyword_And_Return    Execute_Command_At_Cwd_Should_Pass    source ${SSHKeywords__current_venv_path}/bin/activate; ${cmd}; deactivate    log_on_success=${log_on_success}    log_on_failure=${log_on_failure}    stderr_must_be_empty=${stderr_must_be_empty}
 179
 180 Virtual_Env_Install_Package
 181     [Arguments]    ${package}
 182     [Documentation]    Installs python package into virtual env. Use with version if needed (e.g. exabgp==3.4.16). Returns stdout.
 183     BuiltIn.Run_Keyword_And_Return    Virtual_Env_Run_Cmd_At_Cwd    pip install ${package}    stderr_must_be_empty=False
 184
 185 Virtual_Env_Uninstall_Package
 186     [Arguments]    ${package}
 187     [Documentation]    Uninstalls python package from virtual env and returns stdout.
 188     BuiltIn.Run_Keyword_And_Return    Virtual_Env_Run_Cmd_At_Cwd    pip uninstall -y ${package}
 189
 190 Virtual_Env_Freeze
 191     [Documentation]    Shows installed packages within the returned stdout.
 192     BuiltIn.Run_Keyword_And_Return    Virtual_Env_Run_Cmd_At_Cwd    pip freeze --all
 193
 194 Virtual_Env_Activate_On_Current_Session
 195     [Arguments]    ${log_output}=${False}
 196     [Documentation]    Activates virtual environment. To run anything in the env activated this way you should use SSHLibrary.Write and Read commands.
 197     SSHLibrary.Write    source ${SSHKeywords__current_venv_path}/bin/activate
 198     ${output}=    SSHLibrary.Read_Until_Prompt
 199     BuiltIn.Run_Keyword_If    ${log_output}==${True}    BuiltIn.Log    ${output}
 200
 201 Virtual_Env_Deactivate_On_Current_Session
 202     [Arguments]    ${log_output}=${False}
 203     [Documentation]    Deactivates virtual environment.
 204     SSHLibrary.Write    deactivate
 205     ${output}=    SSHLibrary.Read_Until_Prompt
 206     BuiltIn.Run_Keyword_If    ${log_output}==${True}    BuiltIn.Log    ${output}
 207
 208 Unsafe_Copy_File_To_Remote_System
 209     [Arguments]    ${system}    ${source}    ${destination}=./    ${user}=${DEFAULT_USER}    ${password}=${DEFAULT_PASSWORD}    ${prompt}=${DEFAULT_LINUX_PROMPT}
 210     ...    ${prompt_timeout}=5s
 211     [Documentation]    Copy the ${source} file to the ${destination} file on the remote ${system}. The keyword opens and closes a single
 212     ...    ssh connection and does not rely on any existing ssh connection that may be open.
 213     SSHLibrary.Open_Connection    ${system}    prompt=${prompt}    timeout=${prompt_timeout}
 214     Flexible_SSH_Login    ${user}    ${password}
 215     SSHLibrary.Put_File    ${source}    ${destination}
 216     SSHLibrary.Close Connection
 217
 218 Copy_File_To_Remote_System
 219     [Arguments]    ${system}    ${source}    ${destination}=./    ${user}=${DEFAULT_USER}    ${password}=${DEFAULT_PASSWORD}    ${prompt}=${DEFAULT_LINUX_PROMPT}
 220     ...    ${prompt_timeout}=5s
 221     [Documentation]    Copy the ${source} file to the ${destination} file on the remote ${system}. Any pre-existing active
 222     ...    ssh connection will be retained.
 223     SSHKeywords.Run_Keyword_Preserve_Connection    SSHKeywords.Unsafe_Copy_File_To_Remote_System    ${system}    ${source}    ${destination}    ${user}    ${password}
 224     ...    ${prompt}    ${prompt_timeout}
 225
 226 Copy_File_To_Odl_System
 227     [Arguments]    ${system}    ${source}    ${destination}=./
 228     [Documentation]    Wrapper keyword to make it easier to copy a file to an ODL specific system
 229     SSHKeywords.Copy_File_To_Remote_System    ${system}    ${source}    ${destination}    ${ODL_SYSTEM_USER}    ${ODL_SYSTEM_PASSWORD}    ${ODL_SYSTEM_PROMPT}
 230
 231 Copy_File_To_Tools_System
 232     [Arguments]    ${system}    ${source}    ${destination}=./
 233     [Documentation]    Wrapper keyword to make it easier to copy a file to an Tools specific system
 234     SSHKeywords.Copy_File_To_Remote_System    ${system}    ${source}    ${destination}    ${TOOLS_SYSTEM_USER}    ${TOOLS_SYSTEM_PASSWORD}    ${TOOLS_SYSTEM_PROMPT}
 235
 236 Flexible_SSH_Login
 237     [Arguments]    ${user}    ${password}=${EMPTY}    ${delay}=0.5s
 238     [Documentation]    On active SSH session: if given non-empty password, do Login, else do Login With Public Key.
 239     ${pwd_length} =    BuiltIn.Get Length    ${password}
 240     # ${pwd_length} is guaranteed to be an integer, so we are safe to evaluate it as Python expression.
 241     BuiltIn.Run Keyword And Return If    ${pwd_length} > 0    SSHLibrary.Login    ${user}    ${password}    delay=${delay}
 242     BuiltIn.Run Keyword And Return    SSHLibrary.Login With Public Key    ${user}    ${USER_HOME}/.ssh/${SSH_KEY}    ${KEYFILE_PASS}    delay=${delay}
 243
 244 Flexible_Mininet_Login
 245     [Arguments]    ${user}=${TOOLS_SYSTEM_USER}    ${password}=${TOOLS_SYSTEM_PASSWORD}    ${delay}=0.5s
 246     [Documentation]    Call Flexible SSH Login, but with default values suitable for Mininet machine.
 247     BuiltIn.Run Keyword And Return    Flexible SSH Login    user=${user}    password=${password}    delay=${delay}
 248
 249 Flexible_Controller_Login
 250     [Arguments]    ${user}=${ODL_SYSTEM_USER}    ${password}=${ODL_SYSTEM_PASSWORD}    ${delay}=0.5s
 251     [Documentation]    Call Flexible SSH Login, but with default values suitable for Controller machine.
 252     BuiltIn.Run Keyword And Return    Flexible SSH Login    user=${user}    password=${password}    delay=${delay}