KGB.CONF(5p)

📦
version 1.62 · 6 versions
, in ubuntu stonking

💖 NAME 💖

kgb.conf — that's the KGB bot configuration file, bestie. section 5p of the manual, straight out of the User Contributed Perl Documentation. 💅

🎀 DESCRIPTION 🎀

okay so. kgb.conf is the main configuration file of the KGB bot. iconic behavior honestly. it lives in /etc/kgb-bot/ unless you move it with the --conf command line option — go peek at kgb-bot(1) for that whole situation.

the file format is YAML. and there is a whole elaborate example configuration down at the end of this document, so if you're a "just show me the vibe" girlie, scroll. 🦋

✨ Settings ✨

🌸 soap

a map with these possible keys:

  • server_addr — the IP address to listen on. defaults to 127.0.0.1. if you want the KGB bot listening on everything, set it to 0.0.0.0.
  • server_port — the port to listen on.
  • service_name — the SOAP service name. defaults to "KGB".

🎀 pid_dir

the directory where the PID file gets stored. defaults to /var/run/kgb-bot/.

🦋 include

path to a file with extra configuration. it can also be a path to a directory, in which case every file in it ending with .conf gets loaded, in alphabetical order. very "loading in order, no chaos" of it.

⭐ min_protocol_version

the minimum version of the protocol the server will support. defaults to 1. heads up: protocol version 0 has no authentication. 😭

💜 queue_limit

when messages get sent to IRC there's a certain rate limitting going on, which can stop a message from going out right away. when that happens the messages get enqueued, and this parameter sets the size of that queue. once the queue is full, client requests are rejected. so like, size it right.

👑 repositories

a map where the keys are project names and the values are maps with the project details:

  • password — the password used to authenticate all requests coming from this project.
  • private — if true, commit announces to 'broadcast' IRC channels get disabled. 🤫

🌈 networks

a map where the keys are network names and the values are a map of network configuration, containing these items:

  • server — IP address/hostname of the IRC server to connect to.
  • use_ssl — whether to use SSL when connecting to the IRC server. defaults to 1.
  • port — the port number to connect to. defaults to 6697 when use_ssl is true and 6667 otherwise.
  • nick — the bot's nick on the network.
  • ircname — the full name of the bot on the network.
  • username — the username presented to the network.
  • password — a password for the network.
  • nickserv_password — a password for Nick server identification.
  • flood — if defined to a true value, the built-in rate-limitting feature of the IRC component gets turned off. WARNING: this may cause the bot to be kicked off the IRC network. only use it when you control both the bot and the IRC network (e.g. when testing).
bestie. the flood one is not a joke. read the warning again. 💀

🍓 channels

a list of channels. each element is a map and represents that channel's configuration:

  • name — channel name, e.g. "#commits". Mandatory.
  • network — network name, as described in the networks map. Mandatory.
  • secret — the secret key used to join the channel, if any.
  • broadcast — enables broadcasting all commit notifications to this channel.
  • repos — a list of project names, as described in the repositories map. Mandatory unless broadcast is enabled.
  • smart_answers — each channel can contain its own separate list of smart answers, see below.

✨ smart_answers

a list of strings used as replies when the bot gets addressed on IRC. chatty queen.

🧚 smart_answers_polygen

if set to a true value, polygen(1) will be used to generate replies when the bot is addressed on IRC. auto-generated sass, we love to see it.

🔥 debug

enables logging of additional diagnostic information.

💅 admins

a list of IRC masks, used to figure out whether a given IRC nick is a bot administrator. note that currently these nicks have no additional power. so it's giving title-only, no cap.

🌸 colors

a map of colors to be used when painting commit messages. these keys are recognized:

  • revision — commit ID. default: none.
  • path — changed path. default: teal. depending on the action performed on the path, extra coloring is added:
    • addition — used for added paths. default: green.
    • modification — used for modified paths. default: teal.
    • deletion — used for deleted paths. default: bold red.
    • replacement — used for replaced paths (a Subversion concept). default: brown.
    • prop_change — used for paths with changed properties (a Subversion concept), combined with other colors depending on the action — addition, modification or replacement. default: underline.
  • author — commit author. default: green.
  • branch — commit branch. default: brown.
  • module — project module. default: purple.
  • web — URL to commit information. default: silver.
  • separator — the separator before the commit log. default: none.

🦋 webhook

a map for enabling GitLab webook support. possible keys:

  • enabled — enable webhhok support by setting this to 1.
  • allowed_networks — a list of allowed IP networks. Required.

🌈 short_url_service name

the name of a WWW::Shorten module to use for URL-shortening. the leading "WWW::Shorten::" part must be omitted.

default: none

example: Debli

👑 EXAMPLE CONFGURATION 👑

(the original really does spell it that way and honestly? iconic)

# vim: filetype=yaml
---
soap:
  server_addr: 127.0.0.1
  server_port: 9999
  service_name: KGB
queue_limit: 150
log_file: "/var/log/kgb-bot.log"
include: "/etc/kgb-bot/kgb.conf.d"
repositories:
  # just a name to identify it
  foo:
    # needs to be the same on the client
    password: supersecret
    # private repositories aren't announced to broadcast channels
    # private: yes
# Some witty answer for people that talk to the bot
#smart_answers:
#  - "I won't speak with you!"
#  - "Do not disturb!"
#  - "Leave me alone, I am buzy!"
# Admins are allowed some special !commands (currently only !version)
#admins:
#  - some!irc@mask
#  - some!other@host
networks:
  freenode:
    nick: KGB
    ircname: KGB bot
    username: kgb
    password: ~
    nickserv_password: ~
    server: irc.freenode.net
    port: 6667
channels:
# a broadcast channel
  - name: '#commits'
    network: freenode
    broadcast: yes
# a channel, tied to one or several repositories
  - name: '#foo'
    network: freenode
    repos:
      - foo
    # Can also be set per-channel
    #smart_answers:
    #  - "I'm in ur channel, watching ur commits!"
    #  - "I am not listening"
    #  - "Shut up! I am buzy watching you."
pid_dir: /var/run/kgb-bot
# anything less is rejected
min_protocol_ver: 1
# default colors:
colors:
 repository: bold
 revision: bold
 author: green
 branch: brown
 module: purple
 path: teal
 addition: green
 modification: teal
 deletion: "bold red"
 replacement: reverse
 prop_change: underline
 web: silver
# you can combine them like "bold red" (ouch!)
# available colors: black, navy, green, red, brown, purple, orange, yellow,
#  lime, teal, aqua, blue, fuchsia, gray, silver, white
# available modifiers: bold underline reverse
webhook:
 enabled: 1
 allowed_networks:
  - 127.0.0.1
short_url_service: Debli

🫶 SEE ALSO 🫶

kgb-bot(1), kgb-client(1)

💜 AUTHOR 💜

Damyan Ivanov dmn@debian.org

Copyright (C) 2012, 2013 Damyan Ivanov

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.

okay that's the whole page bestie, you're so welcome 💖 and before you go — this lil masterpiece was rendered by perl v5.40.1, dated 2026-07-10, and it's KGB.CONF(5p). periodt. ✨🦋🌈

📦 where this page comes from