Infrastructure/caddy
0
Fork 0
mirror of https://github.com/caddyserver/caddy.git synced 2025-01-13 22:51:08 -05:00
Code Issues Activity

improvements for Linux systemd integration (#1127)

Browse source 
* Remove unnecessary config options from systemd service so it will work with earlier versions of systemd. Simplify the systemd service instructions and make them more complete.

* Minor systemd README improvements.

* Add back some of the optional systemd 229 stuff but commented out for compat.

* A bunch of updates to the README for linux systemd.
This commit is contained in:
Josh Aas 2016-09-23 17:50:39 -05:00 committed by Matt Holt
parent d60a26ae30
commit 3f83eccfbd
2 changed files with 108 additions and 69 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

161
dist/init/linux-systemd/README.md vendored
View file

@ -1,84 +1,127 @@
# systemd unit for caddy # systemd Service Unit for Caddy
Please do not hesitate to ask on Please do not hesitate to ask on
[caddyserver/support](https://gitter.im/caddyserver/support) [caddyserver/support](https://gitter.im/caddyserver/support)
if you have any questions. if you have any questions. Feel free to prepend to your question
Feel free to prepend to your question the username of whoever touched the file most recently, the username of whoever touched the file most recently, for example
for example `@wmark re systemd: …`. `@wmark re systemd: …`.
The provided file is written for **systemd version 229** or later! The provided file should work with systemd version 219 or later. It might work with earlier versions.
The easiest way to check your systemd version is to look at the version of the installed package
(e.g. 'sudo yum info systemd' on RedHat/Fedora systems).
## Quickstart ## Instructions
In the following sections, we will assume that you want to run caddy We will assume the following:
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! * that you want to run caddy as user `www-data` and group `www-data`, with UID and GID 33
* you are working from a non-root user account that can use 'sudo' to execute commands as root
Adjust as necessary or according to your preferences.
First, put the caddy binary in the system wide binary directory and give it
appropriate ownership and permissions:
```bash ```bash
groupadd -g 33 www-data sudo cp /path/to/caddy /usr/local/bin
useradd \ sudo chown root:root /usr/local/bin/caddy
sudo chmod 755 /usr/local/bin/caddy
```
Give the caddy binary the ability to bind to privileged ports (e.g. 80, 443) as a non-root user:
```bash
sudo setcap 'cap_net_bind_service=+ep' /usr/local/bin/caddy
```
Set up the user, group, and directories that will be needed:
```bash
sudo groupadd -g 33 www-data
sudo useradd \
-g www-data --no-user-group \ -g www-data --no-user-group \
--home-dir /var/www --no-create-home \ --home-dir /var/www --no-create-home \
--shell /usr/sbin/nologin \ --shell /usr/sbin/nologin \
--system --uid 33 www-data --system --uid 33 www-data
mkdir /etc/caddy sudo mkdir /etc/caddy
chown -R root:www-data /etc/caddy sudo chown -R root:www-data /etc/caddy
mkdir /etc/ssl/caddy sudo mkdir /etc/ssl/caddy
chown -R www-data:root /etc/ssl/caddy sudo chown -R www-data:root /etc/ssl/caddy
chmod 0770 /etc/ssl/caddy sudo chmod 0770 /etc/ssl/caddy
``` ```
- Install the unit configuration file: `cp caddy.service /etc/systemd/system/` Place your caddy configuration file ("Caddyfile") in the proper directory
- Reload the systemd daemon: `systemctl daemon-reload` and give it appropriate ownership and permissions:
- Make sure to [configure](#configuration) the service unit before starting caddy.
- Start caddy: `systemctl start 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;
you can change that by providing an environment variable `HOME`,
i.e. `Environment=HOME=/var/lib/caddy` will result in `/var/lib/caddy/.caddy`
## Configuration
- 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 arguments in the `ExecStart` directive:
```ini
[Service]
; an empty value clears the original (and preceding) settings
ExecStart=
ExecStart=/usr/local/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:
```bash ```bash
# caddy would run as www-data:www-data sudo cp /path/to/Caddyfile /etc/caddy/
# serving, in this example: /var/www sudo chown www-data:www-data /etc/caddy/Caddyfile
sudo chmod 444 /etc/caddy/Caddyfile
sudo -u www-data -g www-data -s \
ls -hlAS /var/www
# Got an error? Revisit permissions!
``` ```
## Tips Create the home directory for the server and give it appropriate ownership
and permissions:
- Use `log stdout` and `errors stderr` in your Caddyfile to fully utilize **journald**. ```bash
- `journalctl` is *journald's* log query tool. sudo mkdir /var/www
- Did caddy not start? Check the logfiles for any error messages using `journalctl --boot -u caddy.service` sudo chown www-data:www-data /var/www
- To follow caddy's log output: `journalctl -f -u caddy.service` sudo chmod 555 /var/www
- 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`. Let's assume you have the contents of your website in a directory called 'example.com'.
Although if `caddy.service` is all you have, then you can just use `caddy` without any extension, such as in: `systemctl status caddy` Put your website into place for it to be served by caddy:
- You can make other certificates and private key files accessible to a user `www-data` by command `setfacl`, if you must: ```bash
sudo cp -R example.com /var/www/
sudo chown -R www-data:www-data /var/www/example.com
sudo chmod -R 555 /var/www/example.com
```
You'll need to explicity configure caddy to serve the site from this location by adding
the following to your Caddyfile if you haven't already:
```
example.com {
root /var/www/example.com
...
}
```
Install the systemd service unit configuration file, reload the systemd daemon,
and start caddy:
```bash
sudo cp caddy.service /etc/systemd/system/
sudo chown root:root /etc/systemd/system/caddy.service
sudo chmod 744 /etc/systemd/system/caddy.service
sudo systemctl daemon-reload
sudo systemctl start caddy.service
```
Have the caddy service start automatically on boot if you like:
```bash
sudo systemctl enable caddy.service
```
If caddy doesn't seem to start properly you can view the log data to help figure out what the problem is:
```bash
journalctl --boot -u caddy.service
```
Use `log stdout` and `errors stderr` in your Caddyfile to fully utilize systemd journaling.
If your GNU/Linux distribution does not use *journald* with *systemd* then check any logfiles in `/var/log`.
If you want to follow the latest logs from caddy you can do so like this:
```bash
journalctl -f -u caddy.service
```
You can make other certificates and private key files accessible to the `www-data` user with the following command:
```bash ```bash
setfacl -m user:www-data:r-- /etc/ssl/private/my.key setfacl -m user:www-data:r-- /etc/ssl/private/my.key

16
dist/init/linux-systemd/caddy.service vendored
View file

@ -35,16 +35,12 @@ ProtectSystem=full
; This merely retains r/w access rights, it does not add any new. Must still be writable on the host! ; This merely retains r/w access rights, it does not add any new. Must still be writable on the host!
ReadWriteDirectories=/etc/ssl/caddy ReadWriteDirectories=/etc/ssl/caddy
; Drop all other capabilities. Important if you run caddy as privileged user (which you should not). ; The following additional security directives only work with systemd v229 or later.
CapabilityBoundingSet=CAP_NET_BIND_SERVICE ; They further retrict privileges that can be gained by caddy. Uncomment if you like.
; … but permit caddy to open ports reserved for system services. ; Note that you may have to add capabilities required by any plugins in use.
; This could be redundant here, but is needed in case caddy runs as nobody:nogroup. ;CapabilityBoundingSet=CAP_NET_BIND_SERVICE
AmbientCapabilities=CAP_NET_BIND_SERVICE ;AmbientCapabilities=CAP_NET_BIND_SERVICE
; … and prevent gaining any new privileges. ;NoNewPrivileges=true
NoNewPrivileges=true
; Caveat: Some plugins need additional capabilities. Add them to both above lines.
; - plugin "upload" needs: CAP_LEASE
[Install] [Install]
WantedBy=multi-user.target WantedBy=multi-user.target