Debian Codegraph @

docs/src/cdist-remote-exec-copy.rst

raw
1 Remote exec and copy commands
2 =============================
3
4 Cdist interacts with the target host in two ways:
5
6 - it executes code (__remote_exec)
7 - and it copies files (__remote_copy)
8
9 By default this is accomplished with ssh and scp respectively.
10 The default implementations used by cdist are::
11
12 __remote_exec: ssh -o User=root
13 __remote_copy: scp -o User=root -q
14
15 The user can override these defaults by providing custom implementations and
16 passing them to cdist with the --remote-exec and/or --remote-copy arguments.
17
18 For __remote_exec, the custom implementation must behave as if it where ssh.
19 For __remote_copy, it must behave like scp.
20 Please notice, custom implementations should work like ssh/scp so __remote_copy
21 must support IPv6 addresses enclosed in square brackets. For __remote_exec you
22 must take into account that for some options (like -L) IPv6 addresses can be
23 specified by enclosed in square brackets (see :strong:`ssh`\ (1) and
24 :strong:`scp`\ (1)).
25
26 With this simple interface the user can take total control of how cdist
27 interacts with the target when required, while the default implementation
28 remains as simple as possible.
29
30
31 Examples
32 --------
33
34 Here are examples of using alternative __remote_copy and __remote_exec scripts.
35
36 All scripts from below are present in cdist sources in `other/examples/remote`
37 directory.
38
39 ssh
40 ~~~
41
42 Same as cdist default.
43
44 **copy**
45
46 Usage: cdist config --remote-copy "/path/to/this/script" target_host
47
48 .. code-block:: sh
49
50 #echo "$@" | logger -t "cdist-ssh-copy"
51 scp -o User=root -q $@
52
53 **exec**
54
55 Usage: cdist config --remote-exec "/path/to/this/script" target_host
56
57 .. code-block:: sh
58
59 #echo "$@" | logger -t "cdist-ssh-exec"
60 ssh -o User=root $@
61
62 local
63 ~~~~~
64
65 This effectively turns remote calling into local calling. Probably most useful
66 for the unit testing.
67
68 **copy**
69
70 .. code-block:: sh
71
72 code="$(echo "$@" | sed "s|\([[:space:]]\)$__target_host:|\1|g")"
73 cp -L $code
74
75 **exec**
76
77 .. code-block:: sh
78
79 target_host=$1; shift
80 echo "$@" | /bin/sh
81
82 chroot
83 ~~~~~~
84
85 **copy**
86
87 Usage: cdist config --remote-copy "/path/to/this/script /path/to/your/chroot" target-id
88
89 .. code-block:: sh
90
91 log() {
92 #echo "$@" | logger -t "cdist-chroot-copy"
93 :
94 }
95
96 chroot="$1"; shift
97 target_host="$__target_host"
98
99 # replace target_host with chroot location
100 code="$(echo "$@" | sed "s|$target_host:|$chroot|g")"
101
102 log "target_host: $target_host"
103 log "chroot: $chroot"
104 log "$@"
105 log "$code"
106
107 # copy files into chroot
108 cp $code
109
110 log "-----"
111
112 **exec**
113
114 Usage: cdist config --remote-exec "/path/to/this/script /path/to/your/chroot" target-id
115
116 .. code-block:: sh
117
118 log() {
119 #echo "$@" | logger -t "cdist-chroot-exec"
120 :
121 }
122
123 chroot="$1"; shift
124 target_host="$1"; shift
125
126 script=$(mktemp "${chroot}/tmp/chroot-${0##*/}.XXXXXXXXXX")
127 trap cleanup INT TERM EXIT
128 cleanup() {
129 [ $__cdist_debug ] || rm "$script"
130 }
131
132 log "target_host: $target_host"
133 log "script: $script"
134 log "@: $@"
135 echo "#!/bin/sh -l" > "$script"
136 echo "$@" >> "$script"
137 chmod +x "$script"
138
139 relative_script="${script#$chroot}"
140 log "relative_script: $relative_script"
141
142 # run in chroot
143 chroot "$chroot" "$relative_script"
144
145 log "-----"
146
147 rsync
148 ~~~~~
149
150 **copy**
151
152 Usage: cdist config --remote-copy /path/to/this/script target_host
153
154 .. code-block:: sh
155
156 # For rsync to do the right thing, the source has to end with "/" if it is
157 # a directory. The below preprocessor loop takes care of that.
158
159 # second last argument is the source
160 source_index=$(($#-1))
161 index=0
162 for arg in $@; do
163 if [ $index -eq 0 ]; then
164 # reset $@
165 set --
166 fi
167 index=$((index+=1))
168 if [ $index -eq $source_index -a -d "$arg" ]; then
169 arg="${arg%/}/"
170 fi
171 set -- "$@" "$arg"
172 done
173
174 rsync --backup --suffix=~cdist -e 'ssh -o User=root' $@
175
176 schroot
177 ~~~~~~~
178
179 __remote_copy and __remote_exec scripts to run cdist against a chroot on the
180 target host over ssh.
181
182 **copy**
183
184 Usage: cdist config --remote-copy "/path/to/this/script schroot-chroot-name" target_host
185
186
187 .. code-block:: sh
188
189 log() {
190 #echo "$@" | logger -t "cdist-schroot-copy"
191 :
192 }
193
194 chroot_name="$1"; shift
195 target_host="$__target_host"
196
197 # get directory for given chroot_name
198 chroot="$(ssh -o User=root -q $target_host schroot -c $chroot_name --config | awk -F = '/directory=/ {print $2}')"
199
200 # prefix destination with chroot
201 code="$(echo "$@" | sed "s|$target_host:|$target_host:$chroot|g")"
202
203 log "target_host: $target_host"
204 log "chroot_name: $chroot_name"
205 log "chroot: $chroot"
206 log "@: $@"
207 log "code: $code"
208
209 # copy files into remote chroot
210 scp -o User=root -q $code
211
212 log "-----"
213
214 **exec**
215
216 Usage: cdist config --remote-exec "/path/to/this/script schroot-chroot-name" target_host
217
218 .. code-block:: sh
219
220 log() {
221 #echo "$@" | logger -t "cdist-schroot-exec"
222 :
223 }
224
225 chroot_name="$1"; shift
226 target_host="$1"; shift
227
228 code="ssh -o User=root -q $target_host schroot -c $chroot_name -- $@"
229
230 log "target_host: $target_host"
231 log "chroot_name: $chroot_name"
232 log "@: $@"
233 log "code: $code"
234
235 # run in remote chroot
236 $code
237
238 log "-----"
239
240 schroot-uri
241 ~~~~~~~~~~~
242
243 __remote_exec/__remote_copy script to run cdist against a schroot target URI.
244
245 Usage::
246
247 cdist config \
248 --remote-exec "/path/to/this/script exec" \
249 --remote-copy "/path/to/this/script copy" \
250 target_uri
251
252 # target_uri examples:
253 schroot:///chroot-name
254 schroot://foo.ethz.ch/chroot-name
255 schroot://[email protected]/chroot-name
256
257 # and how to match them in .../manifest/init
258 case "$target_host" in
259 schroot://*)
260 # any schroot
261 ;;
262 schroot://foo.ethz.ch/*)
263 # any schroot on specific host
264 ;;
265 schroot://foo.ethz.ch/chroot-name)
266 # specific schroot on specific host
267 ;;
268 schroot:///chroot-name)
269 # specific schroot on localhost
270 ;;
271 esac
272
273 **copy/exec**
274
275 .. code-block:: sh
276
277 my_name="${0##*/}"
278 mode="$1"; shift
279
280 log() {
281 # uncomment me for debugging
282 #echo "$@" | logger -t "cdist-$my_name-$mode"
283 :
284 }
285
286 die() {
287 echo "$@" >&2
288 exit 1
289 }
290
291
292 uri="$__target_host"
293
294 scheme="${uri%%:*}"; rest="${uri#$scheme:}"; rest="${rest#//}"
295 authority="${rest%%/*}"; rest="${rest#$authority}"
296 path="${rest%\?*}"; rest="${rest#$path}"
297 schroot_name="${path#/}"
298
299 [ "$scheme" = "schroot" ] || die "Failed to parse scheme from __target_host ($__target_host). Expected 'schroot', got '$scheme'"
300 [ -n "$schroot_name" ] || die "Failed to parse schroot name from __target_host: $__target_host"
301
302 case "$authority" in
303 '')
304 # authority is empty, neither user nor host given
305 user=""
306 host=""
307 ;;
308 *@*)
309 # authority contains @, take user from authority
310 user="${authority%@*}"
311 host="${authority#*@}"
312 ;;
313 *)
314 # no user in authority, default to root
315 user="root"
316 host="$authority"
317 ;;
318 esac
319
320 log "mode: $mode"
321 log "@: $@"
322 log "uri: $uri"
323 log "scheme: $scheme"
324 log "authority: $authority"
325 log "user: $user"
326 log "host: $host"
327 log "path: $path"
328 log "schroot_name: $schroot_name"
329
330 exec_prefix=""
331 copy_prefix=""
332 if [ -n "$host" ]; then
333 # we are working on a remote host
334 exec_prefix="ssh -o User=$user -q $host"
335 copy_prefix="scp -o User=$user -q"
336 copy_destination_prefix="$host:"
337 else
338 # working on local machine
339 copy_prefix="cp"
340 copy_destination_prefix=""
341 fi
342 log "exec_prefix: $exec_prefix"
343 log "copy_prefix: $copy_prefix"
344 log "copy_destination_prefix: $copy_destination_prefix"
345
346 case "$mode" in
347 exec)
348 # In exec mode the first argument is the __target_host which we already got from env. Get rid of it.
349 shift
350 code="$exec_prefix schroot -c $schroot_name -- sh -c '$@'"
351 ;;
352 copy)
353 # get directory for given chroot_name
354 schroot_directory="$($exec_prefix schroot -c $schroot_name --config | awk -F = '/directory=/ {print $2}')"
355 [ -n "$schroot_directory" ] || die "Failed to retreive schroot directory for schroot: $schroot_name"
356 log "schroot_directory: $schroot_directory"
357 # prefix destination with chroot
358 code="$copy_prefix $(echo "$@" | sed "s|$uri:|${copy_destination_prefix}${schroot_directory}|g")"
359 ;;
360 *) die "Unknown mode: $mode";;
361 esac
362
363 log "code: $code"
364
365 # Run the code
366 $code
367
368 log "-----"
369
370 sudo
371 ~~~~
372
373 **copy**
374
375 Use rsync over ssh to copy files. Uses the "--rsync-path" option
376 to run the remote rsync instance with sudo.
377
378 This command assumes your ssh configuration is already set up in ~/.ssh/config.
379
380 Usage: cdist config --remote-copy /path/to/this/script target_host
381
382 .. code-block:: sh
383
384 # For rsync to do the right thing, the source has to end with "/" if it is
385 # a directory. The below preprocessor loop takes care of that.
386
387 # second last argument is the source
388 source_index=$(($#-1))
389 index=0
390 for arg in $@; do
391 if [ $index -eq 0 ]; then
392 # reset $@
393 set --
394 fi
395 index=$((index+=1))
396 if [ $index -eq $source_index -a -d "$arg" ]; then
397 arg="${arg%/}/"
398 fi
399 set -- "$@" "$arg"
400 done
401
402 rsync --copy-links --rsync-path="sudo rsync" -e 'ssh' "$@"
403
404 **exec**
405
406 Prefixes all remote commands with sudo.
407
408 This command assumes your ssh configuration is already set up in ~/.ssh/config.
409
410 Usage: cdist config --remote-exec "/path/to/this/script" target_host
411
412 .. code-block:: sh
413
414 host="$1"; shift
415 ssh -q "$host" sudo sh -c \""$@"\"