DOCS: Migrated documentation website to Gitbook (#1809)

documentation/cli-variables.md

@@ -0,0 +1,132 @@
+# CLI variables
+
+You can pass variables into your configuration from the command line using the `-v key=value` flag. There is also a mechanism called `CLI_DEFAULTS` which lets you easily set the defaults on variables that are otherwise controlled from the command line.
+
+This gives you the opportunity to run different code when a value is passed.
+
+## Passing variables
+
+To pass a variable from CLI, just use the parameter `-v key=value` when using subcommands `preview` or `push`.
+
+Example: `dnscontrol preview -v testKey=testValue`
+
+This would set the variable with the name `testKey` and the value of `testValue` when processing `dnsconfig.js`
+
+## Define defaults
+
+The `CLI_DEFAULTS` feature is used to define default values for when a variable is not defined on the command line.
+
+```javascript
+CLI_DEFAULTS({
+    "variableName": "defaultValue",
+});
+```
+
+You need to define this defaults just once in your `dnsconfig.js`. It should be defined **before** using it.
+
+_Please keep in mind that accessing an undefined variable is an error. If it is not set on the command line nor in `CLI_DEFAULTS`, accessing the variable will fail._
+
+## Example 1: Different IPs for internal/external DNS
+
+In this example we have a number of variables which need to be set differently when `view=internal`.
+
+In this configuration:
+
+* `dnscontrol push` would generate the external (default) view.
+* `dnscontrol push -v view=internal` would generate the internal view.
+
+```javascript
+// See https://docs.dnscontrol.org/advanced-features/cli-variables
+CLI_DEFAULTS({
+    "view": "external",
+});
+if (view == "external") {
+    // BIND view: external (192.168.0.0/16 addresses)
+    var host01 = "192.168.0.16";
+    var host02 = "192.168.0.17";
+} else {
+    // BIND view: internal (10.0.0.0/8 addresses)
+    var host01 = "10.0.0.16";
+    var host02 = "10.0.0.17";
+}
+
+/// ...much later...
+
+D("example.org", REG_NAMECOM, DnsProvider(DNS_NAMECOM), DnsProvider(DNS_BIND),
+    A("sitea", host01, TTL(1800)),
+    A("siteb", host01, TTL(1800)),
+    A("sitec", host02, TTL(1800)),
+    A("sited", host02, TTL(1800))
+);
+```
+
+## Example 2: Different DNS records
+
+In this example different code is run when `emergency=true`.  Normally
+`server12` is an A record but in an emergency it is a CNAME.
+
+In this configuration:
+
+* `dnscontrol push` would generate the normal configuration.
+* `dnscontrol push -v emergency=true` would generate the emergency configuration.
+
+```javascript
+// See https://docs.dnscontrol.org/advanced-features/cli-variables
+CLI_DEFAULTS({
+    "emergency": false,
+});
+
+// ...much later...
+
+D("example.com", REG_EXAMPLE, DnsProvider(DNS_EXAMPLE),
+    A("www", "10.10.10.10"),
+);
+
+if (emergency) {
+    // Emergency mode: Configure A/B/C using CNAMEs to our alternate site.
+
+    D_EXTEND("example.com",
+        CNAME("a", "a.othersite"),
+        CNAME("b", "b.othersite"),
+        CNAME("c", "c.othersite")
+    );
+
+} else {
+    // Normal operation: Configure A/B/C using A records.
+
+    D_EXTEND("example.com",
+        A("a", "10.10.10.10"),
+        A("b", "10.10.10.11"),
+        A("c", "10.10.10.12")
+    );
+
+}
+```
+
+#### ProTips
+
+The cli variables functionality permits you to create very complex and
+sophisticated configurations, but you shouldn't. Be nice to the next person
+that edits the file, who may not be as expert as yourself.
+
+While there is no limit to the number of variables that can be set on the
+command line, doing so is annoying to the person using the tool.  It is better
+to set one variables which specifies a "mode".  This mode is then used to
+automatically set other variables. This way the user can determine the mode and
+the code can determine what to do in that mode. This is less error-prone and
+more testable.
+
+In the first example, you'll see that one variable is used to set a mode which
+then determines many other variables.  This is done in one place, at the top of
+the file. Everything related to this is isolated to one place, thus easier to
+maintain. The rest of the file simply uses those variables.
+
+In the second example, you'll see a boolean variable is set which selects which
+code will run different code. While the conditional code is not isolated to the
+top of the file, the conditional code is placed immediately after the domain.
+
+In both examples, not setting any variables on the command line does something
+reasonable. If someone accidentally runs `dnscontrol push` without any
+variables, the behavior is correct (assuming we're not in emergency mode, which
+is unlikely).
+