Commit bee9c50a authored by W-Mark Kubacki's avatar W-Mark Kubacki

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
parent bac29cc2
# 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
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment