General docs improvements (#481)

* docs improvements * Updated matrix as part of "go generate" (e.g. adds SSHFP row) * Commiting full matrix file * Added docs for SSHFP record * Matrix: Mark OVH as SSHFP-capable in docs (see PR #482)
2025-01-11 01:47:53 +08:00 · 2019-05-21 04:33:50 +02:00 · 2019-05-21 04:33:50 +02:00 · c65ba1c84c
commit c65ba1c84c
parent d84a91c848
10 changed files with 180 additions and 29 deletions
--- a/docs/_functions/domain/CAA.md
+++ b/docs/_functions/domain/CAA.md
@ -13,11 +13,11 @@ Tag can be one of "issue", "issuewild" or "iodef".

 Value is a string. The format of the contents is different depending on the tag.  DNSControl will handle any escaping or quoting required, similar to TXT records.  For example use `CAA("@", "issue", "letsencrypt.org")` rather than `CAA("@", "issue", "\"letsencrypt.org\"")`.

-Flags are controlled by modifier.:
+Flags are controlled by modifier:

 - CAA_CRITICAL: Issuer critical flag. CA that does not understand this tag will refuse to issue certificate for this domain.

-CAA record is supported only by BIND, Google Cloud DNS, and Amazon Route 53. Some certificate authorities may not support this record until the mandatory date of September 2017.
+CAA record is supported only by BIND, Google Cloud DNS, Amazon Route 53 and OVH. Some certificate authorities may not support this record until the mandatory date of September 2017.

 {% include startExample.html %}
 {% highlight js %}
--- a/docs/_functions/domain/NS.md
+++ b/docs/_functions/domain/NS.md
@ -15,8 +15,8 @@ Target should be a string representing the NS target. If it is a single label we
 {% highlight js %}

 D("example.com", REGISTRAR, DnsProvider("R53"),
-  NS("foo", "ns1.example2.com"), // Delegate ".foo.example.com" zone to another server.
-  NS("foo", "ns2.example2.com"), // Delegate ".foo.example.com" zone to another server.
+  NS("foo", "ns1.example2.com."), // Delegate ".foo.example.com" zone to another server.
+  NS("foo", "ns2.example2.com."), // Delegate ".foo.example.com" zone to another server.
  A("ns1.example2.com", "10.10.10.10"), // Glue records
  A("ns2.example2.com", "10.10.10.20"), // Glue records
 );
--- a/docs/_functions/domain/SSHFP.md
+++ b/docs/_functions/domain/SSHFP.md
@ -0,0 +1,37 @@
+---
+name: SSHFP
+parameters:
+  - name
+  - algorithm
+  - type
+  - value
+  - modifiers...
+---
+
+SSHFP contains a fingerprint of a SSH server which can be validated before SSH clients are establishing the connection.
+
+**Algorithm** (type of the key)
+| ID | Algorithm |
+|----|-----------|
+| 0  | reserved  |
+| 1  | RSA       |
+| 2  | DSA       |
+| 3  | ECDSA     |
+| 4  | ED25519   |
+
+**Type** (fingerprint format)
+| ID | Algorithm |
+|----|-----------|
+| 0  | reserved  |
+| 1  | SHA-1     |
+| 2  | SHA-256   |
+
+`value` is the fingerprint as a string.
+
+{% include startExample.html %}
+{% highlight js %}
+
+SSHFP('@', 1, 1, '00yourAmazingFingerprint00'),
+
+{%endhighlight%}
+{% include endExample.html %}
--- a/docs/_functions/global/IP.md
+++ b/docs/_functions/global/IP.md
@ -0,0 +1,17 @@
+---
+name: IP
+parameters:
+  - ip
+---
+
+Converts the IP address from string to an integer. This allows performing mathematical operations with the IP address.
+
+{% include startExample.html %}
+{% highlight js %}
+
+var addrA = IP('1.2.3.4')
+var addrB = addrA + 1
+// addrB = 1.2.3.5
+
+{%endhighlight%}
+{% include endExample.html %}
--- a/docs/_includes/matrix.html
+++ b/docs/_includes/matrix.html
@ -136,6 +136,9 @@
 		<td class="success">
 			<i class="fa fa-check text-success" aria-hidden="true"></i>
 		</td>
+		<td class="success">
+			<i class="fa fa-check text-success" aria-hidden="true"></i>
+		</td>
 		<td class="danger">
 			<i class="fa fa-times text-danger" aria-hidden="true"></i>
 		</td>
@ -285,6 +288,9 @@
 		<td class="success">
 			<i class="fa fa-check text-success" aria-hidden="true"></i>
 		</td>
+		<td class="success">
+			<i class="fa fa-check text-success" aria-hidden="true"></i>
+		</td>
 		<td><i class="fa fa-minus dim"></i></td>
 		<td class="danger">
 			<i class="fa fa-times text-danger" aria-hidden="true"></i>
@ -293,8 +299,8 @@
 		<td><i class="fa fa-minus dim"></i></td>
 		<td><i class="fa fa-minus dim"></i></td>
 		<td><i class="fa fa-minus dim"></i></td>
-		<td class="danger">
-			<i class="fa fa-times text-danger" aria-hidden="true"></i>
+		<td class="success">
+			<i class="fa fa-check text-success" aria-hidden="true"></i>
 		</td>
 		<td class="success">
 			<i class="fa fa-check text-success" aria-hidden="true"></i>
@ -329,6 +335,9 @@
 		<td class="success">
 			<i class="fa fa-check text-success" aria-hidden="true"></i>
 		</td>
+		<td class="success">
+			<i class="fa fa-check text-success" aria-hidden="true"></i>
+		</td>
 		<td><i class="fa fa-minus dim"></i></td>
 		<td class="danger">
 			<i class="fa fa-times text-danger" aria-hidden="true"></i>
@ -352,6 +361,31 @@
 			<i class="fa fa-times text-danger" aria-hidden="true"></i>
 		</td>
 		</tr>
+	<tr>
+		<th class="row-header" style="text-decoration: underline;" data-toggle="tooltip" data-container="body" data-placement="top" title="Provider can manage NAPTR records">NAPTR</th>
+		<td><i class="fa fa-minus dim"></i></td>
+		<td class="success">
+			<i class="fa fa-check text-success" aria-hidden="true"></i>
+		</td>
+		<td><i class="fa fa-minus dim"></i></td>
+		<td><i class="fa fa-minus dim"></i></td>
+		<td><i class="fa fa-minus dim"></i></td>
+		<td><i class="fa fa-minus dim"></i></td>
+		<td><i class="fa fa-minus dim"></i></td>
+		<td><i class="fa fa-minus dim"></i></td>
+		<td><i class="fa fa-minus dim"></i></td>
+		<td><i class="fa fa-minus dim"></i></td>
+		<td><i class="fa fa-minus dim"></i></td>
+		<td><i class="fa fa-minus dim"></i></td>
+		<td><i class="fa fa-minus dim"></i></td>
+		<td><i class="fa fa-minus dim"></i></td>
+		<td><i class="fa fa-minus dim"></i></td>
+		<td><i class="fa fa-minus dim"></i></td>
+		<td><i class="fa fa-minus dim"></i></td>
+		<td><i class="fa fa-minus dim"></i></td>
+		<td><i class="fa fa-minus dim"></i></td>
+		<td><i class="fa fa-minus dim"></i></td>
+		</tr>
 	<tr>
 		<th class="row-header" style="text-decoration: underline;" data-toggle="tooltip" data-container="body" data-placement="top" title="Driver has explicitly implemented SRV record management">SRV</th>
 		<td class="danger">
@ -381,6 +415,9 @@
 		<td class="success">
 			<i class="fa fa-check text-success" aria-hidden="true"></i>
 		</td>
+		<td class="success">
+			<i class="fa fa-check text-success" aria-hidden="true"></i>
+		</td>
 		<td><i class="fa fa-minus dim"></i></td>
 		<td class="danger" data-toggle="tooltip" data-container="body" data-placement="top" title="The namecheap web console allows you to make SRV records, but their api does not let you read or set them">
 			<i class="fa has-tooltip fa-times text-danger" aria-hidden="true"></i>
@ -408,6 +445,33 @@
 			<i class="fa fa-check text-success" aria-hidden="true"></i>
 		</td>
 		</tr>
+	<tr>
+		<th class="row-header" style="text-decoration: underline;" data-toggle="tooltip" data-container="body" data-placement="top" title="Provider can manage SSHFP records">SSHFP</th>
+		<td><i class="fa fa-minus dim"></i></td>
+		<td class="success">
+			<i class="fa fa-check text-success" aria-hidden="true"></i>
+		</td>
+		<td><i class="fa fa-minus dim"></i></td>
+		<td><i class="fa fa-minus dim"></i></td>
+		<td><i class="fa fa-minus dim"></i></td>
+		<td><i class="fa fa-minus dim"></i></td>
+		<td><i class="fa fa-minus dim"></i></td>
+		<td><i class="fa fa-minus dim"></i></td>
+		<td><i class="fa fa-minus dim"></i></td>
+		<td><i class="fa fa-minus dim"></i></td>
+		<td><i class="fa fa-minus dim"></i></td>
+		<td><i class="fa fa-minus dim"></i></td>
+		<td><i class="fa fa-minus dim"></i></td>
+		<td><i class="fa fa-minus dim"></i></td>
+		<td><i class="fa fa-minus dim"></i></td>
+		<td><i class="fa fa-minus dim"></i></td>
+		<td class="success">
+			<i class="fa fa-check text-success" aria-hidden="true"></i>
+		</td>
+		<td><i class="fa fa-minus dim"></i></td>
+		<td><i class="fa fa-minus dim"></i></td>
+		<td><i class="fa fa-minus dim"></i></td>
+		</tr>
 	<tr>
 		<th class="row-header" style="text-decoration: underline;" data-toggle="tooltip" data-container="body" data-placement="top" title="Provider can manage TLSA records">TLSA</th>
 		<td><i class="fa fa-minus dim"></i></td>
@ -456,13 +520,13 @@
 		<td><i class="fa fa-minus dim"></i></td>
 		<td><i class="fa fa-minus dim"></i></td>
 		<td><i class="fa fa-minus dim"></i></td>
-		<td class="success">
-			<i class="fa fa-check text-success" aria-hidden="true"></i>
-		</td>
-		<td class="success">
-			<i class="fa fa-check text-success" aria-hidden="true"></i>
-		</td>
 		<td><i class="fa fa-minus dim"></i></td>
+		<td class="success">
+			<i class="fa fa-check text-success" aria-hidden="true"></i>
+		</td>
+		<td class="success">
+			<i class="fa fa-check text-success" aria-hidden="true"></i>
+		</td>
 		<td><i class="fa fa-minus dim"></i></td>
 		<td><i class="fa fa-minus dim"></i></td>
 		<td class="success">
@ -488,6 +552,7 @@
 		<td><i class="fa fa-minus dim"></i></td>
 		<td><i class="fa fa-minus dim"></i></td>
 		<td><i class="fa fa-minus dim"></i></td>
+		<td><i class="fa fa-minus dim"></i></td>
 		<td class="danger" data-toggle="tooltip" data-container="body" data-placement="top" title="Using ALIAS is possible through our extended DNS (X-DNS) service. Feel free to get in touch with us.">
 			<i class="fa has-tooltip fa-times text-danger" aria-hidden="true"></i>
 		</td>
@ -498,7 +563,6 @@
 		<td><i class="fa fa-minus dim"></i></td>
 		<td><i class="fa fa-minus dim"></i></td>
 		<td><i class="fa fa-minus dim"></i></td>
-		<td><i class="fa fa-minus dim"></i></td>
 		<td class="success">
 			<i class="fa fa-check text-success" aria-hidden="true"></i>
 		</td>
@ -520,8 +584,8 @@
 		<td class="danger" data-toggle="tooltip" data-container="body" data-placement="top" title="DNSimple does not allow sufficient control over the apex NS records">
 			<i class="fa has-tooltip fa-times text-danger" aria-hidden="true"></i>
 		</td>
-		<td class="danger">
-			<i class="fa fa-times text-danger" aria-hidden="true"></i>
+		<td class="danger" data-toggle="tooltip" data-container="body" data-placement="top" title="Exoscale does not allow sufficient control over the apex NS records">
+			<i class="fa has-tooltip fa-times text-danger" aria-hidden="true"></i>
 		</td>
 		<td><i class="fa fa-minus dim"></i></td>
 		<td><i class="fa fa-minus dim"></i></td>
--- a/docs/_providers/cloudflare.md
+++ b/docs/_providers/cloudflare.md
@ -52,10 +52,19 @@ What does on/off/full mean?
   * "on" enables the Cloudflare proxy (turns on the "orange cloud")
   * "full" is the same as "on" but also enables Railgun.  DNSControl will prevent you from accidentally enabling "full" on a CNAME that points to an A record that is set to "off", as this is generally not desired.

+Good to know: You can also set the default proxy mode using `DEFAULTS()` function, see:
+{% highlight js %}
+
+DEFAULTS(
+	CF_PROXY_DEFAULT_OFF // turn proxy off when not specified otherwise
+);
+
+{% endhighlight %}
+
 **Aliases:**

 To make configuration files more readable and less prone to errors,
-the following aliases are pre-defined:
+the following aliases are *pre-defined*:

 {% highlight js %}
 // Meta settings for individual records.
--- a/docs/caa-builder.md
+++ b/docs/caa-builder.md
@ -18,7 +18,7 @@ For example you can use:
 ```
 CAA_BUILDER({
  label: "@",
-  iodef: "test@domain.tld",
+  iodef: "mailto:test@domain.tld",
  iodef_critical: true,
  issue: [
    "letsencrypt.org",
@ -38,7 +38,7 @@ The parameters are:

 `CAA_BUILDER()` returns multiple records (when configured as example above):

-  * `CAA("@", "iodef", "test@domain.tld", CAA_CRITICAL)`
+  * `CAA("@", "iodef", "mailto:test@domain.tld", CAA_CRITICAL)`
  * `CAA("@", "issue", "letsencrypt.org")`
  * `CAA("@", "issue", "comodoca.com")`
  * `CAA("@", "issuewild", ";")`
--- a/docs/examples.md
+++ b/docs/examples.md
@ -21,8 +21,8 @@ D('example.com', REG, DnsProvider('GCLOUD'),
    MX('mail', 10, 'mailserver'),
    MX('mail', 20, 'mailqueue'),
    TXT('the', 'message'),
-    NS('delegated', 'ns1.dnsexample.com.'),
-    NS('delegated', 'ns2.dnsexample.com.')
+    NS('department2', 'ns1.dnsexample.com.'), // use different nameservers
+    NS('department2', 'ns2.dnsexample.com.') // for department2.example.com
 )

 {% endhighlight %}
@ -31,10 +31,17 @@ D('example.com', REG, DnsProvider('GCLOUD'),

 {% highlight javascript %}

+var mailTTL = TTL('1h');
+
 D('example.com', registrar,
+    NAMESERVER_TTL('10m'), // On domain apex NS RRs
    DefaultTTL('5m'), // Default for a domain
+
+    MX('@', 5, '1.2.3.4', mailTTL), // use variable to
+    MX('@', 10, '4.3.2.1', mailTTL), // set TTL
+
    A('@', '1.2.3.4', TTL('10m')), // individual record
-    NAMESERVER_TTL('10m') // On domain apex NS RRs
+    CNAME('mail', 'mx01') // TTL of 5m, as defined per DefaultTTL()
 );

 {% endhighlight %}
@ -138,3 +145,15 @@ D('example3.com', REG, DnsProvider('R53'), DnsProvider('GCLOUD',0),
 )

 {% endhighlight %}
+
+## Set default records modifiers
+
+{% highlight javascript %}
+
+DEFAULTS(
+	NAMESERVER_TTL('24h'),
+	DefaultTTL('12h'),
+	CF_PROXY_DEFAULT_OFF
+);
+
+{% endhighlight %}
--- a/docs/index.md
+++ b/docs/index.md
@ -114,7 +114,7 @@ title: DnsControl
 					<a href="{{site.github.url}}/spf-optimizer">SPF Optimizer</a>: Optimize your SPF records
 				</li>
 				<li>
-					<a href="{{site.github.url}}/caa-builder"CAA Builder</a>: Build CAA records the easy way
+					<a href="{{site.github.url}}/caa-builder">CAA Builder</a>: Build CAA records the easy way
 				</li>
 			</ul>
 		</div>
--- a/docs/provider-list.md
+++ b/docs/provider-list.md
@ -95,19 +95,24 @@ These providers have an open pr with (potentially) working code. They may be rea
 </ul>

 <script>
+$(function() {
  $.get("https://api.github.com/repos/StackExchange/dnscontrol/issues?state=all&labels=provider-request&direction=asc")
-  .done(function(data){
-    for(var i of data){
-      var el = $(`<li><a href='${i.html_url}'>${i.title}</a> (#${i.number})</li>`)
+  .done(function(data) {
+    for(var i of data) {
+      var el = $(`<li><a href='${i.html_url}'>${i.title}</a> (#${i.number})</li>`);
      var target = $("#requests");
-      if (i.state == "open") target = $("#inprog");
-      for(var l of i.labels){
-        if (l.name == "has-pr") target = $("#haspr");
+      if (i.state == "open") {
+        target = $("#inprog");
+        for(var l of i.labels) {
+          if (l.name == "has-pr")
+            target = $("#haspr");
+        }
      }
      target.append(el);
    }
  })
  .fail(function(err){
    console.log("???", err)
-  })
+  });
+});
 </script>