Update docs for new --config option

Author: brunorijsman

TODO

@@ -61,7 +61,7 @@ TODO: Testcase for invalid signature
 
 TODO: Test case for: if signature validation fails, return fragment to pool
 
-TODO: Error message if --client or --hub does not exist in topology
+TODO: Error message if --client or --hub does not exist in configuration
 
 TODO: Check SAE IDs on GET share, just as we do for POST share
 

common/configuration.py

@@ -1,5 +1,5 @@
 """
-Configuration for a DSKE topology.
+Configuration for DSKE manager.
 """
 
 import pprint
@@ -9,12 +9,11 @@
 from common.node import Node, NodeType
 
 DEFAULT_BASE_PORT = 8100
-DEFAULT_CONFIGURATION_FILE = "topology.yaml"
 
 
 class Configuration:
     """
-    Configuration for a DSKE topology.
+    Configuration for the DSKE manager.
     """
 
     _nodes: list[Node]
@@ -44,7 +43,7 @@ def _assign_ports_and_urls(self):
             port += 1
 
 
-def parse_configuration_file(filename: str = DEFAULT_CONFIGURATION_FILE):
+def parse_configuration_file(filename: str):
     """
     Parse the configuration file.
     """

docs/developer-guide.md

@@ -86,7 +86,7 @@ $ <b>open htmlcov/index.html</b>
 For full and up-to-date documentation of the API endpoints, each network node provides OpenAPI
 documentation.
 To view the documentation go to URL `http://localhost:PORT/docs` where PORT is the port number
-for the network node as reported when the topology is started.
+for the network node as reported when the network is started.
 
 Here we provide a summary of the API endpoints and their purpose.
 

docs/getting-started-guide.md

@@ -66,12 +66,12 @@ Install de dependencies:
 pip install -r requirements.txt
 ```
 
-## The example topology
+## The default configuration
 
-View the example topology file `topology.yaml`:
+View the default configuration file `dske-config.yaml`:
 
 ```
-$ cat topology.yaml
+$ cat dske-config.yaml
 hubs:
   - name: hank
   - name: helen
@@ -95,7 +95,7 @@ clients:
       - name: susan
 ```
 
-This is a diagram of the topology:
+This is a diagram of the network topology::
 
 ![Topology diagram](figures/topology.png)
 
@@ -105,13 +105,12 @@ The `manager.py` is used to manage topologies.
 Use the `--help` option to see how it is used:
 
 ```
-$ ./manager.py topology.yaml --help
-usage: manager.py [-h] [--client CLIENT | --hub HUB] configfile {start,stop,status,etsi-qkd} ...
+$ ./manager.py --help
+usage: manager.py [-h] [--config CONFIG_FILE] [--client CLIENT] [--hub HUB] {start,stop,status,etsi-qkd} ...
 
 DSKE Manager
 
 positional arguments:
-  configfile            Configuration filename
   {start,stop,status,etsi-qkd}
     start               Start all hubs and clients
     stop                Stop all hubs and clients
@@ -120,6 +119,7 @@ positional arguments:
 
 options:
   -h, --help            show this help message and exit
+  --config CONFIG_FILE  Configuration file name (default: dske-config.yaml)
   --client CLIENT       Filter on client name
   --hub HUB             Filter on hub name
 ```
@@ -138,7 +138,7 @@ Start a capture on loopback interface `lo0` and filter on HTTP messages.
 Use the `manager.py` script to start the topology:
 
 ```
-$ ./manager.py topology.yaml start
+$ ./manager.py start
 Waiting for all nodes to be stopped
 Starting hub hank on port 8100
 Starting hub helen on port 8101
@@ -172,7 +172,7 @@ You will get different key IDs and key values, but they should match.
 
 
 ```
-$ ./manager.py topology.yaml etsi-qkd sam sofia get-key-pair
+$ ./manager.py etsi-qkd sam sofia get-key-pair
 Invoke ETSI QKD Get Key API on client (KME) carol port 8105 master encryptor (SAE) sam slave encryptor (SAE) sofia:
 {
   "keys": {
@@ -204,7 +204,7 @@ The protocol is explained in the [protocol guide](protocol-guide.md).
 Use the `manager.py` script to view the internal state of a node, in this case client carol:
 
 ```
-$ ./manager.py topology.yaml --client carol status
+$ ./manager.py --client carol status
 Status for client carol on port 8105
 {
   "name": "carol",
@@ -250,7 +250,7 @@ Status for client carol on port 8105
 Use the `manager.py` script to stop the topology:
 
 ```
-$ ./manager.py topology.yaml stop
+$ ./manager.py stop
 Stopping client curtis on port 8109
 Stopping client connie on port 8108
 Stopping client cindy on port 8107

docs/protocol-guide.md

@@ -41,7 +41,7 @@ We say "inspired by" because:
 ## Network topology
 
 The following figure shows the topology that we use in all of our examples and which is specified
-in file `topology.yaml`:
+in file `dske-config.yaml`:
 
 ![Example network topology](figures/topology.png)
 

docs/user-guide.md

@@ -19,19 +19,19 @@ For a detailed description of the DSKE protocol, see the
 If you are a software developer and would like more details about the implementation, see the
 [developer guide](developer-guide.md).
 
-## Topology file
+## Configuration file
 
-We first need a topology YAML file which describes the topology of the network.
+We first need a configuration YAML file which describes the topology of the network.
 It lists the names of 
 the DSKE security hubs (hubs for short),
 the DSKE clients (clients for short),
 and the encryptors.
 .
 
-The repository contains an example `topology.yaml` file:
+The repository contains an example `dske-config.yaml` file, which is the default configuration:
 
 <pre>
-$ <b>cat topology.yaml</b>
+$ <b>cat dske-config.yaml</b>
 hubs:
   - name: hank
   - name: helen
@@ -88,7 +88,7 @@ options:
 You can also use the `--help` option to see the command line parameters for a specific sub-command:
 
 <pre>
-$ <b>./manager.py topology.yaml etsi-qkd --help</b>
+$ <b>./manager.py etsi-qkd --help</b>
 usage: manager.py configfile etsi-qkd [-h] master_sae_id slave_sae_id {get-status,get-key,get-key-with-key-ids,get-key-pair} ...
 
 positional arguments:
@@ -110,7 +110,7 @@ options:
 To start all nodes in the DSKE topology, use the manager `start` command:
 
 <pre>
-$ <b>./manager.py topology.yaml start</b>
+$ <b>./manager.py start</b>
 Waiting for all nodes to be stopped
 Starting hub hank on port 8100
 Starting hub helen on port 8101
@@ -125,9 +125,6 @@ Starting client curtis on port 8109
 Waiting for all nodes to be started
 </pre>
 
-`topology.yaml` is the topology file that specifies the names of the hubs and clients that
-are part of the topology.
-
 The output reports that 10 nodes are started in total: 5 hub nodes (hank, helen, hilary, holly,
 and hugo) and 5 client nodes (carol, celia, cindy, connie, and curtis).
 
@@ -139,7 +136,7 @@ each node.
 To stop all nodes in the topology, use the manager `stop` command:
 
 <pre>
-$ <b>./manager.py topology.yaml stop</b>
+$ <b>./manager.py stop</b>
 Stopping client curtis on port 8109
 Stopping client connie on port 8108
 Stopping client cindy on port 8107
@@ -182,7 +179,7 @@ This is why the `start` command explicitly waits for all nodes to be started (it
 reports `Waiting for all nodes to be started` at the end):
 
 <pre>
-$ <b>./manager.py topology.yaml start</b>
+$ <b>./manager.py start</b>
 Waiting for all nodes to be stopped
 Starting hub hank on port 8100
 ...
@@ -200,7 +197,7 @@ This is why the `start` command explicitly waits for all needed TCP ports to be
 (it reports `Waiting for all nodes to be stopped` at the beginning).
 
 <pre>
-$ <b>./manager.py topology.yaml start</b>
+$ <b>./manager.py start</b>
 <b>Waiting for all nodes to be stopped</b>
 Starting hub hank on port 8100
 ...
@@ -213,7 +210,7 @@ If it takes longer than expected for a node to stop and for the TCP port to beco
 waiting (this should not take longer than 60 seconds):
 
 <pre>
-$ <b>./manager.py topology.yaml stop</b>
+$ <b>./manager.py stop</b>
 Stopping client curtis on port 8109
 ...
 Stopping hub hank on port 8100
@@ -230,7 +227,7 @@ client node.
 For example, to start one individual client carol:
 
 <pre>
-$ <b>./manager.py topology.yaml --client carol start</b>
+$ <b>./manager.py --client carol start</b>
 Waiting for client carol to be stopped
 Starting client carol on port 8105
 Waiting for client carol to be started
@@ -241,15 +238,15 @@ hub node.
 For example, to stop one individual hub hugo:
 
 <pre>
-$ <b>./manager.py topology.yaml --hub hugo stop</b>
+$ <b>./manager.py --hub hugo stop</b>
 Stopping hub hugo on port 8104
 Waiting for hub hugo to be stopped
 </pre>
 
 You can use the `--client` and `--hub` command line options multiple times.
 For example:
 
-<pre>$ <b>./manager.py topology.yaml --client carol --client corrie --hub hank start</b>
+<pre>$ <b>./manager.py --client carol --client corrie --hub hank start</b>
 Waiting for client carol, client corrie, hub hank to be stopped
 Starting hub hank on port 8100
 Starting client carol on port 8105
@@ -328,7 +325,7 @@ Use the manager `get-key` sub-command under the `etsi-qkd` command to invoke the
 The `get-key` sub-command has the following command-line options:
 
 <pre>
-$ <b>./manager.py topology.yaml etsi-qkd sam sunny get-key --help</b>
+$ <b>./manager.py etsi-qkd sam sunny get-key --help</b>
 usage: manager.py configfile etsi-qkd master_sae_id slave_sae_id get-key [-h] [--size SIZE]
 
 options:
@@ -340,7 +337,7 @@ In the following example we invoke the Get Key API for the QKD link between mast
 slave SAE Serena:
 
 <pre>
- $ <b>./manager.py topology.yaml etsi-qkd sam serena get-key</b>
+ $ <b>./manager.py etsi-qkd sam serena get-key</b>
 Invoke ETSI QKD Get Key API on client (KME) carol port 8105 master encryptor (SAE) sam slave encryptor (SAE) serena:
 {
   "keys": {
@@ -360,7 +357,7 @@ ETSI QKD 014 "Get Key" API to retrieve a key for a pair of SAEs on the slave SAE
 The `get-key` sub-command has the following command-line options:
 
 <pre>
-$ <b>./manager.py topology.yaml etsi-qkd sam serena get-key-with-key-ids --help</b>
+$ <b>./manager.py etsi-qkd sam serena get-key-with-key-ids --help</b>
 usage: manager.py configfile etsi-qkd master_sae_id slave_sae_id get-key-with-key-ids [-h] key_id
 
 positional arguments:
@@ -375,7 +372,7 @@ SAE Sam and slave SAE Serena, where the Key ID is d6a116f1-104e-4213-8cf1-0557cf
 Key ID returned by the Get Key API call above):
 
 <pre>
-$ <b>./manager.py topology.yaml etsi-qkd sam serena get-key-with-key-ids 6a116f1-104e-4213-8cf1-0557cf33cb29</b>
+$ <b>./manager.py etsi-qkd sam serena get-key-with-key-ids 6a116f1-104e-4213-8cf1-0557cf33cb29</b>
 Invoke ETSI QKD Get Key with Key IDs API on client (KME) celia port 8106 master encryptor (SAE) sam slave encryptor (SAE) serena:
 {
   "keys": [
@@ -395,7 +392,7 @@ As a matter of convenience, there is also a `get-key-pair` sub-command to combin
 The `get-key-pair` sub-command has the following command-line options:
 
 <pre>
-$ <b>./manager.py topology.yaml etsi-qkd carol curtis get-key-pair --help</b>
+$ <b>./manager.py etsi-qkd carol curtis get-key-pair --help</b>
 usage: manager.py configfile etsi-qkd master_sae_id slave_sae_id get-key-pair [-h] [--size SIZE]
 
 options:
@@ -406,7 +403,7 @@ options:
 In the following example, we ask for a key pair between master SAE Sam and slave SAE Sunny:
 
 <pre>
-$ <b>./manager.py topology.yaml etsi-qkd sam sunny get-key-pair</b>
+$ <b>./manager.py etsi-qkd sam sunny get-key-pair</b>
 Invoke ETSI QKD Get Key API on client (KME) carol port 8105 master encryptor (SAE) sam slave encryptor (SAE) sunny:
 {
   "keys": {
@@ -429,7 +426,7 @@ Key values match
 And, finally, there is a `status` subcommand to invoke the "Status" ETSI QKD 014 API:
 
 <pre>
-$ <b<>./manager.py topology.yaml etsi-qkd sam sunny get-status</b>
+$ <b<>./manager.py etsi-qkd sam sunny get-status</b>
 Invoke ETSI QKD Status API on client (KME) carol port 8105 master encryptor (SAE) sam slave encryptor (SAE) sunny:
 {
   "source_kme_id": "carol",
@@ -452,7 +449,7 @@ Use the manager `status` command (not to be confused with the `etsi-qkd status`
 to report the status of each node in the topology:
 
 <pre>
-$ <b>./manager.py topology.yaml status</b>
+$ <b>./manager.py status</b>
 Status for hub hank on port 8100
 {
   "name": "hank",
@@ -493,7 +490,7 @@ You can also use the `--client` or `--hub` command-line option to only report th
 client or hub node, for example:
 
 <pre>
-$ <b>./manager.py topology.yaml --client celia status</b>
+$ <b>./manager.py --client celia status</b>
 Status for hub hank on port 8100
 {
   "name": "hank",
@@ -537,7 +534,7 @@ A useful trick is to use the `tail -n +2` command to skip the first line of outp
 the remaining output (which is JSON) through the `jq` command to colorize the JSON output:
 
 <pre>
-$ <b>./manager.py topology.yaml --client carol status | tail -n +2 | jq</b>
+$ <b>./manager.py --client carol status | tail -n +2 | jq</b>
 {
   "name": "carol",
   "encryptor_names": [
@@ -583,7 +580,7 @@ In the following example we display the information about the local pool for pee
 on client carol:
 
 <pre>
-$ <b>./manager.py topology.yaml --client carol status | tail -n +2 | jq '(.peer_hubs[] | select(.hub_name == "hank") .local_pool)'</b>
+$ <b>./manager.py --client carol status | tail -n +2 | jq '(.peer_hubs[] | select(.hub_name == "hank") .local_pool)'</b>
 {
   "blocks": [
     {