Merge ~barryprice/charm-tor/+git/charm-tor:main into charm-tor:main
- Git
- lp:~barryprice/charm-tor/+git/charm-tor
- main
- Merge into main
Status: | Work in progress |
---|---|
Proposed branch: | ~barryprice/charm-tor/+git/charm-tor:main |
Merge into: | charm-tor:main |
Diff against target: |
2994 lines (+2405/-408) 15 files modified
.gitignore (+6/-3) LICENSE (+674/-202) Makefile (+21/-0) README.md (+8/-16) charmcraft.yaml (+3/-3) config.yaml (+31/-12) dev/null (+0/-16) lib/charms/operator_libs_linux/v0/apt.py (+1329/-0) metadata.yaml (+12/-21) pyproject.toml (+38/-0) src/charm.py (+184/-82) templates/torrc (+12/-0) tests/__init__.py (+4/-0) tests/test_charm.py (+5/-53) tox.ini (+78/-0) |
Related bugs: |
Reviewer | Review Type | Date Requested | Status |
---|---|---|---|
Tor Charmers | Pending | ||
Review via email: mp+425423@code.launchpad.net |
Commit message
WIP MP to replace the charmcraft boilerplate with a functional charm
Description of the change
- d39909c... by Barry Price
-
Add lib, pyproject, tox, refresh ,gitignore
- 47bd6c5... by Barry Price
-
Initial Makefile
- 6264307... by Barry Price
-
Add paths, lint target, run lint
- 1d7bc86... by Barry Price
-
Handle upstream torproject repo installation/
removal - d762c48... by Barry Price
-
Ensure packages are installed on hooks, sort package defs
- 2892df0... by Barry Price
-
Bugfixes
- 6b266a9... by Barry Price
-
Still WIP but a clean deploy with multiple related services works after a fashion (but relation changes fail catastrophically)
- 05532b8... by Barry Price
-
Restore boilerplate
Unmerged commits
- 05532b8... by Barry Price
-
Restore boilerplate
- 6b266a9... by Barry Price
-
Still WIP but a clean deploy with multiple related services works after a fashion (but relation changes fail catastrophically)
- 2892df0... by Barry Price
-
Bugfixes
- d762c48... by Barry Price
-
Ensure packages are installed on hooks, sort package defs
- 1d7bc86... by Barry Price
-
Handle upstream torproject repo installation/
removal - 6264307... by Barry Price
-
Add paths, lint target, run lint
- 47bd6c5... by Barry Price
-
Initial Makefile
- d39909c... by Barry Price
-
Add lib, pyproject, tox, refresh ,gitignore
- 4220710... by Barry Price
-
Basic skeleton, remove most boilerplate, no functionality yet
Preview Diff
1 | diff --git a/.gitignore b/.gitignore | |||
2 | index 2c3f0e5..69a2281 100644 | |||
3 | --- a/.gitignore | |||
4 | +++ b/.gitignore | |||
5 | @@ -1,7 +1,10 @@ | |||
8 | 1 | venv/ | 1 | /build |
9 | 2 | build/ | 2 | /venv |
10 | 3 | |||
11 | 3 | *.charm | 4 | *.charm |
12 | 5 | *.py[cod] | ||
13 | 6 | *.swp | ||
14 | 4 | 7 | ||
15 | 5 | .coverage | 8 | .coverage |
16 | 9 | .tox | ||
17 | 6 | __pycache__/ | 10 | __pycache__/ |
18 | 7 | *.py[cod] | ||
19 | diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md | |||
20 | 8 | deleted file mode 100644 | 11 | deleted file mode 100644 |
21 | index f5dac3b..0000000 | |||
22 | --- a/CONTRIBUTING.md | |||
23 | +++ /dev/null | |||
24 | @@ -1,34 +0,0 @@ | |||
25 | 1 | # charm-tor | ||
26 | 2 | |||
27 | 3 | ## Developing | ||
28 | 4 | |||
29 | 5 | Create and activate a virtualenv with the development requirements: | ||
30 | 6 | |||
31 | 7 | virtualenv -p python3 venv | ||
32 | 8 | source venv/bin/activate | ||
33 | 9 | pip install -r requirements-dev.txt | ||
34 | 10 | |||
35 | 11 | ## Code overview | ||
36 | 12 | |||
37 | 13 | TEMPLATE-TODO: | ||
38 | 14 | One of the most important things a consumer of your charm (or library) | ||
39 | 15 | needs to know is what set of functionality it provides. Which categories | ||
40 | 16 | does it fit into? Which events do you listen to? Which libraries do you | ||
41 | 17 | consume? Which ones do you export and how are they used? | ||
42 | 18 | |||
43 | 19 | ## Intended use case | ||
44 | 20 | |||
45 | 21 | TEMPLATE-TODO: | ||
46 | 22 | Why were these decisions made? What's the scope of your charm? | ||
47 | 23 | |||
48 | 24 | ## Roadmap | ||
49 | 25 | |||
50 | 26 | If this Charm doesn't fulfill all of the initial functionality you were | ||
51 | 27 | hoping for or planning on, please add a Roadmap or TODO here | ||
52 | 28 | |||
53 | 29 | ## Testing | ||
54 | 30 | |||
55 | 31 | The Python operator framework includes a very nice harness for testing | ||
56 | 32 | operator behaviour without full deployment. Just `run_tests`: | ||
57 | 33 | |||
58 | 34 | ./run_tests | ||
59 | diff --git a/LICENSE b/LICENSE | |||
60 | index d645695..f288702 100644 | |||
61 | --- a/LICENSE | |||
62 | +++ b/LICENSE | |||
63 | @@ -1,202 +1,674 @@ | |||
266 | 1 | 1 | GNU GENERAL PUBLIC LICENSE | |
267 | 2 | Apache License | 2 | Version 3, 29 June 2007 |
268 | 3 | Version 2.0, January 2004 | 3 | |
269 | 4 | http://www.apache.org/licenses/ | 4 | Copyright (C) 2007 Free Software Foundation, Inc. <https://fsf.org/> |
270 | 5 | 5 | Everyone is permitted to copy and distribute verbatim copies | |
271 | 6 | TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION | 6 | of this license document, but changing it is not allowed. |
272 | 7 | 7 | ||
273 | 8 | 1. Definitions. | 8 | Preamble |
274 | 9 | 9 | ||
275 | 10 | "License" shall mean the terms and conditions for use, reproduction, | 10 | The GNU General Public License is a free, copyleft license for |
276 | 11 | and distribution as defined by Sections 1 through 9 of this document. | 11 | software and other kinds of works. |
277 | 12 | 12 | ||
278 | 13 | "Licensor" shall mean the copyright owner or entity authorized by | 13 | The licenses for most software and other practical works are designed |
279 | 14 | the copyright owner that is granting the License. | 14 | to take away your freedom to share and change the works. By contrast, |
280 | 15 | 15 | the GNU General Public License is intended to guarantee your freedom to | |
281 | 16 | "Legal Entity" shall mean the union of the acting entity and all | 16 | share and change all versions of a program--to make sure it remains free |
282 | 17 | other entities that control, are controlled by, or are under common | 17 | software for all its users. We, the Free Software Foundation, use the |
283 | 18 | control with that entity. For the purposes of this definition, | 18 | GNU General Public License for most of our software; it applies also to |
284 | 19 | "control" means (i) the power, direct or indirect, to cause the | 19 | any other work released this way by its authors. You can apply it to |
285 | 20 | direction or management of such entity, whether by contract or | 20 | your programs, too. |
286 | 21 | otherwise, or (ii) ownership of fifty percent (50%) or more of the | 21 | |
287 | 22 | outstanding shares, or (iii) beneficial ownership of such entity. | 22 | When we speak of free software, we are referring to freedom, not |
288 | 23 | 23 | price. Our General Public Licenses are designed to make sure that you | |
289 | 24 | "You" (or "Your") shall mean an individual or Legal Entity | 24 | have the freedom to distribute copies of free software (and charge for |
290 | 25 | exercising permissions granted by this License. | 25 | them if you wish), that you receive source code or can get it if you |
291 | 26 | 26 | want it, that you can change the software or use pieces of it in new | |
292 | 27 | "Source" form shall mean the preferred form for making modifications, | 27 | free programs, and that you know you can do these things. |
293 | 28 | including but not limited to software source code, documentation | 28 | |
294 | 29 | source, and configuration files. | 29 | To protect your rights, we need to prevent others from denying you |
295 | 30 | 30 | these rights or asking you to surrender the rights. Therefore, you have | |
296 | 31 | "Object" form shall mean any form resulting from mechanical | 31 | certain responsibilities if you distribute copies of the software, or if |
297 | 32 | transformation or translation of a Source form, including but | 32 | you modify it: responsibilities to respect the freedom of others. |
298 | 33 | not limited to compiled object code, generated documentation, | 33 | |
299 | 34 | and conversions to other media types. | 34 | For example, if you distribute copies of such a program, whether |
300 | 35 | 35 | gratis or for a fee, you must pass on to the recipients the same | |
301 | 36 | "Work" shall mean the work of authorship, whether in Source or | 36 | freedoms that you received. You must make sure that they, too, receive |
302 | 37 | Object form, made available under the License, as indicated by a | 37 | or can get the source code. And you must show them these terms so they |
303 | 38 | copyright notice that is included in or attached to the work | 38 | know their rights. |
304 | 39 | (an example is provided in the Appendix below). | 39 | |
305 | 40 | 40 | Developers that use the GNU GPL protect your rights with two steps: | |
306 | 41 | "Derivative Works" shall mean any work, whether in Source or Object | 41 | (1) assert copyright on the software, and (2) offer you this License |
307 | 42 | form, that is based on (or derived from) the Work and for which the | 42 | giving you legal permission to copy, distribute and/or modify it. |
308 | 43 | editorial revisions, annotations, elaborations, or other modifications | 43 | |
309 | 44 | represent, as a whole, an original work of authorship. For the purposes | 44 | For the developers' and authors' protection, the GPL clearly explains |
310 | 45 | of this License, Derivative Works shall not include works that remain | 45 | that there is no warranty for this free software. For both users' and |
311 | 46 | separable from, or merely link (or bind by name) to the interfaces of, | 46 | authors' sake, the GPL requires that modified versions be marked as |
312 | 47 | the Work and Derivative Works thereof. | 47 | changed, so that their problems will not be attributed erroneously to |
313 | 48 | 48 | authors of previous versions. | |
314 | 49 | "Contribution" shall mean any work of authorship, including | 49 | |
315 | 50 | the original version of the Work and any modifications or additions | 50 | Some devices are designed to deny users access to install or run |
316 | 51 | to that Work or Derivative Works thereof, that is intentionally | 51 | modified versions of the software inside them, although the manufacturer |
317 | 52 | submitted to Licensor for inclusion in the Work by the copyright owner | 52 | can do so. This is fundamentally incompatible with the aim of |
318 | 53 | or by an individual or Legal Entity authorized to submit on behalf of | 53 | protecting users' freedom to change the software. The systematic |
319 | 54 | the copyright owner. For the purposes of this definition, "submitted" | 54 | pattern of such abuse occurs in the area of products for individuals to |
320 | 55 | means any form of electronic, verbal, or written communication sent | 55 | use, which is precisely where it is most unacceptable. Therefore, we |
321 | 56 | to the Licensor or its representatives, including but not limited to | 56 | have designed this version of the GPL to prohibit the practice for those |
322 | 57 | communication on electronic mailing lists, source code control systems, | 57 | products. If such problems arise substantially in other domains, we |
323 | 58 | and issue tracking systems that are managed by, or on behalf of, the | 58 | stand ready to extend this provision to those domains in future versions |
324 | 59 | Licensor for the purpose of discussing and improving the Work, but | 59 | of the GPL, as needed to protect the freedom of users. |
325 | 60 | excluding communication that is conspicuously marked or otherwise | 60 | |
326 | 61 | designated in writing by the copyright owner as "Not a Contribution." | 61 | Finally, every program is threatened constantly by software patents. |
327 | 62 | 62 | States should not allow patents to restrict development and use of | |
328 | 63 | "Contributor" shall mean Licensor and any individual or Legal Entity | 63 | software on general-purpose computers, but in those that do, we wish to |
329 | 64 | on behalf of whom a Contribution has been received by Licensor and | 64 | avoid the special danger that patents applied to a free program could |
330 | 65 | subsequently incorporated within the Work. | 65 | make it effectively proprietary. To prevent this, the GPL assures that |
331 | 66 | 66 | patents cannot be used to render the program non-free. | |
332 | 67 | 2. Grant of Copyright License. Subject to the terms and conditions of | 67 | |
333 | 68 | this License, each Contributor hereby grants to You a perpetual, | 68 | The precise terms and conditions for copying, distribution and |
334 | 69 | worldwide, non-exclusive, no-charge, royalty-free, irrevocable | 69 | modification follow. |
335 | 70 | copyright license to reproduce, prepare Derivative Works of, | 70 | |
336 | 71 | publicly display, publicly perform, sublicense, and distribute the | 71 | TERMS AND CONDITIONS |
337 | 72 | Work and such Derivative Works in Source or Object form. | 72 | |
338 | 73 | 73 | 0. Definitions. | |
339 | 74 | 3. Grant of Patent License. Subject to the terms and conditions of | 74 | |
340 | 75 | this License, each Contributor hereby grants to You a perpetual, | 75 | "This License" refers to version 3 of the GNU General Public License. |
341 | 76 | worldwide, non-exclusive, no-charge, royalty-free, irrevocable | 76 | |
342 | 77 | (except as stated in this section) patent license to make, have made, | 77 | "Copyright" also means copyright-like laws that apply to other kinds of |
343 | 78 | use, offer to sell, sell, import, and otherwise transfer the Work, | 78 | works, such as semiconductor masks. |
344 | 79 | where such license applies only to those patent claims licensable | 79 | |
345 | 80 | by such Contributor that are necessarily infringed by their | 80 | "The Program" refers to any copyrightable work licensed under this |
346 | 81 | Contribution(s) alone or by combination of their Contribution(s) | 81 | License. Each licensee is addressed as "you". "Licensees" and |
347 | 82 | with the Work to which such Contribution(s) was submitted. If You | 82 | "recipients" may be individuals or organizations. |
348 | 83 | institute patent litigation against any entity (including a | 83 | |
349 | 84 | cross-claim or counterclaim in a lawsuit) alleging that the Work | 84 | To "modify" a work means to copy from or adapt all or part of the work |
350 | 85 | or a Contribution incorporated within the Work constitutes direct | 85 | in a fashion requiring copyright permission, other than the making of an |
351 | 86 | or contributory patent infringement, then any patent licenses | 86 | exact copy. The resulting work is called a "modified version" of the |
352 | 87 | granted to You under this License for that Work shall terminate | 87 | earlier work or a work "based on" the earlier work. |
353 | 88 | as of the date such litigation is filed. | 88 | |
354 | 89 | 89 | A "covered work" means either the unmodified Program or a work based | |
355 | 90 | 4. Redistribution. You may reproduce and distribute copies of the | 90 | on the Program. |
356 | 91 | Work or Derivative Works thereof in any medium, with or without | 91 | |
357 | 92 | modifications, and in Source or Object form, provided that You | 92 | To "propagate" a work means to do anything with it that, without |
358 | 93 | meet the following conditions: | 93 | permission, would make you directly or secondarily liable for |
359 | 94 | 94 | infringement under applicable copyright law, except executing it on a | |
360 | 95 | (a) You must give any other recipients of the Work or | 95 | computer or modifying a private copy. Propagation includes copying, |
361 | 96 | Derivative Works a copy of this License; and | 96 | distribution (with or without modification), making available to the |
362 | 97 | 97 | public, and in some countries other activities as well. | |
363 | 98 | (b) You must cause any modified files to carry prominent notices | 98 | |
364 | 99 | stating that You changed the files; and | 99 | To "convey" a work means any kind of propagation that enables other |
365 | 100 | 100 | parties to make or receive copies. Mere interaction with a user through | |
366 | 101 | (c) You must retain, in the Source form of any Derivative Works | 101 | a computer network, with no transfer of a copy, is not conveying. |
367 | 102 | that You distribute, all copyright, patent, trademark, and | 102 | |
368 | 103 | attribution notices from the Source form of the Work, | 103 | An interactive user interface displays "Appropriate Legal Notices" |
369 | 104 | excluding those notices that do not pertain to any part of | 104 | to the extent that it includes a convenient and prominently visible |
370 | 105 | the Derivative Works; and | 105 | feature that (1) displays an appropriate copyright notice, and (2) |
371 | 106 | 106 | tells the user that there is no warranty for the work (except to the | |
372 | 107 | (d) If the Work includes a "NOTICE" text file as part of its | 107 | extent that warranties are provided), that licensees may convey the |
373 | 108 | distribution, then any Derivative Works that You distribute must | 108 | work under this License, and how to view a copy of this License. If |
374 | 109 | include a readable copy of the attribution notices contained | 109 | the interface presents a list of user commands or options, such as a |
375 | 110 | within such NOTICE file, excluding those notices that do not | 110 | menu, a prominent item in the list meets this criterion. |
376 | 111 | pertain to any part of the Derivative Works, in at least one | 111 | |
377 | 112 | of the following places: within a NOTICE text file distributed | 112 | 1. Source Code. |
378 | 113 | as part of the Derivative Works; within the Source form or | 113 | |
379 | 114 | documentation, if provided along with the Derivative Works; or, | 114 | The "source code" for a work means the preferred form of the work |
380 | 115 | within a display generated by the Derivative Works, if and | 115 | for making modifications to it. "Object code" means any non-source |
381 | 116 | wherever such third-party notices normally appear. The contents | 116 | form of a work. |
382 | 117 | of the NOTICE file are for informational purposes only and | 117 | |
383 | 118 | do not modify the License. You may add Your own attribution | 118 | A "Standard Interface" means an interface that either is an official |
384 | 119 | notices within Derivative Works that You distribute, alongside | 119 | standard defined by a recognized standards body, or, in the case of |
385 | 120 | or as an addendum to the NOTICE text from the Work, provided | 120 | interfaces specified for a particular programming language, one that |
386 | 121 | that such additional attribution notices cannot be construed | 121 | is widely used among developers working in that language. |
387 | 122 | as modifying the License. | 122 | |
388 | 123 | 123 | The "System Libraries" of an executable work include anything, other | |
389 | 124 | You may add Your own copyright statement to Your modifications and | 124 | than the work as a whole, that (a) is included in the normal form of |
390 | 125 | may provide additional or different license terms and conditions | 125 | packaging a Major Component, but which is not part of that Major |
391 | 126 | for use, reproduction, or distribution of Your modifications, or | 126 | Component, and (b) serves only to enable use of the work with that |
392 | 127 | for any such Derivative Works as a whole, provided Your use, | 127 | Major Component, or to implement a Standard Interface for which an |
393 | 128 | reproduction, and distribution of the Work otherwise complies with | 128 | implementation is available to the public in source code form. A |
394 | 129 | the conditions stated in this License. | 129 | "Major Component", in this context, means a major essential component |
395 | 130 | 130 | (kernel, window system, and so on) of the specific operating system | |
396 | 131 | 5. Submission of Contributions. Unless You explicitly state otherwise, | 131 | (if any) on which the executable work runs, or a compiler used to |
397 | 132 | any Contribution intentionally submitted for inclusion in the Work | 132 | produce the work, or an object code interpreter used to run it. |
398 | 133 | by You to the Licensor shall be under the terms and conditions of | 133 | |
399 | 134 | this License, without any additional terms or conditions. | 134 | The "Corresponding Source" for a work in object code form means all |
400 | 135 | Notwithstanding the above, nothing herein shall supersede or modify | 135 | the source code needed to generate, install, and (for an executable |
401 | 136 | the terms of any separate license agreement you may have executed | 136 | work) run the object code and to modify the work, including scripts to |
402 | 137 | with Licensor regarding such Contributions. | 137 | control those activities. However, it does not include the work's |
403 | 138 | 138 | System Libraries, or general-purpose tools or generally available free | |
404 | 139 | 6. Trademarks. This License does not grant permission to use the trade | 139 | programs which are used unmodified in performing those activities but |
405 | 140 | names, trademarks, service marks, or product names of the Licensor, | 140 | which are not part of the work. For example, Corresponding Source |
406 | 141 | except as required for reasonable and customary use in describing the | 141 | includes interface definition files associated with source files for |
407 | 142 | origin of the Work and reproducing the content of the NOTICE file. | 142 | the work, and the source code for shared libraries and dynamically |
408 | 143 | 143 | linked subprograms that the work is specifically designed to require, | |
409 | 144 | 7. Disclaimer of Warranty. Unless required by applicable law or | 144 | such as by intimate data communication or control flow between those |
410 | 145 | agreed to in writing, Licensor provides the Work (and each | 145 | subprograms and other parts of the work. |
411 | 146 | Contributor provides its Contributions) on an "AS IS" BASIS, | 146 | |
412 | 147 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or | 147 | The Corresponding Source need not include anything that users |
413 | 148 | implied, including, without limitation, any warranties or conditions | 148 | can regenerate automatically from other parts of the Corresponding |
414 | 149 | of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A | 149 | Source. |
415 | 150 | PARTICULAR PURPOSE. You are solely responsible for determining the | 150 | |
416 | 151 | appropriateness of using or redistributing the Work and assume any | 151 | The Corresponding Source for a work in source code form is that |
417 | 152 | risks associated with Your exercise of permissions under this License. | 152 | same work. |
418 | 153 | 153 | ||
419 | 154 | 8. Limitation of Liability. In no event and under no legal theory, | 154 | 2. Basic Permissions. |
420 | 155 | whether in tort (including negligence), contract, or otherwise, | 155 | |
421 | 156 | unless required by applicable law (such as deliberate and grossly | 156 | All rights granted under this License are granted for the term of |
422 | 157 | negligent acts) or agreed to in writing, shall any Contributor be | 157 | copyright on the Program, and are irrevocable provided the stated |
423 | 158 | liable to You for damages, including any direct, indirect, special, | 158 | conditions are met. This License explicitly affirms your unlimited |
424 | 159 | incidental, or consequential damages of any character arising as a | 159 | permission to run the unmodified Program. The output from running a |
425 | 160 | result of this License or out of the use or inability to use the | 160 | covered work is covered by this License only if the output, given its |
426 | 161 | Work (including but not limited to damages for loss of goodwill, | 161 | content, constitutes a covered work. This License acknowledges your |
427 | 162 | work stoppage, computer failure or malfunction, or any and all | 162 | rights of fair use or other equivalent, as provided by copyright law. |
428 | 163 | other commercial damages or losses), even if such Contributor | 163 | |
429 | 164 | has been advised of the possibility of such damages. | 164 | You may make, run and propagate covered works that you do not |
430 | 165 | 165 | convey, without conditions so long as your license otherwise remains | |
431 | 166 | 9. Accepting Warranty or Additional Liability. While redistributing | 166 | in force. You may convey covered works to others for the sole purpose |
432 | 167 | the Work or Derivative Works thereof, You may choose to offer, | 167 | of having them make modifications exclusively for you, or provide you |
433 | 168 | and charge a fee for, acceptance of support, warranty, indemnity, | 168 | with facilities for running those works, provided that you comply with |
434 | 169 | or other liability obligations and/or rights consistent with this | 169 | the terms of this License in conveying all material for which you do |
435 | 170 | License. However, in accepting such obligations, You may act only | 170 | not control copyright. Those thus making or running the covered works |
436 | 171 | on Your own behalf and on Your sole responsibility, not on behalf | 171 | for you must do so exclusively on your behalf, under your direction |
437 | 172 | of any other Contributor, and only if You agree to indemnify, | 172 | and control, on terms that prohibit them from making any copies of |
438 | 173 | defend, and hold each Contributor harmless for any liability | 173 | your copyrighted material outside their relationship with you. |
439 | 174 | incurred by, or claims asserted against, such Contributor by reason | 174 | |
440 | 175 | of your accepting any such warranty or additional liability. | 175 | Conveying under any other circumstances is permitted solely under |
441 | 176 | 176 | the conditions stated below. Sublicensing is not allowed; section 10 | |
442 | 177 | END OF TERMS AND CONDITIONS | 177 | makes it unnecessary. |
443 | 178 | 178 | ||
444 | 179 | APPENDIX: How to apply the Apache License to your work. | 179 | 3. Protecting Users' Legal Rights From Anti-Circumvention Law. |
445 | 180 | 180 | ||
446 | 181 | To apply the Apache License to your work, attach the following | 181 | No covered work shall be deemed part of an effective technological |
447 | 182 | boilerplate notice, with the fields enclosed by brackets "[]" | 182 | measure under any applicable law fulfilling obligations under article |
448 | 183 | replaced with your own identifying information. (Don't include | 183 | 11 of the WIPO copyright treaty adopted on 20 December 1996, or |
449 | 184 | the brackets!) The text should be enclosed in the appropriate | 184 | similar laws prohibiting or restricting circumvention of such |
450 | 185 | comment syntax for the file format. We also recommend that a | 185 | measures. |
451 | 186 | file or class name and description of purpose be included on the | 186 | |
452 | 187 | same "printed page" as the copyright notice for easier | 187 | When you convey a covered work, you waive any legal power to forbid |
453 | 188 | identification within third-party archives. | 188 | circumvention of technological measures to the extent such circumvention |
454 | 189 | 189 | is effected by exercising rights under this License with respect to | |
455 | 190 | Copyright [yyyy] [name of copyright owner] | 190 | the covered work, and you disclaim any intention to limit operation or |
456 | 191 | 191 | modification of the work as a means of enforcing, against the work's | |
457 | 192 | Licensed under the Apache License, Version 2.0 (the "License"); | 192 | users, your or third parties' legal rights to forbid circumvention of |
458 | 193 | you may not use this file except in compliance with the License. | 193 | technological measures. |
459 | 194 | You may obtain a copy of the License at | 194 | |
460 | 195 | 195 | 4. Conveying Verbatim Copies. | |
461 | 196 | http://www.apache.org/licenses/LICENSE-2.0 | 196 | |
462 | 197 | 197 | You may convey verbatim copies of the Program's source code as you | |
463 | 198 | Unless required by applicable law or agreed to in writing, software | 198 | receive it, in any medium, provided that you conspicuously and |
464 | 199 | distributed under the License is distributed on an "AS IS" BASIS, | 199 | appropriately publish on each copy an appropriate copyright notice; |
465 | 200 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. | 200 | keep intact all notices stating that this License and any |
466 | 201 | See the License for the specific language governing permissions and | 201 | non-permissive terms added in accord with section 7 apply to the code; |
467 | 202 | limitations under the License. | 202 | keep intact all notices of the absence of any warranty; and give all |
468 | 203 | recipients a copy of this License along with the Program. | ||
469 | 204 | |||
470 | 205 | You may charge any price or no price for each copy that you convey, | ||
471 | 206 | and you may offer support or warranty protection for a fee. | ||
472 | 207 | |||
473 | 208 | 5. Conveying Modified Source Versions. | ||
474 | 209 | |||
475 | 210 | You may convey a work based on the Program, or the modifications to | ||
476 | 211 | produce it from the Program, in the form of source code under the | ||
477 | 212 | terms of section 4, provided that you also meet all of these conditions: | ||
478 | 213 | |||
479 | 214 | a) The work must carry prominent notices stating that you modified | ||
480 | 215 | it, and giving a relevant date. | ||
481 | 216 | |||
482 | 217 | b) The work must carry prominent notices stating that it is | ||
483 | 218 | released under this License and any conditions added under section | ||
484 | 219 | 7. This requirement modifies the requirement in section 4 to | ||
485 | 220 | "keep intact all notices". | ||
486 | 221 | |||
487 | 222 | c) You must license the entire work, as a whole, under this | ||
488 | 223 | License to anyone who comes into possession of a copy. This | ||
489 | 224 | License will therefore apply, along with any applicable section 7 | ||
490 | 225 | additional terms, to the whole of the work, and all its parts, | ||
491 | 226 | regardless of how they are packaged. This License gives no | ||
492 | 227 | permission to license the work in any other way, but it does not | ||
493 | 228 | invalidate such permission if you have separately received it. | ||
494 | 229 | |||
495 | 230 | d) If the work has interactive user interfaces, each must display | ||
496 | 231 | Appropriate Legal Notices; however, if the Program has interactive | ||
497 | 232 | interfaces that do not display Appropriate Legal Notices, your | ||
498 | 233 | work need not make them do so. | ||
499 | 234 | |||
500 | 235 | A compilation of a covered work with other separate and independent | ||
501 | 236 | works, which are not by their nature extensions of the covered work, | ||
502 | 237 | and which are not combined with it such as to form a larger program, | ||
503 | 238 | in or on a volume of a storage or distribution medium, is called an | ||
504 | 239 | "aggregate" if the compilation and its resulting copyright are not | ||
505 | 240 | used to limit the access or legal rights of the compilation's users | ||
506 | 241 | beyond what the individual works permit. Inclusion of a covered work | ||
507 | 242 | in an aggregate does not cause this License to apply to the other | ||
508 | 243 | parts of the aggregate. | ||
509 | 244 | |||
510 | 245 | 6. Conveying Non-Source Forms. | ||
511 | 246 | |||
512 | 247 | You may convey a covered work in object code form under the terms | ||
513 | 248 | of sections 4 and 5, provided that you also convey the | ||
514 | 249 | machine-readable Corresponding Source under the terms of this License, | ||
515 | 250 | in one of these ways: | ||
516 | 251 | |||
517 | 252 | a) Convey the object code in, or embodied in, a physical product | ||
518 | 253 | (including a physical distribution medium), accompanied by the | ||
519 | 254 | Corresponding Source fixed on a durable physical medium | ||
520 | 255 | customarily used for software interchange. | ||
521 | 256 | |||
522 | 257 | b) Convey the object code in, or embodied in, a physical product | ||
523 | 258 | (including a physical distribution medium), accompanied by a | ||
524 | 259 | written offer, valid for at least three years and valid for as | ||
525 | 260 | long as you offer spare parts or customer support for that product | ||
526 | 261 | model, to give anyone who possesses the object code either (1) a | ||
527 | 262 | copy of the Corresponding Source for all the software in the | ||
528 | 263 | product that is covered by this License, on a durable physical | ||
529 | 264 | medium customarily used for software interchange, for a price no | ||
530 | 265 | more than your reasonable cost of physically performing this | ||
531 | 266 | conveying of source, or (2) access to copy the | ||
532 | 267 | Corresponding Source from a network server at no charge. | ||
533 | 268 | |||
534 | 269 | c) Convey individual copies of the object code with a copy of the | ||
535 | 270 | written offer to provide the Corresponding Source. This | ||
536 | 271 | alternative is allowed only occasionally and noncommercially, and | ||
537 | 272 | only if you received the object code with such an offer, in accord | ||
538 | 273 | with subsection 6b. | ||
539 | 274 | |||
540 | 275 | d) Convey the object code by offering access from a designated | ||
541 | 276 | place (gratis or for a charge), and offer equivalent access to the | ||
542 | 277 | Corresponding Source in the same way through the same place at no | ||
543 | 278 | further charge. You need not require recipients to copy the | ||
544 | 279 | Corresponding Source along with the object code. If the place to | ||
545 | 280 | copy the object code is a network server, the Corresponding Source | ||
546 | 281 | may be on a different server (operated by you or a third party) | ||
547 | 282 | that supports equivalent copying facilities, provided you maintain | ||
548 | 283 | clear directions next to the object code saying where to find the | ||
549 | 284 | Corresponding Source. Regardless of what server hosts the | ||
550 | 285 | Corresponding Source, you remain obligated to ensure that it is | ||
551 | 286 | available for as long as needed to satisfy these requirements. | ||
552 | 287 | |||
553 | 288 | e) Convey the object code using peer-to-peer transmission, provided | ||
554 | 289 | you inform other peers where the object code and Corresponding | ||
555 | 290 | Source of the work are being offered to the general public at no | ||
556 | 291 | charge under subsection 6d. | ||
557 | 292 | |||
558 | 293 | A separable portion of the object code, whose source code is excluded | ||
559 | 294 | from the Corresponding Source as a System Library, need not be | ||
560 | 295 | included in conveying the object code work. | ||
561 | 296 | |||
562 | 297 | A "User Product" is either (1) a "consumer product", which means any | ||
563 | 298 | tangible personal property which is normally used for personal, family, | ||
564 | 299 | or household purposes, or (2) anything designed or sold for incorporation | ||
565 | 300 | into a dwelling. In determining whether a product is a consumer product, | ||
566 | 301 | doubtful cases shall be resolved in favor of coverage. For a particular | ||
567 | 302 | product received by a particular user, "normally used" refers to a | ||
568 | 303 | typical or common use of that class of product, regardless of the status | ||
569 | 304 | of the particular user or of the way in which the particular user | ||
570 | 305 | actually uses, or expects or is expected to use, the product. A product | ||
571 | 306 | is a consumer product regardless of whether the product has substantial | ||
572 | 307 | commercial, industrial or non-consumer uses, unless such uses represent | ||
573 | 308 | the only significant mode of use of the product. | ||
574 | 309 | |||
575 | 310 | "Installation Information" for a User Product means any methods, | ||
576 | 311 | procedures, authorization keys, or other information required to install | ||
577 | 312 | and execute modified versions of a covered work in that User Product from | ||
578 | 313 | a modified version of its Corresponding Source. The information must | ||
579 | 314 | suffice to ensure that the continued functioning of the modified object | ||
580 | 315 | code is in no case prevented or interfered with solely because | ||
581 | 316 | modification has been made. | ||
582 | 317 | |||
583 | 318 | If you convey an object code work under this section in, or with, or | ||
584 | 319 | specifically for use in, a User Product, and the conveying occurs as | ||
585 | 320 | part of a transaction in which the right of possession and use of the | ||
586 | 321 | User Product is transferred to the recipient in perpetuity or for a | ||
587 | 322 | fixed term (regardless of how the transaction is characterized), the | ||
588 | 323 | Corresponding Source conveyed under this section must be accompanied | ||
589 | 324 | by the Installation Information. But this requirement does not apply | ||
590 | 325 | if neither you nor any third party retains the ability to install | ||
591 | 326 | modified object code on the User Product (for example, the work has | ||
592 | 327 | been installed in ROM). | ||
593 | 328 | |||
594 | 329 | The requirement to provide Installation Information does not include a | ||
595 | 330 | requirement to continue to provide support service, warranty, or updates | ||
596 | 331 | for a work that has been modified or installed by the recipient, or for | ||
597 | 332 | the User Product in which it has been modified or installed. Access to a | ||
598 | 333 | network may be denied when the modification itself materially and | ||
599 | 334 | adversely affects the operation of the network or violates the rules and | ||
600 | 335 | protocols for communication across the network. | ||
601 | 336 | |||
602 | 337 | Corresponding Source conveyed, and Installation Information provided, | ||
603 | 338 | in accord with this section must be in a format that is publicly | ||
604 | 339 | documented (and with an implementation available to the public in | ||
605 | 340 | source code form), and must require no special password or key for | ||
606 | 341 | unpacking, reading or copying. | ||
607 | 342 | |||
608 | 343 | 7. Additional Terms. | ||
609 | 344 | |||
610 | 345 | "Additional permissions" are terms that supplement the terms of this | ||
611 | 346 | License by making exceptions from one or more of its conditions. | ||
612 | 347 | Additional permissions that are applicable to the entire Program shall | ||
613 | 348 | be treated as though they were included in this License, to the extent | ||
614 | 349 | that they are valid under applicable law. If additional permissions | ||
615 | 350 | apply only to part of the Program, that part may be used separately | ||
616 | 351 | under those permissions, but the entire Program remains governed by | ||
617 | 352 | this License without regard to the additional permissions. | ||
618 | 353 | |||
619 | 354 | When you convey a copy of a covered work, you may at your option | ||
620 | 355 | remove any additional permissions from that copy, or from any part of | ||
621 | 356 | it. (Additional permissions may be written to require their own | ||
622 | 357 | removal in certain cases when you modify the work.) You may place | ||
623 | 358 | additional permissions on material, added by you to a covered work, | ||
624 | 359 | for which you have or can give appropriate copyright permission. | ||
625 | 360 | |||
626 | 361 | Notwithstanding any other provision of this License, for material you | ||
627 | 362 | add to a covered work, you may (if authorized by the copyright holders of | ||
628 | 363 | that material) supplement the terms of this License with terms: | ||
629 | 364 | |||
630 | 365 | a) Disclaiming warranty or limiting liability differently from the | ||
631 | 366 | terms of sections 15 and 16 of this License; or | ||
632 | 367 | |||
633 | 368 | b) Requiring preservation of specified reasonable legal notices or | ||
634 | 369 | author attributions in that material or in the Appropriate Legal | ||
635 | 370 | Notices displayed by works containing it; or | ||
636 | 371 | |||
637 | 372 | c) Prohibiting misrepresentation of the origin of that material, or | ||
638 | 373 | requiring that modified versions of such material be marked in | ||
639 | 374 | reasonable ways as different from the original version; or | ||
640 | 375 | |||
641 | 376 | d) Limiting the use for publicity purposes of names of licensors or | ||
642 | 377 | authors of the material; or | ||
643 | 378 | |||
644 | 379 | e) Declining to grant rights under trademark law for use of some | ||
645 | 380 | trade names, trademarks, or service marks; or | ||
646 | 381 | |||
647 | 382 | f) Requiring indemnification of licensors and authors of that | ||
648 | 383 | material by anyone who conveys the material (or modified versions of | ||
649 | 384 | it) with contractual assumptions of liability to the recipient, for | ||
650 | 385 | any liability that these contractual assumptions directly impose on | ||
651 | 386 | those licensors and authors. | ||
652 | 387 | |||
653 | 388 | All other non-permissive additional terms are considered "further | ||
654 | 389 | restrictions" within the meaning of section 10. If the Program as you | ||
655 | 390 | received it, or any part of it, contains a notice stating that it is | ||
656 | 391 | governed by this License along with a term that is a further | ||
657 | 392 | restriction, you may remove that term. If a license document contains | ||
658 | 393 | a further restriction but permits relicensing or conveying under this | ||
659 | 394 | License, you may add to a covered work material governed by the terms | ||
660 | 395 | of that license document, provided that the further restriction does | ||
661 | 396 | not survive such relicensing or conveying. | ||
662 | 397 | |||
663 | 398 | If you add terms to a covered work in accord with this section, you | ||
664 | 399 | must place, in the relevant source files, a statement of the | ||
665 | 400 | additional terms that apply to those files, or a notice indicating | ||
666 | 401 | where to find the applicable terms. | ||
667 | 402 | |||
668 | 403 | Additional terms, permissive or non-permissive, may be stated in the | ||
669 | 404 | form of a separately written license, or stated as exceptions; | ||
670 | 405 | the above requirements apply either way. | ||
671 | 406 | |||
672 | 407 | 8. Termination. | ||
673 | 408 | |||
674 | 409 | You may not propagate or modify a covered work except as expressly | ||
675 | 410 | provided under this License. Any attempt otherwise to propagate or | ||
676 | 411 | modify it is void, and will automatically terminate your rights under | ||
677 | 412 | this License (including any patent licenses granted under the third | ||
678 | 413 | paragraph of section 11). | ||
679 | 414 | |||
680 | 415 | However, if you cease all violation of this License, then your | ||
681 | 416 | license from a particular copyright holder is reinstated (a) | ||
682 | 417 | provisionally, unless and until the copyright holder explicitly and | ||
683 | 418 | finally terminates your license, and (b) permanently, if the copyright | ||
684 | 419 | holder fails to notify you of the violation by some reasonable means | ||
685 | 420 | prior to 60 days after the cessation. | ||
686 | 421 | |||
687 | 422 | Moreover, your license from a particular copyright holder is | ||
688 | 423 | reinstated permanently if the copyright holder notifies you of the | ||
689 | 424 | violation by some reasonable means, this is the first time you have | ||
690 | 425 | received notice of violation of this License (for any work) from that | ||
691 | 426 | copyright holder, and you cure the violation prior to 30 days after | ||
692 | 427 | your receipt of the notice. | ||
693 | 428 | |||
694 | 429 | Termination of your rights under this section does not terminate the | ||
695 | 430 | licenses of parties who have received copies or rights from you under | ||
696 | 431 | this License. If your rights have been terminated and not permanently | ||
697 | 432 | reinstated, you do not qualify to receive new licenses for the same | ||
698 | 433 | material under section 10. | ||
699 | 434 | |||
700 | 435 | 9. Acceptance Not Required for Having Copies. | ||
701 | 436 | |||
702 | 437 | You are not required to accept this License in order to receive or | ||
703 | 438 | run a copy of the Program. Ancillary propagation of a covered work | ||
704 | 439 | occurring solely as a consequence of using peer-to-peer transmission | ||
705 | 440 | to receive a copy likewise does not require acceptance. However, | ||
706 | 441 | nothing other than this License grants you permission to propagate or | ||
707 | 442 | modify any covered work. These actions infringe copyright if you do | ||
708 | 443 | not accept this License. Therefore, by modifying or propagating a | ||
709 | 444 | covered work, you indicate your acceptance of this License to do so. | ||
710 | 445 | |||
711 | 446 | 10. Automatic Licensing of Downstream Recipients. | ||
712 | 447 | |||
713 | 448 | Each time you convey a covered work, the recipient automatically | ||
714 | 449 | receives a license from the original licensors, to run, modify and | ||
715 | 450 | propagate that work, subject to this License. You are not responsible | ||
716 | 451 | for enforcing compliance by third parties with this License. | ||
717 | 452 | |||
718 | 453 | An "entity transaction" is a transaction transferring control of an | ||
719 | 454 | organization, or substantially all assets of one, or subdividing an | ||
720 | 455 | organization, or merging organizations. If propagation of a covered | ||
721 | 456 | work results from an entity transaction, each party to that | ||
722 | 457 | transaction who receives a copy of the work also receives whatever | ||
723 | 458 | licenses to the work the party's predecessor in interest had or could | ||
724 | 459 | give under the previous paragraph, plus a right to possession of the | ||
725 | 460 | Corresponding Source of the work from the predecessor in interest, if | ||
726 | 461 | the predecessor has it or can get it with reasonable efforts. | ||
727 | 462 | |||
728 | 463 | You may not impose any further restrictions on the exercise of the | ||
729 | 464 | rights granted or affirmed under this License. For example, you may | ||
730 | 465 | not impose a license fee, royalty, or other charge for exercise of | ||
731 | 466 | rights granted under this License, and you may not initiate litigation | ||
732 | 467 | (including a cross-claim or counterclaim in a lawsuit) alleging that | ||
733 | 468 | any patent claim is infringed by making, using, selling, offering for | ||
734 | 469 | sale, or importing the Program or any portion of it. | ||
735 | 470 | |||
736 | 471 | 11. Patents. | ||
737 | 472 | |||
738 | 473 | A "contributor" is a copyright holder who authorizes use under this | ||
739 | 474 | License of the Program or a work on which the Program is based. The | ||
740 | 475 | work thus licensed is called the contributor's "contributor version". | ||
741 | 476 | |||
742 | 477 | A contributor's "essential patent claims" are all patent claims | ||
743 | 478 | owned or controlled by the contributor, whether already acquired or | ||
744 | 479 | hereafter acquired, that would be infringed by some manner, permitted | ||
745 | 480 | by this License, of making, using, or selling its contributor version, | ||
746 | 481 | but do not include claims that would be infringed only as a | ||
747 | 482 | consequence of further modification of the contributor version. For | ||
748 | 483 | purposes of this definition, "control" includes the right to grant | ||
749 | 484 | patent sublicenses in a manner consistent with the requirements of | ||
750 | 485 | this License. | ||
751 | 486 | |||
752 | 487 | Each contributor grants you a non-exclusive, worldwide, royalty-free | ||
753 | 488 | patent license under the contributor's essential patent claims, to | ||
754 | 489 | make, use, sell, offer for sale, import and otherwise run, modify and | ||
755 | 490 | propagate the contents of its contributor version. | ||
756 | 491 | |||
757 | 492 | In the following three paragraphs, a "patent license" is any express | ||
758 | 493 | agreement or commitment, however denominated, not to enforce a patent | ||
759 | 494 | (such as an express permission to practice a patent or covenant not to | ||
760 | 495 | sue for patent infringement). To "grant" such a patent license to a | ||
761 | 496 | party means to make such an agreement or commitment not to enforce a | ||
762 | 497 | patent against the party. | ||
763 | 498 | |||
764 | 499 | If you convey a covered work, knowingly relying on a patent license, | ||
765 | 500 | and the Corresponding Source of the work is not available for anyone | ||
766 | 501 | to copy, free of charge and under the terms of this License, through a | ||
767 | 502 | publicly available network server or other readily accessible means, | ||
768 | 503 | then you must either (1) cause the Corresponding Source to be so | ||
769 | 504 | available, or (2) arrange to deprive yourself of the benefit of the | ||
770 | 505 | patent license for this particular work, or (3) arrange, in a manner | ||
771 | 506 | consistent with the requirements of this License, to extend the patent | ||
772 | 507 | license to downstream recipients. "Knowingly relying" means you have | ||
773 | 508 | actual knowledge that, but for the patent license, your conveying the | ||
774 | 509 | covered work in a country, or your recipient's use of the covered work | ||
775 | 510 | in a country, would infringe one or more identifiable patents in that | ||
776 | 511 | country that you have reason to believe are valid. | ||
777 | 512 | |||
778 | 513 | If, pursuant to or in connection with a single transaction or | ||
779 | 514 | arrangement, you convey, or propagate by procuring conveyance of, a | ||
780 | 515 | covered work, and grant a patent license to some of the parties | ||
781 | 516 | receiving the covered work authorizing them to use, propagate, modify | ||
782 | 517 | or convey a specific copy of the covered work, then the patent license | ||
783 | 518 | you grant is automatically extended to all recipients of the covered | ||
784 | 519 | work and works based on it. | ||
785 | 520 | |||
786 | 521 | A patent license is "discriminatory" if it does not include within | ||
787 | 522 | the scope of its coverage, prohibits the exercise of, or is | ||
788 | 523 | conditioned on the non-exercise of one or more of the rights that are | ||
789 | 524 | specifically granted under this License. You may not convey a covered | ||
790 | 525 | work if you are a party to an arrangement with a third party that is | ||
791 | 526 | in the business of distributing software, under which you make payment | ||
792 | 527 | to the third party based on the extent of your activity of conveying | ||
793 | 528 | the work, and under which the third party grants, to any of the | ||
794 | 529 | parties who would receive the covered work from you, a discriminatory | ||
795 | 530 | patent license (a) in connection with copies of the covered work | ||
796 | 531 | conveyed by you (or copies made from those copies), or (b) primarily | ||
797 | 532 | for and in connection with specific products or compilations that | ||
798 | 533 | contain the covered work, unless you entered into that arrangement, | ||
799 | 534 | or that patent license was granted, prior to 28 March 2007. | ||
800 | 535 | |||
801 | 536 | Nothing in this License shall be construed as excluding or limiting | ||
802 | 537 | any implied license or other defenses to infringement that may | ||
803 | 538 | otherwise be available to you under applicable patent law. | ||
804 | 539 | |||
805 | 540 | 12. No Surrender of Others' Freedom. | ||
806 | 541 | |||
807 | 542 | If conditions are imposed on you (whether by court order, agreement or | ||
808 | 543 | otherwise) that contradict the conditions of this License, they do not | ||
809 | 544 | excuse you from the conditions of this License. If you cannot convey a | ||
810 | 545 | covered work so as to satisfy simultaneously your obligations under this | ||
811 | 546 | License and any other pertinent obligations, then as a consequence you may | ||
812 | 547 | not convey it at all. For example, if you agree to terms that obligate you | ||
813 | 548 | to collect a royalty for further conveying from those to whom you convey | ||
814 | 549 | the Program, the only way you could satisfy both those terms and this | ||
815 | 550 | License would be to refrain entirely from conveying the Program. | ||
816 | 551 | |||
817 | 552 | 13. Use with the GNU Affero General Public License. | ||
818 | 553 | |||
819 | 554 | Notwithstanding any other provision of this License, you have | ||
820 | 555 | permission to link or combine any covered work with a work licensed | ||
821 | 556 | under version 3 of the GNU Affero General Public License into a single | ||
822 | 557 | combined work, and to convey the resulting work. The terms of this | ||
823 | 558 | License will continue to apply to the part which is the covered work, | ||
824 | 559 | but the special requirements of the GNU Affero General Public License, | ||
825 | 560 | section 13, concerning interaction through a network will apply to the | ||
826 | 561 | combination as such. | ||
827 | 562 | |||
828 | 563 | 14. Revised Versions of this License. | ||
829 | 564 | |||
830 | 565 | The Free Software Foundation may publish revised and/or new versions of | ||
831 | 566 | the GNU General Public License from time to time. Such new versions will | ||
832 | 567 | be similar in spirit to the present version, but may differ in detail to | ||
833 | 568 | address new problems or concerns. | ||
834 | 569 | |||
835 | 570 | Each version is given a distinguishing version number. If the | ||
836 | 571 | Program specifies that a certain numbered version of the GNU General | ||
837 | 572 | Public License "or any later version" applies to it, you have the | ||
838 | 573 | option of following the terms and conditions either of that numbered | ||
839 | 574 | version or of any later version published by the Free Software | ||
840 | 575 | Foundation. If the Program does not specify a version number of the | ||
841 | 576 | GNU General Public License, you may choose any version ever published | ||
842 | 577 | by the Free Software Foundation. | ||
843 | 578 | |||
844 | 579 | If the Program specifies that a proxy can decide which future | ||
845 | 580 | versions of the GNU General Public License can be used, that proxy's | ||
846 | 581 | public statement of acceptance of a version permanently authorizes you | ||
847 | 582 | to choose that version for the Program. | ||
848 | 583 | |||
849 | 584 | Later license versions may give you additional or different | ||
850 | 585 | permissions. However, no additional obligations are imposed on any | ||
851 | 586 | author or copyright holder as a result of your choosing to follow a | ||
852 | 587 | later version. | ||
853 | 588 | |||
854 | 589 | 15. Disclaimer of Warranty. | ||
855 | 590 | |||
856 | 591 | THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY | ||
857 | 592 | APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT | ||
858 | 593 | HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY | ||
859 | 594 | OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, | ||
860 | 595 | THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR | ||
861 | 596 | PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM | ||
862 | 597 | IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF | ||
863 | 598 | ALL NECESSARY SERVICING, REPAIR OR CORRECTION. | ||
864 | 599 | |||
865 | 600 | 16. Limitation of Liability. | ||
866 | 601 | |||
867 | 602 | IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING | ||
868 | 603 | WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS | ||
869 | 604 | THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY | ||
870 | 605 | GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE | ||
871 | 606 | USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF | ||
872 | 607 | DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD | ||
873 | 608 | PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), | ||
874 | 609 | EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF | ||
875 | 610 | SUCH DAMAGES. | ||
876 | 611 | |||
877 | 612 | 17. Interpretation of Sections 15 and 16. | ||
878 | 613 | |||
879 | 614 | If the disclaimer of warranty and limitation of liability provided | ||
880 | 615 | above cannot be given local legal effect according to their terms, | ||
881 | 616 | reviewing courts shall apply local law that most closely approximates | ||
882 | 617 | an absolute waiver of all civil liability in connection with the | ||
883 | 618 | Program, unless a warranty or assumption of liability accompanies a | ||
884 | 619 | copy of the Program in return for a fee. | ||
885 | 620 | |||
886 | 621 | END OF TERMS AND CONDITIONS | ||
887 | 622 | |||
888 | 623 | How to Apply These Terms to Your New Programs | ||
889 | 624 | |||
890 | 625 | If you develop a new program, and you want it to be of the greatest | ||
891 | 626 | possible use to the public, the best way to achieve this is to make it | ||
892 | 627 | free software which everyone can redistribute and change under these terms. | ||
893 | 628 | |||
894 | 629 | To do so, attach the following notices to the program. It is safest | ||
895 | 630 | to attach them to the start of each source file to most effectively | ||
896 | 631 | state the exclusion of warranty; and each file should have at least | ||
897 | 632 | the "copyright" line and a pointer to where the full notice is found. | ||
898 | 633 | |||
899 | 634 | <one line to give the program's name and a brief idea of what it does.> | ||
900 | 635 | Copyright (C) <year> <name of author> | ||
901 | 636 | |||
902 | 637 | This program is free software: you can redistribute it and/or modify | ||
903 | 638 | it under the terms of the GNU General Public License as published by | ||
904 | 639 | the Free Software Foundation, either version 3 of the License, or | ||
905 | 640 | (at your option) any later version. | ||
906 | 641 | |||
907 | 642 | This program is distributed in the hope that it will be useful, | ||
908 | 643 | but WITHOUT ANY WARRANTY; without even the implied warranty of | ||
909 | 644 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the | ||
910 | 645 | GNU General Public License for more details. | ||
911 | 646 | |||
912 | 647 | You should have received a copy of the GNU General Public License | ||
913 | 648 | along with this program. If not, see <https://www.gnu.org/licenses/>. | ||
914 | 649 | |||
915 | 650 | Also add information on how to contact you by electronic and paper mail. | ||
916 | 651 | |||
917 | 652 | If the program does terminal interaction, make it output a short | ||
918 | 653 | notice like this when it starts in an interactive mode: | ||
919 | 654 | |||
920 | 655 | <program> Copyright (C) <year> <name of author> | ||
921 | 656 | This program comes with ABSOLUTELY NO WARRANTY; for details type `show w'. | ||
922 | 657 | This is free software, and you are welcome to redistribute it | ||
923 | 658 | under certain conditions; type `show c' for details. | ||
924 | 659 | |||
925 | 660 | The hypothetical commands `show w' and `show c' should show the appropriate | ||
926 | 661 | parts of the General Public License. Of course, your program's commands | ||
927 | 662 | might be different; for a GUI interface, you would use an "about box". | ||
928 | 663 | |||
929 | 664 | You should also get your employer (if you work as a programmer) or school, | ||
930 | 665 | if any, to sign a "copyright disclaimer" for the program, if necessary. | ||
931 | 666 | For more information on this, and how to apply and follow the GNU GPL, see | ||
932 | 667 | <https://www.gnu.org/licenses/>. | ||
933 | 668 | |||
934 | 669 | The GNU General Public License does not permit incorporating your program | ||
935 | 670 | into proprietary programs. If your program is a subroutine library, you | ||
936 | 671 | may consider it more useful to permit linking proprietary applications with | ||
937 | 672 | the library. If this is what you want to do, use the GNU Lesser General | ||
938 | 673 | Public License instead of this License. But first, please read | ||
939 | 674 | <https://www.gnu.org/licenses/why-not-lgpl.html>. | ||
940 | diff --git a/Makefile b/Makefile | |||
941 | 203 | new file mode 100644 | 675 | new file mode 100644 |
942 | index 0000000..8c14478 | |||
943 | --- /dev/null | |||
944 | +++ b/Makefile | |||
945 | @@ -0,0 +1,21 @@ | |||
946 | 1 | METADATA_FILE="metadata.yaml" | ||
947 | 2 | PROJECTPATH=$(dir $(realpath $(MAKEFILE_LIST))) | ||
948 | 3 | |||
949 | 4 | ifndef CHARM_BUILD_DIR | ||
950 | 5 | CHARM_BUILD_DIR=${PROJECTPATH}/../builds | ||
951 | 6 | endif | ||
952 | 7 | |||
953 | 8 | CHARM_NAME=$(shell cat ${PROJECTPATH}/${METADATA_FILE} | grep -E "^name:" | awk '{print $$2}') | ||
954 | 9 | |||
955 | 10 | clean: | ||
956 | 11 | @echo "Cleaning files" | ||
957 | 12 | @git clean -ffXd -e '!.idea' | ||
958 | 13 | @echo "Cleaning existing build" | ||
959 | 14 | @rm -rf ${CHARM_BUILD_DIR}/${CHARM_NAME} | ||
960 | 15 | |||
961 | 16 | lint: | ||
962 | 17 | @echo "Running lint checks" | ||
963 | 18 | @cd src && tox -e lint | ||
964 | 19 | |||
965 | 20 | # The targets below don't depend on a file | ||
966 | 21 | .PHONY: clean lint | ||
967 | diff --git a/README.md b/README.md | |||
968 | index 148c70d..a53a7ed 100644 | |||
969 | --- a/README.md | |||
970 | +++ b/README.md | |||
971 | @@ -1,24 +1,16 @@ | |||
973 | 1 | # charm-tor | 1 | # charm-tor-hidden-service |
974 | 2 | 2 | ||
975 | 3 | ## Description | 3 | ## Description |
976 | 4 | 4 | ||
978 | 5 | TODO: Describe your charm in a few paragraphs of Markdown | 5 | This charm enables Tor hidden services |
979 | 6 | 6 | ||
980 | 7 | ## Usage | 7 | ## Usage |
981 | 8 | 8 | ||
983 | 9 | TODO: Provide high-level usage, such as required config or relations | 9 | The charm relates to any number of services (e.g. ch:apache2) over the |
984 | 10 | `reverseproxy` relation, and serves up a proxied version of that site on a | ||
985 | 11 | .onion (v3) hostname. | ||
986 | 10 | 12 | ||
987 | 13 | If you require a specific .onion hostname (or multiple) we suggest using the | ||
988 | 14 | mkp224o tool to create them, and configuring the charm with those private keys. | ||
989 | 11 | 15 | ||
1003 | 12 | ## Relations | 16 | TODO |
991 | 13 | |||
992 | 14 | TODO: Provide any relations which are provided or required by your charm | ||
993 | 15 | |||
994 | 16 | ## OCI Images | ||
995 | 17 | |||
996 | 18 | TODO: Include a link to the default image your charm uses | ||
997 | 19 | |||
998 | 20 | ## Contributing | ||
999 | 21 | |||
1000 | 22 | Please see the [Juju SDK docs](https://juju.is/docs/sdk) for guidelines | ||
1001 | 23 | on enhancements to this charm following best practice guidelines, and | ||
1002 | 24 | `CONTRIBUTING.md` for developer guidance. | ||
1004 | diff --git a/actions.yaml b/actions.yaml | |||
1005 | 25 | deleted file mode 100644 | 17 | deleted file mode 100644 |
1006 | index 7cda621..0000000 | |||
1007 | --- a/actions.yaml | |||
1008 | +++ /dev/null | |||
1009 | @@ -1,16 +0,0 @@ | |||
1010 | 1 | # Copyright 2022 Barry Price | ||
1011 | 2 | # See LICENSE file for licensing details. | ||
1012 | 3 | # | ||
1013 | 4 | # TEMPLATE-TODO: change this example to suit your needs. | ||
1014 | 5 | # If you don't need actions, you can remove the file entirely. | ||
1015 | 6 | # It ties in to the example _on_fortune_action handler in src/charm.py | ||
1016 | 7 | # | ||
1017 | 8 | # Learn more about actions at: https://juju.is/docs/sdk/actions | ||
1018 | 9 | |||
1019 | 10 | fortune: | ||
1020 | 11 | description: Returns a pithy phrase. | ||
1021 | 12 | params: | ||
1022 | 13 | fail: | ||
1023 | 14 | description: "Fail with this message" | ||
1024 | 15 | type: string | ||
1025 | 16 | default: "" | ||
1026 | diff --git a/charmcraft.yaml b/charmcraft.yaml | |||
1027 | index 048d454..0d1497e 100644 | |||
1028 | --- a/charmcraft.yaml | |||
1029 | +++ b/charmcraft.yaml | |||
1030 | @@ -1,10 +1,10 @@ | |||
1031 | 1 | # Learn more about charmcraft.yaml configuration at: | ||
1032 | 2 | # https://juju.is/docs/sdk/charmcraft-config | ||
1033 | 3 | type: "charm" | 1 | type: "charm" |
1034 | 4 | bases: | 2 | bases: |
1035 | 5 | - build-on: | 3 | - build-on: |
1036 | 6 | - name: "ubuntu" | 4 | - name: "ubuntu" |
1038 | 7 | channel: "20.04" | 5 | channel: "22.04" |
1039 | 8 | run-on: | 6 | run-on: |
1040 | 9 | - name: "ubuntu" | 7 | - name: "ubuntu" |
1041 | 10 | channel: "20.04" | 8 | channel: "20.04" |
1042 | 9 | - name: "ubuntu" | ||
1043 | 10 | channel: "22.04" | ||
1044 | diff --git a/config.yaml b/config.yaml | |||
1045 | index 65fb1ce..35643c0 100644 | |||
1046 | --- a/config.yaml | |||
1047 | +++ b/config.yaml | |||
1048 | @@ -1,14 +1,33 @@ | |||
1049 | 1 | # Copyright 2022 Barry Price | ||
1050 | 2 | # See LICENSE file for licensing details. | ||
1051 | 3 | # | ||
1052 | 4 | # TEMPLATE-TODO: change this example to suit your needs. | ||
1053 | 5 | # If you don't need a config, you can remove the file entirely. | ||
1054 | 6 | # It ties in to the example _on_config_changed handler in src/charm.py | ||
1055 | 7 | # | ||
1056 | 8 | # Learn more about config at: https://juju.is/docs/sdk/config | ||
1057 | 9 | |||
1058 | 10 | options: | 1 | options: |
1062 | 11 | thing: | 2 | hidden_keys_base64: |
1063 | 12 | default: 🎁 | 3 | default: "" |
1064 | 13 | description: A thing used by the charm. | 4 | description: | |
1065 | 5 | Optional pre-generated tor private keys to run your service. The | ||
1066 | 6 | .onion hostname(s) will be derived from this value. | ||
1067 | 7 | |||
1068 | 8 | Since the key is a binary file, this field expects a YAML formattaed | ||
1069 | 9 | list of source hostnames (passed via the reverseproxy relation and | ||
1070 | 10 | visible in the Message column via `juju status`) with corresponding | ||
1071 | 11 | base-64 encoded strings, via e.g. `base64 -w0 path/to/secretkey`. | ||
1072 | 12 | |||
1073 | 13 | If left unconfigured, a random key (and address) will be generated for | ||
1074 | 14 | each site. | ||
1075 | 15 | |||
1076 | 16 | e.g. | ||
1077 | 17 | example1.com: ZXhhbXBsZTEK | ||
1078 | 18 | example2.internal: ZXhhbXBsZTIK | ||
1079 | 19 | 10.0.0.1: ZXhhbXBsZTMK # example3 | ||
1080 | 20 | type: string | ||
1081 | 21 | socks5_port: | ||
1082 | 22 | description: SOCKS5 proxy port on which to listen | ||
1083 | 23 | type: int | ||
1084 | 24 | default: 9050 | ||
1085 | 25 | tor_source: | ||
1086 | 26 | default: torproject | ||
1087 | 27 | description: | | ||
1088 | 28 | Source from which tor will be installed. | ||
1089 | 29 | Options are "torproject" (default), which will use the packages from | ||
1090 | 30 | deb.torproject.org, or "ubuntu" which will use the package in ubuntu's | ||
1091 | 31 | universe component (this option may be outdated/insecure, but is the | ||
1092 | 32 | only current option for architectures other than amd64/arm64). | ||
1093 | 14 | type: string | 33 | type: string |
1094 | diff --git a/lib/charms/operator_libs_linux/v0/apt.py b/lib/charms/operator_libs_linux/v0/apt.py | |||
1095 | 15 | new file mode 100644 | 34 | new file mode 100644 |
1096 | index 0000000..2b5c8f2 | |||
1097 | --- /dev/null | |||
1098 | +++ b/lib/charms/operator_libs_linux/v0/apt.py | |||
1099 | @@ -0,0 +1,1329 @@ | |||
1100 | 1 | # Copyright 2021 Canonical Ltd. | ||
1101 | 2 | # | ||
1102 | 3 | # Licensed under the Apache License, Version 2.0 (the "License"); | ||
1103 | 4 | # you may not use this file except in compliance with the License. | ||
1104 | 5 | # You may obtain a copy of the License at | ||
1105 | 6 | # | ||
1106 | 7 | # http://www.apache.org/licenses/LICENSE-2.0 | ||
1107 | 8 | # | ||
1108 | 9 | # Unless required by applicable law or agreed to in writing, software | ||
1109 | 10 | # distributed under the License is distributed on an "AS IS" BASIS, | ||
1110 | 11 | # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. | ||
1111 | 12 | # See the License for the specific language governing permissions and | ||
1112 | 13 | # limitations under the License. | ||
1113 | 14 | |||
1114 | 15 | """Abstractions for the system's Debian/Ubuntu package information and repositories. | ||
1115 | 16 | |||
1116 | 17 | This module contains abstractions and wrappers around Debian/Ubuntu-style repositories and | ||
1117 | 18 | packages, in order to easily provide an idiomatic and Pythonic mechanism for adding packages and/or | ||
1118 | 19 | repositories to systems for use in machine charms. | ||
1119 | 20 | |||
1120 | 21 | A sane default configuration is attainable through nothing more than instantiation of the | ||
1121 | 22 | appropriate classes. `DebianPackage` objects provide information about the architecture, version, | ||
1122 | 23 | name, and status of a package. | ||
1123 | 24 | |||
1124 | 25 | `DebianPackage` will try to look up a package either from `dpkg -L` or from `apt-cache` when | ||
1125 | 26 | provided with a string indicating the package name. If it cannot be located, `PackageNotFoundError` | ||
1126 | 27 | will be returned, as `apt` and `dpkg` otherwise return `100` for all errors, and a meaningful error | ||
1127 | 28 | message if the package is not known is desirable. | ||
1128 | 29 | |||
1129 | 30 | To install packages with convenience methods: | ||
1130 | 31 | |||
1131 | 32 | ```python | ||
1132 | 33 | try: | ||
1133 | 34 | # Run `apt-get update` | ||
1134 | 35 | apt.update() | ||
1135 | 36 | apt.add_package("zsh") | ||
1136 | 37 | apt.add_package(["vim", "htop", "wget"]) | ||
1137 | 38 | except PackageNotFoundError: | ||
1138 | 39 | logger.error("a specified package not found in package cache or on system") | ||
1139 | 40 | except PackageError as e: | ||
1140 | 41 | logger.error("could not install package. Reason: %s", e.message) | ||
1141 | 42 | ```` | ||
1142 | 43 | |||
1143 | 44 | To find details of a specific package: | ||
1144 | 45 | |||
1145 | 46 | ```python | ||
1146 | 47 | try: | ||
1147 | 48 | vim = apt.DebianPackage.from_system("vim") | ||
1148 | 49 | |||
1149 | 50 | # To find from the apt cache only | ||
1150 | 51 | # apt.DebianPackage.from_apt_cache("vim") | ||
1151 | 52 | |||
1152 | 53 | # To find from installed packages only | ||
1153 | 54 | # apt.DebianPackage.from_installed_package("vim") | ||
1154 | 55 | |||
1155 | 56 | vim.ensure(PackageState.Latest) | ||
1156 | 57 | logger.info("updated vim to version: %s", vim.fullversion) | ||
1157 | 58 | except PackageNotFoundError: | ||
1158 | 59 | logger.error("a specified package not found in package cache or on system") | ||
1159 | 60 | except PackageError as e: | ||
1160 | 61 | logger.error("could not install package. Reason: %s", e.message) | ||
1161 | 62 | ``` | ||
1162 | 63 | |||
1163 | 64 | |||
1164 | 65 | `RepositoryMapping` will return a dict-like object containing enabled system repositories | ||
1165 | 66 | and their properties (available groups, baseuri. gpg key). This class can add, disable, or | ||
1166 | 67 | manipulate repositories. Items can be retrieved as `DebianRepository` objects. | ||
1167 | 68 | |||
1168 | 69 | In order add a new repository with explicit details for fields, a new `DebianRepository` can | ||
1169 | 70 | be added to `RepositoryMapping` | ||
1170 | 71 | |||
1171 | 72 | `RepositoryMapping` provides an abstraction around the existing repositories on the system, | ||
1172 | 73 | and can be accessed and iterated over like any `Mapping` object, to retrieve values by key, | ||
1173 | 74 | iterate, or perform other operations. | ||
1174 | 75 | |||
1175 | 76 | Keys are constructed as `{repo_type}-{}-{release}` in order to uniquely identify a repository. | ||
1176 | 77 | |||
1177 | 78 | Repositories can be added with explicit values through a Python constructor. | ||
1178 | 79 | |||
1179 | 80 | Example: | ||
1180 | 81 | |||
1181 | 82 | ```python | ||
1182 | 83 | repositories = apt.RepositoryMapping() | ||
1183 | 84 | |||
1184 | 85 | if "deb-example.com-focal" not in repositories: | ||
1185 | 86 | repositories.add(DebianRepository(enabled=True, repotype="deb", | ||
1186 | 87 | uri="https://example.com", release="focal", groups=["universe"])) | ||
1187 | 88 | ``` | ||
1188 | 89 | |||
1189 | 90 | Alternatively, any valid `sources.list` line may be used to construct a new | ||
1190 | 91 | `DebianRepository`. | ||
1191 | 92 | |||
1192 | 93 | Example: | ||
1193 | 94 | |||
1194 | 95 | ```python | ||
1195 | 96 | repositories = apt.RepositoryMapping() | ||
1196 | 97 | |||
1197 | 98 | if "deb-us.archive.ubuntu.com-xenial" not in repositories: | ||
1198 | 99 | line = "deb http://us.archive.ubuntu.com/ubuntu xenial main restricted" | ||
1199 | 100 | repo = DebianRepository.from_repo_line(line) | ||
1200 | 101 | repositories.add(repo) | ||
1201 | 102 | ``` | ||
1202 | 103 | """ | ||
1203 | 104 | |||
1204 | 105 | import fileinput | ||
1205 | 106 | import glob | ||
1206 | 107 | import logging | ||
1207 | 108 | import os | ||
1208 | 109 | import re | ||
1209 | 110 | import subprocess | ||
1210 | 111 | from collections.abc import Mapping | ||
1211 | 112 | from enum import Enum | ||
1212 | 113 | from subprocess import PIPE, CalledProcessError, check_call, check_output | ||
1213 | 114 | from typing import Iterable, List, Optional, Tuple, Union | ||
1214 | 115 | from urllib.parse import urlparse | ||
1215 | 116 | |||
1216 | 117 | logger = logging.getLogger(__name__) | ||
1217 | 118 | |||
1218 | 119 | # The unique Charmhub library identifier, never change it | ||
1219 | 120 | LIBID = "7c3dbc9c2ad44a47bd6fcb25caa270e5" | ||
1220 | 121 | |||
1221 | 122 | # Increment this major API version when introducing breaking changes | ||
1222 | 123 | LIBAPI = 0 | ||
1223 | 124 | |||
1224 | 125 | # Increment this PATCH version before using `charmcraft publish-lib` or reset | ||
1225 | 126 | # to 0 if you are raising the major API version | ||
1226 | 127 | LIBPATCH = 7 | ||
1227 | 128 | |||
1228 | 129 | |||
1229 | 130 | VALID_SOURCE_TYPES = ("deb", "deb-src") | ||
1230 | 131 | OPTIONS_MATCHER = re.compile(r"\[.*?\]") | ||
1231 | 132 | |||
1232 | 133 | |||
1233 | 134 | class Error(Exception): | ||
1234 | 135 | """Base class of most errors raised by this library.""" | ||
1235 | 136 | |||
1236 | 137 | def __repr__(self): | ||
1237 | 138 | """String representation of Error.""" | ||
1238 | 139 | return "<{}.{} {}>".format(type(self).__module__, type(self).__name__, self.args) | ||
1239 | 140 | |||
1240 | 141 | @property | ||
1241 | 142 | def name(self): | ||
1242 | 143 | """Return a string representation of the model plus class.""" | ||
1243 | 144 | return "<{}.{}>".format(type(self).__module__, type(self).__name__) | ||
1244 | 145 | |||
1245 | 146 | @property | ||
1246 | 147 | def message(self): | ||
1247 | 148 | """Return the message passed as an argument.""" | ||
1248 | 149 | return self.args[0] | ||
1249 | 150 | |||
1250 | 151 | |||
1251 | 152 | class PackageError(Error): | ||
1252 | 153 | """Raised when there's an error installing or removing a package.""" | ||
1253 | 154 | |||
1254 | 155 | |||
1255 | 156 | class PackageNotFoundError(Error): | ||
1256 | 157 | """Raised when a requested package is not known to the system.""" | ||
1257 | 158 | |||
1258 | 159 | |||
1259 | 160 | class PackageState(Enum): | ||
1260 | 161 | """A class to represent possible package states.""" | ||
1261 | 162 | |||
1262 | 163 | Present = "present" | ||
1263 | 164 | Absent = "absent" | ||
1264 | 165 | Latest = "latest" | ||
1265 | 166 | Available = "available" | ||
1266 | 167 | |||
1267 | 168 | |||
1268 | 169 | class DebianPackage: | ||
1269 | 170 | """Represents a traditional Debian package and its utility functions. | ||
1270 | 171 | |||
1271 | 172 | `DebianPackage` wraps information and functionality around a known package, whether installed | ||
1272 | 173 | or available. The version, epoch, name, and architecture can be easily queried and compared | ||
1273 | 174 | against other `DebianPackage` objects to determine the latest version or to install a specific | ||
1274 | 175 | version. | ||
1275 | 176 | |||
1276 | 177 | The representation of this object as a string mimics the output from `dpkg` for familiarity. | ||
1277 | 178 | |||
1278 | 179 | Installation and removal of packages is handled through the `state` property or `ensure` | ||
1279 | 180 | method, with the following options: | ||
1280 | 181 | |||
1281 | 182 | apt.PackageState.Absent | ||
1282 | 183 | apt.PackageState.Available | ||
1283 | 184 | apt.PackageState.Present | ||
1284 | 185 | apt.PackageState.Latest | ||
1285 | 186 | |||
1286 | 187 | When `DebianPackage` is initialized, the state of a given `DebianPackage` object will be set to | ||
1287 | 188 | `Available`, `Present`, or `Latest`, with `Absent` implemented as a convenience for removal | ||
1288 | 189 | (though it operates essentially the same as `Available`). | ||
1289 | 190 | """ | ||
1290 | 191 | |||
1291 | 192 | def __init__( | ||
1292 | 193 | self, name: str, version: str, epoch: str, arch: str, state: PackageState | ||
1293 | 194 | ) -> None: | ||
1294 | 195 | self._name = name | ||
1295 | 196 | self._arch = arch | ||
1296 | 197 | self._state = state | ||
1297 | 198 | self._version = Version(version, epoch) | ||
1298 | 199 | |||
1299 | 200 | def __eq__(self, other) -> bool: | ||
1300 | 201 | """Equality for comparison. | ||
1301 | 202 | |||
1302 | 203 | Args: | ||
1303 | 204 | other: a `DebianPackage` object for comparison | ||
1304 | 205 | |||
1305 | 206 | Returns: | ||
1306 | 207 | A boolean reflecting equality | ||
1307 | 208 | """ | ||
1308 | 209 | return isinstance(other, self.__class__) and ( | ||
1309 | 210 | self._name, | ||
1310 | 211 | self._version.number, | ||
1311 | 212 | ) == (other._name, other._version.number) | ||
1312 | 213 | |||
1313 | 214 | def __hash__(self): | ||
1314 | 215 | """A basic hash so this class can be used in Mappings and dicts.""" | ||
1315 | 216 | return hash((self._name, self._version.number)) | ||
1316 | 217 | |||
1317 | 218 | def __repr__(self): | ||
1318 | 219 | """A representation of the package.""" | ||
1319 | 220 | return "<{}.{}: {}>".format(self.__module__, self.__class__.__name__, self.__dict__) | ||
1320 | 221 | |||
1321 | 222 | def __str__(self): | ||
1322 | 223 | """A human-readable representation of the package.""" | ||
1323 | 224 | return "<{}: {}-{}.{} -- {}>".format( | ||
1324 | 225 | self.__class__.__name__, | ||
1325 | 226 | self._name, | ||
1326 | 227 | self._version, | ||
1327 | 228 | self._arch, | ||
1328 | 229 | str(self._state), | ||
1329 | 230 | ) | ||
1330 | 231 | |||
1331 | 232 | @staticmethod | ||
1332 | 233 | def _apt( | ||
1333 | 234 | command: str, | ||
1334 | 235 | package_names: Union[str, List], | ||
1335 | 236 | optargs: Optional[List[str]] = None, | ||
1336 | 237 | ) -> None: | ||
1337 | 238 | """Wrap package management commands for Debian/Ubuntu systems. | ||
1338 | 239 | |||
1339 | 240 | Args: | ||
1340 | 241 | command: the command given to `apt-get` | ||
1341 | 242 | package_names: a package name or list of package names to operate on | ||
1342 | 243 | optargs: an (Optional) list of additioanl arguments | ||
1343 | 244 | |||
1344 | 245 | Raises: | ||
1345 | 246 | PackageError if an error is encountered | ||
1346 | 247 | """ | ||
1347 | 248 | optargs = optargs if optargs is not None else [] | ||
1348 | 249 | if isinstance(package_names, str): | ||
1349 | 250 | package_names = [package_names] | ||
1350 | 251 | _cmd = ["apt-get", "-y", *optargs, command, *package_names] | ||
1351 | 252 | try: | ||
1352 | 253 | check_call(_cmd, stderr=PIPE, stdout=PIPE) | ||
1353 | 254 | except CalledProcessError as e: | ||
1354 | 255 | raise PackageError( | ||
1355 | 256 | "Could not {} package(s) [{}]: {}".format(command, [*package_names], e.output) | ||
1356 | 257 | ) from None | ||
1357 | 258 | |||
1358 | 259 | def _add(self) -> None: | ||
1359 | 260 | """Add a package to the system.""" | ||
1360 | 261 | self._apt( | ||
1361 | 262 | "install", | ||
1362 | 263 | "{}={}".format(self.name, self.version), | ||
1363 | 264 | optargs=["--option=Dpkg::Options::=--force-confold"], | ||
1364 | 265 | ) | ||
1365 | 266 | |||
1366 | 267 | def _remove(self) -> None: | ||
1367 | 268 | """Removes a package from the system. Implementation-specific.""" | ||
1368 | 269 | return self._apt("remove", "{}={}".format(self.name, self.version)) | ||
1369 | 270 | |||
1370 | 271 | @property | ||
1371 | 272 | def name(self) -> str: | ||
1372 | 273 | """Returns the name of the package.""" | ||
1373 | 274 | return self._name | ||
1374 | 275 | |||
1375 | 276 | def ensure(self, state: PackageState): | ||
1376 | 277 | """Ensures that a package is in a given state. | ||
1377 | 278 | |||
1378 | 279 | Args: | ||
1379 | 280 | state: a `PackageState` to reconcile the package to | ||
1380 | 281 | |||
1381 | 282 | Raises: | ||
1382 | 283 | PackageError from the underlying call to apt | ||
1383 | 284 | """ | ||
1384 | 285 | if self._state is not state: | ||
1385 | 286 | if state not in (PackageState.Present, PackageState.Latest): | ||
1386 | 287 | self._remove() | ||
1387 | 288 | else: | ||
1388 | 289 | self._add() | ||
1389 | 290 | self._state = state | ||
1390 | 291 | |||
1391 | 292 | @property | ||
1392 | 293 | def present(self) -> bool: | ||
1393 | 294 | """Returns whether or not a package is present.""" | ||
1394 | 295 | return self._state in (PackageState.Present, PackageState.Latest) | ||
1395 | 296 | |||
1396 | 297 | @property | ||
1397 | 298 | def latest(self) -> bool: | ||
1398 | 299 | """Returns whether the package is the most recent version.""" | ||
1399 | 300 | return self._state is PackageState.Latest | ||
1400 | 301 | |||
1401 | 302 | @property | ||
1402 | 303 | def state(self) -> PackageState: | ||
1403 | 304 | """Returns the current package state.""" | ||
1404 | 305 | return self._state | ||
1405 | 306 | |||
1406 | 307 | @state.setter | ||
1407 | 308 | def state(self, state: PackageState) -> None: | ||
1408 | 309 | """Sets the package state to a given value. | ||
1409 | 310 | |||
1410 | 311 | Args: | ||
1411 | 312 | state: a `PackageState` to reconcile the package to | ||
1412 | 313 | |||
1413 | 314 | Raises: | ||
1414 | 315 | PackageError from the underlying call to apt | ||
1415 | 316 | """ | ||
1416 | 317 | if state in (PackageState.Latest, PackageState.Present): | ||
1417 | 318 | self._add() | ||
1418 | 319 | else: | ||
1419 | 320 | self._remove() | ||
1420 | 321 | self._state = state | ||
1421 | 322 | |||
1422 | 323 | @property | ||
1423 | 324 | def version(self) -> "Version": | ||
1424 | 325 | """Returns the version for a package.""" | ||
1425 | 326 | return self._version | ||
1426 | 327 | |||
1427 | 328 | @property | ||
1428 | 329 | def epoch(self) -> str: | ||
1429 | 330 | """Returns the epoch for a package. May be unset.""" | ||
1430 | 331 | return self._version.epoch | ||
1431 | 332 | |||
1432 | 333 | @property | ||
1433 | 334 | def arch(self) -> str: | ||
1434 | 335 | """Returns the architecture for a package.""" | ||
1435 | 336 | return self._arch | ||
1436 | 337 | |||
1437 | 338 | @property | ||
1438 | 339 | def fullversion(self) -> str: | ||
1439 | 340 | """Returns the name+epoch for a package.""" | ||
1440 | 341 | return "{}.{}".format(self._version, self._arch) | ||
1441 | 342 | |||
1442 | 343 | @staticmethod | ||
1443 | 344 | def _get_epoch_from_version(version: str) -> Tuple[str, str]: | ||
1444 | 345 | """Pull the epoch, if any, out of a version string.""" | ||
1445 | 346 | epoch_matcher = re.compile(r"^((?P<epoch>\d+):)?(?P<version>.*)") | ||
1446 | 347 | matches = epoch_matcher.search(version).groupdict() | ||
1447 | 348 | return matches.get("epoch", ""), matches.get("version") | ||
1448 | 349 | |||
1449 | 350 | @classmethod | ||
1450 | 351 | def from_system( | ||
1451 | 352 | cls, package: str, version: Optional[str] = "", arch: Optional[str] = "" | ||
1452 | 353 | ) -> "DebianPackage": | ||
1453 | 354 | """Locates a package, either on the system or known to apt, and serializes the information. | ||
1454 | 355 | |||
1455 | 356 | Args: | ||
1456 | 357 | package: a string representing the package | ||
1457 | 358 | version: an optional string if a specific version isr equested | ||
1458 | 359 | arch: an optional architecture, defaulting to `dpkg --print-architecture`. If an | ||
1459 | 360 | architecture is not specified, this will be used for selection. | ||
1460 | 361 | |||
1461 | 362 | """ | ||
1462 | 363 | try: | ||
1463 | 364 | return DebianPackage.from_installed_package(package, version, arch) | ||
1464 | 365 | except PackageNotFoundError: | ||
1465 | 366 | logger.debug( | ||
1466 | 367 | "package '%s' is not currently installed or has the wrong architecture.", package | ||
1467 | 368 | ) | ||
1468 | 369 | |||
1469 | 370 | # Ok, try `apt-cache ...` | ||
1470 | 371 | try: | ||
1471 | 372 | return DebianPackage.from_apt_cache(package, version, arch) | ||
1472 | 373 | except (PackageNotFoundError, PackageError): | ||
1473 | 374 | # If we get here, it's not known to the systems. | ||
1474 | 375 | # This seems unnecessary, but virtually all `apt` commands have a return code of `100`, | ||
1475 | 376 | # and providing meaningful error messages without this is ugly. | ||
1476 | 377 | raise PackageNotFoundError( | ||
1477 | 378 | "Package '{}{}' could not be found on the system or in the apt cache!".format( | ||
1478 | 379 | package, ".{}".format(arch) if arch else "" | ||
1479 | 380 | ) | ||
1480 | 381 | ) from None | ||
1481 | 382 | |||
1482 | 383 | @classmethod | ||
1483 | 384 | def from_installed_package( | ||
1484 | 385 | cls, package: str, version: Optional[str] = "", arch: Optional[str] = "" | ||
1485 | 386 | ) -> "DebianPackage": | ||
1486 | 387 | """Check whether the package is already installed and return an instance. | ||
1487 | 388 | |||
1488 | 389 | Args: | ||
1489 | 390 | package: a string representing the package | ||
1490 | 391 | version: an optional string if a specific version isr equested | ||
1491 | 392 | arch: an optional architecture, defaulting to `dpkg --print-architecture`. | ||
1492 | 393 | If an architecture is not specified, this will be used for selection. | ||
1493 | 394 | """ | ||
1494 | 395 | system_arch = check_output( | ||
1495 | 396 | ["dpkg", "--print-architecture"], universal_newlines=True | ||
1496 | 397 | ).strip() | ||
1497 | 398 | arch = arch if arch else system_arch | ||
1498 | 399 | |||
1499 | 400 | # Regexps are a really terrible way to do this. Thanks dpkg | ||
1500 | 401 | output = "" | ||
1501 | 402 | try: | ||
1502 | 403 | output = check_output(["dpkg", "-l", package], stderr=PIPE, universal_newlines=True) | ||
1503 | 404 | except CalledProcessError: | ||
1504 | 405 | raise PackageNotFoundError("Package is not installed: {}".format(package)) from None | ||
1505 | 406 | |||
1506 | 407 | # Pop off the output from `dpkg -l' because there's no flag to | ||
1507 | 408 | # omit it` | ||
1508 | 409 | lines = str(output).splitlines()[5:] | ||
1509 | 410 | |||
1510 | 411 | dpkg_matcher = re.compile( | ||
1511 | 412 | r""" | ||
1512 | 413 | ^(?P<package_status>\w+?)\s+ | ||
1513 | 414 | (?P<package_name>.*?)(?P<throwaway_arch>:\w+?)?\s+ | ||
1514 | 415 | (?P<version>.*?)\s+ | ||
1515 | 416 | (?P<arch>\w+?)\s+ | ||
1516 | 417 | (?P<description>.*) | ||
1517 | 418 | """, | ||
1518 | 419 | re.VERBOSE, | ||
1519 | 420 | ) | ||
1520 | 421 | |||
1521 | 422 | for line in lines: | ||
1522 | 423 | try: | ||
1523 | 424 | matches = dpkg_matcher.search(line).groupdict() | ||
1524 | 425 | package_status = matches["package_status"] | ||
1525 | 426 | |||
1526 | 427 | if not package_status.endswith("i"): | ||
1527 | 428 | logger.debug( | ||
1528 | 429 | "package '%s' in dpkg output but not installed, status: '%s'", | ||
1529 | 430 | package, | ||
1530 | 431 | package_status, | ||
1531 | 432 | ) | ||
1532 | 433 | break | ||
1533 | 434 | |||
1534 | 435 | epoch, split_version = DebianPackage._get_epoch_from_version(matches["version"]) | ||
1535 | 436 | pkg = DebianPackage( | ||
1536 | 437 | matches["package_name"], | ||
1537 | 438 | split_version, | ||
1538 | 439 | epoch, | ||
1539 | 440 | matches["arch"], | ||
1540 | 441 | PackageState.Present, | ||
1541 | 442 | ) | ||
1542 | 443 | if (pkg.arch == "all" or pkg.arch == arch) and ( | ||
1543 | 444 | version == "" or str(pkg.version) == version | ||
1544 | 445 | ): | ||
1545 | 446 | return pkg | ||
1546 | 447 | except AttributeError: | ||
1547 | 448 | logger.warning("dpkg matcher could not parse line: %s", line) | ||
1548 | 449 | |||
1549 | 450 | # If we didn't find it, fail through | ||
1550 | 451 | raise PackageNotFoundError("Package {}.{} is not installed!".format(package, arch)) | ||
1551 | 452 | |||
1552 | 453 | @classmethod | ||
1553 | 454 | def from_apt_cache( | ||
1554 | 455 | cls, package: str, version: Optional[str] = "", arch: Optional[str] = "" | ||
1555 | 456 | ) -> "DebianPackage": | ||
1556 | 457 | """Check whether the package is already installed and return an instance. | ||
1557 | 458 | |||
1558 | 459 | Args: | ||
1559 | 460 | package: a string representing the package | ||
1560 | 461 | version: an optional string if a specific version isr equested | ||
1561 | 462 | arch: an optional architecture, defaulting to `dpkg --print-architecture`. | ||
1562 | 463 | If an architecture is not specified, this will be used for selection. | ||
1563 | 464 | """ | ||
1564 | 465 | system_arch = check_output( | ||
1565 | 466 | ["dpkg", "--print-architecture"], universal_newlines=True | ||
1566 | 467 | ).strip() | ||
1567 | 468 | arch = arch if arch else system_arch | ||
1568 | 469 | |||
1569 | 470 | # Regexps are a really terrible way to do this. Thanks dpkg | ||
1570 | 471 | keys = ("Package", "Architecture", "Version") | ||
1571 | 472 | |||
1572 | 473 | try: | ||
1573 | 474 | output = check_output( | ||
1574 | 475 | ["apt-cache", "show", package], stderr=PIPE, universal_newlines=True | ||
1575 | 476 | ) | ||
1576 | 477 | except CalledProcessError as e: | ||
1577 | 478 | raise PackageError( | ||
1578 | 479 | "Could not list packages in apt-cache: {}".format(e.output) | ||
1579 | 480 | ) from None | ||
1580 | 481 | |||
1581 | 482 | pkg_groups = output.strip().split("\n\n") | ||
1582 | 483 | keys = ("Package", "Architecture", "Version") | ||
1583 | 484 | |||
1584 | 485 | for pkg_raw in pkg_groups: | ||
1585 | 486 | lines = str(pkg_raw).splitlines() | ||
1586 | 487 | vals = {} | ||
1587 | 488 | for line in lines: | ||
1588 | 489 | if line.startswith(keys): | ||
1589 | 490 | items = line.split(":", 1) | ||
1590 | 491 | vals[items[0]] = items[1].strip() | ||
1591 | 492 | else: | ||
1592 | 493 | continue | ||
1593 | 494 | |||
1594 | 495 | epoch, split_version = DebianPackage._get_epoch_from_version(vals["Version"]) | ||
1595 | 496 | pkg = DebianPackage( | ||
1596 | 497 | vals["Package"], | ||
1597 | 498 | split_version, | ||
1598 | 499 | epoch, | ||
1599 | 500 | vals["Architecture"], | ||
1600 | 501 | PackageState.Available, | ||
1601 | 502 | ) | ||
1602 | 503 | |||
1603 | 504 | if (pkg.arch == "all" or pkg.arch == arch) and ( | ||
1604 | 505 | version == "" or str(pkg.version) == version | ||
1605 | 506 | ): | ||
1606 | 507 | return pkg | ||
1607 | 508 | |||
1608 | 509 | # If we didn't find it, fail through | ||
1609 | 510 | raise PackageNotFoundError("Package {}.{} is not in the apt cache!".format(package, arch)) | ||
1610 | 511 | |||
1611 | 512 | |||
1612 | 513 | class Version: | ||
1613 | 514 | """An abstraction around package versions. | ||
1614 | 515 | |||
1615 | 516 | This seems like it should be strictly unnecessary, except that `apt_pkg` is not usable inside a | ||
1616 | 517 | venv, and wedging version comparisions into `DebianPackage` would overcomplicate it. | ||
1617 | 518 | |||
1618 | 519 | This class implements the algorithm found here: | ||
1619 | 520 | https://www.debian.org/doc/debian-policy/ch-controlfields.html#version | ||
1620 | 521 | """ | ||
1621 | 522 | |||
1622 | 523 | def __init__(self, version: str, epoch: str): | ||
1623 | 524 | self._version = version | ||
1624 | 525 | self._epoch = epoch or "" | ||
1625 | 526 | |||
1626 | 527 | def __repr__(self): | ||
1627 | 528 | """A representation of the package.""" | ||
1628 | 529 | return "<{}.{}: {}>".format(self.__module__, self.__class__.__name__, self.__dict__) | ||
1629 | 530 | |||
1630 | 531 | def __str__(self): | ||
1631 | 532 | """A human-readable representation of the package.""" | ||
1632 | 533 | return "{}{}".format("{}:".format(self._epoch) if self._epoch else "", self._version) | ||
1633 | 534 | |||
1634 | 535 | @property | ||
1635 | 536 | def epoch(self): | ||
1636 | 537 | """Returns the epoch for a package. May be empty.""" | ||
1637 | 538 | return self._epoch | ||
1638 | 539 | |||
1639 | 540 | @property | ||
1640 | 541 | def number(self) -> str: | ||
1641 | 542 | """Returns the version number for a package.""" | ||
1642 | 543 | return self._version | ||
1643 | 544 | |||
1644 | 545 | def _get_parts(self, version: str) -> Tuple[str, str]: | ||
1645 | 546 | """Separate the version into component upstream and Debian pieces.""" | ||
1646 | 547 | try: | ||
1647 | 548 | version.rindex("-") | ||
1648 | 549 | except ValueError: | ||
1649 | 550 | # No hyphens means no Debian version | ||
1650 | 551 | return version, "0" | ||
1651 | 552 | |||
1652 | 553 | upstream, debian = version.rsplit("-", 1) | ||
1653 | 554 | return upstream, debian | ||
1654 | 555 | |||
1655 | 556 | def _listify(self, revision: str) -> List[str]: | ||
1656 | 557 | """Split a revision string into a listself. | ||
1657 | 558 | |||
1658 | 559 | This list is comprised of alternating between strings and numbers, | ||
1659 | 560 | padded on either end to always be "str, int, str, int..." and | ||
1660 | 561 | always be of even length. This allows us to trivially implement the | ||
1661 | 562 | comparison algorithm described. | ||
1662 | 563 | """ | ||
1663 | 564 | result = [] | ||
1664 | 565 | while revision: | ||
1665 | 566 | rev_1, remains = self._get_alphas(revision) | ||
1666 | 567 | rev_2, remains = self._get_digits(remains) | ||
1667 | 568 | result.extend([rev_1, rev_2]) | ||
1668 | 569 | revision = remains | ||
1669 | 570 | return result | ||
1670 | 571 | |||
1671 | 572 | def _get_alphas(self, revision: str) -> Tuple[str, str]: | ||
1672 | 573 | """Return a tuple of the first non-digit characters of a revision.""" | ||
1673 | 574 | # get the index of the first digit | ||
1674 | 575 | for i, char in enumerate(revision): | ||
1675 | 576 | if char.isdigit(): | ||
1676 | 577 | if i == 0: | ||
1677 | 578 | return "", revision | ||
1678 | 579 | return revision[0:i], revision[i:] | ||
1679 | 580 | # string is entirely alphas | ||
1680 | 581 | return revision, "" | ||
1681 | 582 | |||
1682 | 583 | def _get_digits(self, revision: str) -> Tuple[int, str]: | ||
1683 | 584 | """Return a tuple of the first integer characters of a revision.""" | ||
1684 | 585 | # If the string is empty, return (0,'') | ||
1685 | 586 | if not revision: | ||
1686 | 587 | return 0, "" | ||
1687 | 588 | # get the index of the first non-digit | ||
1688 | 589 | for i, char in enumerate(revision): | ||
1689 | 590 | if not char.isdigit(): | ||
1690 | 591 | if i == 0: | ||
1691 | 592 | return 0, revision | ||
1692 | 593 | return int(revision[0:i]), revision[i:] | ||
1693 | 594 | # string is entirely digits | ||
1694 | 595 | return int(revision), "" | ||
1695 | 596 | |||
1696 | 597 | def _dstringcmp(self, a, b): # noqa: C901 | ||
1697 | 598 | """Debian package version string section lexical sort algorithm. | ||
1698 | 599 | |||
1699 | 600 | The lexical comparison is a comparison of ASCII values modified so | ||
1700 | 601 | that all the letters sort earlier than all the non-letters and so that | ||
1701 | 602 | a tilde sorts before anything, even the end of a part. | ||
1702 | 603 | """ | ||
1703 | 604 | if a == b: | ||
1704 | 605 | return 0 | ||
1705 | 606 | try: | ||
1706 | 607 | for i, char in enumerate(a): | ||
1707 | 608 | if char == b[i]: | ||
1708 | 609 | continue | ||
1709 | 610 | # "a tilde sorts before anything, even the end of a part" | ||
1710 | 611 | # (emptyness) | ||
1711 | 612 | if char == "~": | ||
1712 | 613 | return -1 | ||
1713 | 614 | if b[i] == "~": | ||
1714 | 615 | return 1 | ||
1715 | 616 | # "all the letters sort earlier than all the non-letters" | ||
1716 | 617 | if char.isalpha() and not b[i].isalpha(): | ||
1717 | 618 | return -1 | ||
1718 | 619 | if not char.isalpha() and b[i].isalpha(): | ||
1719 | 620 | return 1 | ||
1720 | 621 | # otherwise lexical sort | ||
1721 | 622 | if ord(char) > ord(b[i]): | ||
1722 | 623 | return 1 | ||
1723 | 624 | if ord(char) < ord(b[i]): | ||
1724 | 625 | return -1 | ||
1725 | 626 | except IndexError: | ||
1726 | 627 | # a is longer than b but otherwise equal, greater unless there are tildes | ||
1727 | 628 | if char == "~": | ||
1728 | 629 | return -1 | ||
1729 | 630 | return 1 | ||
1730 | 631 | # if we get here, a is shorter than b but otherwise equal, so check for tildes... | ||
1731 | 632 | if b[len(a)] == "~": | ||
1732 | 633 | return 1 | ||
1733 | 634 | return -1 | ||
1734 | 635 | |||
1735 | 636 | def _compare_revision_strings(self, first: str, second: str): # noqa: C901 | ||
1736 | 637 | """Compare two debian revision strings.""" | ||
1737 | 638 | if first == second: | ||
1738 | 639 | return 0 | ||
1739 | 640 | |||
1740 | 641 | # listify pads results so that we will always be comparing ints to ints | ||
1741 | 642 | # and strings to strings (at least until we fall off the end of a list) | ||
1742 | 643 | first_list = self._listify(first) | ||
1743 | 644 | second_list = self._listify(second) | ||
1744 | 645 | if first_list == second_list: | ||
1745 | 646 | return 0 | ||
1746 | 647 | try: | ||
1747 | 648 | for i, item in enumerate(first_list): | ||
1748 | 649 | # explicitly raise IndexError if we've fallen off the edge of list2 | ||
1749 | 650 | if i >= len(second_list): | ||
1750 | 651 | raise IndexError | ||
1751 | 652 | # if the items are equal, next | ||
1752 | 653 | if item == second_list[i]: | ||
1753 | 654 | continue | ||
1754 | 655 | # numeric comparison | ||
1755 | 656 | if isinstance(item, int): | ||
1756 | 657 | if item > second_list[i]: | ||
1757 | 658 | return 1 | ||
1758 | 659 | if item < second_list[i]: | ||
1759 | 660 | return -1 | ||
1760 | 661 | else: | ||
1761 | 662 | # string comparison | ||
1762 | 663 | return self._dstringcmp(item, second_list[i]) | ||
1763 | 664 | except IndexError: | ||
1764 | 665 | # rev1 is longer than rev2 but otherwise equal, hence greater | ||
1765 | 666 | # ...except for goddamn tildes | ||
1766 | 667 | if first_list[len(second_list)][0][0] == "~": | ||
1767 | 668 | return 1 | ||
1768 | 669 | return 1 | ||
1769 | 670 | # rev1 is shorter than rev2 but otherwise equal, hence lesser | ||
1770 | 671 | # ...except for goddamn tildes | ||
1771 | 672 | if second_list[len(first_list)][0][0] == "~": | ||
1772 | 673 | return -1 | ||
1773 | 674 | return -1 | ||
1774 | 675 | |||
1775 | 676 | def _compare_version(self, other) -> int: | ||
1776 | 677 | if (self.number, self.epoch) == (other.number, other.epoch): | ||
1777 | 678 | return 0 | ||
1778 | 679 | |||
1779 | 680 | if self.epoch < other.epoch: | ||
1780 | 681 | return -1 | ||
1781 | 682 | if self.epoch > other.epoch: | ||
1782 | 683 | return 1 | ||
1783 | 684 | |||
1784 | 685 | # If none of these are true, follow the algorithm | ||
1785 | 686 | upstream_version, debian_version = self._get_parts(self.number) | ||
1786 | 687 | other_upstream_version, other_debian_version = self._get_parts(other.number) | ||
1787 | 688 | |||
1788 | 689 | upstream_cmp = self._compare_revision_strings(upstream_version, other_upstream_version) | ||
1789 | 690 | if upstream_cmp != 0: | ||
1790 | 691 | return upstream_cmp | ||
1791 | 692 | |||
1792 | 693 | debian_cmp = self._compare_revision_strings(debian_version, other_debian_version) | ||
1793 | 694 | if debian_cmp != 0: | ||
1794 | 695 | return debian_cmp | ||
1795 | 696 | |||
1796 | 697 | return 0 | ||
1797 | 698 | |||
1798 | 699 | def __lt__(self, other) -> bool: | ||
1799 | 700 | """Less than magic method impl.""" | ||
1800 | 701 | return self._compare_version(other) < 0 | ||
1801 | 702 | |||
1802 | 703 | def __eq__(self, other) -> bool: | ||
1803 | 704 | """Equality magic method impl.""" | ||
1804 | 705 | return self._compare_version(other) == 0 | ||
1805 | 706 | |||
1806 | 707 | def __gt__(self, other) -> bool: | ||
1807 | 708 | """Greater than magic method impl.""" | ||
1808 | 709 | return self._compare_version(other) > 0 | ||
1809 | 710 | |||
1810 | 711 | def __le__(self, other) -> bool: | ||
1811 | 712 | """Less than or equal to magic method impl.""" | ||
1812 | 713 | return self.__eq__(other) or self.__lt__(other) | ||
1813 | 714 | |||
1814 | 715 | def __ge__(self, other) -> bool: | ||
1815 | 716 | """Greater than or equal to magic method impl.""" | ||
1816 | 717 | return self.__gt__(other) or self.__eq__(other) | ||
1817 | 718 | |||
1818 | 719 | def __ne__(self, other) -> bool: | ||
1819 | 720 | """Not equal to magic method impl.""" | ||
1820 | 721 | return not self.__eq__(other) | ||
1821 | 722 | |||
1822 | 723 | |||
1823 | 724 | def add_package( | ||
1824 | 725 | package_names: Union[str, List[str]], | ||
1825 | 726 | version: Optional[str] = "", | ||
1826 | 727 | arch: Optional[str] = "", | ||
1827 | 728 | update_cache: Optional[bool] = False, | ||
1828 | 729 | ) -> Union[DebianPackage, List[DebianPackage]]: | ||
1829 | 730 | """Add a package or list of packages to the system. | ||
1830 | 731 | |||
1831 | 732 | Args: | ||
1832 | 733 | name: the name(s) of the package(s) | ||
1833 | 734 | version: an (Optional) version as a string. Defaults to the latest known | ||
1834 | 735 | arch: an optional architecture for the package | ||
1835 | 736 | update_cache: whether or not to run `apt-get update` prior to operating | ||
1836 | 737 | |||
1837 | 738 | Raises: | ||
1838 | 739 | PackageNotFoundError if the package is not in the cache. | ||
1839 | 740 | """ | ||
1840 | 741 | cache_refreshed = False | ||
1841 | 742 | if update_cache: | ||
1842 | 743 | update() | ||
1843 | 744 | cache_refreshed = True | ||
1844 | 745 | |||
1845 | 746 | packages = {"success": [], "retry": [], "failed": []} | ||
1846 | 747 | |||
1847 | 748 | package_names = [package_names] if type(package_names) is str else package_names | ||
1848 | 749 | if not package_names: | ||
1849 | 750 | raise TypeError("Expected at least one package name to add, received zero!") | ||
1850 | 751 | |||
1851 | 752 | if len(package_names) != 1 and version: | ||
1852 | 753 | raise TypeError( | ||
1853 | 754 | "Explicit version should not be set if more than one package is being added!" | ||
1854 | 755 | ) | ||
1855 | 756 | |||
1856 | 757 | for p in package_names: | ||
1857 | 758 | pkg, success = _add(p, version, arch) | ||
1858 | 759 | if success: | ||
1859 | 760 | packages["success"].append(pkg) | ||
1860 | 761 | else: | ||
1861 | 762 | logger.warning("failed to locate and install/update '%s'", pkg) | ||
1862 | 763 | packages["retry"].append(p) | ||
1863 | 764 | |||
1864 | 765 | if packages["retry"] and not cache_refreshed: | ||
1865 | 766 | logger.info("updating the apt-cache and retrying installation of failed packages.") | ||
1866 | 767 | update() | ||
1867 | 768 | |||
1868 | 769 | for p in packages["retry"]: | ||
1869 | 770 | pkg, success = _add(p, version, arch) | ||
1870 | 771 | if success: | ||
1871 | 772 | packages["success"].append(pkg) | ||
1872 | 773 | else: | ||
1873 | 774 | packages["failed"].append(p) | ||
1874 | 775 | |||
1875 | 776 | if packages["failed"]: | ||
1876 | 777 | raise PackageError("Failed to install packages: {}".format(", ".join(packages["failed"]))) | ||
1877 | 778 | |||
1878 | 779 | return packages["success"] if len(packages["success"]) > 1 else packages["success"][0] | ||
1879 | 780 | |||
1880 | 781 | |||
1881 | 782 | def _add( | ||
1882 | 783 | name: str, | ||
1883 | 784 | version: Optional[str] = "", | ||
1884 | 785 | arch: Optional[str] = "", | ||
1885 | 786 | ) -> Tuple[Union[DebianPackage, str], bool]: | ||
1886 | 787 | """Adds a package. | ||
1887 | 788 | |||
1888 | 789 | Args: | ||
1889 | 790 | name: the name(s) of the package(s) | ||
1890 | 791 | version: an (Optional) version as a string. Defaults to the latest known | ||
1891 | 792 | arch: an optional architecture for the package | ||
1892 | 793 | |||
1893 | 794 | Returns: a tuple of `DebianPackage` if found, or a :str: if it is not, and | ||
1894 | 795 | a boolean indicating success | ||
1895 | 796 | """ | ||
1896 | 797 | try: | ||
1897 | 798 | pkg = DebianPackage.from_system(name, version, arch) | ||
1898 | 799 | pkg.ensure(state=PackageState.Present) | ||
1899 | 800 | return pkg, True | ||
1900 | 801 | except PackageNotFoundError: | ||
1901 | 802 | return name, False | ||
1902 | 803 | |||
1903 | 804 | |||
1904 | 805 | def remove_package( | ||
1905 | 806 | package_names: Union[str, List[str]] | ||
1906 | 807 | ) -> Union[DebianPackage, List[DebianPackage]]: | ||
1907 | 808 | """Removes a package from the system. | ||
1908 | 809 | |||
1909 | 810 | Args: | ||
1910 | 811 | package_names: the name of a package | ||
1911 | 812 | |||
1912 | 813 | Raises: | ||
1913 | 814 | PackageNotFoundError if the package is not found. | ||
1914 | 815 | """ | ||
1915 | 816 | packages = [] | ||
1916 | 817 | |||
1917 | 818 | package_names = [package_names] if type(package_names) is str else package_names | ||
1918 | 819 | if not package_names: | ||
1919 | 820 | raise TypeError("Expected at least one package name to add, received zero!") | ||
1920 | 821 | |||
1921 | 822 | for p in package_names: | ||
1922 | 823 | try: | ||
1923 | 824 | pkg = DebianPackage.from_installed_package(p) | ||
1924 | 825 | pkg.ensure(state=PackageState.Absent) | ||
1925 | 826 | packages.append(pkg) | ||
1926 | 827 | except PackageNotFoundError: | ||
1927 | 828 | logger.info("package '%s' was requested for removal, but it was not installed.", p) | ||
1928 | 829 | |||
1929 | 830 | # the list of packages will be empty when no package is removed | ||
1930 | 831 | logger.debug("packages: '%s'", packages) | ||
1931 | 832 | return packages[0] if len(packages) == 1 else packages | ||
1932 | 833 | |||
1933 | 834 | |||
1934 | 835 | def update() -> None: | ||
1935 | 836 | """Updates the apt cache via `apt-get update`.""" | ||
1936 | 837 | check_call(["apt-get", "update"], stderr=PIPE, stdout=PIPE) | ||
1937 | 838 | |||
1938 | 839 | |||
1939 | 840 | class InvalidSourceError(Error): | ||
1940 | 841 | """Exceptions for invalid source entries.""" | ||
1941 | 842 | |||
1942 | 843 | |||
1943 | 844 | class GPGKeyError(Error): | ||
1944 | 845 | """Exceptions for GPG keys.""" | ||
1945 | 846 | |||
1946 | 847 | |||
1947 | 848 | class DebianRepository: | ||
1948 | 849 | """An abstraction to represent a repository.""" | ||
1949 | 850 | |||
1950 | 851 | def __init__( | ||
1951 | 852 | self, | ||
1952 | 853 | enabled: bool, | ||
1953 | 854 | repotype: str, | ||
1954 | 855 | uri: str, | ||
1955 | 856 | release: str, | ||
1956 | 857 | groups: List[str], | ||
1957 | 858 | filename: Optional[str] = "", | ||
1958 | 859 | gpg_key_filename: Optional[str] = "", | ||
1959 | 860 | options: Optional[dict] = None, | ||
1960 | 861 | ): | ||
1961 | 862 | self._enabled = enabled | ||
1962 | 863 | self._repotype = repotype | ||
1963 | 864 | self._uri = uri | ||
1964 | 865 | self._release = release | ||
1965 | 866 | self._groups = groups | ||
1966 | 867 | self._filename = filename | ||
1967 | 868 | self._gpg_key_filename = gpg_key_filename | ||
1968 | 869 | self._options = options | ||
1969 | 870 | |||
1970 | 871 | @property | ||
1971 | 872 | def enabled(self): | ||
1972 | 873 | """Return whether or not the repository is enabled.""" | ||
1973 | 874 | return self._enabled | ||
1974 | 875 | |||
1975 | 876 | @property | ||
1976 | 877 | def repotype(self): | ||
1977 | 878 | """Return whether it is binary or source.""" | ||
1978 | 879 | return self._repotype | ||
1979 | 880 | |||
1980 | 881 | @property | ||
1981 | 882 | def uri(self): | ||
1982 | 883 | """Return the URI.""" | ||
1983 | 884 | return self._uri | ||
1984 | 885 | |||
1985 | 886 | @property | ||
1986 | 887 | def release(self): | ||
1987 | 888 | """Return which Debian/Ubuntu releases it is valid for.""" | ||
1988 | 889 | return self._release | ||
1989 | 890 | |||
1990 | 891 | @property | ||
1991 | 892 | def groups(self): | ||
1992 | 893 | """Return the enabled package groups.""" | ||
1993 | 894 | return self._groups | ||
1994 | 895 | |||
1995 | 896 | @property | ||
1996 | 897 | def filename(self): | ||
1997 | 898 | """Returns the filename for a repository.""" | ||
1998 | 899 | return self._filename | ||
1999 | 900 | |||
2000 | 901 | @filename.setter | ||
2001 | 902 | def filename(self, fname: str) -> None: | ||
2002 | 903 | """Sets the filename used when a repo is written back to diskself. | ||
2003 | 904 | |||
2004 | 905 | Args: | ||
2005 | 906 | fname: a filename to write the repository information to. | ||
2006 | 907 | """ | ||
2007 | 908 | if not fname.endswith(".list"): | ||
2008 | 909 | raise InvalidSourceError("apt source filenames should end in .list!") | ||
2009 | 910 | |||
2010 | 911 | self._filename = fname | ||
2011 | 912 | |||
2012 | 913 | @property | ||
2013 | 914 | def gpg_key(self): | ||
2014 | 915 | """Returns the path to the GPG key for this repository.""" | ||
2015 | 916 | return self._gpg_key_filename | ||
2016 | 917 | |||
2017 | 918 | @property | ||
2018 | 919 | def options(self): | ||
2019 | 920 | """Returns any additional repo options which are set.""" | ||
2020 | 921 | return self._options | ||
2021 | 922 | |||
2022 | 923 | def make_options_string(self) -> str: | ||
2023 | 924 | """Generate the complete options string for a a repository. | ||
2024 | 925 | |||
2025 | 926 | Combining `gpg_key`, if set, and the rest of the options to find | ||
2026 | 927 | a complex repo string. | ||
2027 | 928 | """ | ||
2028 | 929 | options = self._options if self._options else {} | ||
2029 | 930 | if self._gpg_key_filename: | ||
2030 | 931 | options["signed-by"] = self._gpg_key_filename | ||
2031 | 932 | |||
2032 | 933 | return ( | ||
2033 | 934 | "[{}] ".format(" ".join(["{}={}".format(k, v) for k, v in options.items()])) | ||
2034 | 935 | if options | ||
2035 | 936 | else "" | ||
2036 | 937 | ) | ||
2037 | 938 | |||
2038 | 939 | @staticmethod | ||
2039 | 940 | def prefix_from_uri(uri: str) -> str: | ||
2040 | 941 | """Get a repo list prefix from the uri, depending on whether a path is set.""" | ||
2041 | 942 | uridetails = urlparse(uri) | ||
2042 | 943 | path = ( | ||
2043 | 944 | uridetails.path.lstrip("/").replace("/", "-") if uridetails.path else uridetails.netloc | ||
2044 | 945 | ) | ||
2045 | 946 | return "/etc/apt/sources.list.d/{}".format(path) | ||
2046 | 947 | |||
2047 | 948 | @staticmethod | ||
2048 | 949 | def from_repo_line(repo_line: str, write_file: Optional[bool] = True) -> "DebianRepository": | ||
2049 | 950 | """Instantiate a new `DebianRepository` a `sources.list` entry line. | ||
2050 | 951 | |||
2051 | 952 | Args: | ||
2052 | 953 | repo_line: a string representing a repository entry | ||
2053 | 954 | write_file: boolean to enable writing the new repo to disk | ||
2054 | 955 | """ | ||
2055 | 956 | repo = RepositoryMapping._parse(repo_line, "UserInput") | ||
2056 | 957 | fname = "{}-{}.list".format( | ||
2057 | 958 | DebianRepository.prefix_from_uri(repo.uri), repo.release.replace("/", "-") | ||
2058 | 959 | ) | ||
2059 | 960 | repo.filename = fname | ||
2060 | 961 | |||
2061 | 962 | options = repo.options if repo.options else {} | ||
2062 | 963 | if repo.gpg_key: | ||
2063 | 964 | options["signed-by"] = repo.gpg_key | ||
2064 | 965 | |||
2065 | 966 | # For Python 3.5 it's required to use sorted in the options dict in order to not have | ||
2066 | 967 | # different results in the order of the options between executions. | ||
2067 | 968 | options_str = ( | ||
2068 | 969 | "[{}] ".format(" ".join(["{}={}".format(k, v) for k, v in sorted(options.items())])) | ||
2069 | 970 | if options | ||
2070 | 971 | else "" | ||
2071 | 972 | ) | ||
2072 | 973 | |||
2073 | 974 | if write_file: | ||
2074 | 975 | with open(fname, "wb") as f: | ||
2075 | 976 | f.write( | ||
2076 | 977 | ( | ||
2077 | 978 | "{}".format("#" if not repo.enabled else "") | ||
2078 | 979 | + "{} {}{} ".format(repo.repotype, options_str, repo.uri) | ||
2079 | 980 | + "{} {}\n".format(repo.release, " ".join(repo.groups)) | ||
2080 | 981 | ).encode("utf-8") | ||
2081 | 982 | ) | ||
2082 | 983 | |||
2083 | 984 | return repo | ||
2084 | 985 | |||
2085 | 986 | def disable(self) -> None: | ||
2086 | 987 | """Remove this repository from consideration. | ||
2087 | 988 | |||
2088 | 989 | Disable it instead of removing from the repository file. | ||
2089 | 990 | """ | ||
2090 | 991 | searcher = "{} {}{} {}".format( | ||
2091 | 992 | self.repotype, self.make_options_string(), self.uri, self.release | ||
2092 | 993 | ) | ||
2093 | 994 | for line in fileinput.input(self._filename, inplace=True): | ||
2094 | 995 | if re.match(r"^{}\s".format(re.escape(searcher)), line): | ||
2095 | 996 | print("# {}".format(line), end="") | ||
2096 | 997 | else: | ||
2097 | 998 | print(line, end="") | ||
2098 | 999 | |||
2099 | 1000 | def import_key(self, key: str) -> None: | ||
2100 | 1001 | """Import an ASCII Armor key. | ||
2101 | 1002 | |||
2102 | 1003 | A Radix64 format keyid is also supported for backwards | ||
2103 | 1004 | compatibility. In this case Ubuntu keyserver will be | ||
2104 | 1005 | queried for a key via HTTPS by its keyid. This method | ||
2105 | 1006 | is less preferrable because https proxy servers may | ||
2106 | 1007 | require traffic decryption which is equivalent to a | ||
2107 | 1008 | man-in-the-middle attack (a proxy server impersonates | ||
2108 | 1009 | keyserver TLS certificates and has to be explicitly | ||
2109 | 1010 | trusted by the system). | ||
2110 | 1011 | |||
2111 | 1012 | Args: | ||
2112 | 1013 | key: A GPG key in ASCII armor format, | ||
2113 | 1014 | including BEGIN and END markers or a keyid. | ||
2114 | 1015 | |||
2115 | 1016 | Raises: | ||
2116 | 1017 | GPGKeyError if the key could not be imported | ||
2117 | 1018 | """ | ||
2118 | 1019 | key = key.strip() | ||
2119 | 1020 | if "-" in key or "\n" in key: | ||
2120 | 1021 | # Send everything not obviously a keyid to GPG to import, as | ||
2121 | 1022 | # we trust its validation better than our own. eg. handling | ||
2122 | 1023 | # comments before the key. | ||
2123 | 1024 | logger.debug("PGP key found (looks like ASCII Armor format)") | ||
2124 | 1025 | if ( | ||
2125 | 1026 | "-----BEGIN PGP PUBLIC KEY BLOCK-----" in key | ||
2126 | 1027 | and "-----END PGP PUBLIC KEY BLOCK-----" in key | ||
2127 | 1028 | ): | ||
2128 | 1029 | logger.debug("Writing provided PGP key in the binary format") | ||
2129 | 1030 | key_bytes = key.encode("utf-8") | ||
2130 | 1031 | key_name = self._get_keyid_by_gpg_key(key_bytes) | ||
2131 | 1032 | key_gpg = self._dearmor_gpg_key(key_bytes) | ||
2132 | 1033 | self._gpg_key_filename = "/etc/apt/trusted.gpg.d/{}.gpg".format(key_name) | ||
2133 | 1034 | self._write_apt_gpg_keyfile(key_name=self._gpg_key_filename, key_material=key_gpg) | ||
2134 | 1035 | else: | ||
2135 | 1036 | raise GPGKeyError("ASCII armor markers missing from GPG key") | ||
2136 | 1037 | else: | ||
2137 | 1038 | logger.warning( | ||
2138 | 1039 | "PGP key found (looks like Radix64 format). " | ||
2139 | 1040 | "SECURELY importing PGP key from keyserver; " | ||
2140 | 1041 | "full key not provided." | ||
2141 | 1042 | ) | ||
2142 | 1043 | # as of bionic add-apt-repository uses curl with an HTTPS keyserver URL | ||
2143 | 1044 | # to retrieve GPG keys. `apt-key adv` command is deprecated as is | ||
2144 | 1045 | # apt-key in general as noted in its manpage. See lp:1433761 for more | ||
2145 | 1046 | # history. Instead, /etc/apt/trusted.gpg.d is used directly to drop | ||
2146 | 1047 | # gpg | ||
2147 | 1048 | key_asc = self._get_key_by_keyid(key) | ||
2148 | 1049 | # write the key in GPG format so that apt-key list shows it | ||
2149 | 1050 | key_gpg = self._dearmor_gpg_key(key_asc.encode("utf-8")) | ||
2150 | 1051 | self._gpg_key_filename = "/etc/apt/trusted.gpg.d/{}.gpg".format(key) | ||
2151 | 1052 | self._write_apt_gpg_keyfile(key_name=key, key_material=key_gpg) | ||
2152 | 1053 | |||
2153 | 1054 | @staticmethod | ||
2154 | 1055 | def _get_keyid_by_gpg_key(key_material: bytes) -> str: | ||
2155 | 1056 | """Get a GPG key fingerprint by GPG key material. | ||
2156 | 1057 | |||
2157 | 1058 | Gets a GPG key fingerprint (40-digit, 160-bit) by the ASCII armor-encoded | ||
2158 | 1059 | or binary GPG key material. Can be used, for example, to generate file | ||
2159 | 1060 | names for keys passed via charm options. | ||
2160 | 1061 | """ | ||
2161 | 1062 | # Use the same gpg command for both Xenial and Bionic | ||
2162 | 1063 | cmd = ["gpg", "--with-colons", "--with-fingerprint"] | ||
2163 | 1064 | ps = subprocess.run( | ||
2164 | 1065 | cmd, | ||
2165 | 1066 | stdout=PIPE, | ||
2166 | 1067 | stderr=PIPE, | ||
2167 | 1068 | input=key_material, | ||
2168 | 1069 | ) | ||
2169 | 1070 | out, err = ps.stdout.decode(), ps.stderr.decode() | ||
2170 | 1071 | if "gpg: no valid OpenPGP data found." in err: | ||
2171 | 1072 | raise GPGKeyError("Invalid GPG key material provided") | ||
2172 | 1073 | # from gnupg2 docs: fpr :: Fingerprint (fingerprint is in field 10) | ||
2173 | 1074 | return re.search(r"^fpr:{9}([0-9A-F]{40}):$", out, re.MULTILINE).group(1) | ||
2174 | 1075 | |||
2175 | 1076 | @staticmethod | ||
2176 | 1077 | def _get_key_by_keyid(keyid: str) -> str: | ||
2177 | 1078 | """Get a key via HTTPS from the Ubuntu keyserver. | ||
2178 | 1079 | |||
2179 | 1080 | Different key ID formats are supported by SKS keyservers (the longer ones | ||
2180 | 1081 | are more secure, see "dead beef attack" and https://evil32.com/). Since | ||
2181 | 1082 | HTTPS is used, if SSLBump-like HTTPS proxies are in place, they will | ||
2182 | 1083 | impersonate keyserver.ubuntu.com and generate a certificate with | ||
2183 | 1084 | keyserver.ubuntu.com in the CN field or in SubjAltName fields of a | ||
2184 | 1085 | certificate. If such proxy behavior is expected it is necessary to add the | ||
2185 | 1086 | CA certificate chain containing the intermediate CA of the SSLBump proxy to | ||
2186 | 1087 | every machine that this code runs on via ca-certs cloud-init directive (via | ||
2187 | 1088 | cloudinit-userdata model-config) or via other means (such as through a | ||
2188 | 1089 | custom charm option). Also note that DNS resolution for the hostname in a | ||
2189 | 1090 | URL is done at a proxy server - not at the client side. | ||
2190 | 1091 | 8-digit (32 bit) key ID | ||
2191 | 1092 | https://keyserver.ubuntu.com/pks/lookup?search=0x4652B4E6 | ||
2192 | 1093 | 16-digit (64 bit) key ID | ||
2193 | 1094 | https://keyserver.ubuntu.com/pks/lookup?search=0x6E85A86E4652B4E6 | ||
2194 | 1095 | 40-digit key ID: | ||
2195 | 1096 | https://keyserver.ubuntu.com/pks/lookup?search=0x35F77D63B5CEC106C577ED856E85A86E4652B4E6 | ||
2196 | 1097 | |||
2197 | 1098 | Args: | ||
2198 | 1099 | keyid: An 8, 16 or 40 hex digit keyid to find a key for | ||
2199 | 1100 | |||
2200 | 1101 | Returns: | ||
2201 | 1102 | A string contining key material for the specified GPG key id | ||
2202 | 1103 | |||
2203 | 1104 | |||
2204 | 1105 | Raises: | ||
2205 | 1106 | subprocess.CalledProcessError | ||
2206 | 1107 | """ | ||
2207 | 1108 | # options=mr - machine-readable output (disables html wrappers) | ||
2208 | 1109 | keyserver_url = ( | ||
2209 | 1110 | "https://keyserver.ubuntu.com" "/pks/lookup?op=get&options=mr&exact=on&search=0x{}" | ||
2210 | 1111 | ) | ||
2211 | 1112 | curl_cmd = ["curl", keyserver_url.format(keyid)] | ||
2212 | 1113 | # use proxy server settings in order to retrieve the key | ||
2213 | 1114 | return check_output(curl_cmd).decode() | ||
2214 | 1115 | |||
2215 | 1116 | @staticmethod | ||
2216 | 1117 | def _dearmor_gpg_key(key_asc: bytes) -> bytes: | ||
2217 | 1118 | """Converts a GPG key in the ASCII armor format to the binary format. | ||
2218 | 1119 | |||
2219 | 1120 | Args: | ||
2220 | 1121 | key_asc: A GPG key in ASCII armor format. | ||
2221 | 1122 | |||
2222 | 1123 | Returns: | ||
2223 | 1124 | A GPG key in binary format as a string | ||
2224 | 1125 | |||
2225 | 1126 | Raises: | ||
2226 | 1127 | GPGKeyError | ||
2227 | 1128 | """ | ||
2228 | 1129 | ps = subprocess.run(["gpg", "--dearmor"], stdout=PIPE, stderr=PIPE, input=key_asc) | ||
2229 | 1130 | out, err = ps.stdout, ps.stderr.decode() | ||
2230 | 1131 | if "gpg: no valid OpenPGP data found." in err: | ||
2231 | 1132 | raise GPGKeyError( | ||
2232 | 1133 | "Invalid GPG key material. Check your network setup" | ||
2233 | 1134 | " (MTU, routing, DNS) and/or proxy server settings" | ||
2234 | 1135 | " as well as destination keyserver status." | ||
2235 | 1136 | ) | ||
2236 | 1137 | else: | ||
2237 | 1138 | return out | ||
2238 | 1139 | |||
2239 | 1140 | @staticmethod | ||
2240 | 1141 | def _write_apt_gpg_keyfile(key_name: str, key_material: bytes) -> None: | ||
2241 | 1142 | """Writes GPG key material into a file at a provided path. | ||
2242 | 1143 | |||
2243 | 1144 | Args: | ||
2244 | 1145 | key_name: A key name to use for a key file (could be a fingerprint) | ||
2245 | 1146 | key_material: A GPG key material (binary) | ||
2246 | 1147 | """ | ||
2247 | 1148 | with open(key_name, "wb") as keyf: | ||
2248 | 1149 | keyf.write(key_material) | ||
2249 | 1150 | |||
2250 | 1151 | |||
2251 | 1152 | class RepositoryMapping(Mapping): | ||
2252 | 1153 | """An representation of known repositories. | ||
2253 | 1154 | |||
2254 | 1155 | Instantiation of `RepositoryMapping` will iterate through the | ||
2255 | 1156 | filesystem, parse out repository files in `/etc/apt/...`, and create | ||
2256 | 1157 | `DebianRepository` objects in this list. | ||
2257 | 1158 | |||
2258 | 1159 | Typical usage: | ||
2259 | 1160 | |||
2260 | 1161 | repositories = apt.RepositoryMapping() | ||
2261 | 1162 | repositories.add(DebianRepository( | ||
2262 | 1163 | enabled=True, repotype="deb", uri="https://example.com", release="focal", | ||
2263 | 1164 | groups=["universe"] | ||
2264 | 1165 | )) | ||
2265 | 1166 | """ | ||
2266 | 1167 | |||
2267 | 1168 | def __init__(self): | ||
2268 | 1169 | self._repository_map = {} | ||
2269 | 1170 | # Repositories that we're adding -- used to implement mode param | ||
2270 | 1171 | self.default_file = "/etc/apt/sources.list" | ||
2271 | 1172 | |||
2272 | 1173 | # read sources.list if it exists | ||
2273 | 1174 | if os.path.isfile(self.default_file): | ||
2274 | 1175 | self.load(self.default_file) | ||
2275 | 1176 | |||
2276 | 1177 | # read sources.list.d | ||
2277 | 1178 | for file in glob.iglob("/etc/apt/sources.list.d/*.list"): | ||
2278 | 1179 | self.load(file) | ||
2279 | 1180 | |||
2280 | 1181 | def __contains__(self, key: str) -> bool: | ||
2281 | 1182 | """Magic method for checking presence of repo in mapping.""" | ||
2282 | 1183 | return key in self._repository_map | ||
2283 | 1184 | |||
2284 | 1185 | def __len__(self) -> int: | ||
2285 | 1186 | """Return number of repositories in map.""" | ||
2286 | 1187 | return len(self._repository_map) | ||
2287 | 1188 | |||
2288 | 1189 | def __iter__(self) -> Iterable[DebianRepository]: | ||
2289 | 1190 | """Iterator magic method for RepositoryMapping.""" | ||
2290 | 1191 | return iter(self._repository_map.values()) | ||
2291 | 1192 | |||
2292 | 1193 | def __getitem__(self, repository_uri: str) -> DebianRepository: | ||
2293 | 1194 | """Return a given `DebianRepository`.""" | ||
2294 | 1195 | return self._repository_map[repository_uri] | ||
2295 | 1196 | |||
2296 | 1197 | def __setitem__(self, repository_uri: str, repository: DebianRepository) -> None: | ||
2297 | 1198 | """Add a `DebianRepository` to the cache.""" | ||
2298 | 1199 | self._repository_map[repository_uri] = repository | ||
2299 | 1200 | |||
2300 | 1201 | def load(self, filename: str): | ||
2301 | 1202 | """Load a repository source file into the cache. | ||
2302 | 1203 | |||
2303 | 1204 | Args: | ||
2304 | 1205 | filename: the path to the repository file | ||
2305 | 1206 | """ | ||
2306 | 1207 | parsed = [] | ||
2307 | 1208 | skipped = [] | ||
2308 | 1209 | with open(filename, "r") as f: | ||
2309 | 1210 | for n, line in enumerate(f): | ||
2310 | 1211 | try: | ||
2311 | 1212 | repo = self._parse(line, filename) | ||
2312 | 1213 | except InvalidSourceError: | ||
2313 | 1214 | skipped.append(n) | ||
2314 | 1215 | else: | ||
2315 | 1216 | repo_identifier = "{}-{}-{}".format(repo.repotype, repo.uri, repo.release) | ||
2316 | 1217 | self._repository_map[repo_identifier] = repo | ||
2317 | 1218 | parsed.append(n) | ||
2318 | 1219 | logger.debug("parsed repo: '%s'", repo_identifier) | ||
2319 | 1220 | |||
2320 | 1221 | if skipped: | ||
2321 | 1222 | skip_list = ", ".join(str(s) for s in skipped) | ||
2322 | 1223 | logger.debug("skipped the following lines in file '%s': %s", filename, skip_list) | ||
2323 | 1224 | |||
2324 | 1225 | if parsed: | ||
2325 | 1226 | logger.info("parsed %d apt package repositories", len(parsed)) | ||
2326 | 1227 | else: | ||
2327 | 1228 | raise InvalidSourceError("all repository lines in '{}' were invalid!".format(filename)) | ||
2328 | 1229 | |||
2329 | 1230 | @staticmethod | ||
2330 | 1231 | def _parse(line: str, filename: str) -> DebianRepository: | ||
2331 | 1232 | """Parse a line in a sources.list file. | ||
2332 | 1233 | |||
2333 | 1234 | Args: | ||
2334 | 1235 | line: a single line from `load` to parse | ||
2335 | 1236 | filename: the filename being read | ||
2336 | 1237 | |||
2337 | 1238 | Raises: | ||
2338 | 1239 | InvalidSourceError if the source type is unknown | ||
2339 | 1240 | """ | ||
2340 | 1241 | enabled = True | ||
2341 | 1242 | repotype = uri = release = gpg_key = "" | ||
2342 | 1243 | options = {} | ||
2343 | 1244 | groups = [] | ||
2344 | 1245 | |||
2345 | 1246 | line = line.strip() | ||
2346 | 1247 | if line.startswith("#"): | ||
2347 | 1248 | enabled = False | ||
2348 | 1249 | line = line[1:] | ||
2349 | 1250 | |||
2350 | 1251 | # Check for "#" in the line and treat a part after it as a comment then strip it off. | ||
2351 | 1252 | i = line.find("#") | ||
2352 | 1253 | if i > 0: | ||
2353 | 1254 | line = line[:i] | ||
2354 | 1255 | |||
2355 | 1256 | # Split a source into substrings to initialize a new repo. | ||
2356 | 1257 | source = line.strip() | ||
2357 | 1258 | if source: | ||
2358 | 1259 | # Match any repo options, and get a dict representation. | ||
2359 | 1260 | for v in re.findall(OPTIONS_MATCHER, source): | ||
2360 | 1261 | opts = dict(o.split("=") for o in v.strip("[]").split()) | ||
2361 | 1262 | # Extract the 'signed-by' option for the gpg_key | ||
2362 | 1263 | gpg_key = opts.pop("signed-by", "") | ||
2363 | 1264 | options = opts | ||
2364 | 1265 | |||
2365 | 1266 | # Remove any options from the source string and split the string into chunks | ||
2366 | 1267 | source = re.sub(OPTIONS_MATCHER, "", source) | ||
2367 | 1268 | chunks = source.split() | ||
2368 | 1269 | |||
2369 | 1270 | # Check we've got a valid list of chunks | ||
2370 | 1271 | if len(chunks) < 3 or chunks[0] not in VALID_SOURCE_TYPES: | ||
2371 | 1272 | raise InvalidSourceError("An invalid sources line was found in %s!", filename) | ||
2372 | 1273 | |||
2373 | 1274 | repotype = chunks[0] | ||
2374 | 1275 | uri = chunks[1] | ||
2375 | 1276 | release = chunks[2] | ||
2376 | 1277 | groups = chunks[3:] | ||
2377 | 1278 | |||
2378 | 1279 | return DebianRepository( | ||
2379 | 1280 | enabled, repotype, uri, release, groups, filename, gpg_key, options | ||
2380 | 1281 | ) | ||
2381 | 1282 | else: | ||
2382 | 1283 | raise InvalidSourceError("An invalid sources line was found in %s!", filename) | ||
2383 | 1284 | |||
2384 | 1285 | def add(self, repo: DebianRepository, default_filename: Optional[bool] = False) -> None: | ||
2385 | 1286 | """Add a new repository to the system. | ||
2386 | 1287 | |||
2387 | 1288 | Args: | ||
2388 | 1289 | repo: a `DebianRepository` object | ||
2389 | 1290 | default_filename: an (Optional) filename if the default is not desirable | ||
2390 | 1291 | """ | ||
2391 | 1292 | new_filename = "{}-{}.list".format( | ||
2392 | 1293 | DebianRepository.prefix_from_uri(repo.uri), repo.release.replace("/", "-") | ||
2393 | 1294 | ) | ||
2394 | 1295 | |||
2395 | 1296 | fname = repo.filename or new_filename | ||
2396 | 1297 | |||
2397 | 1298 | options = repo.options if repo.options else {} | ||
2398 | 1299 | if repo.gpg_key: | ||
2399 | 1300 | options["signed-by"] = repo.gpg_key | ||
2400 | 1301 | |||
2401 | 1302 | with open(fname, "wb") as f: | ||
2402 | 1303 | f.write( | ||
2403 | 1304 | ( | ||
2404 | 1305 | "{}".format("#" if not repo.enabled else "") | ||
2405 | 1306 | + "{} {}{} ".format(repo.repotype, repo.make_options_string(), repo.uri) | ||
2406 | 1307 | + "{} {}\n".format(repo.release, " ".join(repo.groups)) | ||
2407 | 1308 | ).encode("utf-8") | ||
2408 | 1309 | ) | ||
2409 | 1310 | |||
2410 | 1311 | self._repository_map["{}-{}-{}".format(repo.repotype, repo.uri, repo.release)] = repo | ||
2411 | 1312 | |||
2412 | 1313 | def disable(self, repo: DebianRepository) -> None: | ||
2413 | 1314 | """Remove a repository. Disable by default. | ||
2414 | 1315 | |||
2415 | 1316 | Args: | ||
2416 | 1317 | repo: a `DebianRepository` to disable | ||
2417 | 1318 | """ | ||
2418 | 1319 | searcher = "{} {}{} {}".format( | ||
2419 | 1320 | repo.repotype, repo.make_options_string(), repo.uri, repo.release | ||
2420 | 1321 | ) | ||
2421 | 1322 | |||
2422 | 1323 | for line in fileinput.input(repo.filename, inplace=True): | ||
2423 | 1324 | if re.match(r"^{}\s".format(re.escape(searcher)), line): | ||
2424 | 1325 | print("# {}".format(line), end="") | ||
2425 | 1326 | else: | ||
2426 | 1327 | print(line, end="") | ||
2427 | 1328 | |||
2428 | 1329 | self._repository_map["{}-{}-{}".format(repo.repotype, repo.uri, repo.release)] = repo | ||
2429 | diff --git a/metadata.yaml b/metadata.yaml | |||
2430 | index de1439f..5becf33 100644 | |||
2431 | --- a/metadata.yaml | |||
2432 | +++ b/metadata.yaml | |||
2433 | @@ -1,23 +1,14 @@ | |||
2442 | 1 | # Copyright 2022 Barry Price | 1 | name: charm-tor-hidden-service |
2443 | 2 | # See LICENSE file for licensing details. | 2 | display-name: Tor Hidden Service Charmed Operator |
2444 | 3 | 3 | summary: Tor Hidden Service Charmed Operator | |
2437 | 4 | # For a complete list of supported options, see: | ||
2438 | 5 | # https://juju.is/docs/sdk/metadata-reference | ||
2439 | 6 | name: charm-tor | ||
2440 | 7 | display-name: | | ||
2441 | 8 | TEMPLATE-TODO: fill out a display name for the Charmcraft store | ||
2445 | 9 | description: | | 4 | description: | |
2454 | 10 | TEMPLATE-TODO: fill out the charm's description | 5 | Tor is free software and an open network that helps you defend against |
2455 | 11 | summary: | | 6 | traffic analysis, a form of network surveillance that threatens personal |
2456 | 12 | TEMPLATE-TODO: fill out the charm's summary | 7 | freedom and privacy, confidential business activities and relationships, and |
2457 | 13 | 8 | state security. | |
2458 | 14 | # TEMPLATE-TODO: replace with containers for your workload (delete for non-k8s) | 9 | requires: |
2459 | 15 | containers: | 10 | reverseproxy: |
2460 | 16 | httpbin: | 11 | interface: http |
2461 | 17 | resource: httpbin-image | 12 | series: |
2462 | 13 | - jammy | ||
2463 | 18 | 14 | ||
2464 | 19 | # TEMPLATE-TODO: each container defined above must specify an oci-image resource | ||
2465 | 20 | resources: | ||
2466 | 21 | httpbin-image: | ||
2467 | 22 | type: oci-image | ||
2468 | 23 | description: OCI image for httpbin (kennethreitz/httpbin) | ||
2469 | diff --git a/pyproject.toml b/pyproject.toml | |||
2470 | 24 | new file mode 100644 | 15 | new file mode 100644 |
2471 | index 0000000..177269a | |||
2472 | --- /dev/null | |||
2473 | +++ b/pyproject.toml | |||
2474 | @@ -0,0 +1,38 @@ | |||
2475 | 1 | # Copyright 2022 Canonical Ltd. | ||
2476 | 2 | # See LICENSE file for licensing details. | ||
2477 | 3 | |||
2478 | 4 | # Testing tools configuration | ||
2479 | 5 | [tool.coverage.run] | ||
2480 | 6 | branch = true | ||
2481 | 7 | |||
2482 | 8 | [tool.coverage.report] | ||
2483 | 9 | show_missing = true | ||
2484 | 10 | |||
2485 | 11 | [tool.pytest.ini_options] | ||
2486 | 12 | minversion = "6.0" | ||
2487 | 13 | log_cli_level = "INFO" | ||
2488 | 14 | |||
2489 | 15 | # Formatting tools configuration | ||
2490 | 16 | [tool.black] | ||
2491 | 17 | line-length = 99 | ||
2492 | 18 | target-version = ["py310"] | ||
2493 | 19 | |||
2494 | 20 | [tool.isort] | ||
2495 | 21 | profile = "black" | ||
2496 | 22 | |||
2497 | 23 | # Linting tools configuration | ||
2498 | 24 | [tool.flake8] | ||
2499 | 25 | max-line-length = 99 | ||
2500 | 26 | max-doc-length = 99 | ||
2501 | 27 | max-complexity = 10 | ||
2502 | 28 | exclude = [".git", "__pycache__", ".tox", "build", "dist", "*.egg_info", "venv"] | ||
2503 | 29 | select = ["E", "W", "F", "C", "N", "R", "D", "H"] | ||
2504 | 30 | # Ignore D107 Missing docstring in __init__ | ||
2505 | 31 | ignore = ["D107"] | ||
2506 | 32 | # D100, D101, D102, D103: Ignore missing docstrings in tests | ||
2507 | 33 | per-file-ignores = ["tests/*:D100,D101,D102,D103,D104"] | ||
2508 | 34 | docstring-convention = "google" | ||
2509 | 35 | # Check for properly formatted copyright header in each file | ||
2510 | 36 | copyright-check = "True" | ||
2511 | 37 | copyright-author = "Canonical Ltd." | ||
2512 | 38 | copyright-regexp = "Copyright\\s\\d{4}([-,]\\d{4})*\\s+%(author)s" | ||
2513 | diff --git a/src/charm.py b/src/charm.py | |||
2514 | index 2cac651..73b10fa 100755 | |||
2515 | --- a/src/charm.py | |||
2516 | +++ b/src/charm.py | |||
2517 | @@ -1,104 +1,206 @@ | |||
2518 | 1 | #!/usr/bin/env python3 | 1 | #!/usr/bin/env python3 |
2520 | 2 | # Copyright 2022 Barry Price | 2 | # Copyright 2022 Canonical Ltd. |
2521 | 3 | # See LICENSE file for licensing details. | 3 | # See LICENSE file for licensing details. |
2522 | 4 | # | ||
2523 | 5 | # Learn more at: https://juju.is/docs/sdk | ||
2524 | 6 | 4 | ||
2532 | 7 | """Charm the service. | 5 | """Charmed Operator to provide Tor hidden services.""" |
2526 | 8 | |||
2527 | 9 | Refer to the following post for a quick-start guide that will help you | ||
2528 | 10 | develop a new k8s charm using the Operator Framework: | ||
2529 | 11 | |||
2530 | 12 | https://discourse.charmhub.io/t/4208 | ||
2531 | 13 | """ | ||
2533 | 14 | 6 | ||
2534 | 15 | import logging | 7 | import logging |
2537 | 16 | 8 | import os | |
2538 | 17 | from ops.charm import CharmBase | 9 | import shutil |
2539 | 10 | import subprocess | ||
2540 | 11 | import urllib.request | ||
2541 | 12 | |||
2542 | 13 | import jinja2 | ||
2543 | 14 | |||
2544 | 15 | from charms.operator_libs_linux.v0 import apt | ||
2545 | 16 | from ops.charm import ( | ||
2546 | 17 | CharmBase, | ||
2547 | 18 | RelationChangedEvent, | ||
2548 | 19 | ) | ||
2549 | 18 | from ops.framework import StoredState | 20 | from ops.framework import StoredState |
2550 | 19 | from ops.main import main | 21 | from ops.main import main |
2552 | 20 | from ops.model import ActiveStatus | 22 | from ops.model import ( |
2553 | 23 | BlockedStatus, | ||
2554 | 24 | Unit, | ||
2555 | 25 | ) | ||
2556 | 21 | 26 | ||
2557 | 22 | logger = logging.getLogger(__name__) | 27 | logger = logging.getLogger(__name__) |
2558 | 23 | 28 | ||
2559 | 24 | 29 | ||
2562 | 25 | class CharmTorCharm(CharmBase): | 30 | def get_series(): |
2563 | 26 | """Charm the service.""" | 31 | """Return the installed Ubuntu series (e.g. "jammy").""" |
2564 | 32 | return subprocess.check_output(["lsb_release", "-sc"]).decode('utf-8').strip() | ||
2565 | 27 | 33 | ||
2566 | 28 | _stored = StoredState() | ||
2567 | 29 | 34 | ||
2608 | 30 | def __init__(self, *args): | 35 | def install_tor_repo(): |
2609 | 31 | super().__init__(*args) | 36 | """Authenticate, install and pin the tor package to the torproject.org repo.""" |
2610 | 32 | self.framework.observe(self.on.httpbin_pebble_ready, self._on_httpbin_pebble_ready) | 37 | # Installation is based on Tor installation instructions for Debian/Ubuntu: |
2611 | 33 | self.framework.observe(self.on.config_changed, self._on_config_changed) | 38 | # https://support.torproject.org/apt/tor-deb-repo/ |
2612 | 34 | self.framework.observe(self.on.fortune_action, self._on_fortune_action) | 39 | keyring_path = "/usr/share/keyrings/tor-archive-keyring.gpg" |
2613 | 35 | self._stored.set_default(things=[]) | 40 | base_url = "https://deb.torproject.org/torproject.org" |
2574 | 36 | |||
2575 | 37 | def _on_httpbin_pebble_ready(self, event): | ||
2576 | 38 | """Define and start a workload using the Pebble API. | ||
2577 | 39 | |||
2578 | 40 | TEMPLATE-TODO: change this example to suit your needs. | ||
2579 | 41 | You'll need to specify the right entrypoint and environment | ||
2580 | 42 | configuration for your specific workload. Tip: you can see the | ||
2581 | 43 | standard entrypoint of an existing container using docker inspect | ||
2582 | 44 | |||
2583 | 45 | Learn more about Pebble layers at https://github.com/canonical/pebble | ||
2584 | 46 | """ | ||
2585 | 47 | # Get a reference the container attribute on the PebbleReadyEvent | ||
2586 | 48 | container = event.workload | ||
2587 | 49 | # Define an initial Pebble layer configuration | ||
2588 | 50 | pebble_layer = { | ||
2589 | 51 | "summary": "httpbin layer", | ||
2590 | 52 | "description": "pebble config layer for httpbin", | ||
2591 | 53 | "services": { | ||
2592 | 54 | "httpbin": { | ||
2593 | 55 | "override": "replace", | ||
2594 | 56 | "summary": "httpbin", | ||
2595 | 57 | "command": "gunicorn -b 0.0.0.0:80 httpbin:app -k gevent", | ||
2596 | 58 | "startup": "enabled", | ||
2597 | 59 | "environment": {"thing": self.model.config["thing"]}, | ||
2598 | 60 | } | ||
2599 | 61 | }, | ||
2600 | 62 | } | ||
2601 | 63 | # Add initial Pebble config layer using the Pebble API | ||
2602 | 64 | container.add_layer("httpbin", pebble_layer, combine=True) | ||
2603 | 65 | # Autostart any services that were defined with startup: enabled | ||
2604 | 66 | container.autostart() | ||
2605 | 67 | # Learn more about statuses in the SDK docs: | ||
2606 | 68 | # https://juju.is/docs/sdk/constructs#heading--statuses | ||
2607 | 69 | self.unit.status = ActiveStatus() | ||
2614 | 70 | 41 | ||
2617 | 71 | def _on_config_changed(self, _): | 42 | # retrieve the signing key |
2618 | 72 | """Just an example to show how to deal with changed configuration. | 43 | keyring_url = "{}/A3C4F0F979CAA22CDBA8F512EE8CBC9E886DDD89.asc".format(base_url) |
2619 | 44 | with urllib.request.urlopen(keyring_url) as f: | ||
2620 | 45 | keyring = f.read() | ||
2621 | 46 | |||
2622 | 47 | with open(keyring_path, "wb") as f: | ||
2623 | 48 | f.write(keyring) | ||
2624 | 49 | |||
2625 | 50 | # identify our running series | ||
2626 | 51 | series = get_series() | ||
2627 | 52 | |||
2628 | 53 | # build .list file | ||
2629 | 54 | tor_list = "deb [signed-by={}] {} {} main\n".format(keyring_path, base_url, series) | ||
2630 | 55 | tor_list += "deb-src [signed-by={}] {} {} main\n".format(keyring_path, base_url, series) | ||
2631 | 73 | 56 | ||
2636 | 74 | TEMPLATE-TODO: change this example to suit your needs. | 57 | # write .list file |
2637 | 75 | If you don't need to handle config, you can remove this method, | 58 | with open("/etc/apt/sources.list.d/tor.list", "wb") as f: |
2638 | 76 | the hook created in __init__.py for it, the corresponding test, | 59 | f.write(tor_list.encode('utf-8')) |
2635 | 77 | and the config.py file. | ||
2639 | 78 | 60 | ||
2646 | 79 | Learn more about config at https://juju.is/docs/sdk/config | 61 | # pin the tor package to this repo |
2647 | 80 | """ | 62 | pin_config = "Package: tor\n" |
2648 | 81 | current = self.config["thing"] | 63 | pin_config += "Pin: release c=main\n" |
2649 | 82 | if current not in self._stored.things: | 64 | pin_config += "Pin-Priority: 900\n\n" |
2644 | 83 | logger.debug("found a new thing: %r", current) | ||
2645 | 84 | self._stored.things.append(current) | ||
2650 | 85 | 65 | ||
2653 | 86 | def _on_fortune_action(self, event): | 66 | # don't use the universe version |
2654 | 87 | """Just an example to show how to receive actions. | 67 | pin_config += "Package: tor\n" |
2655 | 68 | pin_config += "Pin: release c=universe\n" | ||
2656 | 69 | pin_config += "Pin-Priority: 1\n\n" | ||
2657 | 88 | 70 | ||
2662 | 89 | TEMPLATE-TODO: change this example to suit your needs. | 71 | with open("/etc/apt/preferences.d/tor-pin", "wb") as f: |
2663 | 90 | If you don't need to handle actions, you can remove this method, | 72 | f.write(pin_config.encode('utf-8')) |
2660 | 91 | the hook created in __init__.py for it, the corresponding test, | ||
2661 | 92 | and the actions.py file. | ||
2664 | 93 | 73 | ||
2672 | 94 | Learn more about actions at https://juju.is/docs/sdk/actions | 74 | |
2673 | 95 | """ | 75 | def remove_tor_repo(): |
2674 | 96 | fail = event.params["fail"] | 76 | """Remove and unpin the torproject.org repo.""" |
2675 | 97 | if fail: | 77 | paths = ( |
2676 | 98 | event.fail(fail) | 78 | "/etc/apt/sources.list.d/tor.list", |
2677 | 99 | else: | 79 | "/etc/apt/preferences.d/tor-pin", |
2678 | 100 | event.set_results({"fortune": "A bug in the code is worth two in the documentation."}) | 80 | "/usr/share/keyrings/tor-archive-keyring.gpg", |
2679 | 81 | ) | ||
2680 | 82 | for p in paths: | ||
2681 | 83 | if os.path.isfile(p): | ||
2682 | 84 | os.unlink(p) | ||
2683 | 85 | |||
2684 | 86 | |||
2685 | 87 | class TorCharm(CharmBase): | ||
2686 | 88 | """Charm the tor service.""" | ||
2687 | 89 | |||
2688 | 90 | _state = StoredState() | ||
2689 | 91 | |||
2690 | 92 | def __init__(self, *args): | ||
2691 | 93 | super().__init__(*args) | ||
2692 | 94 | self._state.set_default( | ||
2693 | 95 | need_package_apt_transport_https=True, | ||
2694 | 96 | need_package_gpg=True, | ||
2695 | 97 | need_package_tor=True, | ||
2696 | 98 | ) | ||
2697 | 99 | self.framework.observe(self.on.config_changed, self._on_config_changed) | ||
2698 | 100 | self.framework.observe( | ||
2699 | 101 | self.on.reverseproxy_relation_changed, self._on_reverseproxy_relation_changed | ||
2700 | 102 | ) | ||
2701 | 103 | |||
2702 | 104 | def _on_config_changed(self, _): | ||
2703 | 105 | """Handle config changes.""" | ||
2704 | 106 | # ensure required packages are installed | ||
2705 | 107 | self._ensure_apt_transport_https() | ||
2706 | 108 | self._ensure_gpg() | ||
2707 | 109 | self._ensure_tor() | ||
2708 | 110 | |||
2709 | 111 | def _ensure_apt_transport_https(self): | ||
2710 | 112 | if self._state.need_package_apt_transport_https: | ||
2711 | 113 | logger.info("Ensuring apt-transport-https is installed") | ||
2712 | 114 | apt.add_package("apt-transport-https", update_cache=True) | ||
2713 | 115 | self._state.need_package_apt_transport_https = False | ||
2714 | 116 | |||
2715 | 117 | def _ensure_gpg(self): | ||
2716 | 118 | if self._state.need_package_gpg: | ||
2717 | 119 | logger.info("Ensuring gpg is installed") | ||
2718 | 120 | apt.add_package("gpg", update_cache=True) | ||
2719 | 121 | self._state.need_package_gpg = False | ||
2720 | 122 | |||
2721 | 123 | def _ensure_tor(self): | ||
2722 | 124 | if self._state.need_package_tor: | ||
2723 | 125 | tor_source = self.model.config['tor_source'] | ||
2724 | 126 | if tor_source == 'ubuntu': | ||
2725 | 127 | logger.info("Source is ubuntu, ensuring torproject repo is not set up") | ||
2726 | 128 | remove_tor_repo() | ||
2727 | 129 | elif tor_source == 'torproject': | ||
2728 | 130 | logger.info("Source is torproject, ensuring torproject repo is set up") | ||
2729 | 131 | install_tor_repo() | ||
2730 | 132 | else: | ||
2731 | 133 | err = "Unexpected tor_source value: {}".format(tor_source) | ||
2732 | 134 | logger.error(err) | ||
2733 | 135 | self.unit.status = BlockedStatus(err) | ||
2734 | 136 | logger.info("Ensuring tor is installed") | ||
2735 | 137 | apt.add_package("tor", update_cache=True) | ||
2736 | 138 | |||
2737 | 139 | def _tor_setup(self, services): | ||
2738 | 140 | cfg = {} | ||
2739 | 141 | cfg['socks5_port'] = self.model.config['socks5_port'] | ||
2740 | 142 | root_dir = '/var/lib/tor' | ||
2741 | 143 | for k, v in services.items(): | ||
2742 | 144 | logger.info('Got service name {} with value {}'.format(k, v)) | ||
2743 | 145 | service_dir = '{}/{}'.format(root_dir, v.get('servername')) | ||
2744 | 146 | if not os.path.isdir(service_dir): | ||
2745 | 147 | subprocess.check_call( | ||
2746 | 148 | ['install', '-d', service_dir, '-o', 'debian-tor', '-m', '700'] | ||
2747 | 149 | ) | ||
2748 | 150 | |||
2749 | 151 | for file in os.listdir(root_dir): | ||
2750 | 152 | if os.path.isdir(file): | ||
2751 | 153 | basename = os.path.basename(file) | ||
2752 | 154 | for k, v in services.items(): | ||
2753 | 155 | if k.get('servername') == basename: | ||
2754 | 156 | # keep this configured directory | ||
2755 | 157 | pass | ||
2756 | 158 | else: | ||
2757 | 159 | logger.info('Removing unconfigured site {}'.format(basename)) | ||
2758 | 160 | shutil.rmtree(file) | ||
2759 | 161 | |||
2760 | 162 | # NOTE: Once the below closed issue is actually resolved[1], this function | ||
2761 | 163 | # should be replaced with a built-in one in Operator Framework. | ||
2762 | 164 | # [1]: https://github.com/canonical/operator/issues/228 | ||
2763 | 165 | |||
2764 | 166 | list_services = [] | ||
2765 | 167 | for k, v in services.items(): | ||
2766 | 168 | list_services.append(v) | ||
2767 | 169 | |||
2768 | 170 | templates = jinja2.Environment( | ||
2769 | 171 | loader=jinja2.FileSystemLoader(self.charm_dir / "templates"), | ||
2770 | 172 | ) | ||
2771 | 173 | template = templates.get_template("torrc") | ||
2772 | 174 | torrc = template.render({'cfg': cfg, 'services': list_services}) | ||
2773 | 175 | |||
2774 | 176 | torrc_filename = '/etc/tor/torrc' | ||
2775 | 177 | |||
2776 | 178 | with open(torrc_filename, 'wb') as f: | ||
2777 | 179 | f.write(torrc.encode('utf-8')) | ||
2778 | 180 | |||
2779 | 181 | def _on_reverseproxy_relation_changed(self, event: RelationChangedEvent): | ||
2780 | 182 | unit_data = event.relation.data | ||
2781 | 183 | logger.info(unit_data) | ||
2782 | 184 | services = {} | ||
2783 | 185 | for unit in unit_data: | ||
2784 | 186 | if not isinstance(unit, Unit): | ||
2785 | 187 | logger.info("Skipping data of type {}".format(type(unit))) | ||
2786 | 188 | continue | ||
2787 | 189 | if unit.name == self.unit.name: | ||
2788 | 190 | logger.info("Skipping our own unit ({})".format(unit.name)) | ||
2789 | 191 | continue | ||
2790 | 192 | logger.info("Found related unit {}".format(unit)) | ||
2791 | 193 | |||
2792 | 194 | services.update({ | ||
2793 | 195 | unit.name: { | ||
2794 | 196 | 'hostname': unit_data[unit].get('hostname'), | ||
2795 | 197 | 'private_address': unit_data[unit].get('private-address'), | ||
2796 | 198 | 'port': unit_data[unit].get('port'), | ||
2797 | 199 | 'servername': unit_data[unit].get('servername'), | ||
2798 | 200 | } | ||
2799 | 201 | }) | ||
2800 | 202 | self._tor_setup(services) | ||
2801 | 101 | 203 | ||
2802 | 102 | 204 | ||
2803 | 103 | if __name__ == "__main__": | 205 | if __name__ == "__main__": |
2805 | 104 | main(CharmTorCharm) | 206 | main(TorCharm) |
2806 | diff --git a/templates/torrc b/templates/torrc | |||
2807 | 105 | new file mode 100644 | 207 | new file mode 100644 |
2808 | index 0000000..d709005 | |||
2809 | --- /dev/null | |||
2810 | +++ b/templates/torrc | |||
2811 | @@ -0,0 +1,12 @@ | |||
2812 | 1 | # torrc generated by Juju. | ||
2813 | 2 | # Do not edit, changes are subject to being overwritten. | ||
2814 | 3 | |||
2815 | 4 | SocksPort 127.0.0.1:{{ cfg.socks5_port }} | ||
2816 | 5 | |||
2817 | 6 | {% for service in services %} | ||
2818 | 7 | HiddenServiceDir /var/lib/tor/{{ service.servername }}/ | ||
2819 | 8 | # service.hostname is {{ service.hostname }} | ||
2820 | 9 | # service.private-address is {{ service.private_address }} | ||
2821 | 10 | HiddenServicePort {{ service.port }} {{ service.private_address }}:{{ service.port }} | ||
2822 | 11 | |||
2823 | 12 | {% endfor %} | ||
2824 | diff --git a/tests/__init__.py b/tests/__init__.py | |||
2825 | index e163492..0c77dd5 100644 | |||
2826 | --- a/tests/__init__.py | |||
2827 | +++ b/tests/__init__.py | |||
2828 | @@ -1,2 +1,6 @@ | |||
2829 | 1 | # Copyright 2022 Canonical Ltd. | ||
2830 | 2 | # See LICENSE file for licensing details. | ||
2831 | 3 | |||
2832 | 1 | import ops.testing | 4 | import ops.testing |
2833 | 5 | |||
2834 | 2 | ops.testing.SIMULATE_CAN_CONNECT = True | 6 | ops.testing.SIMULATE_CAN_CONNECT = True |
2835 | diff --git a/tests/test_charm.py b/tests/test_charm.py | |||
2836 | index 0830b8d..c7e4d40 100644 | |||
2837 | --- a/tests/test_charm.py | |||
2838 | +++ b/tests/test_charm.py | |||
2839 | @@ -1,15 +1,12 @@ | |||
2841 | 1 | # Copyright 2022 Barry Price | 1 | # Copyright 2022 Canonical Ltd. |
2842 | 2 | # See LICENSE file for licensing details. | 2 | # See LICENSE file for licensing details. |
2843 | 3 | # | ||
2844 | 4 | # Learn more about testing at: https://juju.is/docs/sdk/testing | ||
2845 | 5 | 3 | ||
2846 | 6 | import unittest | 4 | import unittest |
2847 | 7 | from unittest.mock import Mock | ||
2848 | 8 | 5 | ||
2849 | 9 | from charm import CharmTorCharm | ||
2850 | 10 | from ops.model import ActiveStatus | ||
2851 | 11 | from ops.testing import Harness | 6 | from ops.testing import Harness |
2852 | 12 | 7 | ||
2853 | 8 | from charm import CharmTorCharm | ||
2854 | 9 | |||
2855 | 13 | 10 | ||
2856 | 14 | class TestCharm(unittest.TestCase): | 11 | class TestCharm(unittest.TestCase): |
2857 | 15 | def setUp(self): | 12 | def setUp(self): |
2858 | @@ -19,50 +16,5 @@ class TestCharm(unittest.TestCase): | |||
2859 | 19 | 16 | ||
2860 | 20 | def test_config_changed(self): | 17 | def test_config_changed(self): |
2861 | 21 | self.assertEqual(list(self.harness.charm._stored.things), []) | 18 | self.assertEqual(list(self.harness.charm._stored.things), []) |
2909 | 22 | self.harness.update_config({"thing": "foo"}) | 19 | self.harness.update_config({"tor-mode": "hidden"}) |
2910 | 23 | self.assertEqual(list(self.harness.charm._stored.things), ["foo"]) | 20 | self.assertEqual(list(self.harness.charm._stored.things), ["hidden"]) |
2864 | 24 | |||
2865 | 25 | def test_action(self): | ||
2866 | 26 | # the harness doesn't (yet!) help much with actions themselves | ||
2867 | 27 | action_event = Mock(params={"fail": ""}) | ||
2868 | 28 | self.harness.charm._on_fortune_action(action_event) | ||
2869 | 29 | |||
2870 | 30 | self.assertTrue(action_event.set_results.called) | ||
2871 | 31 | |||
2872 | 32 | def test_action_fail(self): | ||
2873 | 33 | action_event = Mock(params={"fail": "fail this"}) | ||
2874 | 34 | self.harness.charm._on_fortune_action(action_event) | ||
2875 | 35 | |||
2876 | 36 | self.assertEqual(action_event.fail.call_args, [("fail this",)]) | ||
2877 | 37 | |||
2878 | 38 | def test_httpbin_pebble_ready(self): | ||
2879 | 39 | # Simulate making the Pebble socket available | ||
2880 | 40 | self.harness.set_can_connect("httpbin", True) | ||
2881 | 41 | # Check the initial Pebble plan is empty | ||
2882 | 42 | initial_plan = self.harness.get_container_pebble_plan("httpbin") | ||
2883 | 43 | self.assertEqual(initial_plan.to_yaml(), "{}\n") | ||
2884 | 44 | # Expected plan after Pebble ready with default config | ||
2885 | 45 | expected_plan = { | ||
2886 | 46 | "services": { | ||
2887 | 47 | "httpbin": { | ||
2888 | 48 | "override": "replace", | ||
2889 | 49 | "summary": "httpbin", | ||
2890 | 50 | "command": "gunicorn -b 0.0.0.0:80 httpbin:app -k gevent", | ||
2891 | 51 | "startup": "enabled", | ||
2892 | 52 | "environment": {"thing": "🎁"}, | ||
2893 | 53 | } | ||
2894 | 54 | }, | ||
2895 | 55 | } | ||
2896 | 56 | # Get the httpbin container from the model | ||
2897 | 57 | container = self.harness.model.unit.get_container("httpbin") | ||
2898 | 58 | # Emit the PebbleReadyEvent carrying the httpbin container | ||
2899 | 59 | self.harness.charm.on.httpbin_pebble_ready.emit(container) | ||
2900 | 60 | # Get the plan now we've run PebbleReady | ||
2901 | 61 | updated_plan = self.harness.get_container_pebble_plan("httpbin").to_dict() | ||
2902 | 62 | # Check we've got the plan we expected | ||
2903 | 63 | self.assertEqual(expected_plan, updated_plan) | ||
2904 | 64 | # Check the service was started | ||
2905 | 65 | service = self.harness.model.unit.get_container("httpbin").get_service("httpbin") | ||
2906 | 66 | self.assertTrue(service.is_running()) | ||
2907 | 67 | # Ensure we set an ActiveStatus with no message | ||
2908 | 68 | self.assertEqual(self.harness.model.unit.status, ActiveStatus()) | ||
2911 | diff --git a/tox.ini b/tox.ini | |||
2912 | 69 | new file mode 100644 | 21 | new file mode 100644 |
2913 | index 0000000..bca0088 | |||
2914 | --- /dev/null | |||
2915 | +++ b/tox.ini | |||
2916 | @@ -0,0 +1,78 @@ | |||
2917 | 1 | # Copyright 2022 Canonical Ltd. | ||
2918 | 2 | # See LICENSE file for licensing details. | ||
2919 | 3 | |||
2920 | 4 | [tox] | ||
2921 | 5 | skipsdist=True | ||
2922 | 6 | skip_missing_interpreters = True | ||
2923 | 7 | envlist = lint, unit | ||
2924 | 8 | |||
2925 | 9 | [vars] | ||
2926 | 10 | src_path = {toxinidir}/src/ | ||
2927 | 11 | tst_path = {toxinidir}/tests/ | ||
2928 | 12 | lib_path = {toxinidir}/lib/charms/operator_libs_linux | ||
2929 | 13 | all_path = {[vars]src_path} {[vars]tst_path} | ||
2930 | 14 | |||
2931 | 15 | [testenv] | ||
2932 | 16 | setenv = | ||
2933 | 17 | PYTHONPATH = {toxinidir}:{toxinidir}/lib:{[vars]src_path} | ||
2934 | 18 | PYTHONBREAKPOINT=ipdb.set_trace | ||
2935 | 19 | PY_COLORS=1 | ||
2936 | 20 | passenv = | ||
2937 | 21 | PYTHONPATH | ||
2938 | 22 | HOME | ||
2939 | 23 | PATH | ||
2940 | 24 | CHARM_BUILD_DIR | ||
2941 | 25 | MODEL_SETTINGS | ||
2942 | 26 | HTTP_PROXY | ||
2943 | 27 | HTTPS_PROXY | ||
2944 | 28 | NO_PROXY | ||
2945 | 29 | |||
2946 | 30 | [testenv:fmt] | ||
2947 | 31 | description = Apply coding style standards to code | ||
2948 | 32 | deps = | ||
2949 | 33 | black | ||
2950 | 34 | isort | ||
2951 | 35 | commands = | ||
2952 | 36 | isort {[vars]all_path} | ||
2953 | 37 | black {[vars]all_path} | ||
2954 | 38 | |||
2955 | 39 | [testenv:lint] | ||
2956 | 40 | description = Check code against coding style standards | ||
2957 | 41 | deps = | ||
2958 | 42 | black | ||
2959 | 43 | flake8 | ||
2960 | 44 | flake8-docstrings | ||
2961 | 45 | flake8-copyright | ||
2962 | 46 | flake8-builtins | ||
2963 | 47 | pyproject-flake8 | ||
2964 | 48 | pep8-naming | ||
2965 | 49 | isort | ||
2966 | 50 | codespell | ||
2967 | 51 | commands = | ||
2968 | 52 | codespell {toxinidir}/*.yaml {toxinidir}/*.ini {toxinidir}/*.md \ | ||
2969 | 53 | {toxinidir}/*.toml {toxinidir}/*.txt {toxinidir}/.github | ||
2970 | 54 | # pflake8 wrapper supports config from pyproject.toml | ||
2971 | 55 | pflake8 {[vars]all_path} | ||
2972 | 56 | isort --check-only --diff {[vars]all_path} | ||
2973 | 57 | black --check --diff {[vars]all_path} | ||
2974 | 58 | |||
2975 | 59 | [testenv:unit] | ||
2976 | 60 | description = Run unit tests | ||
2977 | 61 | deps = | ||
2978 | 62 | pytest | ||
2979 | 63 | coverage[toml] | ||
2980 | 64 | -r{toxinidir}/requirements.txt | ||
2981 | 65 | commands = | ||
2982 | 66 | coverage run --source={[vars]src_path} \ | ||
2983 | 67 | -m pytest --ignore={[vars]tst_path}integration -v --tb native -s {posargs} | ||
2984 | 68 | coverage report | ||
2985 | 69 | |||
2986 | 70 | [testenv:integration] | ||
2987 | 71 | description = Run integration tests | ||
2988 | 72 | deps = | ||
2989 | 73 | git+https://github.com/juju/python-libjuju.git | ||
2990 | 74 | pytest | ||
2991 | 75 | git+https://github.com/charmed-kubernetes/pytest-operator.git | ||
2992 | 76 | -r{toxinidir}/requirements.txt | ||
2993 | 77 | commands = | ||
2994 | 78 | pytest -v --tb native --ignore={[vars]tst_path}unit --log-cli-level=INFO -s {posargs} |