Update docs for dns-scripting, acme-dns etc

Author: webprofusion-chrisc

docs/dns-scripting.md

@@ -0,0 +1,82 @@
+---
+id: dns-scripting
+title: DNS Scripting
+---
+
+To provide your own script to update DNS you need to create (or source) a Windows (CMD) batch file which expects the following sequence of arguments and update a corresponding TXT record in your DNS zone:
+- Target Domain (e.g. `example.com`)
+- Record Name (e.g. `_acme-challenge.example.com`)
+- Record Value (e.g. `ABCBD123456789`)
+- Zone Id (e.g. `OptionalZoneId`, this is often useful to match the specific zone to update)
+
+e.g. given a script at *C:\customscripts\UpdateDNS.bat*, this will be executed as:
+ ```
+C:\customscripts\UpdateDNS.bat example.com _acme-challenge.example.com ABCBD123456789 OptionalZoneId
+```
+Important Notes: 
+
+- Your script will run as the background service user (local system), not as your account.
+- You should assume the working directory of the process will not be the same as the script. 
+- When an 'apex domain' like `example.com` is included in the certificate request for a wildcard (e.g. `*.example.com`) both TXT records will have the same name but different values, so updates need to add to the TXT record values. For this reason it's also a good idea to provide a (well tested!) delete script to clean up the TXT record once the request has completed, otherwise your TXT record values will grow with every validation attempt.
+
+
+## Calling a Python or node script
+To use a Python script (or similarly Node etc) start with a .bat file which can then forward all the arguments as required to your script using `%*` (or you could pass specific arguments if you needed). Note also the fully qualified path to the python exe (or node) as your script will run as local system (using the apps background service) and the path environment variable settings may be different:
+
+```bat
+REM This script would be called with the parameters <target domain> <record name> <record value> <zone id (optionally)>
+
+REM this example then calls a custom python script forwarding all the arguments
+
+c:\python27\python.exe create_dns_txt_example.py %*
+```
+
+In the following Pythong example the args are available in the `sys.argv` list. This example passes that list to a function called `main` and logs some example stuff (`create_dns_txt_example.py` logging to `dns_create_test.log`).
+
+Your real script would use your DNS providers API or a library such as Apache libcloud.
+
+```python
+# Example
+
+import sys
+import os
+import getopt
+import logging
+
+# TODO: added module for DNS updates (libcloud etc)
+
+
+def main(argv):
+
+    # init logging etc
+    logging.basicConfig(filename='dns_create_test.log',
+                        filemode='a', level=logging.INFO)
+
+    logging.info("Example Python DNS helper.")
+
+   # TODO: setup your DNS provider (apache libcloud etc)
+
+   # TODO: add/append the txt record
+
+    logging.info("args: " + " ".join(sys.argv))
+
+    logging.info(
+        "If this script did anything it would create a TXT record called " + sys.argv[2]
+        + " with the value " + sys.argv[3]
+        + " you could optionally use the domain ("+sys.argv[1]+") "
+        + " or zoneId ("+sys.argv[4]+") in your python script")
+
+
+#########################################
+if __name__ == "__main__":
+    main(sys.argv)
+
+```
+When the script runs that app will call the .bat file like:
+```
+ExampleDNSCreatePython.bat mydomain.com _acme-challenge.mydomain.com ABCD1234 myoptionalZoneId
+```
+Which in turn (based on the above example .bat) will call the python script as :
+```
+python create_dns_txt_basic.py.bat mydomain.com _acme-challenge.mydomain.com ABCD1234 myoptionalZoneId
+```

docs/dns-validation.md

@@ -4,41 +4,60 @@ title: About DNS Validation (dns-01)
 ---
 
 ## Why use DNS Validation?
-To request a certificate from Let's Encrypt (or any Certificate Authority), you need to provide some kind of proof that you are entitled to receive the certificate for given domain(s). Let's Encrypt supports two methods of validation to prove control of your domain, `http-01` ([validation over HTTP](http-validation.md)) and `dns-01` (validation via DNS). 
+To request a certificate from Let's Encrypt (or any Certificate Authority), you need to provide some kind of proof that you are entitled to receive the certificate for given domain(s). Let's Encrypt supports two methods of validation to prove control of your domain, `http-01` ([validation over HTTP](http-validation.md)) and `dns-01` (validation over DNS). 
 
 **Wildcard domain certificates (those covering `*.yourdomain.com`) can only be requested using DNS validation.** DNS Validation is also especially useful if the domains you are trying to get certification for are not public websites, or cannot serve http requests on port 80.
 
 ## How to use DNS Validation
 
 In order to validate your control of your domains to the certificate authority you will be required to create a specified TXT record in your domain's DNS zone.
 
-To do this you need to get the API credentials for the (hosted) DNS from your DNS providers control panel, store these credentials in the app then select them to be used for specific certificate requests.
+To do this you may need to get the API credentials for the (hosted) DNS from your DNS providers control panel, store these credentials in the app then select them to be used for specific certificate requests.
 
 If your DNS provider (or custom DNS setup) does not have an API we can talk to, you can write your own DNS update script or use the Manual DNS option (the request pauses while you manually update DNS).
 
-## DNS Providers
+### DNS API Providers
 
-The following DNS providers are supported:
-- [Azure DNS](dns-azuredns.md)
+Currently supported DNS API providers include:
+- Aliyun
 - [AWS Route53](dns-awsroute53.md)
+- [Azure DNS](dns-azuredns.md)
 - [Cloudflare](dns-cloudflare.md) DNS *(Note: Cloudflare offer a free tier for DNS services)*
 - [DNS Made Easy](dns-dnsmadeeasy.md)
 - [GoDaddy](dns-godaddy.md)
+- Microsoft DNS
+- NameCheap
 - [OVH](dns-ovh.md)
 - Simple DNS Plus
 
 **If you change API credentials, you need to replace the credential settings in Certify under 'Settings > Stored Credentials' to ensure renewals keep working. Once saved, there is also a 'Test' option so you can try out the credentials to check they still work.**
 
-## DNS Scripting
-To provide your own script to update DNS you need to create (or source) a Windows (CMD) batch file which expects the following sequence of arguments and update a corresponding TXT record in your DNS zone:
-- Target Domain (e.g. `example.com`)
-- Record Name (e.g. `_acme-challenge.example.com`)
-- Record Value (e.g. `ABCBD123456789`)
-- Zone Id (e.g. `OptionalZoneId`, this is often useful to match the specific zone to update)
-
-e.g. given a script at *C:\customscripts\UpdateDNS.bat*, this will be executed as:
- ```
-C:\customscripts\UpdateDNS.bat example.com _acme-challenge.example.com ABCBD123456789 OptionalZoneId
-```
-Notes: you should assume the working directory of the process will not be the same as the script. When an 'apex domain' like `example.com` is included in the certificate request for a wildcard (e.g. `*.example.com`) both TXT records will have the same name but different values, so updates need to add to the TXT record values. For this reason it's also a good idea to provide a (well tested!) delete script to clean up the TXT record once the request has completed, otherwise your TXT record values will grow with every validation attempt.
+## Other DNS Validation Methods
+You can alternatively use the following methods to manage your DNS TXT records:
+
+### ACME DNS 
+[acme-dns](https://github.com/joohoi/acme-dns) is a system to automatically manage TXT record values on behalf of your domain **just for challenge validation**. This is probably the easiest method if you have a  trusted acme-dns server you can use, this also avoids storing powerful DNS admin credentials on your server.
+
+- Select acme-dns as the DNS update method
+- Point to a trusted acme-dns server
+- Request certificate, the first time you do so you will be prompted to create a CNAME pointing to the acme-dns server. 
+- Resume the request using Request Certificate, the acme-dns server will provide the required TXT record responses on your behalf.
+- Automatic renewals will then perform this process again without manual intervention.
+
+### DNS Scripting
+[DNS Scripting](dns-scripting.md) involves providing your own custom script to update/delete TXT records in your DNS using a .bat file which can then optionally call python, node scripts etc.
+
+### Manual DNS 
+If you are just experimenting with wildcard domains you may opt to use manual DNS updates (editing manually via your DNS control panel). 
+
+**This is the least recommended option as you will need to update this for every renewal.** 
+
+This method can also be extremely confusing when requesting a single cert for `*.domain.com` and `domain.com`, as you need to provide 2 values for the same TXT `_acme-challenge.domain.com` record (to answer both the `*.domain.com` and `domain.com` challenge responses).
+
+To use Manual DNS:
+- Select Manual DNS as your DNS update method
+- Perform your initial certificate request. The request will pause and ask you to create a TXT record in your domain (one value for each domain or wildcard). Once you have completed that, wait for your DNS name servers to complete propagation. If you have trouble validating, wait an hour or more for this to complete.
+- Use 'Request Certificate' to resume the request and check validation. 
+- If the certificate authority can see the TXT value they asked for in your DNS, they will then allow a certificate to be issued and the request will resume as normal.
+
 

website/i18n/en.json

@@ -41,6 +41,9 @@
       "dns-ovh": {
         "title": "OVH DNS API"
       },
+      "dns-scripting": {
+        "title": "DNS Scripting"
+      },
       "dns-validation": {
         "title": "About DNS Validation (dns-01)"
       },