From 9cba3810315fdac68f6f66e1ec0499ff71eb7eaf Mon Sep 17 00:00:00 2001
From: sinkingpoint <colin@quirl.co.nz>
Date: Mon, 25 Oct 2021 12:40:08 +1100
Subject: [PATCH] Update README

---
 README.md   | 87 +++++++++++++++++++++++++++++++++++++++++++++++++++++
 src/main.rs |  2 +-
 2 files changed, 88 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 2fb3ff5..44c85e3 100644
--- a/README.md
+++ b/README.md
@@ -57,6 +57,93 @@ value_total 4
 
 With the counter value being replaced, the gauge value being sumed, and the version value completly replacing the old version. You'll auso note that the clearmode label is removed by the gateway - it's not included in the metrics exposed to the Prometheus scrape. In that way, this aggregating process is completly transparent to the Prometheus.
 
+## Usage
+
+```
+Prometheus Gravel Gateway 
+
+USAGE:
+    gravel-gateway [OPTIONS]
+
+FLAGS:
+    -h, --help       
+            Prints help information
+
+    -V, --version    
+            Prints version information
+
+
+OPTIONS:
+        --basic-auth-file <basic-auth-file>    
+            The file to use for basic authentication validation.
+                            This should be a path to a file of bcrypt hashes, one per line,
+                            with each line being an allowed hash.
+    -l <listen>                                
+            The address/port to listen on [default: localhost:4278]
+
+        --tls-cert <tls-cert>                  
+            The certificate file to use with TLS
+
+        --tls-key <tls-key>                    
+            The private key file to use with TLS
+```
+
+To use, run the gateway:
+
+```
+gravel-gateway
+```
+
+You can then make POSTs to /metrics to push metrics:
+
+```bash
+echo '# TYPE value_total counter
+value_total{clearmode="replace"} 3
+# TYPE value2 gauge
+value2{clearmode="aggregate"} 1
+# TYPE version gauge
+version{version="0.0.2",clearmode="family"} 1' | curl --data-binary @- localhost:4278/metrics
+```
+
+And point Prometheus at it to scrape:
+
+```
+global:
+  scrape_interval: 15s
+  evaluation_interval: 30s
+scrape_configs:
+  - job_name: prometheus
+    honor_labels: true
+    static_configs:
+      - targets: ["127.0.0.1:4278"]
+```
+
+### Authentication
+
+Gravel Gateway supports (pseudo) Basic autentication (with the auth feature). To use, populate a file with bcrypt hashes, 1 per line, e.g.
+
+```bash
+htpasswd -bnBC 10 "" supersecrets | tr -d ':\n' > passwords
+```
+
+and then start gravel-gateway pointing to that file:
+
+```bash
+gravel-gateway --basic-auth-file ./passwords
+```
+
+Requests to the POST /metrics endpoint will then be rejected unless they contain a valid `Authorization` header:
+
+```
+curl http://localhost:4278/metrics -vvv --data-binary @metrics.txt -H "Authorization: Basic supersecrets"
+```
+
+You'll note that we don't base64 the authorization header, so it's not _technically_ Basic Auth, but I don't like Base64ing it because I believe that gives a false sense of security. Instead, you should enable TLS
+
+### TLS
+
+TLS is provided by the `tls-key` and `tls-cert` args. Both are required to start a TLS server, and represent the private key, and the certificate that is presented respectivly.
+
 ## Motivation
 I [recently wrote](https://blog.sinkingpoint.com/posts/prometheus-for-faas/) about my frustrations with trying to orchestrate Prometheus in an FAAS (Functions-As-A-Service) system that will rename nameless.
 My key frustration was that the number of semantics I was trying to extract from my Prometheus metrics was too much for the limited amount of data you can 
diff --git a/src/main.rs b/src/main.rs
index 109cd33..705c986 100644
--- a/src/main.rs
+++ b/src/main.rs
@@ -17,7 +17,7 @@ mod auth;
 async fn main() {
     let agg = Aggregator::new();
 
-    let app = App::new("notes-thing backend")
+    let app = App::new("Prometheus Gravel Gateway")
         .arg(
             Arg::with_name("listen")
                 .short("l")