open4ssh 0.1.1 → 0.1.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- checksums.yaml +4 -4
- data/CHANGELOG.md +9 -4
- data/README.md +54 -27
- data/lib/open4ssh/version.rb +1 -1
- data/lib/open4ssh.rb +119 -1
- metadata +2 -2
checksums.yaml
CHANGED
@@ -1,7 +1,7 @@
|
|
1
1
|
---
|
2
2
|
SHA1:
|
3
|
-
metadata.gz:
|
4
|
-
data.tar.gz:
|
3
|
+
metadata.gz: 26bd3a93e22a85fff7203c396a7f9a63c9370b2d
|
4
|
+
data.tar.gz: 4ef5d35b8d5770e9d67c32da55e06f04552478af
|
5
5
|
SHA512:
|
6
|
-
metadata.gz:
|
7
|
-
data.tar.gz:
|
6
|
+
metadata.gz: 2913a4e37a357677c7865581f6108ed91c9633e6d3f5b0160654b4a94cc51217fd8775354c3d42f45ff888ac8b9d655e1f4827ac765eac975cb148f3255f7bce
|
7
|
+
data.tar.gz: a384c9dd93d1964c060be4bf1aedf3994f0530d926152db775169a552fa299b9c18f4db0277322db0f4a36063b14887c11d20e2e03eb614af62f28cbca7e035e
|
data/CHANGELOG.md
CHANGED
@@ -1,15 +1,20 @@
|
|
1
1
|
# Changelog
|
2
2
|
|
3
|
+
## Version 0.1.2
|
4
|
+
|
5
|
+
- Added <code>success(), stdout(), stderr(), console()</code> functions.
|
6
|
+
- Optimized documentation.
|
7
|
+
|
3
8
|
## Version 0.1.1
|
4
9
|
|
5
10
|
Warning, this update is not backward compatible.
|
6
11
|
|
7
|
-
-
|
8
|
-
-
|
12
|
+
- Renamed <code>exec</code> to <code>capture</code> function (better alignment to Open3)
|
13
|
+
- Renamed <code>exec4</code> to <code>capture4</code> function (better alignment to Open3)
|
9
14
|
|
10
15
|
## Version 0.1.0
|
11
16
|
|
12
17
|
Initial release.
|
13
18
|
|
14
|
-
- exec function
|
15
|
-
-
|
19
|
+
- Introduced <code>exec</code> function.
|
20
|
+
- Introduced <code>exec4</code> function.
|
data/README.md
CHANGED
@@ -15,6 +15,10 @@ sequence of commands and returns their exit codes, standard out and standard err
|
|
15
15
|
|
16
16
|
Open4ssh is most useful in remote automation scenarios which are triggered from Ruby environments.
|
17
17
|
|
18
|
+
- [RubyGems](https://rubygems.org/gems/open4ssh)
|
19
|
+
- [CHANGELOG](file.CHANGELOG.html)
|
20
|
+
- [LICENSE](file.LICENSE.html)
|
21
|
+
|
18
22
|
## Installation
|
19
23
|
|
20
24
|
Add this line to your application's Gemfile:
|
@@ -33,9 +37,9 @@ Or install it yourself as:
|
|
33
37
|
|
34
38
|
## Usage
|
35
39
|
|
36
|
-
### Remote execution of a single command via SSH
|
40
|
+
### Remote execution of a single command via SSH using <code>capture()</code>
|
37
41
|
|
38
|
-
All parameters of the
|
42
|
+
All parameters of the <code>capture()</code> command are explained [here](Open4ssh.html#capture-class_method).
|
39
43
|
|
40
44
|
However, the following snippets explain how to use Open4ssh.
|
41
45
|
To execute simply one single command on a remote host, we can do the following:
|
@@ -69,9 +73,9 @@ stdout = Open4ssh.capture(
|
|
69
73
|
puts stdout
|
70
74
|
```
|
71
75
|
|
72
|
-
### Remote execution of a sequence of commands via SSH
|
76
|
+
### Remote execution of a sequence of commands via SSH using <code>capture4()</code>
|
73
77
|
|
74
|
-
All parameters of the
|
78
|
+
All parameters of the <code>capture4()</code> function are explained [here](Open4ssh.html#capture4-class_method).
|
75
79
|
The following snippets will explain how to use Open4ssh to execute a (sequence) of commands.
|
76
80
|
|
77
81
|
This snippet here will execute five shell commands sequentially
|
@@ -108,7 +112,7 @@ So, for each command a list of return values is returned.
|
|
108
112
|
1. exit code of the executed command
|
109
113
|
2. standard out message (might be empty)
|
110
114
|
3. standard error message (might be empty)
|
111
|
-
4. executed command (as passed by the _cmd_ parameter
|
115
|
+
4. executed command (as passed by the _cmd_ parameter)
|
112
116
|
|
113
117
|
However, if we launch a sequence of commands exiting with exit codes not equal 0, this sequence is only executed as long as
|
114
118
|
each command could be successfully processed (exit code 0). So this snippet here
|
@@ -140,13 +144,13 @@ would produce the following output
|
|
140
144
|
|
141
145
|
and the last two commands would not been executed on the remote host, because the third command failed.
|
142
146
|
|
143
|
-
### How to check whether a sequence of commands was successful?
|
147
|
+
### How to check whether a sequence of commands was successful? Use <code>success()</code>
|
144
148
|
|
145
149
|
Because Open4ssh only executes commands as long as they are returning a exit code of 0, we can check
|
146
150
|
pragmatically whether all commands of a sequence have been executed successfully:
|
147
151
|
|
148
152
|
```ruby
|
149
|
-
|
153
|
+
returns = Open4ssh.capture4(
|
150
154
|
host: 'remote.host.io',
|
151
155
|
user: 'nane',
|
152
156
|
key: '/path/to/your/sshkey.pem',
|
@@ -157,59 +161,77 @@ exit_code, stderr, stdout, command = Open4ssh.capture4(
|
|
157
161
|
"cat helloworld.txt",
|
158
162
|
"rm helloworld.txt"
|
159
163
|
]
|
160
|
-
)
|
164
|
+
)
|
161
165
|
|
162
|
-
if (
|
166
|
+
if Open4ssh.success(returns)
|
163
167
|
puts "Everything worked fine"
|
164
168
|
end
|
165
169
|
```
|
166
170
|
|
167
|
-
###
|
171
|
+
### Verbose mode
|
168
172
|
|
169
|
-
|
173
|
+
If you want to know what is happening there you can turn on the verbose mode (mostly useful for debugging).
|
170
174
|
|
171
175
|
```ruby
|
172
|
-
|
176
|
+
returns = Open4ssh.capture4(
|
173
177
|
host: 'remote.host.io',
|
174
178
|
user: 'nane',
|
175
179
|
key: '/path/to/your/sshkey.pem',
|
176
180
|
cmd: [
|
177
181
|
"curl -fsSL https://test.docker.com/ | sh",
|
178
182
|
"sudo docker swarm init"
|
179
|
-
]
|
180
|
-
|
183
|
+
],
|
184
|
+
verbose: true
|
185
|
+
)
|
181
186
|
|
182
|
-
if (
|
187
|
+
if Open4ssh.success(returns)
|
183
188
|
puts "You started successfully a new Docker Swarm cluster."
|
184
189
|
end
|
185
190
|
```
|
186
191
|
|
187
|
-
This
|
188
|
-
in a few lines of Ruby code. Be patient. This can take several minutes.
|
189
|
-
Of course, you can do any other tasks as well. This was only one example ;-)
|
192
|
+
This will perform the same install like above but will print all messages of the Docker install script on your console.
|
190
193
|
|
191
|
-
###
|
194
|
+
### How to get stdout and stderr outputs? Use <code>stdout(), stderr(), console()</code>
|
192
195
|
|
193
|
-
|
196
|
+
It is possible to print all standard output and error messages of
|
197
|
+
sequentially executed commands by calling <code>stdout()</code>, <code>stderr()</code> or <code>console()</code>
|
198
|
+
with the return of a <code>capture4()</code> call.
|
194
199
|
|
195
200
|
```ruby
|
196
|
-
|
201
|
+
# This will print all standard output messages of all executed commands.
|
202
|
+
puts Open4ssh.stdout(returns)
|
203
|
+
|
204
|
+
# This will print all standard error messages of all executed commands.
|
205
|
+
puts Open4ssh.stderr(returns)
|
206
|
+
|
207
|
+
# This will print all console output messages of all executed commands
|
208
|
+
# (which includes standard out and standard err messages).
|
209
|
+
puts Open4ssh.console(returns)
|
210
|
+
```
|
211
|
+
|
212
|
+
### What is this good for?
|
213
|
+
|
214
|
+
Just a small example. Assuming your remote host is a Ubuntu 14.04 system we could do something like that:
|
215
|
+
|
216
|
+
```ruby
|
217
|
+
returns = Open4ssh.capture4(
|
197
218
|
host: 'remote.host.io',
|
198
219
|
user: 'nane',
|
199
220
|
key: '/path/to/your/sshkey.pem',
|
200
221
|
cmd: [
|
201
222
|
"curl -fsSL https://test.docker.com/ | sh",
|
202
223
|
"sudo docker swarm init"
|
203
|
-
]
|
204
|
-
|
205
|
-
).last
|
224
|
+
]
|
225
|
+
)
|
206
226
|
|
207
|
-
if (
|
227
|
+
if Open4ssh.success(returns)
|
208
228
|
puts "You started successfully a new Docker Swarm cluster."
|
209
229
|
end
|
210
230
|
```
|
211
231
|
|
212
|
-
This
|
232
|
+
This would fire up an initial master for a [Docker Swarm cluster](https://docs.docker.com/engine/swarm/)
|
233
|
+
in a few lines of Ruby code. Be patient. This can take several minutes.
|
234
|
+
Of course, you can do any other tasks as well. This was only one example ;-)
|
213
235
|
|
214
236
|
## Development
|
215
237
|
|
@@ -221,8 +243,13 @@ push git commits and tags, and push the `.gem` file to [rubygems.org](https://ru
|
|
221
243
|
|
222
244
|
## Contributing
|
223
245
|
|
224
|
-
|
246
|
+
All kind of
|
247
|
+
|
248
|
+
- bug reports,
|
249
|
+
- feature requests,
|
250
|
+
- and pull requests
|
225
251
|
|
252
|
+
are welcome on Github at https://github.com/nkratzke/open4ssh.
|
226
253
|
|
227
254
|
## License
|
228
255
|
|
data/lib/open4ssh/version.rb
CHANGED
data/lib/open4ssh.rb
CHANGED
@@ -46,7 +46,7 @@ module Open4ssh
|
|
46
46
|
# @param cmd [Array<String>] List of valid shell command strings to be executed on host (required)
|
47
47
|
# @param verbose [Bool] console outputs are plotted to stdout/stderr if set (defaults to false)
|
48
48
|
#
|
49
|
-
# @return [Array<exit_code,
|
49
|
+
# @return [Array<exit_code, std_out, std_err, command>] List of exit_code, stdout, stderr and executed commands
|
50
50
|
#
|
51
51
|
# @example
|
52
52
|
# exit_code, stderr, stdout, command = Open4ssh.capture4(
|
@@ -101,4 +101,122 @@ module Open4ssh
|
|
101
101
|
|
102
102
|
return results
|
103
103
|
end
|
104
|
+
|
105
|
+
# Determines whether a list of shell commands has been executed successfully.
|
106
|
+
#
|
107
|
+
# @param results [Array<exit_code, std_out, std_err, command>] List of returns by executed commands as returned by capture4
|
108
|
+
#
|
109
|
+
# @return [Bool] true, if all exit codes are 0;
|
110
|
+
# @return [Bool] false, otherwise
|
111
|
+
#
|
112
|
+
# @example
|
113
|
+
# ecodes = Open4ssh.capture4(
|
114
|
+
# host: 'remote.host.io',
|
115
|
+
# user: 'nane',
|
116
|
+
# key: '/path/to/your/sshkey.pem',
|
117
|
+
# cmd: [
|
118
|
+
# "touch helloworld.txt",
|
119
|
+
# "cat helloworld.txt",
|
120
|
+
# "echo 'Hello World' >> helloworld.txt",
|
121
|
+
# "cat helloworld.txt",
|
122
|
+
# "rm helloworld.txt"
|
123
|
+
# ])
|
124
|
+
#
|
125
|
+
# if Open4ssh.success(ecodes)
|
126
|
+
# puts "Success:"
|
127
|
+
# puts Open4ssh.console(ecodes) # Print collected console outputs of all executed commands
|
128
|
+
# end
|
129
|
+
#
|
130
|
+
def self.success(results)
|
131
|
+
results.select { |result| result[0] != 0 }
|
132
|
+
.empty?
|
133
|
+
end
|
134
|
+
|
135
|
+
# Collects all stdout messages of a list of executed shell commands.
|
136
|
+
#
|
137
|
+
# @param results [Array<exit_code, std_out, std_err, command>] List of returns by executed commands as returned by capture4
|
138
|
+
#
|
139
|
+
# @return [String] All stdout messages (separated by line feed \n)
|
140
|
+
#
|
141
|
+
# @example
|
142
|
+
# ecodes = Open4ssh.capture4(
|
143
|
+
# host: 'remote.host.io',
|
144
|
+
# user: 'nane',
|
145
|
+
# key: '/path/to/your/sshkey.pem',
|
146
|
+
# cmd: [
|
147
|
+
# "touch helloworld.txt",
|
148
|
+
# "cat helloworld.txt",
|
149
|
+
# "echo 'Hello World' >> helloworld.txt",
|
150
|
+
# "cat helloworld.txt",
|
151
|
+
# "rm helloworld.txt"
|
152
|
+
# ])
|
153
|
+
#
|
154
|
+
# if Open4ssh.success(ecodes)
|
155
|
+
# puts "Success:"
|
156
|
+
# puts Open4ssh.stdout(ecodes) # Print collected stdout messages of all executed commands
|
157
|
+
# end
|
158
|
+
#
|
159
|
+
def self.stdout(results)
|
160
|
+
output = results.map { |result| result[1] }
|
161
|
+
.select { |stdout| not stdout.strip.empty? } * "\n"
|
162
|
+
output.strip
|
163
|
+
end
|
164
|
+
|
165
|
+
# Collects all stderr messages of a list of executed shell commands.
|
166
|
+
#
|
167
|
+
# @param results [Array<exit_code, std_out, std_err, command>] List of returns by executed commands as returned by capture4
|
168
|
+
#
|
169
|
+
# @return [String] All stderr messages (separated by line feed \n)
|
170
|
+
#
|
171
|
+
# @example
|
172
|
+
# ecodes = Open4ssh.capture4(
|
173
|
+
# host: 'remote.host.io',
|
174
|
+
# user: 'nane',
|
175
|
+
# key: '/path/to/your/sshkey.pem',
|
176
|
+
# cmd: [
|
177
|
+
# "touch helloworld.txt",
|
178
|
+
# "cat helloworld.txt",
|
179
|
+
# "this will fail",
|
180
|
+
# "cat helloworld.txt",
|
181
|
+
# "rm helloworld.txt"
|
182
|
+
# ])
|
183
|
+
#
|
184
|
+
# unless Open4ssh.success(ecodes)
|
185
|
+
# puts "Failure:"
|
186
|
+
# puts Open4ssh.stderr(ecodes) # Print collected stderr messages of all executed commands
|
187
|
+
# end
|
188
|
+
#
|
189
|
+
def self.stderr(results)
|
190
|
+
output = results.map { |result| result[2] }
|
191
|
+
.select { |stderr| not stderr.strip.empty? } * "\n"
|
192
|
+
output.strip
|
193
|
+
end
|
194
|
+
|
195
|
+
# Collects all console messages (stdout + stderr) of a list of executed shell commands.
|
196
|
+
#
|
197
|
+
# @param results [Array<exit_code, std_out, std_err, command>] List of returns by executed commands as returned by capture4
|
198
|
+
#
|
199
|
+
# @return [String] All console messages (separated by line feed \n)
|
200
|
+
#
|
201
|
+
# @example
|
202
|
+
# ecodes = Open4ssh.capture4(
|
203
|
+
# host: 'remote.host.io',
|
204
|
+
# user: 'nane',
|
205
|
+
# key: '/path/to/your/sshkey.pem',
|
206
|
+
# cmd: [
|
207
|
+
# "touch helloworld.txt",
|
208
|
+
# "cat helloworld.txt",
|
209
|
+
# "echo 'Hello World' >> helloworld.txt",
|
210
|
+
# "cat helloworld.txt",
|
211
|
+
# "rm helloworld.txt"
|
212
|
+
# ])
|
213
|
+
#
|
214
|
+
# puts Open4ssh.console(ecodes) # Print collected console messages of all executed commands
|
215
|
+
#
|
216
|
+
def self.console(results)
|
217
|
+
output = results.map { |result| "#{result[1]}\n#{result[2]}" }
|
218
|
+
.select { |console| not console.strip.empty? } * "\n"
|
219
|
+
output.strip
|
220
|
+
end
|
221
|
+
|
104
222
|
end
|
metadata
CHANGED
@@ -1,14 +1,14 @@
|
|
1
1
|
--- !ruby/object:Gem::Specification
|
2
2
|
name: open4ssh
|
3
3
|
version: !ruby/object:Gem::Version
|
4
|
-
version: 0.1.
|
4
|
+
version: 0.1.2
|
5
5
|
platform: ruby
|
6
6
|
authors:
|
7
7
|
- Nane Kratzke
|
8
8
|
autorequire:
|
9
9
|
bindir: bin
|
10
10
|
cert_chain: []
|
11
|
-
date: 2016-07-
|
11
|
+
date: 2016-07-03 00:00:00.000000000 Z
|
12
12
|
dependencies:
|
13
13
|
- !ruby/object:Gem::Dependency
|
14
14
|
name: bundler
|