Debian Codegraph @

docs/examples.rst

raw
1
2 Examples
3 ========
4
5
6 Fixing Bugs By Replacing Shell
7 ------------------------------
8
9 Have you ever encountered shell like this? It arranges to conditionally execute
10 an ``if`` statement as root on a file server behind a bastion host:
11
12 .. code-block:: bash
13
14 ssh bastion "
15 if [ \"$PROD\" ];
16 then
17 ssh fileserver sudo su -c \"
18 if grep -qs /dev/sdb1 /proc/mounts;
19 then
20 echo \\\"sdb1 already mounted!\\\";
21 umount /dev/sdb1
22 fi;
23 rm -rf \\\"/media/Main Backup Volume\\\"/*;
24 mount /dev/sdb1 \\\"/media/Main Backup Volume\\\"
25 \";
26 fi;
27 sudo touch /var/run/start_backup;
28 "
29
30 Chances are high this is familiar territory, we've all seen it, and those
31 working in infrastructure have almost certainly written it. At first glance,
32 ignoring that annoying quoting, it looks perfectly fine: well structured,
33 neatly indented, and the purpose of the snippet seems clear.
34
35 1. At first glance, is ``"/media/Main Backup Volume"`` quoted correctly?
36 2. How will the ``if`` statement behave if there is a problem with the machine,
37 and, say, the ``/bin/grep`` binary is absent?
38 3. Ignoring quoting, are there any other syntax problems?
39 4. If this snippet is pasted from its original script into an interactive
40 shell, will it behave the same as before?
41 5. Can you think offhand of differences in how the arguments to ``sudo
42 ...`` and ``ssh fileserver ...`` are parsed?
43 6. In which context will the ``*`` glob be expanded, if it is expanded at all?
44 7. What will the exit status of ``ssh bastion`` be if ``ssh fileserver`` fails?
45
46
47 Innocent But Deadly
48 ~~~~~~~~~~~~~~~~~~~
49
50 1. The quoting used is nonsense! At best, ``mount`` will receive 3 arguments.
51 At worst, the snippet will not parse at all.
52 2. The ``if`` statement will treat a missing ``grep`` binary (exit status 127)
53 the same as if ``/dev/sdb1`` was not mounted at all (exit status 1). Unless
54 the program executing this script is parsing ``stderr`` output, the failure
55 won't be noticed. Consequently, since the volume was still mounted when
56 ``rm`` was executed, it got wiped.
57 3. There is at least one more syntax error present: a semicolon missing after
58 the ``umount`` command.
59 4. If you paste the snippet into an interactive shell, the apparently quoted
60 "!" character in the ``echo`` command will be interpreted as a history
61 expansion.
62 5. ``sudo`` preserves the remainder of the argument vector as-is, while
63 ``ssh`` **concatenates** each part into a single string that is passed to
64 the login shell. While quotes appearing within arguments are preserved by
65 ``sudo``, without additional effort, pairs of quotes are effectively
66 stripped by ``ssh``.
67 6. As for where the glob is expanded, the answer is I have absolutely no idea
68 without running the code, which might wipe out the backups!
69 7. If the ``ssh fileserver`` command fails, the exit status of ``ssh bastion``
70 will continue to indicate success.
71 8. Depending in which environment the ``PROD`` variable is set, either it will
72 always evaluate to false, because it was set by the bastion host, or it
73 will do the right thing, because it was set by the script host.
74
75 Golly, we've managed to hit at least 8 potentially mission-critical gotchas in
76 only 14 lines of code, and they are just those I can count! Welcome to the
77 reality of "programming" in shell.
78
79 In the end, superficial legibility counted for nothing, it's 4AM, you've been
80 paged, the network is down and your boss is angry.
81
82
83 Shell Quoting Madness
84 ~~~~~~~~~~~~~~~~~~~~~
85
86 Let's assume on first approach that we really want to handle those quoting
87 issues. I wrote a little Python script based around the :py:func:`shlex.quote`
88 function to construct, to the best of my knowledge, the quoting required for
89 each stage:
90
91 .. code-block:: bash
92
93 ssh bastion '
94 if [ "$PROD" ];
95 then
96 ssh fileserver sudo su -c '"'"'
97 if grep -qs /dev/sdb1 /proc/mounts;
98 then
99 echo "sdb1 already mounted!";
100 umount /dev/sdb1
101 fi;
102 rm -rf "/media/Main Backup Volume"/*;
103 mount /dev/sdb1 "/media/Main Backup Volume"
104 '"'"';
105 fi;
106 sudo touch /var/run/start_backup
107 '
108
109 Even with Python handling the heavy lifting of quoting each shell layer, and
110 even if the aforementioned minor disk-wiping issue was fixed, it is still not
111 100% clear that argument handling rules for all of ``su``, ``sudo``, ``ssh``,
112 and ``bash`` are correctly respected.
113
114 Finally, if any login shell involved is not ``bash``, we must introduce
115 additional quoting in order to explicitly invoke ``bash`` at each stage,
116 causing an explosion in quoting:
117
118 .. code-block:: bash
119
120 ssh bastion 'bash -c '"'"'if [ "$PROD" ]; then ssh fileserver bash -c '"'"'
121 "'"'"'"'"'"'sudo su -c '"'"'"'"'"'"'"'"'"'"'"'"'"'"'"'"'"'"'"'"'"'"'"'"'"'"
122 'bash -c '"'"'"'"'"'"'"'"'"'"'"'"'"'"'"'"'"'"'"'"'"'"'"'"'"'"'"'"'"'"'"'"'"
123 '"'"'"'"'"'"'"'"'"'"'"'"'"'"'"'"'"'"'"'"'"'"'"'"'"'"'"'"'"'"'"'"'"'"'"'"'"'
124 "'"'"'"'"'"'"'"'"'"'if grep -qs /dev/sdb1 /proc/mounts; then echo "sdb1 alr
125 eady mounted!"; umount /dev/sdb1 fi; rm -rf "/media/Main Backup Volume"/*;
126 mount /dev/sdb1 "/media/Main Backup Volume"'"'"'"'"'"'"'"'"'"'"'"'"'"'"'"'"
127 '"'"'"'"'"'"'"'"'"'"'"'"'"'"'"'"'"'"'"'"'"'"'"'"'"'"'"'"'"'"'"'"'"'"'"'"'"'
128 "'"'"'"'"'"'"'"'"'"'"'"'"'"'"'"'"'"'"'"'"'"'"'"'"'"'"''"'"'"'"'"'"'"'"'"'"'
129 "'"'"'"'"'"'"'"'"'"'"'"'"'"'"'"''"'"'"'"'"'"'"'"'; fi; sudo touch /var/run/
130 start_backup'"'"''
131
132
133 There Is Hope
134 ~~~~~~~~~~~~~
135
136 We could instead express the above using Mitogen:
137
138 ::
139
140 import shutil, os, subprocess
141 import mitogen
142
143 def run(*args):
144 return subprocess.check_call(args)
145
146 def file_contains(s, path):
147 with open(path, 'rb') as fp:
148 return s in fp.read()
149
150 @mitogen.main()
151 def main(router):
152 device = '/dev/sdb1'
153 mount_point = '/media/Media Volume'
154
155 bastion = router.ssh(hostname='bastion')
156 bastion_sudo = router.sudo(via=bastion)
157
158 if PROD:
159 fileserver = router.ssh(hostname='fileserver', via=bastion)
160 if fileserver.call(file_contains, device, '/proc/mounts'):
161 print('{} already mounted!'.format(device))
162 fileserver.call(run, 'umount', device)
163 fileserver.call(shutil.rmtree, mount_point)
164 fileserver.call(os.mkdir, mount_point, 0777)
165 fileserver.call(run, 'mount', device, mount_point)
166
167 bastion_sudo.call(run, 'touch', '/var/run/start_backup')
168
169 * In which context must the ``PROD`` variable be defined?
170 * On which machine is each step executed?
171 * Are there any escaping issues?
172 * What will happen if the ``grep`` binary is missing?
173 * What will happen if any step fails?
174 * What will happen if any login shell is not ``bash``?
175
176
177 Recursively Nested Bootstrap
178 ----------------------------
179
180 This demonstrates the library's ability to use slave contexts to recursively
181 proxy connections to additional slave contexts, with a uniform API to any
182 slave, and all features (function calls, import forwarding, stdio forwarding,
183 log forwarding) functioning transparently.
184
185 This example uses a chain of local contexts for clarity, however SSH and sudo
186 contexts work identically.
187
188 nested.py:
189
190 .. code-block:: python
191
192 import os
193 import mitogen
194
195 @mitogen.main()
196 def main(router):
197 context = None
198 for x in range(1, 11):
199 print('Connect local%d via %s' % (x, context))
200 context = router.local(via=context, name='local%d' % x)
201
202 context.call(subprocess.check_call, ['pstree', '-s', 'python', '-s', 'mitogen'])
203
204
205 Output:
206
207 .. code-block:: shell
208
209 $ python nested.py
210 Connect local1 via None
211 Connect local2 via Context(1, 'local1')
212 Connect local3 via Context(2, 'local2')
213 Connect local4 via Context(3, 'local3')
214 Connect local5 via Context(4, 'local4')
215 Connect local6 via Context(5, 'local5')
216 Connect local7 via Context(6, 'local6')
217 Connect local8 via Context(7, 'local7')
218 Connect local9 via Context(8, 'local8')
219 Connect local10 via Context(9, 'local9')
220 18:14:07 I ctx.local10: stdout: -+= 00001 root /sbin/launchd
221 18:14:07 I ctx.local10: stdout: \-+= 08126 dmw /Applications/iTerm.app/Contents/MacOS/iTerm2
222 18:14:07 I ctx.local10: stdout: \-+= 10638 dmw /Applications/iTerm.app/Contents/MacOS/iTerm2 --server bash --login
223 18:14:07 I ctx.local10: stdout: \-+= 10639 dmw bash --login
224 18:14:07 I ctx.local10: stdout: \-+= 13632 dmw python nested.py
225 18:14:07 I ctx.local10: stdout: \-+- 13633 dmw mitogen:[email protected]:13632
226 18:14:07 I ctx.local10: stdout: \-+- 13635 dmw mitogen:[email protected]:13633
227 18:14:07 I ctx.local10: stdout: \-+- 13637 dmw mitogen:[email protected]:13635
228 18:14:07 I ctx.local10: stdout: \-+- 13639 dmw mitogen:[email protected]:13637
229 18:14:07 I ctx.local10: stdout: \-+- 13641 dmw mitogen:[email protected]:13639
230 18:14:07 I ctx.local10: stdout: \-+- 13643 dmw mitogen:[email protected]:13641
231 18:14:07 I ctx.local10: stdout: \-+- 13645 dmw mitogen:[email protected]:13643
232 18:14:07 I ctx.local10: stdout: \-+- 13647 dmw mitogen:[email protected]:13645
233 18:14:07 I ctx.local10: stdout: \-+- 13649 dmw mitogen:[email protected]:13647
234 18:14:07 I ctx.local10: stdout: \-+- 13651 dmw mitogen:[email protected]:13649
235 18:14:07 I ctx.local10: stdout: \-+- 13653 dmw pstree -s python -s mitogen
236 18:14:07 I ctx.local10: stdout: \--- 13654 root ps -axwwo user,pid,ppid,pgid,command