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 # 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 ## Quickstart
The provided unit file assumes that you want to run caddy as `www-data` and group `www-data`, In the following sections, we will assume that you want to run caddy
both having UID and GID 33 here. as user `www-data` and group `www-data`, with UID and GID 33.
Adjust this to your liking according to the preferences of you Linux distribution! Adjust this to your liking according to the preferences of your Linux distribution!
```bash ```bash
groupadd -g 33 www-data groupadd -g 33 www-data
...@@ -30,25 +36,24 @@ chmod 0770 /etc/ssl/caddy ...@@ -30,25 +36,24 @@ chmod 0770 /etc/ssl/caddy
- Enable the service (automatically start on boot): `systemctl enable caddy.service` - 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; - 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`, 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 ## 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 caddy.service` to make user-local modifications
- `systemctl edit --full caddy.service` for system-wide ones - `systemctl edit --full caddy.service` for system-wide ones
- In most cases it is enough to override the `ExecStart` directive. - In most cases it is enough to override arguments in the `ExecStart` directive:
- systemd needs absolute paths, therefore make sure that the path to caddy is correct.
- example:
```ini ```ini
[Service] [Service]
; an empty value clears the original (and preceding) settings ; an empty value clears the original (and preceding) settings
ExecStart= 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` - 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. - Double check permissions of your *document root* path.
The user caddy runs as needs to have access to it. For example: 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. ...@@ -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 \ sudo -u www-data -g www-data -s \
ls -hlAS /var/www ls -hlAS /var/www
# Got an error? Revisit permissions!
``` ```
## Tips ## Tips
- Use `log stdout` and `errors stderr` in your Caddyfile to utilize `journalctl`. - Use `log stdout` and `errors stderr` in your Caddyfile to fully utilize **journald**.
- `journalctl` is systemd's log query tool. - `journalctl` is *journald's* log query tool.
- Let's say you want all the log entries since the last boot, beginning from the last entry: - Did caddy not start? Check the logfiles for any error messages using `journalctl --boot -u caddy.service`
`journalctl --reverse --boot --unit caddy.service` - To follow caddy's log output: `journalctl -f -u caddy.service`
- To follow caddy's log output: `journalctl -fu caddy.service` - If your GNU/Linux distribution does not use *systemd* with *journald* then check any logfiles in: `/var/log`
- Send a signal to a service unit's main PID, e.g. have caddy reload its config:
`systemctl kill --signal=USR1 caddy.service`
- 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`. - 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` 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 ```bash
setfacl -m user:www-data:r-- /etc/ssl/private/my.key 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