Content-type: text/html Manpage of kibot

kibot

Section: (1)
Updated: 2003 Apr 6
Index Return to Main Contents

NAME

kibot - a modular python-based irc bot

SYNOPSIS

kibot [options]

DESCRIPTION

Kibot is a python-based IRC bot written to be cleanly and robustly modular, powerful and flexible. It has a rich permissions framework, and writing modules/commands for it is ridiculously simple.

On startup, a kibot connects to an IRC server. You can then interact with it via IRC. The nature of that interaction is largely documented online (do "/msg botnick help" to get started) but there is one important thing you must understand if you're using a kibot for the first time: many commands require some sort of permission, and when you first start a bot, it will not know anyone. You could introduce it to someone (with the meet command) but because it doesn't know you, you don't have permission to do that. The way around this problem is to use kibot-control(1), which allows you to effectively circumvent the permissions checks.

See the EXAMPLES section for how to get up and running quickly.

OPTIONS

kibot takes several options. Most options can be provided on the command line or in the config file. The config file has several sections, and each section can have several options. For each option below, its corresponding section and option names are provided at the end of the description in the format [section, option].

In most cases the format for the option value is identical whether used on the command line or in the config file. The one quirk is with list values. A list can be separated by whitespace and/or commas. If you use whitepace to delimit a list on the command line, you just enclose it in quotes or escape the whitespace, etc. list options can also include the special keyword PREV which will be replaced by the previous value for the list. This can be used to append items to the list rather than replace the list contents. See the EXAMPLES section for a sample config file.

-h, --help: Print a summary of command line options to STDOUT and exit.
-b VAL, --base-dir=VAL: The base directory where most other files are written or searched for. If other files are specified with relative paths, it will be interpreted as relative to the base dir. [files, base_dir] default: . (present working directory)
-C VAL, --conf=VAL: The location of the config file. Like other files, this is considered relative to the base directory if a relative path is give. default: kibot.conf
--py-path=VAL: A list if directories to add to the python module search path. Like other paths, relative paths are relative to the base dir. These directories should be used for support python modules needed by kibot modules that are not in the standard python distribution. [files, py_path] default: pymod,/usr/share/kibot/pymod
-d VAL, --debug=VAL: Set the logging level. This is actually a list option, but using multiple debug levels requires setting multiple log files. Each log level must be an integer. Useful values are from -1 to 10. A log level greater than 5 is really only useful for debugging low-level bot functions. A level of -1 should result in no output at all. [admin, debug] default: 0
--logfile=VAL: This is also a list option, but using multiple log files requires setting multiple debug levels. A value of "-" means STDOUT. [admin, logfile] default: -
-f, --forget: By default, a kibot remembers certain values that can be changed dynamically after startup. This option instructs the bot to ignore those values and use the values in the conf file and/or command line. The currently remembered vales are: the list of loaded modules, the bot's nick, and the bot's channel list. [admin, forget] default: 0
--daemon: This tells the bot to run as a daemon. This causes the bot to disconnect from its controlling terminal. Any logging directed to STDOUT or STDERR will be lost. The bot also forgets its umask, so you may want to use the [admin, daemon] default: 0
--lockfile=VAL: The file to use as a lockfile and to which the bot's pid is written. The lockfile helps prevent you from accidentally running a bot twice with the same data files, which could lead to data corruption. The bot will remove a stale lockfile if everything appears to be safe, so you should never need to manually remove one. [admin, lockfile] default: kibot.pid
--dc-addr=VAL: The direct connection (DC) address to listen for connections on. This is the mechanism used by kibot-control(1). This can either be the address of a unix socket (basically, a file name), or it can be a port number. If it is a port number, the bot will bind to an INET socket and listen. WARNING: you are responsible for securing this connection. Anyone who can bind to this socket will have full control of your bot. If you use a unix socket (recommended) be sure that it has the proper ownership and permissions. If you use an INET socket, you should firewall it appropriately. [admin, dc_addr] default: DC_SOCKET
--umask=VAL: The octal umask adopted in daemon mode. [admin, umask] default: 0077
--autoload=VAL: The list of modules to load on startup. The modules base, auth and irc will always be loaded on startup. [modules, autoload] default: (empty)
--load-path=VAL: The list of directories to look for bot modules in. [modules, load_path] default: modules,/usr/share/kibot/modules
-s VAL, --server=VAL: The irc server to which the bot should connect. This is required, although you can of course specify it on the command line or in the config file. [irc, server] default: (none)
-p VAL, --port=VAL: The port on the irc server to connect to. [irc, port] default: 6667
-c VAL, --channels=VAL: The list of channels join automatically on startup. You can tell the bot to join other channels with the join command. [irc, channels] default: (none)
-n VAL, --nick=VAL: The irc nick to use. This can be changed later with the nick command. [irc, nick] default: kibot
--password=VAL: The password to use for logging in to the server. [irc, password] default: (none)
-u VAL, --username=VAL: The username to use. This is the first part of username@host.domain.com. [irc, username] default: (same as nick)
-N VAL, --ircname=VAL: The descriptive name to use. This is the equivalent of a human's full name. [irc, ircname] default: (same as nick)

Some options are available only in the config file:

[files, override_file]: The file for locally overriding default permissions for commands. This feature is not fully implemented yet. default: override.conf
[files, data_dir]: The directory where the bot will store its data. default: data
[files, ircdb_file]: The file where the bot should store its user database. Note that the extension affects the format of the database. The available extensions are: pickle, repr, and shelve. pickle is highly recommended. default: data/ircdb.pickle
[irc, reconnect_interval]: The interval (in seconds) with which the bot should attempt to reconnect if it should be disconnected, either as the result of an error, or via the disconnect command. Note that some irc servers "throttle" connections to limit reconnect rates. If you choose a reconnect_interval too small, you may not be able to connect (or even harder to diagnose, reconnect) to such servers. default: 30

EXAMPLES

The most minimal conceivable invocation of kibot is this:

: kibot -s myserver.mydomain.com

This will cause the bot to connect to the server. Files will be created in the present working directory (because the default base dir is ".").

The recommended way to run a kibot is to create a config file which includes both the server definition and the location of the base dir. Here is an example config file:

[admin]
debug   = 2 5
logfile = - log5

[files]
base_dir = /var/kibot/

[irc]
nick = foobot
server = localhost
channels = #fooland

You can then start the bot simply with

: kibot -C /your/conf/file

Kibot comes with an init script (/etc/rc.d/init.d/kibot) that can be used for running bots system-wide. This expects to find one or more conf files (ending in ".conf") in /etc/kibot/. b. By default, the init script runs the bots as user "nobody", although this is configurable. Read the comment at the top of the init script for details.

AUTHORS

Kibot and many modules
  Michael Stenner <mstenner@phy.duke.edu>

units, bugzilla
  Konstantin (Icon) Riabitsev <icon@phy.duke.edu>
magic
  Timothy Burt <burt_timothy@yahoo.com>

BUGS

Due to the way python deals with signals, there is some possibility that "bad things" could happen if kibot receives a signal while it's in the process of executing a system call (mostly IO).

For now, send bugs to <mstenner@phy.duke.edu>. Documentation bugs and "this isn't clear"-reports are quite welcome as well.

This document was created by man2html, using the manual pages.
Time: 01:25:05 GMT, September 26, 2003

kibot