weblug(8)

okay bestie, you've opened weblug(8) and honestly? good for you 💅 this one's a little webhook gremlin that runs your scripts when the internet knocks on its door. no cap.

💖 NAME 💖

weblug — a simple webhook receiver program ✨ (yes that's the whole name, we're keeping it cute and keeping it exact)

---

🎀 SYNOPSIS 🎀

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

that's it. that's the whole vibe. you give it yaml, it gives you webhooks 🫶

---

✨ DESCRIPTION ✨

weblug is a configurable webhook receiver that lets you define custom programs and scripts to be executed when a webhook is triggered 🔥

the configuration happens via yaml files, periodt. weblug supports multiple webhooks, limitations for concurrent webhooks to be executed, background execution, running webhooks as a 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. iconic behavior, honestly 💅

---

🌸 OPTIONS 🌸

• -h, --help — print the help message. that's it, that's the only option, she's lowkey minimal and we respect it 🙈

---

💀 CAVEATS 💀

bestie. listen. these are not suggestions, they're warnings, and you need to read them fr fr:

1. weblug should always run behind a http reverse proxy to avoid a whole class of security issues by using the standard go webserver implementation. do not skip this, I'm begging 🫶
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. no https no cap 😭
3. weblug should not be exposed to the public internet. at all. not even a little. 🙈
4. custom UID/GIDs for webhook require weblug to run as root. just so you know what you're signing up for 👑

---

🦋 CONFIGURATION FILES 🦋

weblug needs a configuration file with webhook definitions to run. the program needs at least one configuration file, and 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'

go forth and hook all the things 🌈 iykyk.

---

and that's the page bestie! 🧚 this little love letter is version 1.0, dated 28 May 2023 — treat her well, run her behind a proxy, and she'll slay for you 💜