From bee9c50a71c61962c070c0b700b014d46a5b15ce Mon Sep 17 00:00:00 2001
From: W-Mark Kubacki <wmark@hurrikane.de>
Date: Sat, 21 May 2016 00:29:18 +0200
Subject: [PATCH] systemd, README: needs to be version 229 or later, and how to
 display logs

We have had three operators within a few days which ran into the same cause
and had not been able to figure out what went wrong.

addresses #833, #822
---
 dist/init/linux-systemd/README.md | 42 ++++++++++++++++++-------------
 1 file changed, 24 insertions(+), 18 deletions(-)

diff --git a/dist/init/linux-systemd/README.md b/dist/init/linux-systemd/README.md
index 908954c6d..217630456 100644
--- a/dist/init/linux-systemd/README.md
+++ b/dist/init/linux-systemd/README.md
@@ -1,12 +1,18 @@
 # systemd unit for caddy
 
-Please do not hesitate to ask if you have any questions.
+Please do not hesitate to ask on
+[caddyserver/support](https://gitter.im/caddyserver/support)
+if you have any questions.
+Feel free to prepend to your question the username of whoever touched the file most recently,
+for example `@wmark re systemd: …`.
+
+The provided file is written for **systemd version 229** or later!
 
 ## Quickstart
 
-The provided unit file assumes that you want to run caddy as `www-data` and group `www-data`,
-both having UID and GID 33 here.
-Adjust this to your liking according to the preferences of you Linux distribution!
+In the following sections, we will assume that you want to run caddy
+as user `www-data` and group `www-data`, with UID and GID 33.
+Adjust this to your liking according to the preferences of your Linux distribution!
 
 ```bash
 groupadd -g 33 www-data
@@ -30,25 +36,24 @@ chmod 0770 /etc/ssl/caddy
 - Enable the service (automatically start on boot): `systemctl enable caddy.service`
 - A folder `.caddy` will be created inside the home directory of the user that runs caddy;
   you can change that by providing an environment variable `HOME`,
-  i.e. `Environment=HOME=/var/lib/caddy` will result in `/var/lib/caddy/.caddy`.
+  i.e. `Environment=HOME=/var/lib/caddy` will result in `/var/lib/caddy/.caddy`
 
 ## Configuration
 
-- Do not edit the systemd unit file directly. Instead, use systemd's builtin tools:
+- Prefer `systemctl edit` over modifying the unit file directly:
     - `systemctl edit caddy.service` to make user-local modifications
     - `systemctl edit --full caddy.service` for system-wide ones
-- In most cases it is enough to override the `ExecStart` directive.
-    - systemd needs absolute paths, therefore make sure that the path to caddy is correct.
-    - example:
+- In most cases it is enough to override arguments in the `ExecStart` directive:
 
 ```ini
 [Service]
 ; an empty value clears the original (and preceding) settings
 ExecStart=
-ExecStart=/usr/bin/caddy -conf="/etc/caddy/myCaddy.conf" -agree -email="my@mail.address"
+ExecStart=/usr/bin/caddy -conf="/etc/caddy/myCaddy.conf"
 ```
 
 - To view the resulting configuration use `systemctl cat caddy`
+- systemd needs absolute paths, therefore make sure that the path to caddy is correct.
 - Double check permissions of your *document root* path.
   The user caddy runs as needs to have access to it. For example:
 
@@ -58,21 +63,22 @@ ExecStart=/usr/bin/caddy -conf="/etc/caddy/myCaddy.conf" -agree -email="my@mail.
 
 sudo -u www-data -g www-data -s \
   ls -hlAS /var/www
+
+# Got an error? Revisit permissions!
 ```
 
 ## Tips
 
-- Use `log stdout` and `errors stderr` in your Caddyfile to utilize `journalctl`.
-- `journalctl` is systemd's log query tool.
-- Let's say you want all the log entries since the last boot, beginning from the last entry:
-  `journalctl --reverse --boot --unit caddy.service`
-- To follow caddy's log output: `journalctl -fu caddy.service`
-- Send a signal to a service unit's main PID, e.g. have caddy reload its config:
-  `systemctl kill --signal=USR1 caddy.service`
+- Use `log stdout` and `errors stderr` in your Caddyfile to fully utilize **journald**.
+- `journalctl` is *journald's* log query tool.
+- Did caddy not start? Check the logfiles for any error messages using `journalctl --boot -u caddy.service`
+- To follow caddy's log output: `journalctl -f -u caddy.service`
+- If your GNU/Linux distribution does not use *systemd* with *journald* then check any logfiles in: `/var/log`
+
 - If you have more files that start with `caddy` – like a `caddy.timer`, `caddy.path`, or `caddy.socket` – then it is important to append `.service`.
   Although if `caddy.service` is all you have, then you can just use `caddy` without any extension, such as in: `systemctl status caddy`
 
-- You can make your other certificates and private key files accessible to a user `www-data` by command `setfacl`, if you must:
+- You can make other certificates and private key files accessible to a user `www-data` by command `setfacl`, if you must:
 
 ```bash
 setfacl -m user:www-data:r-- /etc/ssl/private/my.key