Documentation formatting, arranging, and some edits; add unbound_ssh …

…docs (#199)

CHANGELOG.md → docs/CHANGELOG.md

@@ -1,6 +1,36 @@
 ## `sewer` changelog:
 most recent version is listed first.   
 
+## **version:** 0.8.3
+STILL TO DO:
+- tests for unbound_ssh?!
+
+
+Features and Improvements:
+- added `--acme-timeout <seconds>` option to adjust timeout on queries to
+  the ACME server
+- `--action {run,renew}` has been doing nothing useful and is now deprecated.
+- added `--p_opt <name>=<value>` for passing kwargs to drivers
+- Added optional parameters accepted by base class for DNS drivers:
+  - `alias=<alias_domain>` specifies a separate domain for DNS challenges
+  - `prop_delay=<seconds>` gives a fixed delay (sleep) after challenge setup
+- gandi (legacy DNS driver) fixed internal bugs that broke common wildcard
+  use cases (eg., `*.domain.tld`) as well as the "wildcard plus" pattern
+- added unbound_ssh legacy-style DNS provider as a working demo of adding
+  new features to legacy drivers.  It does work in the right environment, and
+  could be useful to someone, maybe.
+
+Internals:
+- added `**kwargs` to all legacy providers to allow new options that are
+  handled in a parent class to pass through (for `alias`, `prop_delay`, etc.)
+- removed imports that were in `sewer/__init__` and
+  `sewer/dns_providers/__init__`; fixed all uses in cli.py and tests.
+- began cleanup/refactor of cli.py (there will be more to come and/or a new,
+  more config driven, alternative command (0.9?))
+- added `__main__.py` to support `python3 -m sewer` invocation of sewer-cli
+- fixed imports in client.py that didn't actually import the parts of
+  OpenSSL and cryptography that we use (worked because we import requests?)
+
 ## **version:** 0.8.2
 Feature additions:
 
@@ -16,6 +46,8 @@ Internals (features and/or annoying changes for sewer-as-a-library users)
 - client no longer prepends`*.` to wildcards; remove spotty code in providers to strip it
 - begin addition of annotations, mostly opportunistically
 
+See also [release notes](notes/0.8.2-notes).
+
 ## **version:** 0.8.1
 - Fix bug where `sewer` was unable to delete wildcard names from clouflare: https://github.com/komuw/sewer/pull/139    
 - Fix a StopIteration bug: https://github.com/komuw/sewer/pull/148   

docs/README.md

@@ -9,11 +9,9 @@
 Sewer is a Let's Encrypt(ACME) client.  
 It's name is derived from Kenyan hip hop artiste, Kitu Sewer.  
 
-The current release is [0.8.2](https://komuw.github.io/sewer/0.8.2-notes).
-You can see notes for the forthcoming [0.8.3](https://komuw.github.io/sewer/0.8.3-notes)
-release.
-There is also the [CHANGELOG](https://github.com/komuw/sewer/blob/master/CHANGELOG.md).
-_(These should all be integrated soon as part of the move to Pages.)_
+- The current PRE-release is [0.8.3](https://komuw.github.io/sewer/notes/0.8.3-notes).
+- Current stable release is [0.8.2](https://komuw.github.io/sewer/notes/0.8.2-notes).
+- More history in the [CHANGELOG](https://komuw.github.io/sewer/CHANGELOG).
 
 ## Features
 - Obtain or renew SSL/TLS certificates from [Let's Encrypt](https://letsencrypt.org)
@@ -27,10 +25,10 @@ _(These should all be integrated soon as part of the move to Pages.)_
   - HTTP challenges are a new feature, no operational drivers in the tree
     yet.  [See usage and BYO-service notes](https://komuw.github.io/sewer/http-01)
 - sewer is both a [command-line program](https://komuw.github.io/sewer/sewer-cli)
-  and a [Python library](#usage) for custom use
+  and a [Python library](https://komuw.github.io/sewer/sewer-as-a-library) for custom use
 - Well written(if I have to say so myself):
   - [Good test coverage](https://codecov.io/gh/komuW/sewer)
-  - [Passing continous integration](https://circleci.com/gh/komuW/sewer)
+  - [Passing continuous integration](https://circleci.com/gh/komuW/sewer)
   - [High grade statically analyzed code](https://www.codacy.com/app/komuW/sewer/dashboard)
   - type hinting to support mypy verification is a recently begun WIP
 

docs/dns-01.md

@@ -1,11 +1,11 @@
-# sewer's DNS service support
+## sewer's DNS service support
 
 ACME's dns-01 authorization was sewer's original target.
 There are a number of DNS services supported in-tree,
 and implementations for other services are difficult to write only if the
 service's API is difficult.
 
-## DNS services supported
+### DNS services supported
 
 - [acme-dns](https://github.com/joohoi/acme-dns)
 - [Aliyun](https://help.aliyun.com/document_detail/29739.html)
@@ -20,7 +20,7 @@ service's API is difficult.
 - [PowerDNS](https://doc.powerdns.com/authoritative/http-api/index.html)
 - [Rackspace](https://www.rackspace.com/cloud/dns)
 
-## Add a driver for your DNS service
+### Add a driver for your DNS service
 
 Most (?) of the DNS drivers came about because someone wanted to use sewer
 with their DNS service provider, but there wasn't a driver to use with the
@@ -37,20 +37,20 @@ and will be placed in sewer/providers/ if added to the project.
 
     # sketch of dns-01 provider, including alias support [which is NOT in 0.8.2]
 
-    from ..auth import DNSProviderBase
-    from ..lib import dns_challenge
+    from .. import auth
+    from .. import lib
 
-    class Provider(DNSProviderBase):
+    class Provider(auth.DNSProviderBase):
         def __init__(self, *, my_api_url, my_api_id, my_api_key, **kwargs):
-	    super().__init__(self, **kwargs)
+            super().__init__(self, **kwargs)
             self.api_url = my_api_url
             self.api_id = my_api_id
             self.api_key = my_api_key
 
         def setup(self, challenges):
-	    for challenge in challenges:
+            for challenge in challenges:
                 fqdn = self.target_domain(challenge)
-                txt_value = dns_challenge(challenge["key_auth"])
+                txt_value = lib.dns_challenge(challenge["key_auth"])
                 self.my_api_add_txt(fqdn, txt_value)
 
         def unpropagated(self, challenges):
@@ -66,18 +66,19 @@ and will be placed in sewer/providers/ if added to the project.
             # talk to DNS service to remove TXT
 
 Most of your work is in implementing the two methods (or one method, or
-inline code) which actually communicate with the DNS service.  This can be
+inline code, but inline makes testing without access to the service more
+difficult) which actually communicate with the DNS service.  This can be
 easy or very difficult, depending on the service provider's API (or lack of
 designed API if you have to use a mix of web scraping and HTTP request
 generation to operate a mechanism that was designed for interactive use).
 
 The above is bare-bones, not taking advantage of the batching of challenges
-which the new-model interface provides - that can be huge if you have to
-grovel the service's API (or web pages) to guide the construction of your
-commands to them.  It does show the use of target_domain to support
-[DNS aliasing](Aliasing).
+which the new-model interface provides - that can be a big win for large-SAN
+certificates if you have to grovel the service's API (or web pages) to guide
+the construction of your commands to them.  It does show the use of
+target_domain to support [DNS aliasing](Aliasing).
 
-## Legacy DNS drivers vs. $FEATURES
+### Legacy DNS drivers vs. $FEATURES
 
 Three features that have varying support in the Legacy drivers.
 

docs/drivers/unbound_ssh.md

@@ -0,0 +1,40 @@
+## unbound_ssh legacy DNS driver
+
+A working, if somewhat quirky, driver to setup challenges in the unbound
+server, using ssh to connect to an account able to run unbound-control
+commands.  The driver does NOT handle the login authorization, assuming that
+it is running interactively and ssh will prompt for your input, or that a
+key agent (eg., ssh-agent) is active to supply the cryptographic
+credentials.
+
+### `__init__(self, *, ssh_des, **kwargs)`
+
+There is one REQUIRED parameter, `ssh_des`, which is the login target, such
+as [email protected].  This is simply passed to the ssh command,
+with the unbound-control commands passed as the command to execute remotely.
+
+### Driver features
+
+unbound_ssh supports the `alias` parameter.
+
+Only `prop_delay` is supported; there is no custom `unpropagated` method.
+
+### Usage
+
+From the command line:
+
+    python3 -m sewer ... --provider=unbound_ssh --p_opt [email protected] ...
+
+From custom code:
+
+    from sewer.dns_providers.unbound_ssh import UnboundSSH
+
+    provider = UnboundSSH(ssh_des="[email protected]", alias="validation.example.com")
+    ...
+
+### Bugs
+
+Sadly, This was written using the old paradigm where both the module name
+and the class name were more-or-less the same name aside from
+capitalization... and often less predictable changes.  Should have been
+unbound_ssh.Provider ...

sewer/providers/demo.py

@@ -5,7 +5,7 @@
 from typing import Any
 
 from ..auth import ChalListType, ErrataListType, ProviderBase
-from ..dns_providers.common import dns_challenge
+from ..lib import dns_challenge
 
 
 class ManualProvider(ProviderBase):