98cf5d0163
* feat: add support for systemd socket activation If webhook has been launched via systemd socket activation, simply use the systemd-provided socket rather than opening our own. * docs: documentation for the systemd socket activation mode * refactor: moved setuid and setgid flags into platform-specific section The setuid and setgid flags do not work on Windows, so moved them to platform_unix so they are only added to the flag set on compatible platforms. Also disallow the use of setuid and setgid in combination with -socket, since a setuid webhook process would not be able to clean up a socket that was created while running as root. If you _need_ to have the socket owned by root but the webhook process running as a normal user, you can achieve the same effect with systemd socket activation.
2.5 KiB
Using systemd socket activation
New in v2.9.0
On platforms that use systemd, webhook supports the socket activation mechanism. In this mode, systemd itself is responsible for managing the listening socket, and it launches webhook the first time it receives a request on the socket. This has a number of advantages over the standard mode:
- webhook can run as a normal user while still being able to use a port number like 80 or 443 that would normally require root privilege
- if the webhook process dies and is restarted, pending connections are not dropped - they just keep waiting until the restarted webhook is ready
No special configuration is necessary to tell webhook that socket activation is being used - socket activation sets specific environment variables when launching the activated service, if webhook detects these variables it will ignore the -port and -socket options and simply use the systemd-provided socket instead of opening its own.
Configuration
To run webhook with socket activation you need to create two separate unit files in your systemd configuration directory (typically /etc/systemd/system), one for the socket and one for the service. They must have matching names; in this example we use webhook.socket and webhook.service. At their simplest, these files should look like:
webhook.socket
[Unit]
Description=Webhook server socket
[Socket]
# Listen on all network interfaces, port 9000
ListenStream=9000
# Alternatives:
## Listen on one specific interface only
# ListenStream=10.0.0.1:9000
# FreeBind=true
## Listen on a Unix domain socket
# ListenStream=/tmp/webhook.sock
[Install]
WantedBy=multi-user.target
webhook.service
[Unit]
Description=Webhook server
[Service]
Type=exec
ExecStart=webhook -nopanic -hooks /etc/webhook/hooks.yml
# Which user should the webhooks run as?
User=nobody
Group=nogroup
You should enable and start the socket, but it is not necessary to enable the service - this will be started automatically when the socket receives its first request.
sudo systemctl enable webhook.socket
sudo systemctl start webhook.socket
Systemd unit files support many other options, see the systemd.socket and systemd.service manual pages for full details.