From 615735dc018c5ef12fe7e3359998b8cffaa39a5a Mon Sep 17 00:00:00 2001
From: Stuart Stock <stuart@int08h.com>
Date: Tue, 2 Oct 2018 19:11:47 -0500
Subject: Final touches and bow-tieing on configuration. Update README to
 reflect.

---
 README.md | 57 ++++++++++++++++++++++++++++++++++++++-------------------
 1 file changed, 38 insertions(+), 19 deletions(-)

(limited to 'README.md')

diff --git a/README.md b/README.md
index fc8f83e..d369aef 100644
--- a/README.md
+++ b/README.md
@@ -6,12 +6,11 @@
 **Roughenough** is a [Roughtime](https://roughtime.googlesource.com/roughtime) secure time 
 synchronization client and server implementation in Rust. 
 
-The server and client are functionally complete and at feature parity with the reference 
-C++ and Golang implementations. 
+Roughenough's server and client are functionally complete and 
+at feature parity with the reference C++ and Golang implementations. 
 
-Requires latest stable Rust to compile. Areas for improvement remain, 
-see [limitations](#limitations) below. Contributions are welcome, see
-[CONTRIBUTING](../master/CONTRIBUTING.md) for instructions.
+Requires latest stable Rust to compile. Contribution welcome, see
+[CONTRIBUTING](../master/CONTRIBUTING.md) for instructions and [limitations](#limitations) for areas that could use attention.
 
 ## Links
 * [Roughenough Github repo](https://github.com/int08h/roughenough)
@@ -82,9 +81,26 @@ $ cp target/release/server /usr/local/bin
 $ /usr/local/bin/server /path/to/config.file
 ```
 
-### Configuration File
+### Server Configuration
 
-The server is configured via a YAML file:
+There are two (mutually exclusive) ways to configure the Roughenough server: 
+
+1. A YAML file, or
+2. Environment variables
+
+The server accepts the following configuration parameters:
+
+YAML Key | Environment Variable | Necessity | Description
+--- | --- | --- | ---
+`interface` | `ROUGHENOUGH_INTERFACE` | Required | IP address or interface name for listening to client requests
+`port` | `ROUGHENOUGH_PORT` | Required | UDP port to listen for requests
+`seed` | `ROUGHENOUGH_SEED` | Required | A 32-byte hexadecimal value used to generate the server's long-term key pair. **This is a secret value and must be un-guessable**, treat it with care.
+`batch_size` | `ROUGHENOUGH_BATCH_SIZE` | Optional | The maximum number of requests to process in one batch. All nonces in a batch are used to build a Merkle tree, the root of which is signed. Default is `64` requests per batch.
+`status_interval` | `ROUGHENOUGH_STATUS_INTERVAL` | Optional | Number of _seconds_ between each logged status update. Default is `600` seconds (10 minutes).
+
+#### YAML Configuration 
+
+The table above lists the YAML keys available in the config file. An example:
 
 ```yaml
 interface: 127.0.0.1
@@ -92,19 +108,22 @@ port: 8686
 seed: f61075c988feb9cb700a4a6a3291bfbc9cab11b9c9eca8c802468eb38a43d7d3
 ```
 
-Where:
+Provide the config file as the single command-line argument to the Roughenough server binary:
 
-* **`interface`** - [Mandatory] IP address or interface name for listening to client requests
-* **`port`** - [Mandatory] UDP port to listen for requests
-* **`seed`** - [Mandatory] A 32-byte hexadecimal value used to generate the server's long-term 
-               key pair. **This is a secret value and must be un-guessable**, 
-               treat it with care.
-* **`batch_size`** - [Optional] The maximum number of requests to process in one batch. All nonces
-                   in a batch are used to build a Merkle tree, the root of which
-                   is signed. Default is 64 requests per batch.
-* **`status_interval`** - [Optional] Number of _seconds_ between each logged status update. 
-                   Default is 600 seconds (10 minutes).
+```bash
+$ /path/to/server /path/to/config.yaml
+```
+
+#### Environment Configuration
+
+Roughenough can be configured via the `ROUGHENOUGH_*` [environment variables](https://12factor.net/config) listed in the table above. Example:
 
+```bash
+$ export ROUGHENOUGH_INTERFACE=127.0.0.1
+$ export ROUGHENOUGH_PORT=8686
+$ export ROUGHENOUGH_SEED=f61075c988feb9cb700a4a6a3291bfbc9cab11b9c9eca8c802468eb38a43d7d3
+$ /path/to/server
+```
 
 ### Stopping the Server
 
@@ -114,7 +133,7 @@ Use Ctrl-C or `kill` the process.
 
 Roughtime features not implemented by the server:
 
-* On-line key rotation. The server must be restarted to generate a new delegated key. 
+* On-line (while server is running) key rotation. The server must be restarted to generate a new delegated key. 
 * The Rougheough server depends on the host's time source to comply with the smeared leap-second 
   requirement of the Roughtime protocol. A Roughenough server sourcing time from 
   [Google's public NTP servers](https://developers.google.com/time/) would produce compliant
-- 
cgit v1.2.3