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