config: better document example

config.example.yaml

@@ -1,39 +1,72 @@
-# The values specified here are the default values that Clair uses if no configuration file
-# is specified or if the keys are not defined.
+# Copyright 2015 clair authors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# The values specified here are the default values that Clair uses if no configuration file is specified or if the keys are not defined.
 ---
 database:
-  # PostgreSQL Connection string.
-  # Reference: http://www.postgresql.org/docs/9.4/static/libpq-connect.html
+  # PostgreSQL Connection string
+  # http://www.postgresql.org/docs/9.4/static/libpq-connect.html
   source:
-  # Number of elements to keep in the cache.
+
+  # Number of elements kept in the cache
+  # Values unlikely to change (e.g. namespaces) are cached in order to save prevent needless roundtrips to the database.
   cacheSize: 16384
+
 api:
-  # Port on which the main API and the health API will listen on.
+  # API server port
   port: 6060
+
+  # Health server port
+  # This is an unencrypted endpoint useful for load balancers to check to healthiness of the clair server.
   healthport: 6061
-  # Maximum time that API requests may take before they time-out with a HTTP 503 error.
+
+  # Deadline before an API request will respond with a 503
   timeout: 900s
-  # 32-bit key used to encrypt pagination tokens
-  paginationKey: "2E9IgrgWLNb4gjuU0WbiBIudLH8xolz_qxFn--vxJP8="
-  # Paths to certificates to secure the main API with TLS and client certificate auth.
+
+  # 32-bit URL-safe base64 key used to encrypt pagination tokens
+  # If one is not provided, it will be generated.
+  # Multiple clair instances in the same cluster need the same value.
+  paginationKey:
+
+  # Optional PKI configuration
+  # If you want to easily generate client certificates and CAs, try the following projects:
+  # https://github.com/coreos/etcd-ca
+  # https://github.com/cloudflare/cfssl
   cafile:
   keyfile:
   certfile:
+
 updater:
-  # Frequency at which the vulnerability updater will run.
-  # Use 0 to disable the updater entirely.
+  # Frequency the database will be updated with vulnerabilities from the default data sources
+  # The value 0 disables the updater entirely.
   interval: 2h
+
 notifier:
-  # Number of attempts that the notifier does when a notification backend fails
-  # before it gives up temporarly and try to d
+  # Number of attempts before the notification is marked as failed to be sent
   attempts: 3
-  # After a notification has been sent
+
+  # Duration before a failed notification is retried
   renotifyInterval: 2h
-  # Configuration for HTTP notifier
+
   http:
-    # Endpoint that will receive notifications with POST requests.
+    # Optional endpoint that will receive notifications via POST requests
     endpoint:
-    # Server name and path to certificates to call the endpoint securely with TLS and client certificate auth.
+
+    # Optional PKI configuration
+    # If you want to easily generate client certificates and CAs, try the following projects:
+    # https://github.com/coreos/etcd-ca
+    # https://github.com/cloudflare/cfssl
     servername:
     cafile:
     keyfile: