NAME¶

weblug - Simple webhook receiver program

SYNOPSIS¶

weblug [OPTIONS] YAML1[,YAML2...]

DESCRIPTION¶

weblug is is a configurable webhook receiver that allows to define custom programs and script to be executed when a webhook is triggered.

The configuration happens via yaml files. weblug supports multiple webhooks, limitations for concurrent web hooks to be executed, background execution and running webhooks as separate user (uid/gid) and basic auth.

The system daemon uses the /etc/weblug.yml file. To enable the daemon, edit /etc/weblug.yml to your needs and then simply start/enable the system service.

OPTIONS¶

-h|--help

Print help message

CAVEATS¶

1. weblug should always run behind a http reverse proxy to avoid a whole class of security issues by using the standart go webserver implementation.

2. weblug does not support transport encryption (https). To protect access credentials/tokens, it must run behind a http reverse proxy with configured transport encryption.

3. weblug should not be exposed to the public internet.

4. Custom UID/GIDs for webhook require weblug to run as root.

CONFIGURATION FILES¶

weblug needs a configuration file with webhook definitions to run. The program needs at least one configuration file, multiple files are supported.

See the following example configuration file:

---
## Weblug example config
settings:
#bind: 127.0.0.1:2088" # bind address for webserver
bind: :2088" # bind to all addresses
uid: 0 # run under specified user id
gid: 0 # run under specified group id
# Enable TLS here here
tls:
enabled: true
# Minimum and maximum required TLS version. By default TLS1.2 is the minimum
minversion: '1.2'
maxversion: ''
keypairs:
- keyfile: 'weblug.key'
certificate: 'weblug1.pem'
- keyfile: 'weblug.key'
certificate: 'weblug2.pem'
# hook definitions. A hook needs to define the HTTP endpoint ( route") and the command
# See the following examples for more possible options.
hooks:
- name: 'hook one'
route: /webhooks/1"
# if hosts is present, then limit the incoming requests to the given remote host(s)
# Currently multiplexing the same route to different hosts does not work
hosts:
- example1.local
- example2.local
command: sleep 5"
background: True # Terminate http request immediately
concurrency: 2 # At most 2 parallel processes are allowed
env: # Define environment variables
KEY1: VALUE1"
KEY2: VALUE2"
- name: 'hook two'
route: /webhooks/2"
command: bash -c 'sleep 5'"
concurrency: 5 # At most 5 parallel processes are allowed
- name: 'hook 3'
route: /webhooks/data/3"
command: bash -c 'echo $UID $GID'"
uid: 100 # Run command as system user id (uid) 100
gid: 200 # Run command with system group id (gid) 200
concurrency: 1 # No concurrency. Returns 500 on parallel requests
output: True # Print program output to console
- name: 'hook 4'
route: /webhooks/restricted/4"
command: true"
# Allow only requests from localhost
allowed: [ 127.0.0.1/8", ::1/128 ]
- name: 'hook 5'
route: /webhooks/restricted/5"
command: true"
# Allow everything, except those two subnets
blocked: [ 192.168.0.0/16", 10.0.0.0/8 ]
- name: 'hook auth'
route: /webhooks/restricted/auth"
command: true"
# Require basic auth for this webhook
basic_auth:
# Username is optional. If defined, the following username must match
# If not defined, any user will be accepted
username: 'user'
# Password is obligatory to enable basic_auth. If defined, a request must authenticate with the given password (cleartext)
password: 'password'