# vim: ts=4:sw=4:et:ai:sts=4
#
# KGB - an IRC bot helping collaboration
# Copyright © 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.
=head1 NAME
kgb.conf -- KGB bot configuration file
=head1 DESCRIPTION
F<kgb.conf> is the main configuration file of the KGB bot. Its location is in
F</etc/kgb-bot/> unless changed with the B<--conf> command line option. See
L<kgb-bot(1)>.
The file format is YAML. Elaborate example configuration is at the end of this
document.
=head1 Settings
=head2 soap
A map with the following possible keys:
=over
=item B<server_addr>
IP address to listen to.
=item B<server_port>
Port to listen to.
=item B<service_name>
SOAP service name. Defaults to C<KGB>.
=back
=head2 pid_dir
Directory to store PID file to. Defautls to F</var/run/kgb-bot/>.
=head2 include
Path to file with additional configuration. May be a path to a directory, in
which case all files in it ending with C<.conf> are loaded, in alphabetical
order.
=head2 min_protocol_version
Minimum version of the protocol that will be supported by the server. Defaults
to C<1>. Protocol version 0 has no authentication.
=head2 queue_limit
When messages are sent to IRC, there is certain rate limitting, which may
prevent the message to be sent right away. In this case messages are enqueued,
and this parameter configures the size of the queue. When the queue is full
client requests are rejected.
=head2 repositories
A map with keys project names and values maps with project details:
=over
=item password
Password used for authenticating all requests from this project.
=item private
If true, disables commit announces to 'broadcast' IRC channels.
=back
=head2 networks
A map with keys network names and values map of network configuration,
containing the following items:
=over
=item server
IP address/hostname of the IRC server to connect to.
=item port
Port number to connect to.
=item nick
Bot's nick on the network.
=item ircname
The full name of the bot on the network.
=item username
The username presented to the network.
=item password
A password for the network.
=item nickserv_password
A password for Nick server identification.
=item flood
If defined to a true value, the built-in rate-limitting feature of the IRC
component will be turned off. B<WARNING>: this may cause the bot to be kicked
off the IRC network. Use only when you control both the bot and the IRC network
(e.g. when testing).
=back
=head2 channels
A list of channels. Each element is a map and represents the channel's
configuration:
=over
=item name
Channel name, e.g. C<#commits>. B<Mandatory>.
=item network
Network name, as described in the B<networks> map. B<Mandatory>.
=item broadcast
Enables broadcasting all commit notifications to this channel.
=item repos
A list of project names, as described in the B<repositories> map. Mandatory
unless broadcast is enabled.
=item smart_answers
Each channel can contain separate list of smart answers, see below.
=back
=head2 smart_answers
A list of strings to be used as replies when the bot is addressed on IRC.
=head2 smart_answers_polygen
If set to a true value, L<polygen(1)> will be used to generate replies when the
bot is addressed on IRC.
=head2 debug
Enables logging of additional diagnostic information.
=head2 admins
A list of IRC masks, used to determine if a given IRC nick is bot
administrator. Note that currently these nicks have no additional power.
=head2 colors
A map of colors to be used when painting commit messages. The following keys
are recognized:
=over
=item revision
Commit ID. Default: none.
=item path
Changed path. Default: teal.
Depending on the action performed to the path, additional coloring is made:
=over
=item addition
Used for added paths. Default: green.
=item modification
Used for modified paths. Default: teal.
=item deletion
Used for deleted paths. Default: bold red.
=item replacement
Used for replaced paths (a Subversion concept). Default: brown.
=item 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.
=back
=item author
Commit author. Default: green.
=item branch
Commit branch. Default: brown.
=item module
Project module. Default: purple.
=item web
URL to commit information. Default: silver.
=item separator
The separator before the commit log. Default: none.
=back
=head1 EXAMPLE CONFGURATION
# 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 wont 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
=head1 SEE ALSO
L<kgb-bot(1)>, L<kgb-client(1)>
=head1 AUTHOR
=over
=item Damyan Ivanov L<dmn@debian.org>
=back
=head1 COPYRIGHT & LICENSE
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.
=cut