From b79d65923d03f954f700295e77cb7eccf1908fe0 Mon Sep 17 00:00:00 2001
From: zimbatm <zimbatm@zimbatm.com>
Date: Tue, 19 Jul 2022 20:40:28 +0200
Subject: [PATCH] README: refactor the text a bit

---
 README.md | 71 ++++++++++++++++++++++++++++++++++++++++---------------
 1 file changed, 52 insertions(+), 19 deletions(-)

diff --git a/README.md b/README.md
index 8cd866e..c34f952 100644
--- a/README.md
+++ b/README.md
@@ -1,13 +1,16 @@
-# systemd-vaultd
+# systemd-vaultd - load vault credentials with systemd units
 
-systemd-vaultd is a proxy between systemd and [vault
-agent](https://vaultproject.io). It provides a unix socket that can be used in
-systemd services in the `LoadCredential` option and then waits for vault agent
-to write these secrets at `/run/systemd-vaultd/<service_name>-<secret_name>`.
+> Mostly written in a train
+- Jörg Thalheim
 
-## Systemd's `LoadCredential` option
+This project's goal is to simplify the loading of [HashiCorp
+Vault](https://www.vaultproject.io/) secrets from
+[systemd](https://systemd.io/) units.
 
-Systemd has an option called `LoadCredentials` that allows to provide credentials to a service:
+## Problem statement
+
+Systemd has an option called `LoadCredentials` that allows to provide
+credentials to a service:
 
 ```conf
 # myservice.service
@@ -16,15 +19,28 @@ ExecStart=/usr/bin/myservice.sh
 LoadCredential=foobar:/etc/myfoobarcredential.txt
 ```
 
-In this case systemd will load credential the file `/etc/myfoobarcredential.txt`
-and provide it to the service at `$CREDENTIAL_PATH/foobar`.
+In this case systemd will load credential the file
+`/etc/myfoobarcredential.txt` and provide it to the service at
+`$CREDENTIAL_PATH/foobar`.
+
+It's handy because it bypasses file permission issues.
+/etc/myfoobarcredential.txt can be owned by root, and the unit run as a
+different or dynamic user.
+
+While vault agent also supports writing these secrets, a major issue is that
+the consumer service may be started before vault agent was able to retrieve
+secrets from vault. In that case, systemd would fail to start the service.
 
-While vault agent also supports writing these secrets, a service may be started
-before vault agent was able to retrieve secrets from vault, in which case
-systemd would fail to start the service.
+## The solution
 
-Here is where `systemd-vaultd` is put to use: In additional to normal paths,
-systemd also supports loading credentials from unix sockets.
+In order to do so, I wrote a `systemd-vaultd` service which acts as a proxy
+between systemd and vault agent that is running on the machine. It provides a
+unix socket that can be used in systemd services in the `LoadCredential`
+option and then waits for vault agent to write these secrets at
+`/run/systemd-vaultd/<service_name>-<secret_name>`.
+
+We take advantage that in addition to normal paths, systemd also supports
+loading credentials from unix sockets.
 
 With `systemd-vaultd` the service `myservice.service` would look like this:
 
@@ -43,17 +59,34 @@ template {
 }
 ```
 
-When `myservice` is started, systemd will open a connection to `systemd-vaultd`'s socket.
-`systemd-vaultd` then either serve the secrets from `/run/systemd-vaultd/secrets/myservice.service-foo`
-or it waits with inotify on secret directory for vault agent to write the secret.
+When `myservice` is started, systemd will open a connection to
+`systemd-vaultd`'s socket.  `systemd-vaultd` then either serve the secrets
+from `/run/systemd-vaultd/secrets/myservice.service-foo` or it waits with
+inotify on secret directory for vault agent to write the secret.
+
+⋈
 
 ## Installation
 
 The installation requires a `go` compiler and `make` to be installed.
 
-This command will install the `systemd-vaultd` binary to `/usr/bin/systemd-vaultd` as well
-as installing a following systemd unit files: `systemd-vaultd.service`, `systemd-vaultd.socket`:
+This command will install the `systemd-vaultd` binary to
+`/usr/bin/systemd-vaultd` as well as installing a following systemd unit
+files: `systemd-vaultd.service`, `systemd-vaultd.socket`:
 
 ```shell
 make install
 ```
+
+## License
+
+Copyright (c) 2022 [Jörg Thalheim](https://github.com/mic92) and contributors.
+
+This project is free software, and may be redistributed under the terms
+specified in the [LICENSE](LICENSE) file.
+
+## About
+
+This project is maintained by Numtide.
+
+Need help or support? [Contact us](https://numtide.com/contact)