From a5abe80eca5645e2f94ae23e2b975608993217a3 Mon Sep 17 00:00:00 2001
From: Magnus Ahltorp <map@kth.se>
Date: Wed, 26 Jul 2017 02:37:54 +0200
Subject: Add descriptions to log configuration man page

---
 doc/catlfish-log.cfg.in.5.adoc | 73 +++++++++++++++++++++++++++---------------
 1 file changed, 47 insertions(+), 26 deletions(-)

(limited to 'doc/catlfish-log.cfg.in.5.adoc')

diff --git a/doc/catlfish-log.cfg.in.5.adoc b/doc/catlfish-log.cfg.in.5.adoc
index 43559cc..1f89aa2 100644
--- a/doc/catlfish-log.cfg.in.5.adoc
+++ b/doc/catlfish-log.cfg.in.5.adoc
@@ -10,61 +10,76 @@ catlfish-log.cfg.in - catlfish log configuration
 OPTIONS
 -------
    **apikeys**: (list of items)::
-//    write description here
+      List of internal API keys.
+      Automatically added by the genconfig.sh script.
 
       **nodename**: __nodename__:::
-//       write description here
+          Name of the node, e.g. __frontend-1__
 
       **publickey**: __key__:::
           BASE64-encoded key
 
    **backup-quorum-size**: __number-of-nodes__::
-       number of secondary merge nodes that need to have an entry before the entry is considered committed
+       Number of secondary merge nodes that need to have an entry
+       before the entry is considered properly sequenced.
 
    **baseurl**: __url__::
-//    write description here
+       Base URL for the log
 
    **cafingerprint**: __fingerprint__::
-//    write description here
+      SHA256 fingerprint of the Certificate Authority certificate that
+      signs the X.509 certificates used by the internal API endpoints.
+      Automatically added by the genconfig.sh script.
 
    **frontendnodes**: (list of items)::
-//    write description here
+      Frontend nodes are the nodes that are visible to the outside world.
+      They accept submissions and answer read requests.
 
       **address**: __ip-address__:::
-//       write description here
+         IP address and port for the internal API, e.g. __10.0.0.1:8443__.
 
       **name**: __nodename__:::
-//       write description here
+         Name of the node, e.g. __frontend-1__.
 
       **publicaddress**: __ip-address__:::
-//       write description here
-
+         IP address and port for the external API, e.g. __10.0.0.1:443__.
+      
    **logpublickey**: __key__::
-//    write description here
+      The log's public key in BASE64.
+      Automatically added by the genconfig.sh script.
 
    **mergenodes**: (list of items)::
-//    write description here
+      Merge nodes are responsible for gathering the submissions from
+      the storage nodes, sequence them, and distributing the completed
+      log to the frontend nodes.
 
       **address**: __ip-address__:::
-//       write description here
+          IP address and port for the internal API, e.g. __10.0.0.1:8443__.
+          This is only used by non-primary merge nodes, but since all
+          merge nodes are both potential primary and non-primary nodes,
+          this should be specified on all nodes.
 
       **name**: __nodename__:::
-//       write description here
+          Name of the node, e.g. __merge-1__.
 
    **mmd**: __seconds__::
-//    write description here
+      Maximum Merge Delay, the longest time between submission of a
+      certificate until it appears on the frontend servers.
 
    **primarymergenode**: __nodename__::
-//    write description here
+      The name of the node that will perform the actual merge process.
+      The other merge nodes will act as backup nodes.
 
    **signingnodes**: (list of items)::
-//    write description here
+      Signing nodes have access to the private key of the log. They
+      sign SCTs on behalf of frontend nodes and sign STHs on behalf of
+      merge nodes.
 
       **address**: __ip-address__:::
-//       write description here
+          IP address and port for the internal API, e.g. __10.0.0.1:8443__
 
       **name**: __nodename__:::
-//       write description here
+          Name of the node, e.g. __signing-1__
 
    **statusservers**: (list of items)::
 //    write description here
@@ -79,20 +94,26 @@ OPTIONS
 //       write description here
 
    **storage-quorum-size**: __number-of-nodes__::
-//    write description here
+      Number of storage nodes that need to have an entry
+      before a frontend node replies that the entry has been
+      received.
 
    **storage-sign-quorum-size**: __number-of-nodes__ (default: 0)::
-//    write description here
+      Number of storage nodes that need to have an entry
+      before the signing node produced an SCT.
 
    **storagenodes**: (list of items)::
-//    write description here
+      A storage node is run on the same server as a frontend node and
+      shares a database with it, but receives entries from all frontend
+      nodes.
 
       **address**: __ip-address__:::
-//       write description here
+         IP address and port for the internal API, e.g. __10.0.0.1:8443__.
 
       **name**: __nodename__:::
-//       write description here
+         Name of the node. Normally the same as the frontend node that it
+         shares its database with.
 
    **version**: __version__::
-//    write description here
-
+      Version of the configuration file.
+      Automatically added by the genconfig.sh script.
-- 
cgit v1.1

