Add man page
Adds a man page for weblug. Signed-off-by: phoenix <felix@feldspaten.org>
This commit is contained in:
parent
77a47b5784
commit
ce7ac69371
125
doc/weblug.8
Normal file
125
doc/weblug.8
Normal file
|
@ -0,0 +1,125 @@
|
|||
." Manpage for weblug
|
||||
." Contact felix@feldspaten.org to correct errors and/or typos.
|
||||
.TH weblug 8 "27 Apr 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 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 "# 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
|
||||
.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
|
Loading…
Reference in a new issue