Cleanup documentation to prepare for 0.5.0 release

mesosphere · Nov 19, 2015 · 4bfcdb8 · 4bfcdb8
1 parent f6fa880
commit 4bfcdb8
Show file tree

Hide file tree

Showing 8 changed files with 36 additions and 23 deletions.
diff --git a/docs/_config.yml b/docs/_config.yml
@@ -20,6 +20,6 @@ highlighter: pygments
 lsi: false
 markdown: redcarpet
 redcarpet:
-  extensions: [with_toc_data]
+  extensions: [with_toc_data, tables]
 safe: true
 source: .
diff --git a/docs/docs/configuration-parameters.md b/docs/docs/configuration-parameters.md
@@ -53,6 +53,8 @@ It is sufficient to specify just one of the `zk` or `masters` field. If both are
 
 `refreshSeconds` is the frequency at which Mesos-DNS updates DNS records based on information retrieved from the Mesos master. The default value is 60 seconds. 
 
+`stateTimeoutSeconds` is the time that Mesos-DNS will wait for the Mesos master to respond to its request for state.json in seconds. The default value is 300 seconds.
+
 `ttl` is the [time to live](http://en.wikipedia.org/wiki/Time_to_live#DNS_records) value for DNS records served by Mesos-DNS, in seconds. It allows caching of the DNS record for a period of time in order to reduce DNS request rate. `ttl` should be equal or larger than `refreshSeconds`. The default value is 60 seconds. 
 
 `domain` is the domain name for the Mesos cluster. The domain name can use characters [a-z, A-Z, 0-9], `-` if it is not the first or last character of a domain portion, and `.` as a separator of the textual portions of the domain name. We recommend you avoid valid [top-level domain names](http://en.wikipedia.org/wiki/List_of_Internet_top-level_domains). The default value is `mesos`.

diff --git a/docs/docs/faq.md b/docs/docs/faq.md
@@ -21,14 +21,16 @@ You can customize all fields in the SOA records for the Mesos domain. See the `S
 
 #### Verbose and very verbose modes
 
-If you start Mesos-DNS in verbose mode using the `-v=1` or `-v=2` arguments, it  prints a variety of messages that are useful for debugging and performance tuning. The `-v=2` option will periodically print every A or SRV record Mesos-DNS generates. 
+If you start Mesos-DNS in verbose mode using the `-v=1` or `-v=2` arguments, it  prints a variety of messages that are useful for debugging and performance tuning. The `-v=2` option will periodically print every A or SRV record Mesos-DNS generates. In large clusters, this can overwhelm log management tools, such as [systemd-journald](http://www.freedesktop.org/software/systemd/man/systemd-journald.service.html), and they will drop messages. This is not a viable method to enumerate the state of a Mesos-DNS server.
 
 ---
 
 
 #### Mesos-DNS fails to launch
 
-Make sure that the port used for Mesos-DNS is available and not in use by another process. To use the recommended port `53`, you must start Mesos-DNS as root. 
+Make sure that the port used for Mesos-DNS is available and not in use by another process. To use the recommended port `53`, you must start Mesos-DNS as root.
+
+Alternatively, if you have an operating system and file system that supports [capabilities](http://manpages.ubuntu.com/manpages/hardy/man7/capabilities.7.html), you can run `sudo setcap 'cap_net_bind_service=+ep' mesos-dns`, which will then allow Mesos-DNS to bind to privileged ports, without requiring it to run as root.
 
 ---
 
@@ -54,7 +56,7 @@ Check the configuration file to make sure that Mesos-DNS is configured with the
 
 #### Updating the configuration file
 
-When you update the configuration file, you need to restart Mesos-DNS. No state is lost on restart as Mesos-DNS is stateless and retrieves task state from the Mesos master(s). 
+When you update the configuration file, you need to restart Mesos-DNS. No state is lost long-term on restart as Mesos-DNS is stateless and retrieves task state from the Mesos master(s). There is a short inconsistency window where records may be missing while the zone is being generated from the state.json.
 
 ---
 

diff --git a/docs/docs/http.md b/docs/docs/http.md
@@ -17,7 +17,10 @@ Lists in JSON format the Mesos-DNS version and source code URL.
 
 ``` console
 $ curl http://10.190.238.173:8123/v1/version
-{"Service":"Mesos-DNS","URL":"https://github.com/mesosphere/mesos-dns","Version":"0.1.1"}
+{
+	"Service":"Mesos-DNS",
+	"URL":"https://github.com/mesosphere/mesos-dns","Version":"0.1.1"
+}
 ```
 
 ## `GET /v1/config`
@@ -50,9 +53,9 @@ Lists in JSON format the IP address(es) that correspond to a hostname. It is the
 ```console
 $ curl http://10.190.238.173:8123/v1/hosts/nginx.marathon.mesos
 [
-{"host":"nginx.marathon.mesos.","ip":"10.249.219.155"},
-{"host":"nginx.marathon.mesos.","ip":"10.190.238.173"},
-{"host":"nginx.marathon.mesos.","ip":"10.156.230.230"}
+	{"host":"nginx.marathon.mesos.","ip":"10.249.219.155"},
+	{"host":"nginx.marathon.mesos.","ip":"10.190.238.173"},
+	{"host":"nginx.marathon.mesos.","ip":"10.156.230.230"}
 ]
 ```
 
@@ -63,9 +66,9 @@ Lists in JSON format the hostname, IP addres, and ports that correspond to a hos
 ```console
 curl http://10.190.238.173:8123/v1/services/_nginx._tcp.marathon.mesos.
 [
-{"host":"nginx-s2.marathon.mesos.","ip":"10.249.219.155","port":"31644","service":"_nginx._tcp.marathon.mesos."},
-{"host":"nginx-s1.marathon.mesos.","ip":"10.190.238.173","port":"31667","service":"_nginx._tcp.marathon.mesos."},
-{"host":"nginx-s0.marathon.mesos.","ip":"10.156.230.230","port":"31880","service":"_nginx._tcp.marathon.mesos."}
+	{"host":"nginx-s2.marathon.mesos.","ip":"10.249.219.155","port":"31644","service":"_nginx._tcp.marathon.mesos."},
+	{"host":"nginx-s1.marathon.mesos.","ip":"10.190.238.173","port":"31667","service":"_nginx._tcp.marathon.mesos."},
+	{"host":"nginx-s0.marathon.mesos.","ip":"10.156.230.230","port":"31880","service":"_nginx._tcp.marathon.mesos."}
 ]
 ```
 
diff --git a/docs/docs/index.md b/docs/docs/index.md
@@ -17,12 +17,12 @@ For fault tolerance, we ***recommend*** that you use [Marathon](https://mesosphe
 
 ```
 {
-"cmd": "sudo  /usr/local/mesos-dns/mesos-dns -config=/usr/local/mesos-dns/config.json",
-"cpus": 1.0, 
-"mem": 1024,
-"id": "mesos-dns",
-"instances": 1,
-"constraints": [["hostname", "CLUSTER", "10.181.64.13"]]
+    "cmd": "sudo  /usr/local/mesos-dns/mesos-dns -config=/usr/local/mesos-dns/config.json",
+    "cpus": 1.0,
+    "mem": 1024,
+    "id": "mesos-dns",
+    "instances": 1,
+    "constraints": [["hostname", "CLUSTER", "10.181.64.13"]]
 }
 ```
 Note that the `hostname` field refers to the hostname used by the slave when it registers with Mesos. It may not be an IP address or a valid hostname of any kind. You can inspect the hostnames and attributes of slaves on a Mesos cluster through the master web interface. For instance, you can access the `state` REST endpoint with:

diff --git a/docs/docs/performance-tuning.md b/docs/docs/performance-tuning.md
@@ -10,20 +10,26 @@ The following are suggestions for further performance tuning, focusing primarily
 
 ### Basic Tuning
 
-To increase the number of cores used by Mesos-DNS, set the `GOMAXPROCS` environment variable. For instance, use the following command line to launch Mesos-DNS on 8 cores:
+#### GOMAXPROCS
+In Mesos-DNS 0.5.0, we've moved to Go *1.5*, which automatically sets `GOMAXPROCS` to the number of CPUs that are detected by the Go runtime via `runtime.NumCPU`.
 
-```` 
+In previous versions, it may make sense to increase the number of cores used by Mesos-DNS by setting the `GOMAXPROCS` environment variable. For instance, use the following command line to launch Mesos-DNS on 8 cores:
+
+````
 GOMAXPROCS=8 mesos-dns
 ````
 
+#### Scaling out
 If a single Mesos-DNS server cannot meet the performance requirements in a very large cluster, you can bring up multiple Mesos-DNS servers and configure a subset of the slaves to use each Mesos-DNS server. All Mesos-DNS servers will serve the same settings derived from the Mesos master state. 
 
 
-You should also increase the shell limits for the maximum number of file descriptors and processes. Use `ulimit -a` to check the current settings and, if needed, increase them by executing the following shell commands before launching Mesos-DNS.
+#### Fundamental Operating system limits
+You should also increase the shell limits for the maximum number of file descriptors and processes. Use `ulimit -a` to check the current settings and, if needed, increase them by executing the following shell commands before launching Mesos-DNS. Mesos-DNS uses file descriptors for forwarding queries, making requests to the Mesos master, and keeps FDs open for accepting queries.
 
 ```
 ulimit -n 65536
 ulimit -p 16384
+
 ```
 ### Tuning External Lookups
 

diff --git a/docs/docs/tutorial-external.md b/docs/docs/tutorial-external.md
diff --git a/docs/docs/tutorial-forward.md b/docs/docs/tutorial-forward.md
@@ -15,9 +15,9 @@ Assuming that Mesos-DNS will run on host `192.168.0.100` and uses port `8053`, y
 
 ```
 zone "mesos" {
-type forward;
-forward only;
-forwarders { 192.168.0.100 port 8053; }; 
+  type forward;
+  forward only;
+  forwarders { 192.168.0.100 port 8053; };
 }; 
 ```