From 14eecbf01e541d21316345ab956cccf08d3e9a85 Mon Sep 17 00:00:00 2001
From: William Petit <wpetit@cadoles.com>
Date: Fri, 25 Aug 2023 09:32:00 -0600
Subject: [PATCH] feat: comment packaged agent and server configurations (#1)

---
 misc/packaging/common/config-agent.yml  | 33 +++++++++++++++++-
 misc/packaging/common/config-server.yml | 46 ++++++++++++++++++++++---
 2 files changed, 74 insertions(+), 5 deletions(-)

diff --git a/misc/packaging/common/config-agent.yml b/misc/packaging/common/config-agent.yml
index 7fdaae6..dfcab26 100644
--- a/misc/packaging/common/config-agent.yml
+++ b/misc/packaging/common/config-agent.yml
@@ -1,26 +1,55 @@
+# Emissary agent configuration
+
+# Logger configuration
 logger:
+  # Logging verbosity
+  # DEBUG: 0
+  # INFO: 1
+  # WARN: 2
+  # ERROR: 3
+  # CRITICAL: 4
   level: 1
+  # Logging format
+  # Possible values: human, json
   format: human
+
+# Agent configuration
 agent:
+  # Emissary server URL
   serverUrl: http://127.0.0.1:3000
+  # Agent private key path
   privateKeyPath: /var/lib/emissary/agent-key.json
-  reconciliationInterval: 5
+  # Agent reconciliation interval (in seconds)
+  reconciliationInterval: 30
+
+  # Controllers configuration
   controllers:
+    # Persistence controller configuration
     persistence:
       enabled: true
       stateFile: /var/lib/emissary/state.json
+
+    # Spec controller configuration
     spec:
       enabled: true
+    
+    # Proxy controller configuration
     proxy:
       enabled: true
+
+    # UCI controller configuration
     uci:
       enabled: true
       binPath: uci
       configBackupFile: /var/lib/emissary/uci-backup.conf
+    
+    # App controller configuration
     app:
       enabled: true
       dataDir: /var/lib/emissary/apps/data
       downloadDir: /var/lib/emissary/apps/bundles
+    
+    # Sysupgrade controller configuration
     sysupgrade:
       enabled: true
       sysupgradeCommand:
@@ -33,6 +62,8 @@ agent:
         - sh
         - -c
         - source /etc/openwrt_release && echo "$DISTRIB_ID-$DISTRIB_RELEASE-$DISTRIB_REVISION"
+  
+  # Collectors configuration
   collectors:
     - name: uname
       command: uname
diff --git a/misc/packaging/common/config-server.yml b/misc/packaging/common/config-server.yml
index bf28e04..dc19f03 100644
--- a/misc/packaging/common/config-server.yml
+++ b/misc/packaging/common/config-server.yml
@@ -1,13 +1,38 @@
+# Emissary server configuration
+
+# Logger configuration
 logger:
+  # Logging verbosity
+  # DEBUG: 0
+  # INFO: 1
+  # WARN: 2
+  # ERROR: 3
+  # CRITICAL: 4
   level: 1
+  # Logging format
+  # Possible values: human, json
   format: human
+
+# Server configuration
 server:
+  # HTTP server configuration
   http:
+    # Listening address (0.0.0.0 to listen on all interfaces)
     host: 0.0.0.0
+    # Listening port
     port: 3000
+  
+  # Database configuration
   database:
+    # Database driver
+    # Possible values: sqlite
     driver: sqlite
+    # Database DSN
+    # sqlite: see https://github.com/mattn/go-sqlite3#connection-string
     dsn: sqlite:///var/lib/emissary/data.sqlite?_pragma=foreign_keys(1)&_pragma=busy_timeout=60000
+  
+  # CORS configuration
+  # See https://developer.mozilla.org/en/docs/Glossary/CORS
   cors:
     allowedOrigins: []
     allowCredentials: true
@@ -22,12 +47,25 @@ server:
       - Content-Type
       - Authorization
       - Sentry-Trace
-  debug: false
+  
+  # Auth configuration
   auth:
+    # Local authentication configuration
     local:
       privateKeyPath: /var/lib/emissary/server-key.json
-    roleExtractionRules:
-      - "jwt.role != nil ? str(jwt.role) : ''"
+    
+    # Remote authentication configuration
+    # Disabled by default
     remote: ~
       # jwksUrl: https://my-server/.well-known/jwks.json
-    
+
+    # Role extraction rules
+    # Permit to derivate user's role 
+    # from the received JWT.
+    #
+    # The first rule returning a non empty
+    # string will define the role of the user.
+    #
+    # The role should be 'reader' or 'writer'.
+    roleExtractionRules:
+      - "jwt.role != nil ? str(jwt.role) : ''"