Felix Niederwanger
121ab40b02
Adds the `uid` and `gid` settings in the main configuration file, which allows weblug to run under a unprivileged user account. This comes with the limitation, that unless the program runs as root, custom webhook `uid/gid` settings are not possible.
148 lines
3.9 KiB
Groff
148 lines
3.9 KiB
Groff
." Manpage for weblug
|
|
." Write me an email <felix@feldspaten.org> if you find errors and/or typos. Thank you! :-)
|
|
.TH weblug 8 "28 May 2023" "1.0" "weblug man page"
|
|
.SH NAME
|
|
weblug - Simple webhook receiver program
|
|
|
|
.SH SYNOPSIS
|
|
weblug [OPTIONS] YAML1[,YAML2...]
|
|
.SH 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.
|
|
|
|
.SH OPTIONS
|
|
.TP
|
|
.B -h|--help
|
|
Print help message
|
|
|
|
.SH 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.
|
|
|
|
.SH CONFIGURATION FILES
|
|
|
|
.TP
|
|
|
|
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:
|
|
|
|
.B "---
|
|
.br
|
|
.B "## Weblug example config
|
|
.br
|
|
.B "settings:
|
|
.br
|
|
.B " #bind: "127.0.0.1:2088" # bind address for webserver
|
|
.br
|
|
.B " bind: ":2088" # bind to all addresses
|
|
.br
|
|
.B " uid: 0 # run under specified user id
|
|
.br
|
|
.B " gid: 0 # run under specified group id
|
|
.br
|
|
.B "# hook definitions. A hook needs to define the HTTP endpoint ("route") and the command
|
|
.br
|
|
.B "# See the following examples for more possible options.
|
|
.br
|
|
.B "hooks:
|
|
.br
|
|
.B " - name: 'hook one'
|
|
.br
|
|
.B " route: "/webhooks/1"
|
|
.br
|
|
.B " command: "sleep 5"
|
|
.br
|
|
.B " background: True # Terminate http request immediately
|
|
.br
|
|
.B " concurrency: 2 # At most 2 parallel processes are allowed
|
|
.br
|
|
.B " env: # Define environment variables
|
|
.br
|
|
.B " KEY1: "VALUE1"
|
|
.br
|
|
.B " KEY2: "VALUE2"
|
|
.br
|
|
.br
|
|
.br
|
|
.br
|
|
.B " - name: 'hook two'
|
|
.br
|
|
.B " route: "/webhooks/2"
|
|
.br
|
|
.B " command: "bash -c 'sleep 5'"
|
|
.br
|
|
.B " concurrency: 5 # At most 5 parallel processes are allowed
|
|
.br
|
|
.br
|
|
.br
|
|
.B " - name: 'hook 3'
|
|
.br
|
|
.B " route: "/webhooks/data/3"
|
|
.br
|
|
.B " command: "bash -c 'echo $UID $GID'"
|
|
.br
|
|
.B " uid: 100 # Run command as system user id (uid) 100
|
|
.br
|
|
.B " gid: 200 # Run command with system group id (gid) 200
|
|
.br
|
|
.B " concurrency: 1 # No concurrency. Returns 500 on parallel requests
|
|
.br
|
|
.B " output: True # Print program output to console
|
|
.br
|
|
.br
|
|
.br
|
|
.B " - name: 'hook 4'
|
|
.br
|
|
.B " route: "/webhooks/restricted/4"
|
|
.br
|
|
.br
|
|
.B " command: "true"
|
|
.br
|
|
.B " # Allow only requests from localhost
|
|
.br
|
|
.B " allowed: ["127.0.0.1/8", "::1/128"]
|
|
.br
|
|
.br
|
|
.br
|
|
.B " - name: 'hook 5'
|
|
.br
|
|
.B " route: "/webhooks/restricted/5"
|
|
.br
|
|
.B " command: "true"
|
|
.br
|
|
.B " # Allow everything, except those two subnets
|
|
.br
|
|
.B " blocked: ["192.168.0.0/16", "10.0.0.0/8"]
|
|
.br
|
|
.br
|
|
.B " - name: 'hook auth'
|
|
.br
|
|
.B " route: "/webhooks/restricted/auth"
|
|
.br
|
|
.B " command: "true"
|
|
.br
|
|
.B " # Require basic auth for this webhook
|
|
.br
|
|
.B " basic_auth:
|
|
.br
|
|
.B " # Username is optional. If defined, the following username must match
|
|
.br
|
|
.B " # If not defined, any user will be accepted
|
|
.br
|
|
.B " username: 'user'
|
|
.br
|
|
.B " # Password is obligatory to enable basic_auth. If defined, a request must authenticate with the given password (cleartext)
|
|
.br
|
|
.B " password: 'password'
|
|
.br
|