Skip to content

Latest commit

 

History

History
61 lines (43 loc) · 2.48 KB

Systemd-Activation.md

File metadata and controls

61 lines (43 loc) · 2.48 KB
Raw

Using systemd socket activation

New in v2.8.2

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.