diff options
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 57 |
1 files changed, 38 insertions, 19 deletions
@@ -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 |